kernel: kernel.h doxygen cleanup
Cleanup of document APIs and structure, mostly making doxygen aware of
documented members.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
diff --git a/include/kernel.h b/include/kernel.h
index 251079c..e510e39 100644
--- a/include/kernel.h
+++ b/include/kernel.h
@@ -136,7 +136,10 @@
struct k_mem_partition;
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()
* function in kernel/userspace.c
*/
@@ -197,9 +200,13 @@
{ (&_k_thread_obj_ ## name_), \
(_CONCAT(_object_list_, name_)) }
+/** Object initialized */
#define K_OBJ_FLAG_INITIALIZED BIT(0)
+/** Object is Public */
#define K_OBJ_FLAG_PUBLIC BIT(1)
+/** Object allocated */
#define K_OBJ_FLAG_ALLOC BIT(2)
+/** Driver Object */
#define K_OBJ_FLAG_DRIVER BIT(3)
/**
@@ -283,7 +290,15 @@
*/
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);
/**
@@ -340,7 +355,11 @@
return NULL;
}
-
+/**
+ * @brief Free an object
+ *
+ * @param obj
+ */
static inline void k_obj_free(void *obj)
{
ARG_UNUSED(obj);
@@ -505,9 +524,9 @@
#if defined(CONFIG_USERSPACE)
struct _mem_domain_info {
- /* memory domain queue node */
+ /** memory domain queue node */
sys_dnode_t mem_domain_q_node;
- /* memory domain of the thread */
+ /** memory domain of the thread */
struct k_mem_domain *mem_domain;
};
@@ -548,7 +567,7 @@
#endif
#if defined(CONFIG_THREAD_NAME)
- /* Thread name */
+ /** Thread name */
char name[CONFIG_THREAD_MAX_NAME_LEN];
#endif
@@ -611,6 +630,7 @@
* @addtogroup thread_apis
* @{
*/
+
typedef void (*k_thread_user_cb_t)(const struct k_thread *thread,
void *user_data);
@@ -3222,10 +3242,15 @@
* @ingroup mutex_apis
*/
struct k_mutex {
+ /** Mutex wait queue */
_wait_q_t wait_q;
/** Mutex owner */
struct k_thread *owner;
+
+ /** Current lock count */
u32_t lock_count;
+
+ /** Original thread priority */
int owner_orig_prio;
_OBJECT_TRACING_NEXT_PTR(k_mutex)
@@ -3475,18 +3500,29 @@
* @brief Message Queue Structure
*/
struct k_msgq {
+ /** Message queue wait queue */
_wait_q_t wait_q;
+ /** Lock */
struct k_spinlock lock;
+ /** Message size */
size_t msg_size;
+ /** Maximal number of messages */
u32_t max_msgs;
+ /** Start of message buffer */
char *buffer_start;
+ /** End of message buffer */
char *buffer_end;
+ /** Read pointer */
char *read_ptr;
+ /** Write pointer */
char *write_ptr;
+ /** Number of used messages */
u32_t used_msgs;
_OBJECT_TRACING_NEXT_PTR(k_msgq)
_OBJECT_TRACING_LINKED_FLAG
+
+ /** Message queue */
u8_t flags;
};
/**
@@ -3518,8 +3554,11 @@
* @brief Message Queue Attributes
*/
struct k_msgq_attrs {
+ /** Message Size */
size_t msg_size;
+ /** Maximal number of messages */
u32_t max_msgs;
+ /** Used messages */
u32_t used_msgs;
};
@@ -3597,7 +3636,12 @@
__syscall int k_msgq_alloc_init(struct k_msgq *q, size_t msg_size,
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);
/**
@@ -3753,6 +3797,10 @@
* @{
*/
+/**
+ * @brief Mailbox Message Structure
+ *
+ */
struct k_mbox_msg {
/** internal use only - needed for legacy API support */
u32_t _mailbox;
@@ -3777,9 +3825,14 @@
struct k_sem *_async_sem;
#endif
};
-
+/**
+ * @brief Mailbox Structure
+ *
+ */
struct k_mbox {
+ /** Transmit messages queue */
_wait_q_t tx_msg_queue;
+ /** Receive message queue */
_wait_q_t rx_msg_queue;
struct k_spinlock lock;
@@ -4554,16 +4607,16 @@
/* public - poll signal object */
struct k_poll_signal {
- /* PRIVATE - DO NOT TOUCH */
+ /** PRIVATE - DO NOT TOUCH */
sys_dlist_t poll_events;
- /*
+ /**
* 1 if the event has been signaled, 0 otherwise. Stays set to 1 until
* user resets it to 0.
*/
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;
};
@@ -4573,30 +4626,33 @@
.signaled = 0, \
.result = 0, \
}
-
+/**
+ * @brief Poll Event
+ *
+ */
struct k_poll_event {
- /* PRIVATE - DO NOT TOUCH */
+ /** PRIVATE - DO NOT TOUCH */
sys_dnode_t _node;
- /* PRIVATE - DO NOT TOUCH */
+ /** PRIVATE - DO NOT TOUCH */
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;
- /* 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;
- /* 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;
- /* mode of operation, from enum k_poll_modes */
+ /** mode of operation, from enum k_poll_modes */
u32_t mode:1;
- /* unused bits in 32-bit word */
+ /** unused bits in 32-bit word */
u32_t unused:_POLL_EVENT_NUM_UNUSED_BITS;
- /* per-type data */
+ /** per-type data */
union {
void *obj;
struct k_poll_signal *signal;
@@ -5069,26 +5125,28 @@
/* memory partition */
struct k_mem_partition {
- /* start address of memory partition */
+ /** start address of memory partition */
uintptr_t start;
- /* size of memory partition */
+ /** size of memory partition */
u32_t size;
#if defined(CONFIG_MEMORY_PROTECTION)
- /* attribute of memory partition */
+ /** attribute of memory partition */
k_mem_partition_attr_t attr;
#endif /* CONFIG_MEMORY_PROTECTION */
};
-/* memory domain
+/**
+ * @brief Memory Domain
+ *
*/
struct k_mem_domain {
#ifdef CONFIG_USERSPACE
- /* partitions in the domain */
+ /** partitions in the domain */
struct k_mem_partition partitions[CONFIG_MAX_DOMAIN_PARTITIONS];
#endif /* CONFIG_USERSPACE */
- /* domain q */
+ /** domain q */
sys_dlist_t mem_domain_q;
- /* number of partitions in the domain */
+ /** number of partitions in the domain */
u8_t num_partitions;
};
