kernel: add requirement Ids to implementation
Add requirement ID place holders based on APIS. The requirements will
appear as a list in doxygen documentation. The IDs will be expanded with
more details somewhere else, probably a requirement catalog on GH or
some other requirement management tool. This is still TBD.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
diff --git a/include/kernel.h b/include/kernel.h
index a6a2c61..3312832 100644
--- a/include/kernel.h
+++ b/include/kernel.h
@@ -1978,14 +1978,13 @@
/** @} */
-/**
- * @cond INTERNAL_HIDDEN
- */
-
struct k_fifo {
struct k_queue _queue;
};
+/**
+ * @cond INTERNAL_HIDDEN
+ */
#define _K_FIFO_INITIALIZER(obj) \
{ \
._queue = _K_QUEUE_INITIALIZER(obj._queue) \
@@ -2011,6 +2010,7 @@
* @param fifo Address of the FIFO queue.
*
* @return N/A
+ * @req K-FIFO-001
*/
#define k_fifo_init(fifo) \
k_queue_init((struct k_queue *) fifo)
@@ -2027,6 +2027,7 @@
* @param fifo Address of the FIFO queue.
*
* @return N/A
+ * @req K-FIFO-001
*/
#define k_fifo_cancel_wait(fifo) \
k_queue_cancel_wait((struct k_queue *) fifo)
@@ -2044,6 +2045,7 @@
* @param data Address of the data item.
*
* @return N/A
+ * @req K-FIFO-001
*/
#define k_fifo_put(fifo, data) \
k_queue_append((struct k_queue *) fifo, data)
@@ -2062,6 +2064,7 @@
*
* @retval 0 on success
* @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool
+ * @req K-FIFO-001
*/
#define k_fifo_alloc_put(fifo, data) \
k_queue_alloc_append((struct k_queue *) fifo, data)
@@ -2081,6 +2084,7 @@
* @param tail Pointer to last node in singly-linked list.
*
* @return N/A
+ * @req K-FIFO-001
*/
#define k_fifo_put_list(fifo, head, tail) \
k_queue_append_list((struct k_queue *) fifo, head, tail)
@@ -2099,6 +2103,7 @@
* @param list Pointer to sys_slist_t object.
*
* @return N/A
+ * @req K-FIFO-001
*/
#define k_fifo_put_slist(fifo, list) \
k_queue_merge_slist((struct k_queue *) fifo, list)
@@ -2117,6 +2122,7 @@
*
* @return Address of the data item if successful; NULL if returned
* without waiting, or waiting period timed out.
+ * @req K-FIFO-001
*/
#define k_fifo_get(fifo, timeout) \
k_queue_get((struct k_queue *) fifo, timeout)
@@ -2133,6 +2139,7 @@
*
* @return Non-zero if the FIFO queue is empty.
* @return 0 if data is available.
+ * @req K-FIFO-001
*/
#define k_fifo_is_empty(fifo) \
k_queue_is_empty((struct k_queue *) fifo)
@@ -2149,6 +2156,7 @@
* @param fifo Address of the FIFO queue.
*
* @return Head element, or NULL if the FIFO queue is empty.
+ * @req K-FIFO-001
*/
#define k_fifo_peek_head(fifo) \
k_queue_peek_head((struct k_queue *) fifo)
@@ -2163,6 +2171,7 @@
* @param fifo Address of the FIFO queue.
*
* @return Tail element, or NULL if a FIFO queue is empty.
+ * @req K-FIFO-001
*/
#define k_fifo_peek_tail(fifo) \
k_queue_peek_tail((struct k_queue *) fifo)
@@ -2175,6 +2184,7 @@
* @code extern struct k_fifo <name>; @endcode
*
* @param name Name of the FIFO queue.
+ * @req K-FIFO-002
*/
#define K_FIFO_DEFINE(name) \
struct k_fifo name \
@@ -2183,14 +2193,14 @@
/** @} */
-/**
- * @cond INTERNAL_HIDDEN
- */
-
struct k_lifo {
struct k_queue _queue;
};
+/**
+ * @cond INTERNAL_HIDDEN
+ */
+
#define _K_LIFO_INITIALIZER(obj) \
{ \
._queue = _K_QUEUE_INITIALIZER(obj._queue) \
@@ -2216,6 +2226,7 @@
* @param lifo Address of the LIFO queue.
*
* @return N/A
+ * @req K-LIFO-001
*/
#define k_lifo_init(lifo) \
k_queue_init((struct k_queue *) lifo)
@@ -2233,6 +2244,7 @@
* @param data Address of the data item.
*
* @return N/A
+ * @req K-LIFO-001
*/
#define k_lifo_put(lifo, data) \
k_queue_prepend((struct k_queue *) lifo, data)
@@ -2251,6 +2263,7 @@
*
* @retval 0 on success
* @retval -ENOMEM if there isn't sufficient RAM in the caller's resource pool
+ * @req K-LIFO-001
*/
#define k_lifo_alloc_put(lifo, data) \
k_queue_alloc_prepend((struct k_queue *) lifo, data)
@@ -2269,6 +2282,7 @@
*
* @return Address of the data item if successful; NULL if returned
* without waiting, or waiting period timed out.
+ * @req K-LIFO-001
*/
#define k_lifo_get(lifo, timeout) \
k_queue_get((struct k_queue *) lifo, timeout)
@@ -2281,6 +2295,7 @@
* @code extern struct k_lifo <name>; @endcode
*
* @param name Name of the fifo.
+ * @req K-LIFO-002
*/
#define K_LIFO_DEFINE(name) \
struct k_lifo name \
@@ -2333,6 +2348,7 @@
* @param num_entries Maximum number of values that can be stacked.
*
* @return N/A
+ * @req K-STACK-001
*/
void k_stack_init(struct k_stack *stack,
u32_t *buffer, unsigned int num_entries);
@@ -2350,6 +2366,7 @@
* @param num_entries Maximum number of values that can be stacked.
*
* @return -ENOMEM if memory couldn't be allocated
+ * @req K-STACK-001
*/
__syscall int k_stack_alloc_init(struct k_stack *stack,
@@ -2363,6 +2380,7 @@
* if the buffer wasn't dynamically allocated.
*
* @param stack Address of the stack.
+ * @req K-STACK-001
*/
void k_stack_cleanup(struct k_stack *stack);
@@ -2377,6 +2395,7 @@
* @param data Value to push onto the stack.
*
* @return N/A
+ * @req K-STACK-001
*/
__syscall void k_stack_push(struct k_stack *stack, u32_t data);
@@ -2396,6 +2415,7 @@
* @retval 0 Element popped from stack.
* @retval -EBUSY Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-STACK-001
*/
__syscall int k_stack_pop(struct k_stack *stack, u32_t *data, s32_t timeout);
@@ -2408,6 +2428,7 @@
*
* @param name Name of the stack.
* @param stack_num_entries Maximum number of values that can be stacked.
+ * @req K-STACK-002
*/
#define K_STACK_DEFINE(name, stack_num_entries) \
u32_t __noinit \
@@ -2437,6 +2458,7 @@
* @param work Address of the work item.
*
* @return N/A
+ * @req K-WORK-001
*/
typedef void (*k_work_handler_t)(struct k_work *work);
@@ -2490,6 +2512,7 @@
*
* @param work Symbol name for work item object
* @param work_handler Function to invoke each time work item is processed.
+ * @req K-WORK-002
*/
#define K_WORK_DEFINE(work, work_handler) \
struct k_work work \
@@ -2505,6 +2528,7 @@
* @param handler Function to invoke each time work item is processed.
*
* @return N/A
+ * @req K-WORK-001
*/
static inline void k_work_init(struct k_work *work, k_work_handler_t handler)
{
@@ -2533,6 +2557,7 @@
* @param work Address of work item.
*
* @return N/A
+ * @req K-WORK-001
*/
static inline void k_work_submit_to_queue(struct k_work_q *work_q,
struct k_work *work)
@@ -2553,6 +2578,7 @@
* @param work Address of work item.
*
* @return 1 if work item is pending, or 0 if it is not pending.
+ * @req K-WORK-001
*/
static inline int k_work_pending(struct k_work *work)
{
@@ -2574,6 +2600,7 @@
* @param prio Priority of the work queue's thread.
*
* @return N/A
+ * @req K-WORK-001
*/
extern void k_work_q_start(struct k_work_q *work_q,
k_thread_stack_t *stack,
@@ -2589,6 +2616,7 @@
* @param handler Function to invoke each time work item is processed.
*
* @return N/A
+ * @req K-DWORK-001
*/
extern void k_delayed_work_init(struct k_delayed_work *work,
k_work_handler_t handler);
@@ -2623,6 +2651,7 @@
* @retval -EINPROGRESS Work item is already pending.
* @retval -EINVAL Work item is being processed or has completed its work.
* @retval -EADDRINUSE Work item is pending on a different workqueue.
+ * @req K-DWORK-001
*/
extern int k_delayed_work_submit_to_queue(struct k_work_q *work_q,
struct k_delayed_work *work,
@@ -2642,6 +2671,7 @@
* @retval 0 Work item countdown canceled.
* @retval -EINPROGRESS Work item is already pending.
* @retval -EINVAL Work item is being processed or has completed its work.
+ * @req K-DWORK-001
*/
extern int k_delayed_work_cancel(struct k_delayed_work *work);
@@ -2665,6 +2695,7 @@
* @param work Address of work item.
*
* @return N/A
+ * @req K-WORK-001
*/
static inline void k_work_submit(struct k_work *work)
{
@@ -2702,6 +2733,7 @@
* @retval -EINPROGRESS Work item is already pending.
* @retval -EINVAL Work item is being processed or has completed its work.
* @retval -EADDRINUSE Work item is pending on a different workqueue.
+ * @req K-DWORK-001
*/
static inline int k_delayed_work_submit(struct k_delayed_work *work,
s32_t delay)
@@ -2719,6 +2751,7 @@
* @param work Delayed work item.
*
* @return Remaining time (in milliseconds).
+ * @req K-DWORK-001
*/
static inline s32_t k_delayed_work_remaining_get(struct k_delayed_work *work)
{
@@ -2769,6 +2802,7 @@
* @code extern struct k_mutex <name>; @endcode
*
* @param name Name of the mutex.
+ * @req K-MUTEX-001
*/
#define K_MUTEX_DEFINE(name) \
struct k_mutex name \
@@ -2785,6 +2819,7 @@
* @param mutex Address of the mutex.
*
* @return N/A
+ * @req K-MUTEX-002
*/
__syscall void k_mutex_init(struct k_mutex *mutex);
@@ -2805,6 +2840,7 @@
* @retval 0 Mutex locked.
* @retval -EBUSY Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MUTEX-002
*/
__syscall int k_mutex_lock(struct k_mutex *mutex, s32_t timeout);
@@ -2821,6 +2857,7 @@
* @param mutex Address of the mutex.
*
* @return N/A
+ * @req K-MUTEX-002
*/
__syscall void k_mutex_unlock(struct k_mutex *mutex);
@@ -2872,6 +2909,7 @@
* @param limit Maximum permitted semaphore count.
*
* @return N/A
+ * @req K-SEM-001
*/
__syscall void k_sem_init(struct k_sem *sem, unsigned int initial_count,
unsigned int limit);
@@ -2896,6 +2934,7 @@
* @retval 0 Semaphore taken.
* @retval -EBUSY Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-SEM-001
*/
__syscall int k_sem_take(struct k_sem *sem, s32_t timeout);
@@ -2910,6 +2949,7 @@
* @param sem Address of the semaphore.
*
* @return N/A
+ * @req K-SEM-001
*/
__syscall void k_sem_give(struct k_sem *sem);
@@ -2921,6 +2961,7 @@
* @param sem Address of the semaphore.
*
* @return N/A
+ * @req K-SEM-001
*/
__syscall void k_sem_reset(struct k_sem *sem);
@@ -2940,6 +2981,7 @@
* @param sem Address of the semaphore.
*
* @return Current semaphore count.
+ * @req K-SEM-001
*/
__syscall unsigned int k_sem_count_get(struct k_sem *sem);
@@ -2961,6 +3003,7 @@
* @param name Name of the semaphore.
* @param initial_count Initial semaphore count.
* @param count_limit Maximum permitted semaphore count.
+ * @req K-SEM-002
*/
#define K_SEM_DEFINE(name, initial_count, count_limit) \
struct k_sem name \
@@ -3035,6 +3078,8 @@
*/
/**
+ * @def K_ALERT_DEFINE(name, alert_handler, max_num_pending_alerts)
+ *
* @brief Statically define and initialize an alert.
*
* The alert can be accessed outside the module where it is defined using:
@@ -3047,6 +3092,8 @@
* thread, K_ALERT_IGNORE (which causes the alert to be ignored), or
* K_ALERT_DEFAULT (which causes the alert to pend).
* @param max_num_pending_alerts Maximum number of pending alerts.
+ *
+ * @req K-ALERT-001
*/
#define K_ALERT_DEFINE(name, alert_handler, max_num_pending_alerts) \
struct k_alert name \
@@ -3067,6 +3114,7 @@
* @param max_num_pending_alerts Maximum number of pending alerts.
*
* @return N/A
+ * @req K-ALERT-002
*/
extern void k_alert_init(struct k_alert *alert, k_alert_handler_t handler,
unsigned int max_num_pending_alerts);
@@ -3085,6 +3133,7 @@
* @retval 0 Alert received.
* @retval -EBUSY Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-ALERT-002
*/
__syscall int k_alert_recv(struct k_alert *alert, s32_t timeout);
@@ -3101,6 +3150,7 @@
* @param alert Address of the alert.
*
* @return N/A
+ * @req K-ALERT-002
*/
__syscall void k_alert_send(struct k_alert *alert);
@@ -3109,9 +3159,14 @@
*/
/**
- * @cond INTERNAL_HIDDEN
+ * @defgroup msgq_apis Message Queue APIs
+ * @ingroup kernel_apis
+ * @{
*/
+/**
+ * @brief Message Queue Structure
+ */
struct k_msgq {
_wait_q_t wait_q;
size_t msg_size;
@@ -3125,6 +3180,10 @@
_OBJECT_TRACING_NEXT_PTR(k_msgq);
u8_t flags;
};
+/**
+ * @cond INTERNAL_HIDDEN
+ */
+
#define _K_MSGQ_INITIALIZER(obj, q_buffer, q_msg_size, q_max_msgs) \
{ \
@@ -3138,26 +3197,23 @@
.used_msgs = 0, \
_OBJECT_TRACING_INIT \
}
-
#define K_MSGQ_INITIALIZER DEPRECATED_MACRO _K_MSGQ_INITIALIZER
+/**
+ * INTERNAL_HIDDEN @endcond
+ */
+
#define K_MSGQ_FLAG_ALLOC BIT(0)
+/**
+ * @brief Message Queue Attributes
+ */
struct k_msgq_attrs {
size_t msg_size;
u32_t max_msgs;
u32_t used_msgs;
};
-/**
- * INTERNAL_HIDDEN @endcond
- */
-
-/**
- * @defgroup msgq_apis Message Queue APIs
- * @ingroup kernel_apis
- * @{
- */
/**
* @brief Statically define and initialize a message queue.
@@ -3177,6 +3233,8 @@
* @param q_msg_size Message size (in bytes).
* @param q_max_msgs Maximum number of messages that can be queued.
* @param q_align Alignment of the message queue's ring buffer.
+ *
+ * @req K-MSGQ-001
*/
#define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align) \
static char __kernel_noinit __aligned(q_align) \
@@ -3203,6 +3261,7 @@
* @param max_msgs Maximum number of messages that can be queued.
*
* @return N/A
+ * @req K-MSGQ-002
*/
void k_msgq_init(struct k_msgq *q, char *buffer, size_t msg_size,
u32_t max_msgs);
@@ -3225,6 +3284,7 @@
* @return 0 on success, -ENOMEM if there was insufficient memory in the
* thread's resource pool, or -EINVAL if the size parameters cause
* an integer overflow.
+ * @req K-MSGQ-002
*/
__syscall int k_msgq_alloc_init(struct k_msgq *q, size_t msg_size,
u32_t max_msgs);
@@ -3247,6 +3307,7 @@
* @retval 0 Message sent.
* @retval -ENOMSG Returned without waiting or queue purged.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MSGQ-002
*/
__syscall int k_msgq_put(struct k_msgq *q, void *data, s32_t timeout);
@@ -3266,6 +3327,7 @@
* @retval 0 Message received.
* @retval -ENOMSG Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MSGQ-002
*/
__syscall int k_msgq_get(struct k_msgq *q, void *data, s32_t timeout);
@@ -3279,6 +3341,7 @@
* @param q Address of the message queue.
*
* @return N/A
+ * @req K-MSGQ-002
*/
__syscall void k_msgq_purge(struct k_msgq *q);
@@ -3291,6 +3354,7 @@
* @param q Address of the message queue.
*
* @return Number of unused ring buffer entries.
+ * @req K-MSGQ-002
*/
__syscall u32_t k_msgq_num_free_get(struct k_msgq *q);
@@ -3303,6 +3367,7 @@
* @param attrs pointer to message queue attribute structure.
*
* @return N/A
+ * @req K-MSGQ-003
*/
__syscall void k_msgq_get_attrs(struct k_msgq *q, struct k_msgq_attrs *attrs);
@@ -3320,6 +3385,7 @@
* @param q Address of the message queue.
*
* @return Number of messages.
+ * @req K-MSGQ-002
*/
__syscall u32_t k_msgq_num_used_get(struct k_msgq *q);
@@ -3385,16 +3451,15 @@
#endif
};
-/**
- * @cond INTERNAL_HIDDEN
- */
-
struct k_mbox {
_wait_q_t tx_msg_queue;
_wait_q_t rx_msg_queue;
_OBJECT_TRACING_NEXT_PTR(k_mbox);
};
+/**
+ * @cond INTERNAL_HIDDEN
+ */
#define _K_MBOX_INITIALIZER(obj) \
{ \
@@ -3417,6 +3482,7 @@
* @code extern struct k_mbox <name>; @endcode
*
* @param name Name of the mailbox.
+ * @req K-MBOX-001
*/
#define K_MBOX_DEFINE(name) \
struct k_mbox name \
@@ -3431,6 +3497,7 @@
* @param mbox Address of the mailbox.
*
* @return N/A
+ * @req K-MBOX-002
*/
extern void k_mbox_init(struct k_mbox *mbox);
@@ -3452,6 +3519,7 @@
* @retval 0 Message sent.
* @retval -ENOMSG Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MBOX-002
*/
extern int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
s32_t timeout);
@@ -3470,6 +3538,7 @@
* @param sem Address of a semaphore, or NULL if none is needed.
*
* @return N/A
+ * @req K-MBOX-002
*/
extern void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
struct k_sem *sem);
@@ -3491,6 +3560,7 @@
* @retval 0 Message received.
* @retval -ENOMSG Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MBOX-002
*/
extern int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg,
void *buffer, s32_t timeout);
@@ -3509,6 +3579,7 @@
* the data.
*
* @return N/A
+ * @req K-MBOX-002
*/
extern void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
@@ -3541,6 +3612,7 @@
* @retval 0 Data retrieved.
* @retval -ENOMEM Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MBOX-002
*/
extern int k_mbox_data_block_get(struct k_mbox_msg *rx_msg,
struct k_mem_pool *pool,
@@ -3605,6 +3677,8 @@
* @param pipe_buffer_size Size of the pipe's ring buffer (in bytes),
* or zero if no ring buffer is used.
* @param pipe_align Alignment of the pipe's ring buffer (power of 2).
+ *
+ * @req K-PIPE-001
*/
#define K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align) \
static unsigned char __kernel_noinit __aligned(pipe_align) \
@@ -3625,6 +3699,7 @@
* buffer is used.
*
* @return N/A
+ * @req K-PIPE-002
*/
void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size);
@@ -3636,6 +3711,7 @@
* if the buffer wasn't dynamically allocated.
*
* @param pipe Address of the pipe.
+ * @req K-PIPE-002
*/
void k_pipe_cleanup(struct k_pipe *pipe);
@@ -3653,6 +3729,7 @@
* buffer is used.
* @retval 0 on success
* @retval -ENOMEM if memory couldn't be allocated
+ * @req K-PIPE-002
*/
__syscall int k_pipe_alloc_init(struct k_pipe *pipe, size_t size);
@@ -3674,6 +3751,7 @@
* @retval -EIO Returned without waiting; zero data bytes were written.
* @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer
* minus one data bytes were written.
+ * @req K-PIPE-002
*/
__syscall int k_pipe_put(struct k_pipe *pipe, void *data,
size_t bytes_to_write, size_t *bytes_written,
@@ -3697,6 +3775,7 @@
* @retval -EIO Returned without waiting; zero data bytes were read.
* @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer
* minus one data bytes were read.
+ * @req K-PIPE-002
*/
__syscall int k_pipe_get(struct k_pipe *pipe, void *data,
size_t bytes_to_read, size_t *bytes_read,
@@ -3715,6 +3794,7 @@
* @param sem Semaphore to signal upon completion (else NULL)
*
* @return N/A
+ * @req K-PIPE-002
*/
extern void k_pipe_block_put(struct k_pipe *pipe, struct k_mem_block *block,
size_t size, struct k_sem *sem);
@@ -3779,6 +3859,7 @@
* @param slab_block_size Size of each memory block (in bytes).
* @param slab_num_blocks Number memory blocks.
* @param slab_align Alignment of the memory slab's buffer (power of 2).
+ * @req K-MSLAB-001
*/
#define K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align) \
char __noinit __aligned(slab_align) \
@@ -3805,6 +3886,7 @@
* @param num_blocks Number of memory blocks.
*
* @return N/A
+ * @req K-MSLAB-002
*/
extern void k_mem_slab_init(struct k_mem_slab *slab, void *buffer,
size_t block_size, u32_t num_blocks);
@@ -3824,6 +3906,7 @@
* is set to the starting address of the memory block.
* @retval -ENOMEM Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MSLAB-002
*/
extern int k_mem_slab_alloc(struct k_mem_slab *slab, void **mem,
s32_t timeout);
@@ -3838,6 +3921,7 @@
* @param mem Pointer to block address area (as set by k_mem_slab_alloc()).
*
* @return N/A
+ * @req K-MSLAB-002
*/
extern void k_mem_slab_free(struct k_mem_slab *slab, void **mem);
@@ -3850,6 +3934,7 @@
* @param slab Address of the memory slab.
*
* @return Number of allocated memory blocks.
+ * @req K-MSLAB-002
*/
static inline u32_t k_mem_slab_num_used_get(struct k_mem_slab *slab)
{
@@ -3865,6 +3950,7 @@
* @param slab Address of the memory slab.
*
* @return Number of unallocated memory blocks.
+ * @req K-MSLAB-002
*/
static inline u32_t k_mem_slab_num_free_get(struct k_mem_slab *slab)
{
@@ -3909,6 +3995,7 @@
* @param maxsz Size of the largest blocks in the pool (in bytes).
* @param nmax Number of maximum sized blocks in the pool.
* @param align Alignment of the pool's buffer (power of 2).
+ * @req K-MPOOL-001
*/
#define K_MEM_POOL_DEFINE(name, minsz, maxsz, nmax, align) \
char __aligned(align) _mpool_buf_##name[_ALIGN4(maxsz * nmax) \
@@ -3941,6 +4028,7 @@
* is set to the starting address of the memory block.
* @retval -ENOMEM Returned without waiting.
* @retval -EAGAIN Waiting period timed out.
+ * @req K-MPOOL-002
*/
extern int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block,
size_t size, s32_t timeout);
@@ -3953,6 +4041,7 @@
* @param pool Address of the memory pool.
* @param size Amount of memory to allocate (in bytes).
* @return Address of the allocated memory if successful, otherwise NULL
+ * @req K-MPOOL-002
*/
extern void *k_mem_pool_malloc(struct k_mem_pool *pool, size_t size);
@@ -3965,6 +4054,7 @@
* @param block Pointer to block descriptor for the allocated memory.
*
* @return N/A
+ * @req K-MPOOL-002
*/
extern void k_mem_pool_free(struct k_mem_block *block);
@@ -3977,6 +4067,7 @@
* @param id Memory block identifier.
*
* @return N/A
+ * @req K-MPOOL-002
*/
extern void k_mem_pool_free_id(struct k_mem_block_id *id);
@@ -3999,6 +4090,7 @@
* @param size Amount of memory requested (in bytes).
*
* @return Address of the allocated memory if successful; otherwise NULL.
+ * @req K-HEAP-001
*/
extern void *k_malloc(size_t size);
@@ -4014,6 +4106,7 @@
* @param ptr Pointer to previously allocated memory.
*
* @return N/A
+ * @req K-HEAP-001
*/
extern void k_free(void *ptr);
@@ -4027,6 +4120,7 @@
* @param size Size of each array element (in bytes).
*
* @return Address of the allocated memory if successful; otherwise NULL.
+ * @req K-HEAP-001
*/
extern void *k_calloc(size_t nmemb, size_t size);
@@ -4214,6 +4308,7 @@
* @param obj Kernel object or poll signal.
*
* @return N/A
+ * @req K-POLL-001
*/
extern void k_poll_event_init(struct k_poll_event *event, u32_t type,
@@ -4256,6 +4351,7 @@
* @retval -EINTR Poller thread has been interrupted.
* @retval -ENOMEM Thread resource pool insufficient memory (user mode only)
* @retval -EINVAL Bad parameters (user mode only)
+ * @req K-POLL-001
*/
__syscall int k_poll(struct k_poll_event *events, int num_events,
@@ -4269,6 +4365,7 @@
* @param signal A poll signal.
*
* @return N/A
+ * @req K-POLL-001
*/
__syscall void k_poll_signal_init(struct k_poll_signal *signal);
@@ -4277,6 +4374,7 @@
* @brief Reset a poll signal object's state to unsignaled.
*
* @param signal A poll signal object
+ * @req K-POLL-001
*/
__syscall void k_poll_signal_reset(struct k_poll_signal *signal);
@@ -4294,6 +4392,7 @@
* @param result An integer destination buffer which will be written with the
* result value if the object was signaled, or an undefined
* value if it was not.
+ * @req K-POLL-001
*/
__syscall void k_poll_signal_check(struct k_poll_signal *signal,
unsigned int *signaled, int *result);
@@ -4316,6 +4415,7 @@
*
* @retval 0 The signal was delivered successfully.
* @retval -EAGAIN The polling thread's timeout is in the process of expiring.
+ * @req K-POLL-001
*/
__syscall int k_poll_signal(struct k_poll_signal *signal, int result);
@@ -4338,6 +4438,7 @@
* the only thread would be responsible for this if needed.
*
* @return N/A
+ * @req K-MISC-001
*/
extern void k_cpu_idle(void);
@@ -4350,6 +4451,7 @@
* @param key Interrupt locking key obtained from irq_lock().
*
* @return N/A
+ * @req K-MISC-002
*/
extern void k_cpu_atomic_idle(unsigned int key);
@@ -4389,6 +4491,7 @@
*
* If this is called from ISR context, the default system fatal error handler
* will treat it as an unrecoverable system error, just like k_panic().
+ * @req K-MISC-003
*/
#define k_oops() _k_except_reason(_NANO_ERR_KERNEL_OOPS)
@@ -4399,6 +4502,7 @@
* unrecoverable runtime condition and needs to terminate. What this ultimately
* means is determined by the _fatal_error_handler() implementation, which
* will be called will reason code _NANO_ERR_KERNEL_PANIC.
+ * @req K-MISC-004
*/
#define k_panic() _k_except_reason(_NANO_ERR_KERNEL_PANIC)
@@ -4439,6 +4543,7 @@
* elsewhere into scope.
*
* @param sym Thread stack symbol name
+ * @req K-MISC-005
*/
#define K_THREAD_STACK_EXTERN(sym) extern k_thread_stack_t sym[]
@@ -4473,6 +4578,7 @@
*
* @param sym Thread stack symbol name
* @param size Size of the stack memory region
+ * @req K-TSTACK-001
*/
#define K_THREAD_STACK_DEFINE(sym, size) \
struct _k_thread_stack_element __noinit __aligned(STACK_ALIGN) sym[size]
@@ -4489,8 +4595,8 @@
* @param sym Thread stack symbol name
* @param nmemb Number of stacks to declare
* @param size Size of the stack memory region
+ * @req K-TSTACK-001
*/
-
#define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
struct _k_thread_stack_element __noinit \
__aligned(STACK_ALIGN) sym[nmemb][size]
@@ -4506,6 +4612,7 @@
*
* @param sym Thread stack symbol name
* @param size Size of the stack memory region
+ * @req K-TSTACK-001
*/
#define K_THREAD_STACK_MEMBER(sym, size) \
struct _k_thread_stack_element __aligned(STACK_ALIGN) sym[size]
@@ -4526,6 +4633,7 @@
*
* @param sym Stack memory symbol
* @return Size of the stack
+ * @req K-TSTACK-001
*/
#define K_THREAD_STACK_SIZEOF(sym) sizeof(sym)
@@ -4539,6 +4647,7 @@
*
* @param sym Declared stack symbol name
* @return The buffer itself, a char *
+ * @req K-TSTACK-001
*/
static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t *sym)
{
@@ -4553,8 +4662,10 @@
* @{
*/
-/** @def MEM_PARTITION_ENTRY
- * @brief Used to declare a memory partition entry
+/**
+ * @def MEM_PARTITION_ENTRY
+ * @brief Used to declare a memory partition entry
+ * @req K-MP-001
*/
#define MEM_PARTITION_ENTRY(_start, _size, _attr) \
{\
@@ -4563,8 +4674,10 @@
.attr = _attr, \
}
-/** @def K_MEM_PARTITION_DEFINE
- * @brief Used to declare a memory partition
+/**
+ * @def K_MEM_PARTITION_DEFINE
+ * @brief Used to declare a memory partition
+ * @req K-MP-001
*/
#ifdef _ARCH_MEM_PARTITION_ALIGN_CHECK
#define K_MEM_PARTITION_DEFINE(name, start, size, attr) \
@@ -4613,8 +4726,8 @@
* @param num_parts The number of array items of "parts" parameter.
* @param parts An array of pointers to the memory partitions. Can be NULL
* if num_parts is zero.
+ * @req K-MD-001
*/
-
extern void k_mem_domain_init(struct k_mem_domain *domain, u8_t num_parts,
struct k_mem_partition *parts[]);
/**
@@ -4623,8 +4736,8 @@
* Destroy a memory domain.
*
* @param domain The memory domain to be destroyed.
+ * @req K-MD-001
*/
-
extern void k_mem_domain_destroy(struct k_mem_domain *domain);
/**
@@ -4634,8 +4747,8 @@
*
* @param domain The memory domain to be added a memory partition.
* @param part The memory partition to be added
+ * @req K-MD-001
*/
-
extern void k_mem_domain_add_partition(struct k_mem_domain *domain,
struct k_mem_partition *part);
@@ -4646,8 +4759,8 @@
*
* @param domain The memory domain to be removed a memory partition.
* @param part The memory partition to be removed
+ * @req K-MD-001
*/
-
extern void k_mem_domain_remove_partition(struct k_mem_domain *domain,
struct k_mem_partition *part);
@@ -4658,8 +4771,9 @@
*
* @param domain The memory domain that the thread is going to be added into.
* @param thread ID of thread going to be added into the memory domain.
+ *
+ * @req K-MD-001
*/
-
extern void k_mem_domain_add_thread(struct k_mem_domain *domain,
k_tid_t thread);
@@ -4669,8 +4783,8 @@
* Remove a thread from its memory domain.
*
* @param thread ID of thread going to be removed from its memory domain.
+ * @req K-MD-001
*/
-
extern void k_mem_domain_remove_thread(k_tid_t thread);
/** @} */
@@ -4680,6 +4794,8 @@
*
* @param c String of characters to print
* @param n The length of the string
+ *
+ * @req K-MISC-006
*/
__syscall void k_str_out(char *c, size_t n);
