michaelh/zephyr
1
0
Fork 0
Code Releases Activity

kernel: kernel.h doxygen cleanup

Browse source 
Cleanup of document APIs and structure, mostly making doxygen aware of
documented members.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2019-12-04 20:00:14 -05:00
commit e71293ea44
1 changed files with 85 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

112
include/kernel.h
View file

@ -136,7 +136,10 @@ struct k_mem_domain;
struct k_mem_partition; struct k_mem_partition;
struct k_futex; struct k_futex;
/* This enumeration needs to be kept in sync with the lists of kernel objects /**
* @brief Kernel Object Types
*
* This enumeration needs to be kept in sync with the lists of kernel objects
* and subsystems in scripts/gen_kobject_list.py, as well as the otype_to_str() * and subsystems in scripts/gen_kobject_list.py, as well as the otype_to_str()
* function in kernel/userspace.c * function in kernel/userspace.c
*/ */
@ -197,9 +200,13 @@ struct _k_object_assignment {
{ (&_k_thread_obj_ ## name_), \ { (&_k_thread_obj_ ## name_), \
(_CONCAT(_object_list_, name_)) } (_CONCAT(_object_list_, name_)) }
/** Object initialized */
#define K_OBJ_FLAG_INITIALIZED BIT(0) #define K_OBJ_FLAG_INITIALIZED BIT(0)
/** Object is Public */
#define K_OBJ_FLAG_PUBLIC BIT(1) #define K_OBJ_FLAG_PUBLIC BIT(1)
/** Object allocated */
#define K_OBJ_FLAG_ALLOC BIT(2) #define K_OBJ_FLAG_ALLOC BIT(2)
/** Driver Object */
#define K_OBJ_FLAG_DRIVER BIT(3) #define K_OBJ_FLAG_DRIVER BIT(3)
/** /**
@ -283,7 +290,15 @@ __syscall void k_object_access_grant(void *object, struct k_thread *thread);
*/ */
void k_object_access_revoke(void *object, struct k_thread *thread); void k_object_access_revoke(void *object, struct k_thread *thread);
/**
* @brief Release an object
*
* Allows user threads to drop their own permission on an object
* Their permissions are automatically cleared when a thread terminates.
*
* @param object The object to be released
*
*/
__syscall void k_object_release(void *object); __syscall void k_object_release(void *object);
/** /**
@ -340,7 +355,11 @@ static inline void *z_impl_k_object_alloc(enum k_objects otype)
return NULL; return NULL;
} }
/**
* @brief Free an object
*
* @param obj
*/
static inline void k_obj_free(void *obj) static inline void k_obj_free(void *obj)
{ {
ARG_UNUSED(obj); ARG_UNUSED(obj);
@ -505,9 +524,9 @@ typedef struct _thread_stack_info _thread_stack_info_t;
#if defined(CONFIG_USERSPACE) #if defined(CONFIG_USERSPACE)
struct _mem_domain_info { struct _mem_domain_info {
/* memory domain queue node */ /** memory domain queue node */
sys_dnode_t mem_domain_q_node; sys_dnode_t mem_domain_q_node;
/* memory domain of the thread */ /** memory domain of the thread */
struct k_mem_domain *mem_domain; struct k_mem_domain *mem_domain;
}; };
@ -548,7 +567,7 @@ struct k_thread {
#endif #endif
#if defined(CONFIG_THREAD_NAME) #if defined(CONFIG_THREAD_NAME)
/* Thread name */ /** Thread name */
char name[CONFIG_THREAD_MAX_NAME_LEN]; char name[CONFIG_THREAD_MAX_NAME_LEN];
#endif #endif
@ -611,6 +630,7 @@ enum execution_context_types {
* @addtogroup thread_apis * @addtogroup thread_apis
* @{ * @{
*/ */
typedef void (*k_thread_user_cb_t)(const struct k_thread *thread, typedef void (*k_thread_user_cb_t)(const struct k_thread *thread,
void *user_data); void *user_data);
@ -3222,10 +3242,15 @@ extern int k_work_poll_cancel(struct k_work_poll *work);
* @ingroup mutex_apis * @ingroup mutex_apis
*/ */
struct k_mutex { struct k_mutex {
/** Mutex wait queue */
_wait_q_t wait_q; _wait_q_t wait_q;
/** Mutex owner */ /** Mutex owner */
struct k_thread *owner; struct k_thread *owner;
/** Current lock count */
u32_t lock_count; u32_t lock_count;
/** Original thread priority */
int owner_orig_prio; int owner_orig_prio;
_OBJECT_TRACING_NEXT_PTR(k_mutex) _OBJECT_TRACING_NEXT_PTR(k_mutex)
@ -3475,18 +3500,29 @@ static inline unsigned int z_impl_k_sem_count_get(struct k_sem *sem)
* @brief Message Queue Structure * @brief Message Queue Structure
*/ */
struct k_msgq { struct k_msgq {
/** Message queue wait queue */
_wait_q_t wait_q; _wait_q_t wait_q;
/** Lock */
struct k_spinlock lock; struct k_spinlock lock;
/** Message size */
size_t msg_size; size_t msg_size;
/** Maximal number of messages */
u32_t max_msgs; u32_t max_msgs;
/** Start of message buffer */
char *buffer_start; char *buffer_start;
/** End of message buffer */
char *buffer_end; char *buffer_end;
/** Read pointer */
char *read_ptr; char *read_ptr;
/** Write pointer */
char *write_ptr; char *write_ptr;
/** Number of used messages */
u32_t used_msgs; u32_t used_msgs;
_OBJECT_TRACING_NEXT_PTR(k_msgq) _OBJECT_TRACING_NEXT_PTR(k_msgq)
_OBJECT_TRACING_LINKED_FLAG _OBJECT_TRACING_LINKED_FLAG
/** Message queue */
u8_t flags; u8_t flags;
}; };
/** /**
@ -3518,8 +3554,11 @@ struct k_msgq {
* @brief Message Queue Attributes * @brief Message Queue Attributes
*/ */
struct k_msgq_attrs { struct k_msgq_attrs {
/** Message Size */
size_t msg_size; size_t msg_size;
/** Maximal number of messages */
u32_t max_msgs; u32_t max_msgs;
/** Used messages */
u32_t used_msgs; u32_t used_msgs;
}; };
@ -3597,7 +3636,12 @@ void k_msgq_init(struct k_msgq *q, char *buffer, size_t msg_size,
__syscall int k_msgq_alloc_init(struct k_msgq *q, size_t msg_size, __syscall int k_msgq_alloc_init(struct k_msgq *q, size_t msg_size,
u32_t max_msgs); u32_t max_msgs);
/**
* @brief Cleanup message queue
*
* Releases memory allocated for the ring buffer.
* @param q
*/
void k_msgq_cleanup(struct k_msgq *q); void k_msgq_cleanup(struct k_msgq *q);
/** /**
@ -3753,6 +3797,10 @@ struct k_mem_block {
* @{ * @{
*/ */
/**
* @brief Mailbox Message Structure
*
*/
struct k_mbox_msg { struct k_mbox_msg {
/** internal use only - needed for legacy API support */ /** internal use only - needed for legacy API support */
u32_t _mailbox; u32_t _mailbox;
@ -3777,9 +3825,14 @@ struct k_mbox_msg {
struct k_sem *_async_sem; struct k_sem *_async_sem;
#endif #endif
}; };
/**
* @brief Mailbox Structure
*
*/
struct k_mbox { struct k_mbox {
/** Transmit messages queue */
_wait_q_t tx_msg_queue; _wait_q_t tx_msg_queue;
/** Receive message queue */
_wait_q_t rx_msg_queue; _wait_q_t rx_msg_queue;
struct k_spinlock lock; struct k_spinlock lock;
@ -4554,16 +4607,16 @@ enum k_poll_modes {
/* public - poll signal object */ /* public - poll signal object */
struct k_poll_signal { struct k_poll_signal {
/* PRIVATE - DO NOT TOUCH */ /** PRIVATE - DO NOT TOUCH */
sys_dlist_t poll_events; sys_dlist_t poll_events;
/* /**
* 1 if the event has been signaled, 0 otherwise. Stays set to 1 until * 1 if the event has been signaled, 0 otherwise. Stays set to 1 until
* user resets it to 0. * user resets it to 0.
*/ */
unsigned int signaled; unsigned int signaled;
/* custom result value passed to k_poll_signal_raise() if needed */ /** custom result value passed to k_poll_signal_raise() if needed */
int result; int result;
}; };
@ -4573,30 +4626,33 @@ struct k_poll_signal {
.signaled = 0, \ .signaled = 0, \
.result = 0, \ .result = 0, \
} }
/**
* @brief Poll Event
*
*/
struct k_poll_event { struct k_poll_event {
/* PRIVATE - DO NOT TOUCH */ /** PRIVATE - DO NOT TOUCH */
sys_dnode_t _node; sys_dnode_t _node;
/* PRIVATE - DO NOT TOUCH */ /** PRIVATE - DO NOT TOUCH */
struct _poller *poller; struct _poller *poller;
/* optional user-specified tag, opaque, untouched by the API */ /** optional user-specified tag, opaque, untouched by the API */
u32_t tag:8; u32_t tag:8;
/* bitfield of event types (bitwise-ORed K_POLL_TYPE_xxx values) */ /** bitfield of event types (bitwise-ORed K_POLL_TYPE_xxx values) */
u32_t type:_POLL_NUM_TYPES; u32_t type:_POLL_NUM_TYPES;
/* bitfield of event states (bitwise-ORed K_POLL_STATE_xxx values) */ /** bitfield of event states (bitwise-ORed K_POLL_STATE_xxx values) */
u32_t state:_POLL_NUM_STATES; u32_t state:_POLL_NUM_STATES;
/* mode of operation, from enum k_poll_modes */ /** mode of operation, from enum k_poll_modes */
u32_t mode:1; u32_t mode:1;
/* unused bits in 32-bit word */ /** unused bits in 32-bit word */
u32_t unused:_POLL_EVENT_NUM_UNUSED_BITS; u32_t unused:_POLL_EVENT_NUM_UNUSED_BITS;
/* per-type data */ /** per-type data */
union { union {
void *obj; void *obj;
struct k_poll_signal *signal; struct k_poll_signal *signal;
@ -5069,26 +5125,28 @@ static inline char *Z_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
/* memory partition */ /* memory partition */
struct k_mem_partition { struct k_mem_partition {
/* start address of memory partition */ /** start address of memory partition */
uintptr_t start; uintptr_t start;
/* size of memory partition */ /** size of memory partition */
u32_t size; u32_t size;
#if defined(CONFIG_MEMORY_PROTECTION) #if defined(CONFIG_MEMORY_PROTECTION)
/* attribute of memory partition */ /** attribute of memory partition */
k_mem_partition_attr_t attr; k_mem_partition_attr_t attr;
#endif /* CONFIG_MEMORY_PROTECTION */ #endif /* CONFIG_MEMORY_PROTECTION */
}; };
/* memory domain /**
* @brief Memory Domain
*
*/ */
struct k_mem_domain { struct k_mem_domain {
#ifdef CONFIG_USERSPACE #ifdef CONFIG_USERSPACE
/* partitions in the domain */ /** partitions in the domain */
struct k_mem_partition partitions[CONFIG_MAX_DOMAIN_PARTITIONS]; struct k_mem_partition partitions[CONFIG_MAX_DOMAIN_PARTITIONS];
#endif /* CONFIG_USERSPACE */ #endif /* CONFIG_USERSPACE */
/* domain q */ /** domain q */
sys_dlist_t mem_domain_q; sys_dlist_t mem_domain_q;
/* number of partitions in the domain */ /** number of partitions in the domain */
u8_t num_partitions; u8_t num_partitions;
}; };