[Cbe-oss-dev] [PATCH 9/9]MARS: Update doxygen comments
Yuji Mano
yuji.mano at am.sony.com
Sat Oct 18 10:29:13 EST 2008
This updates the doxygen comments in headers for various changes in the API
and implementation.
Signed-off-by: Yuji Mano <yuji.mano at am.sony.com>
---
include/common/mars/mutex_types.h | 29 --
include/common/mars/task_barrier_types.h | 25 --
include/common/mars/task_event_flag_types.h | 27 --
include/common/mars/task_queue_types.h | 50 ----
include/common/mars/task_semaphore_types.h | 25 --
include/common/mars/task_types.h | 27 +-
include/host/mars/context.h | 38 +++
include/host/mars/mars.h | 3
include/host/mars/mutex.h | 12 -
include/host/mars/task.h | 127 +++--------
include/host/mars/task_barrier.h | 21 +
include/host/mars/task_event_flag.h | 106 +++++++++
include/host/mars/task_queue.h | 132 ++++++++++--
include/host/mars/task_semaphore.h | 20 +
include/host/mars/task_signal.h | 23 --
include/mpu/mars/mars.h | 3
include/mpu/mars/mutex.h | 12 -
include/mpu/mars/task.h | 90 ++++++--
include/mpu/mars/task_barrier.h | 57 ++++-
include/mpu/mars/task_event_flag.h | 82 +++++++
include/mpu/mars/task_queue.h | 303 ++++++++++++++++++++++++++--
include/mpu/mars/task_semaphore.h | 22 +-
include/mpu/mars/task_signal.h | 14 -
23 files changed, 886 insertions(+), 362 deletions(-)
--- a/include/common/mars/mutex_types.h
+++ b/include/common/mars/mutex_types.h
@@ -46,34 +46,11 @@
#include <stdint.h>
-/**
- * \ingroup group_mars_mutex
- * \brief Size of mutex structure
- */
+/* internal defines */
#define MARS_MUTEX_SIZE 128
-
-/**
- * \ingroup group_mars_mutex
- * \brief Alignment of mutex structure
- */
#define MARS_MUTEX_ALIGN 128
-
-/**
- * \ingroup group_mars_mutex
- * \brief Alignment mask of mutex structure
- */
#define MARS_MUTEX_ALIGN_MASK 0x7f
-
-/**
- * \ingroup group_mars_mutex
- * \brief Value of mutex lock variable in locked state
- */
#define MARS_MUTEX_LOCKED 0x1
-
-/**
- * \ingroup group_mars_mutex
- * \brief Value of mutex lock variable in unlocked state
- */
#define MARS_MUTEX_UNLOCKED 0x0
/**
@@ -81,10 +58,6 @@
* \brief MARS mutex structure
*
* An instance of this structure must be created when using the MARS Mutex API.
- *
- * If allocating a memory area for this structure, make sure to allocate
- * a memory area that is aligned to \ref MARS_MUTEX_ALIGN bytes
- * and of size \ref MARS_MUTEX_SIZE bytes.
*/
struct mars_mutex {
uint32_t lock;
--- a/include/common/mars/task_barrier_types.h
+++ b/include/common/mars/task_barrier_types.h
@@ -48,38 +48,21 @@
/**
* \ingroup group_mars_task_barrier
- * \brief Size of task barrier structure
+ * \brief Maximum tasks allowed for single barrier
*/
-#define MARS_TASK_BARRIER_SIZE 128
+#define MARS_TASK_BARRIER_WAIT_MAX 25
-/**
- * \ingroup group_mars_task_barrier
- * \brief Alignment of task barrier structure
- */
+/* internal defines */
+#define MARS_TASK_BARRIER_SIZE 128
#define MARS_TASK_BARRIER_ALIGN 128
-
-/**
- * \ingroup group_mars_task_barrier
- * \brief Alignment mask of task barrier structure
- */
#define MARS_TASK_BARRIER_ALIGN_MASK 0x7f
/**
* \ingroup group_mars_task_barrier
- * \brief Maximum tasks allowed for single barrier
- */
-#define MARS_TASK_BARRIER_WAIT_MAX 25
-
-/**
- * \ingroup group_mars_task_barrier
* \brief MARS task barrier structure
*
* An instance of this structure must be created when using any of the
* MARS task barrier API.
- *
- * If allocating a memory area for this structure, make sure to allocate
- * a memory area that is aligned to \ref MARS_TASK_BARRIER_ALIGN bytes
- * and of size \ref MARS_TASK_BARRIER_SIZE bytes.
*/
struct mars_task_barrier {
uint32_t lock;
--- a/include/common/mars/task_event_flag_types.h
+++ b/include/common/mars/task_event_flag_types.h
@@ -48,24 +48,6 @@
/**
* \ingroup group_mars_task_event_flag
- * \brief Size of task event flag structure
- */
-#define MARS_TASK_EVENT_FLAG_SIZE 128
-
-/**
- * \ingroup group_mars_task_event_flag
- * \brief Alignment of task event flag structure
- */
-#define MARS_TASK_EVENT_FLAG_ALIGN 128
-
-/**
- * \ingroup group_mars_task_event_flag
- * \brief Alignment mask of task event flag structure
- */
-#define MARS_TASK_EVENT_FLAG_ALIGN_MASK 0x7f
-
-/**
- * \ingroup group_mars_task_event_flag
* \brief Event flag direction from PPU to SPU
*/
#define MARS_TASK_EVENT_FLAG_HOST_TO_MPU 0x10
@@ -112,16 +94,17 @@
*/
#define MARS_TASK_EVENT_FLAG_WAIT_MAX 15
+/* internal defines */
+#define MARS_TASK_EVENT_FLAG_SIZE 128
+#define MARS_TASK_EVENT_FLAG_ALIGN 128
+#define MARS_TASK_EVENT_FLAG_ALIGN_MASK 0x7f
+
/**
* \ingroup group_mars_task_event_flag
* \brief MARS task event flag structure
*
* An instance of this structure must be created when using any of the
* MARS event flag API.
- *
- * If allocating a memory area for this structure, make sure to allocate
- * a memory area that is aligned to \ref MARS_TASK_EVENT_FLAG_ALIGN bytes
- * and of size \ref MARS_TASK_EVENT_FLAG_SIZE bytes.
*/
struct mars_task_event_flag {
uint32_t lock;
--- a/include/common/mars/task_queue_types.h
+++ b/include/common/mars/task_queue_types.h
@@ -48,24 +48,6 @@
/**
* \ingroup group_mars_task_queue
- * \brief Size of task queue structure
- */
-#define MARS_TASK_QUEUE_SIZE 128
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment of task queue structure
- */
-#define MARS_TASK_QUEUE_ALIGN 128
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment mask of task queue structure
- */
-#define MARS_TASK_QUEUE_ALIGN_MASK 0x7f
-
-/**
- * \ingroup group_mars_task_queue
* \brief Queue direction from PPU to SPU
*/
#define MARS_TASK_QUEUE_HOST_TO_MPU 0x10
@@ -94,34 +76,14 @@
*/
#define MARS_TASK_QUEUE_ENTRY_SIZE_MAX 16384
-/**
- * \ingroup group_mars_task_queue
- * \brief Mask for 16-byte alignment of queue entry size
- */
+/* internal defines */
+#define MARS_TASK_QUEUE_SIZE 128
+#define MARS_TASK_QUEUE_ALIGN 128
+#define MARS_TASK_QUEUE_ALIGN_MASK 0x7f
#define MARS_TASK_QUEUE_ENTRY_SIZE_MASK 0xf
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment of queue entry data
- */
#define MARS_TASK_QUEUE_ENTRY_ALIGN 16
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment mask of queue entry data
- */
#define MARS_TASK_QUEUE_ENTRY_ALIGN_MASK 0xf
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment of queue buffer
- */
#define MARS_TASK_QUEUE_BUFFER_ALIGN 16
-
-/**
- * \ingroup group_mars_task_queue
- * \brief Alignment mask of queue buffer
- */
#define MARS_TASK_QUEUE_BUFFER_ALIGN_MASK 0xf
/**
@@ -130,10 +92,6 @@
*
* An instance of this structure must be created when using any of the
* MARS queue API.
- *
- * If allocating a memory area for this structure, make sure to allocate
- * a memory area that is aligned to \ref MARS_TASK_QUEUE_ALIGN bytes
- * and of size \ref MARS_TASK_QUEUE_SIZE bytes.
*/
struct mars_task_queue {
uint32_t lock;
--- a/include/common/mars/task_semaphore_types.h
+++ b/include/common/mars/task_semaphore_types.h
@@ -48,38 +48,21 @@
/**
* \ingroup group_mars_task_semaphore
- * \brief Size of task semaphore structure
+ * \brief Maximum task accesses allowed for single semaphore
*/
-#define MARS_TASK_SEMAPHORE_SIZE 128
+#define MARS_TASK_SEMAPHORE_WAIT_MAX 55
-/**
- * \ingroup group_mars_task_semaphore
- * \brief Alignment of task semaphore structure
- */
+/* internal defines */
+#define MARS_TASK_SEMAPHORE_SIZE 128
#define MARS_TASK_SEMAPHORE_ALIGN 128
-
-/**
- * \ingroup group_mars_task_semaphore
- * \brief Alignment mask of task semaphore structure
- */
#define MARS_TASK_SEMAPHORE_ALIGN_MASK 0x7f
/**
* \ingroup group_mars_task_semaphore
- * \brief Maximum task accesses allowed for single semaphore
- */
-#define MARS_TASK_SEMAPHORE_WAIT_MAX 55
-
-/**
- * \ingroup group_mars_task_semaphore
* \brief MARS task semaphore structure
*
* An instance of this structure must be created when using any of the
* MARS semaphore API.
- *
- * If allocating a memory area for this structure, make sure to allocate
- * a memory area that is aligned to \ref MARS_TASK_SEMAPHORE_ALIGN bytes
- * and of size \ref MARS_TASK_SEMAPHORE_SIZE bytes.
*/
struct mars_task_semaphore {
uint32_t lock;
--- a/include/common/mars/task_types.h
+++ b/include/common/mars/task_types.h
@@ -54,6 +54,18 @@
/**
* \ingroup group_mars_task
+ * \brief Max size of context save area
+ */
+#define MARS_TASK_CONTEXT_SAVE_SIZE_MAX 0x30000
+
+/**
+ * \ingroup group_mars_task
+ * \brief Max number of context save units
+ */
+#define MARS_TASK_CONTEXT_SAVE_UNIT_MAX 16
+
+/**
+ * \ingroup group_mars_task
* \brief Parameter for full context switch
*/
#define MARS_TASK_CONTEXT_SAVE_ALL mars_task_context_save_all
@@ -72,8 +84,6 @@
#define MARS_TASK_CONTEXT_SIZE 128
#define MARS_TASK_CONTEXT_ALIGN 16
#define MARS_TASK_CONTEXT_SAVE_ALIGN 128
-#define MARS_TASK_CONTEXT_SAVE_SIZE_MAX 0x30000
-#define MARS_TASK_CONTEXT_SAVE_UNIT_MAX 16
#define MARS_TASK_CONTEXT_SAVE_UNIT_SIZE 8
#define MARS_TASK_CONTEXT_SAVE_UNIT_ALIGN 128
#define MARS_TASK_CONTEXT_SAVE_UNIT_ADDR_ALIGN_MASK 0xf
@@ -83,11 +93,11 @@
* \ingroup group_mars_task
* \brief MARS task id structure
*
- * This structure is initialized during MARS task initialization and returned
- * when calling \ref mars_task_initialize.
+ * This structure is initialized during MARS task creation and returned when
+ * calling \ref mars_task_create.
*
- * An instance of this structure must be kept until the task is finalized by
- * calling \ref mars_task_finalize.
+ * An instance of this structure must be kept until the task is destroyed by
+ * calling \ref mars_task_destroy.
*/
struct mars_task_id {
uint64_t mars_context_ea;
@@ -99,9 +109,8 @@ struct mars_task_id {
* \ingroup group_mars_task
* \brief MARS task argument structure
*
- * This structure is initialized by the user and within the
- * \ref mars_task_params structure which is passed into
- * \ref mars_task_initialize for MARS task initialization.
+ * This structure is initialized by the user and passed into
+ * \ref mars_task_schedule for MARS task scheduling.
*
* This argument structure is directly passed into the MARS
* task's \ref mars_task_main function at task execution.
--- a/include/host/mars/context.h
+++ b/include/host/mars/context.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_context
- * \brief [host] MARS Context API
+ * \brief <b>[host]</b> MARS Context API
*/
#include <stdint.h>
@@ -73,7 +73,7 @@ extern "C" {
/**
* \ingroup group_mars_context
- * \brief [host] Creates a single MARS context.
+ * \brief <b>[host]</b> Creates a single MARS context.
*
* This function creates a single MARS context. A MARS context must be
* created before any of the MARS functionality can be used. This will
@@ -81,6 +81,21 @@ extern "C" {
* The MARS kernel on each MPU will continue to run until the MARS context
* is destroyed through \ref mars_context_destroy.
*
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e num_mpus
+ * - Specify total number of MPUs to be used by the MARS context
+ * - If 0 is specified, MARS will use the maximum number of MPUs available in
+ * the system.
+ *
+ * \e shared
+ * - Specify 1 to share the context with other libraries linked into the
+ * application that also utilize MARS.
+ * - Specify 0 to create an independent MARS context that is not shared with
+ * other libraries linked into the application that also utilize MARS.
+ * - Sharing a single MARS context within an application with other libraries
+ * will maximize the MARS benefits of MPU utilization.
+ *
* \note If there are multiple MARS contexts created in the system, then
* each MARS context will suffer the large over head of MPU context switches.
*
@@ -98,7 +113,7 @@ int mars_context_create(struct mars_cont
/**
* \ingroup group_mars_context
- * \brief [host] Destroys a single MARS context.
+ * \brief <b>[host]</b> Destroys a single MARS context.
*
* This function destroys a single MARS context that was previously
* created by \ref mars_context_create. In order to successfully destroy
@@ -113,12 +128,27 @@ int mars_context_create(struct mars_cont
*/
int mars_context_destroy(struct mars_context *mars);
-
+/**
+ * \ingroup group_mars_context
+ * \brief <b>[host]</b> Converts a 64-bit address to pointer.
+ *
+ * \param[in] ea - 64-bit address
+ * \return
+ * void * - pointer value
+ */
static inline void *mars_ea_to_ptr(uint64_t ea)
{
return (void *)(uintptr_t)ea;
}
+/**
+ * \ingroup group_mars_context
+ * \brief <b>[host]</b> Converts a pointer to 64-bit address.
+ *
+ * \param[in] ptr - pointer value
+ * \return
+ * uint64_t - 64-bit address
+ */
static inline uint64_t mars_ptr_to_ea(const void *ptr)
{
return (uint64_t)(const uintptr_t)ptr;
--- a/include/host/mars/mars.h
+++ b/include/host/mars/mars.h
@@ -40,8 +40,7 @@
/**
* \file
- * \ingroup group_mars_context
- * \brief [host] MARS API
+ * \brief <b>[host]</b> MARS API
*/
#include <mars/context.h>
--- a/include/host/mars/mutex.h
+++ b/include/host/mars/mutex.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_mutex
- * \brief [host] MARS Mutex API
+ * \brief <b>[host]</b> MARS Mutex API
*/
#include <mars/mutex_types.h>
@@ -52,7 +52,7 @@ extern "C" {
/**
* \ingroup group_mars_mutex
- * \brief [host] Creates a mutex.
+ * \brief <b>[host]</b> Creates a mutex.
*
* This function creates a mutex instance that can be locked or unlocked
* from both host and MPU to restrict concurrent accesses.
@@ -67,7 +67,7 @@ int mars_mutex_create(struct mars_mutex
/**
* \ingroup group_mars_mutex
- * \brief [host] Destroys a mutex.
+ * \brief <b>[host]</b> Destroys a mutex.
*
* This function destroys a mutex instance.
*
@@ -81,7 +81,7 @@ int mars_mutex_destroy(struct mars_mutex
/**
* \ingroup group_mars_mutex
- * \brief [host] Resets a mutex.
+ * \brief <b>[host]</b> Resets a mutex.
*
* This function resets a mutex instance and forces it into an unlocked state
* regardless of whether it is locked or unlocked.
@@ -96,7 +96,7 @@ int mars_mutex_reset(struct mars_mutex *
/**
* \ingroup group_mars_mutex
- * \brief [host] Locks a mutex.
+ * \brief <b>[host]</b> Locks a mutex.
*
* This function locks a mutex and blocks other requests to lock it.
*
@@ -110,7 +110,7 @@ int mars_mutex_lock(struct mars_mutex *m
/**
* \ingroup group_mars_mutex
- * \brief [host] Unlocks a mutex.
+ * \brief <b>[host]</b> Unlocks a mutex.
*
* This function unlocks a previously locked mutex to allow other lock requests.
*
--- a/include/host/mars/task.h
+++ b/include/host/mars/task.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task
- * \brief [host] MARS Task API
+ * \brief <b>[host]</b> MARS Task API
*/
#include <mars/task_barrier.h>
@@ -51,14 +51,13 @@
#include <mars/task_signal.h>
#include <mars/task_types.h>
-
#if defined(__cplusplus)
extern "C" {
#endif
/**
* \ingroup group_mars_task
- * \brief [host] Creates a MARS task.
+ * \brief <b>[host]</b> Creates a MARS task.
*
* This function creates a single task and adds it the MARS context's
* workload queue.
@@ -68,45 +67,48 @@ extern "C" {
* The task is in the finished state upon creation and may be destroyed by
* \ref mars_task_destroy without ever being scheduled for execution.
*
- * When creating a MARS task, you must specify its parameters:
- * \n
- * - \e name: The name is optional, but if specified to other than NULL its
- * length must not exceed \ref MARS_TASK_NAME_LEN_MAX.
- * \n \n
- * - \e elf_image: The address of MPU program elf image in host storage that
- * will be to be run by this task.
+ * <b>Key Parameters</b>:
* \n \n
- * - \e save_units: A list of structures defining the areas of MPU storage to
- * save and restore during a task context switch.
+ * \e name
+ * - The name is optional, but if specified to other than NULL its
+ * length must not exceed \ref MARS_TASK_NAME_LEN_MAX.
+ *
+ * \e elf_image
+ * - The address of MPU program elf image in host storage that will be to be run
+ * by this task.
+ *
+ * \e save_units
+ * - A list of structures defining the areas of MPU storage to save and restore
+ * during a task context switch.
+ * - If NULL is specified, then no context save area will be allocated for
+ * the task and therefore the task must be a run-complete task.
+ * - A run-complete task will run and occupy an MPU until it has completed
+ * running and exits.
+ * - A run-complete task cannot context switch, and therefore cannot call
+ * functions that will enter that task into a wait state.
+ * - If \ref MARS_TASK_CONTEXT_SAVE_ALL is specified, the maximum size context
+ * save area will be allocated and all of the MPU storage not occuppied
+ * by the MARS kernel will be saved and restored.
+ * This will guarantee all necessary areas of the task context will be
+ * saved and restored during a context switch.
+ * However, this also may not be the most efficient, since areas of MPU
+ * storage not needed by the task may be saved and restored.
+ * - For maximum efficiency, the user should initialize a static list of
+ * struct \ref mars_task_context_save_unit that define each memory areas
+ * to save and restore during a task context switch.
+ * The user can specify as many save units as desired, but the
+ * responsibility of efficiency will be left up to the user.
+ * The last unit structure's 'size' member should be 0 to specify the end
+ * of the save unit list.
*
- * If NULL is specified, then no context save area will be allocated for
- * the task and therefore the task must be a run-complete task.
- * A run-complete task will run and occupy an MPU until it has completed
- * running and exits.
- * A run-complete task cannot context switch, and therefore cannot call
- * functions that will enter that task into a wait state.
- *
- * If MARS_TASK_CONTEXT_SAVE_ALL is specified, the maximum size context
- * save area will be allocated and all of the MPU storage not occuppied
- * by the MARS kernel will be saved and restored.
- * This will guarantee all necessary areas of the task context will be
- * saved and restored during a context switch.
- * However, this also may not be the most efficient, since areas of MPU
- * storage not needed by the task may be saved and restored.
- *
- * For maximum efficiency, the user should initialize a static list of
- * \ref struct mars_task_context_save_unit that define each memory areas
- * to save and restore during a task context switch.
- * The user can specify as many save units as desired, but the
- * responsibility of efficiency will be left up to the user.
- * The last unit structure's 'size' member should be 0 to specify the end
- * of the save unit list.
+ * \note The efficiency and validity of the specified context save unit
+ * list is left up to the responsibility of the user.
*
* \param[in] mars - pointer to MARS context
* \param[out] id - address of pointer to task id instance
* \param[in] name - name of task
* \param[in] elf_image - address of MPU program elf image
- * \param[in] context_save_unit - pointer to list of context save units
+ * \param[in] save_units - pointer to list of context save units
* \return
* MARS_SUCCESS - successfully created MARS task
* \n MARS_ERROR_NULL - null pointer specified
@@ -118,11 +120,11 @@ int mars_task_create(struct mars_context
struct mars_task_id *id,
const char *name,
const void *elf_image,
- const struct mars_task_context_save_unit *context_save_unit);
+ const struct mars_task_context_save_unit *save_units);
/**
* \ingroup group_mars_task
- * \brief [host] Destroys a MARS task.
+ * \brief <b>[host]</b> Destroys a MARS task.
*
* This function destroys a task created by \ref mars_task_create.
* The task will only be destroyed if the task is in the finished state.
@@ -143,68 +145,17 @@ int mars_task_destroy(struct mars_task_i
/**
* \ingroup group_mars_task
- * \brief [host] Schedules a MARS task for execution.
- *
- * This function schedules the task specified for execution.
- * The actual time of execution is determined by the scheduler.
- * Once the task is scheduled for execution by this function, it may not be
- * scheduled for execution until previous execution has finished.
- * You can wait for task completion by calling \ref mars_task_wait or
- * \ref mars_task_try_wait.
- *
- * - \e args: The task args (\ref mars_task_args) are optional, and only need
- * to be passed in if the task executable expects it. If you specify NULL
- * the task args passed into the task executable's main function will not
- * be initialized.
- * \n \n
- * - \e priority: This is the priority of the task between 0 to 255, 0 being
- * the lowest priority and 255 being the highest priority. Tasks with
- * higher priority will be prioritized during scheduling if both tasks are
- * ready to run at the time of scheduling.
- *
- * \param[out] id - pointer to task id instance
- * \param[in] args - pointer to task args to pass into task main
- * \param[in] priority - priority of scheduling for the task
- * \return
- * MARS_SUCCESS - successfully scheduled MARS task for execution
- * \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_PARAMS - bad task id specified
- * \n MARS_ERROR_STATE - task is in an invalid state
*/
int mars_task_schedule(struct mars_task_id *id, struct mars_task_args *args,
uint8_t priority);
/**
* \ingroup group_mars_task
- * \brief [host] Waits for task completion. (Blocking)
- *
- * This function will block until the scheduled task specified is finished.
- *
- * \param[in] id - pointer to task id instance
- * \param[in] exit_code - pointer to variable to store task exit code
- * \return
- * MARS_SUCCESS - task execution finished
- * \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_PARAMS - bad task id specified
- * \n MARS_ERROR_STATE - task is in an invalid state
*/
int mars_task_wait(struct mars_task_id *id, int32_t *exit_code);
/**
* \ingroup group_mars_task
- * \brief [host] Waits for a task completion. (Non-Blocking)
- *
- * This function will check whether the scheduled task specified is finished
- * or not and return immediately without blocking.
- *
- * \param[in] id - pointer to task id instance
- * \param[in] exit_code - pointer to variable to store task exit code
- * \return
- * MARS_SUCCESS - task execution finished
- * \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_PARAMS - bad task id specified
- * \n MARS_ERROR_STATE - task is in an invalid state
- * \n MARS_ERROR_BUSY - task has not yet finished execution
*/
int mars_task_try_wait(struct mars_task_id *id, int32_t *exit_code);
--- a/include/host/mars/task_barrier.h
+++ b/include/host/mars/task_barrier.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_barrier
- * \brief [host] MARS Task Barrier API
+ * \brief <b>[host]</b> MARS Task Barrier API
*/
#include <mars/task_barrier_types.h>
@@ -54,7 +54,19 @@ extern "C" {
/**
* \ingroup group_mars_task_barrier
- * \brief [host] Creates a task barrier.
+ * \brief <b>[host]</b> Creates a task barrier.
+ *
+ * This function will allocate an instance of the task barrier.
+ * The barrier allows for tasks within the barrier group to wait until all
+ * tasks arrive at some synchronization point and notify the barrier.
+ * All tasks included in the barrier group should call the notify and wait in
+ * pairs.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e total
+ * - Specify total number of tasks that will be associated with this barrier.
+ * - Total must be a value between 1 and \ref MARS_TASK_BARRIER_WAIT_MAX.
*
* \param[in] mars - pointer to MARS context
* \param[out] barrier - address of pointer to barrier instance
@@ -70,7 +82,10 @@ int mars_task_barrier_create(struct mars
/**
* \ingroup group_mars_task_barrier
- * \brief [host] Destroys a task barrier.
+ * \brief <b>[host]</b> Destroys a task barrier.
+ *
+ * This function will free any resources allocated during creation of the task
+ * barrier.
*
* \param[in] barrier - pointer to barrier instance
* \return
--- a/include/host/mars/task_event_flag.h
+++ b/include/host/mars/task_event_flag.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_event_flag
- * \brief [host] MARS Task Event Flag API
+ * \brief <b>[host]</b> MARS Task Event Flag API
*/
#include <mars/task_event_flag_types.h>
@@ -54,7 +54,28 @@ extern "C" {
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Creates a task event flag.
+ * \brief <b>[host]</b> Creates a task event flag.
+ *
+ * This function will allocate an instance of the task event flag.
+ * The event flag allows for tasks to wait on specific events.
+ * The event flag should be used in pairs with calls to set an event flag and
+ * wait for an event flag.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e direction
+ * - Specify the communication direction of the event flag.
+ * - Must be one of \ref MARS_TASK_EVENT_FLAG_HOST_TO_MPU,
+ * \ref MARS_TASK_EVENT_FLAG_MPU_TO_HOST, \ref MARS_TASK_EVENT_FLAG_MPU_TO_MPU.
+ *
+ * \e clear_mode
+ * - Specify when the event flag is cleared.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_CLEAR_AUTO to have event flag bits
+ * cleared automatically when a task waiting on the event flag bits has been
+ * notified of the event.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_CLEAR_MANUAL to have the event flag bits
+ * remain set until the user manually clears them through
+ * \ref mars_task_event_flag_clear.
*
* \param[in] mars - pointer to MARS context
* \param[out] event_flag - address of pointer to event flag instance
@@ -72,7 +93,10 @@ int mars_task_event_flag_create(struct m
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Destroys a task event flag.
+ * \brief <b>[host]</b> Destroys a task event flag.
+ *
+ * This function will free any resources allocated during creation of the task
+ * event flag.
*
* \param[in] event_flag - pointer to event flag instance
* \return
@@ -84,7 +108,15 @@ int mars_task_event_flag_destroy(struct
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Clears the bits specified in the task event flag.
+ * \brief <b>[host]</b> Clears the bits specified in the task event flag.
+ *
+ * This function will clear all bits currently set in the event flag.
+ * Tasks waiting on some events will remain in the waiting state.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e bits
+ * - Specify only the bits you want to be cleared from the event flag bits.
*
* \param[in] event_flag - pointer to event flag instance
* \param[in] bits - bits to clear
@@ -98,7 +130,18 @@ int mars_task_event_flag_clear(struct ma
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Sets the bits specified in the task event flag.
+ * \brief <b>[host]</b> Sets the bits specified in the task event flag.
+ *
+ * This function will set the bits specified. The bits are OR'd with bits
+ * already set in the event flag at the time of this call.
+ * If there are any tasks in the waiting state, and this call satisfies the
+ * release condition of those tasks, all those tasks will be returned to the
+ * ready state.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e bits
+ * - Specify only the bits you want to set in the event flag bits.
*
* \param[in] event_flag - pointer to event flag instance
* \param[in] bits - bits to set
@@ -113,7 +156,30 @@ int mars_task_event_flag_set(struct mars
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Waits on a task event flag. (Blocking)
+ * \brief <b>[host]</b> Waits on a task event flag.
+ *
+ * This call will block until the specified event flag condition is met.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e mask
+ * - Specify only the bits you want to test against in the event flag bits set.
+ * - Whether the test condition is satisfied or not will depend on \e mask_mode.
+ *
+ * \e mask_mode
+ * - Specify how to test the mask bits against the event flag bits set.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_OR (\e mask | event flag bits), so
+ * the condition is satisfied if any bits specified in \e mask is set in the
+ * event flag bits.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_AND (\e mask & event flag bits) so
+ * the condition is satisfied if all bits specified in \e mask are set in the
+ * event flag bits.
+ *
+ * \e bits
+ * - Specify a pointer to a variable where the event flag bits can be returned.
+ * - The resulting bits will be the state of bits in the event flag prior to any
+ * automatic clearing of bits (if \ref MARS_TASK_EVENT_FLAG_CLEAR_AUTO was
+ * specified at creation).
*
* \param[in] event_flag - pointer to event flag instance
* \param[in] mask - bit mask to test event flag bits against
@@ -125,7 +191,6 @@ int mars_task_event_flag_set(struct mars
* \n MARS_ERROR_ALIGN - instance not aligned properly
* \n MARS_ERROR_PARAMS - invalid mask mode
* \n MARS_ERROR_STATE - invalid direction
- * \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
*/
int mars_task_event_flag_wait(struct mars_task_event_flag *event_flag,
uint32_t mask, uint8_t mask_mode,
@@ -133,7 +198,32 @@ int mars_task_event_flag_wait(struct mar
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Waits on a task event flag. (Non-Blocking)
+ * \brief <b>[host]</b> Waits on a task event flag.
+ *
+ * This call will test to see if the specified event flag condition is met
+ * without blocking and returns immediately with \ref MARS_ERROR_BUSY if it did
+ * not.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e mask
+ * - Specify only the bits you want to test against in the event flag bits set.
+ * - Whether the test condition is satisfied or not will depend on \e mask_mode.
+ *
+ * \e mask_mode
+ * - Specify how to test the mask bits against the event flag bits set.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_OR (\e mask | event flag bits), so
+ * the condition is satisfied if any bits specified in \e mask is set in the
+ * event flag bits.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_AND (\e mask & event flag bits) so
+ * the condition is satisfied if all bits specified in \e mask are set in the
+ * event flag bits.
+ *
+ * \e bits
+ * - Specify a pointer to a variable where the event flag bits can be returned.
+ * - The resulting bits will be the state of bits in the event flag prior to any
+ * automatic clearing of bits (if \ref MARS_TASK_EVENT_FLAG_CLEAR_AUTO was
+ * specified at creation).
*
* \param[in] event_flag - pointer to event flag instance
* \param[in] mask - bit mask to test event flag bits against
--- a/include/host/mars/task_queue.h
+++ b/include/host/mars/task_queue.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_queue
- * \brief [host] MARS Task Queue Flag API
+ * \brief <b>[host]</b> MARS Task Queue Flag API
*/
#include <mars/task_queue_types.h>
@@ -54,11 +54,35 @@ extern "C" {
/**
* \ingroup group_mars_task_queue
- * \brief [host] Creates a task queue.
+ * \brief <b>[host]</b> Creates a task queue.
+ *
+ * This function will allocate an instance of the task queue.
+ * The queue allows for tasks to wait until data is available from a FIFO
+ * data queue.
+ * The queue should be used in pairs with various calls to push and pop the
+ * the queue
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e size
+ * - Specify the size of each data item in the queue.
+ * - The size needs to be a multiple of 16 bytes and no larger than
+ * \ref MARS_TASK_QUEUE_ENTRY_SIZE_MAX.
+ *
+ * \e depth
+ * - Specify the depth of the total queue.
+ * - The number specified here is the total number of data items the queue
+ * can hold at a time.
+ * - The size of the total queue is \e size * \e depth.
+ *
+ * \e direction
+ * - Specify the communication direction of the queue.
+ * - Must be one of \ref MARS_TASK_EVENT_FLAG_HOST_TO_MPU,
+ * \ref MARS_TASK_EVENT_FLAG_MPU_TO_HOST, \ref MARS_TASK_EVENT_FLAG_MPU_TO_MPU.
*
* \param[in] mars - pointer to MARS context
* \param[out] queue - address of pointer to queue instance
- * \param[in] size - size of each data entry in data buffer
+ * \param[in] size - size of each data item in data buffer
* \param[in] depth - maximum number of data entries in data buffer
* \param[in] direction - direction of the event flag
* \return
@@ -77,7 +101,10 @@ int mars_task_queue_create(struct mars_c
/**
* \ingroup group_mars_task_queue
- * \brief [host] Destroys a task queue.
+ * \brief <b>[host]</b> Destroys a task queue.
+ *
+ * This function will free any resources allocated during creation of the task
+ * queue.
*
* \param[in] queue - pointer to queue instance
* \return
@@ -89,7 +116,10 @@ int mars_task_queue_destroy(struct mars_
/**
* \ingroup group_mars_task_queue
- * \brief [host] Returns the number of items in the task queue.
+ * \brief <b>[host]</b> Returns the number of data items in the task queue.
+ *
+ * This function will return the total number of data items in the queue at the
+ * time of the call.
*
* \param[in] queue - pointer to queue instance
* \param[out] count - pointer to variable to store return count
@@ -102,7 +132,11 @@ int mars_task_queue_count(struct mars_ta
/**
* \ingroup group_mars_task_queue
- * \brief [host] Clears the items in the task queue.
+ * \brief <b>[host]</b> Clears the data items in the task queue.
+ *
+ * This function will clear all data items currently in the queue.
+ * Tasks waiting to pop data from the queue will remain waiting.
+ * Tasks waiting to push data into the queue will resume.
*
* \param[in] queue - pointer to queue instance
* \return
@@ -114,7 +148,19 @@ int mars_task_queue_clear(struct mars_ta
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pushes the data specified into the task queue. (Blocking)
+ * \brief <b>[host]</b> Pushes the data specified into the task queue.
+ *
+ * This function will push the data specified into the queue.
+ * The task waiting longest to pop data from the queue can resume.
+ *
+ * If the queue is full at the time of this call, this function will block until
+ * there is room in the queue to push the data.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
*
* \param[in] queue - pointer to queue instance
* \param[in] data - address of data to be pushed into queue
@@ -128,7 +174,19 @@ int mars_task_queue_push(struct mars_tas
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pushes the data specified into the task queue. (Non-Blocking)
+ * \brief <b>[host]</b> Pushes the data specified into the task queue.
+ *
+ * This function will push the data specified into the queue.
+ * The task waiting longest to pop data from the queue can resume.
+ *
+ * If the queue is full at the time of this call, this function will not block
+ * and returns immediately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
*
* \param[in] queue - pointer to queue instance
* \param[in] data - address of data to be pushed into queue
@@ -143,7 +201,19 @@ int mars_task_queue_try_push(struct mars
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pops data from a task queue. (Blocking)
+ * \brief <b>[host]</b> Pops data from a task queue.
+ *
+ * This function will pop data from the queue.
+ *
+ * If the queue is empty at the time of this call, this function will block
+ * until there is data to be popped from the queue.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
@@ -157,7 +227,19 @@ int mars_task_queue_pop(struct mars_task
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pops data from a task queue. (Non-Blocking)
+ * \brief <b>[host]</b> Pops data from a task queue.
+ *
+ * This function will pop data from the queue.
+ *
+ * If the queue is empty at the time of this call, this function will not block
+ * and returns immediately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
@@ -172,7 +254,20 @@ int mars_task_queue_try_pop(struct mars_
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pops data from a task queue without removing it. (Blocking)
+ * \brief <b>[host]</b> Pops data from a task queue without removing it.
+ *
+ * This function will retrieve data from the queue without removing it from the
+ * queue.
+ *
+ * If the queue is empty at the time of this call, this function will block
+ * until there is data to be retrieved from the queue.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
@@ -180,14 +275,25 @@ int mars_task_queue_try_pop(struct mars_
* MARS_SUCCESS - successfully received event
* \n MARS_ERROR_NULL - null pointer specified
* \n MARS_ERROR_ALIGN - instance not aligned properly
- * \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
*/
int mars_task_queue_peek(struct mars_task_queue *queue, void *data);
/**
* \ingroup group_mars_task_queue
- * \brief [host] Pops data from a task queue without removing it. (Non-Blocking)
+ * \brief <b>[host]</b> Pops data from a task queue without removing it.
+ *
+ * This function will retrieve data from the queue.
+ *
+ * If the queue is empty at the time of this call, this function will not block
+ * and returns immediately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
--- a/include/host/mars/task_semaphore.h
+++ b/include/host/mars/task_semaphore.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_semaphore
- * \brief [host] MARS Task Semaphore API
+ * \brief <b>[host]</b> MARS Task Semaphore API
*/
#include <mars/task_semaphore_types.h>
@@ -54,7 +54,18 @@ extern "C" {
/**
* \ingroup group_mars_task_semaphore
- * \brief [host] Creates a task semaphore.
+ * \brief <b>[host]</b> Creates a task semaphore.
+ *
+ * This function will allocate an instance of the task semaphore.
+ * The semaphore allows for tasks to wait until a semaphore can be obtained.
+ * The semaphore should be used in pairs with calls to acquire and release.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e count
+ * - Specify the total number of entities that can have access to the semaphore
+ * simultaneously.
+ * - Must not be greater than \ref MARS_TASK_SEMAPHORE_WAIT_MAX.
*
* \param[in] mars - pointer to MARS context
* \param[out] semaphore - address of pointer to semaphore instance
@@ -70,7 +81,10 @@ int mars_task_semaphore_create(struct ma
/**
* \ingroup group_mars_task_semaphore
- * \brief [host] Destroys a task semaphore.
+ * \brief <b>[host]</b> Destroys a task semaphore.
+ *
+ * This function will free any resources allocated during creation of the task
+ * semaphore.
*
* \param[in] semaphore - pointer to semaphore instance
* \return
--- a/include/host/mars/task_signal.h
+++ b/include/host/mars/task_signal.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_signal
- * \brief [host] MARS Task Signal API
+ * \brief <b>[host]</b> MARS Task Signal API
*/
#include <mars/task_types.h>
@@ -51,26 +51,7 @@ extern "C" {
#endif
/**
- * \ingroup group_mars_task_signal
- * \brief [host] Sends a signal to the specified task.
- *
- * This function sends a signal to the task specified.
- * If the task had previously called \ref mars_task_signal_wait and was in the
- * waiting state, this function will cause that task to switch to a ready state
- * and scheduled to run accordingly.
- * If the task has not yet called \ref mars_task_signal_wait, the task's signal
- * buffer will be set and the same order of events will occur as previously
- * explained once \ref mars_task_signal_wait is called.
- * The task signal buffer depth is 1.
- * Therefore if the signal buffer is already set when a another signal is
- * received, it has no effect.
- *
- * \param[in] id - pointer to task id to signal
- * \return
- * MARS_SUCCESS - successfully signaled specified MARS task
- * \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_PARAMS - bad task id specified
- * \n MARS_ERROR_STATE - task is in an invalid state
+ * \ingroup group_mars_task
*/
int mars_task_signal_send(struct mars_task_id *id);
--- a/include/mpu/mars/mars.h
+++ b/include/mpu/mars/mars.h
@@ -40,8 +40,7 @@
/**
* \file
- * \ingroup group_mars_context
- * \brief [MPU] MARS API
+ * \brief <b>[MPU]</b> MARS API
*/
#include <mars/error.h>
--- a/include/mpu/mars/mutex.h
+++ b/include/mpu/mars/mutex.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_mutex
- * \brief [MPU] MARS Mutex API
+ * \brief <b>[MPU]</b> MARS Mutex API
*/
#include <mars/mutex_types.h>
@@ -52,7 +52,7 @@ extern "C" {
/**
* \ingroup group_mars_mutex
- * \brief [MPU] Locks a mutex.
+ * \brief <b>[MPU]</b> Locks a mutex.
*
* This function locks a mutex and blocks other requests to lock it.
*
@@ -66,7 +66,7 @@ int mars_mutex_lock(uint64_t mutex_ea);
/**
* \ingroup group_mars_mutex
- * \brief [MPU] Unlocks a mutex.
+ * \brief <b>[MPU]</b> Unlocks a mutex.
*
* This function unlocks a previously locked mutex to allow other lock requests.
*
@@ -81,7 +81,7 @@ int mars_mutex_unlock(uint64_t mutex_ea)
/**
* \ingroup group_mars_mutex
- * \brief [MPU] Locks a mutex.
+ * \brief <b>[MPU]</b> Locks a mutex.
*
* This function locks a mutex and blocks other requests to lock it.
* It also loads the mutex instance from the effective address specified
@@ -98,10 +98,10 @@ int mars_mutex_lock_get(uint64_t mutex_e
/**
* \ingroup group_mars_mutex
- * \brief [MPU] Unlocks a mutex.
+ * \brief <b>[MPU]</b> Unlocks a mutex.
*
* This function unlocks a previously locked mutex to allow other lock requests.
- * It also loads the local mutex instance into the effective address specified.
+ * It also stores the local mutex instance into the effective address specified.
*
* \param[in] mutex_ea - ea of mutex instance to unlock
* \param[in] mutex - pointer to local mutex instance
--- a/include/mpu/mars/task.h
+++ b/include/mpu/mars/task.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task
- * \brief [MPU] MARS Task API
+ * \brief <b>[MPU]</b> MARS Task API
*/
#include <mars/task_barrier.h>
@@ -57,12 +57,15 @@ extern "C" {
/**
* \ingroup group_mars_task
- * \brief [MPU] Entry point for task.
+ * \brief <b>[MPU]</b> Entry point for task.
*
* This function is the main entry point for the task program. All task
* programs will need to have a definition of this function. The arguments
- * passed into this function are specified during task initialization through
- * the call to \ref mars_task_initialize.
+ * passed into this function are specified during task scheduling through
+ * the call to \ref mars_task_schedule.
+ *
+ * \note If NULL was specified for \e args when calling \ref mars_task_schedule,
+ * the contents of args are undefined.
*
* \param[in] args - pointer to task args structure in MPU storage
* \return
@@ -72,20 +75,34 @@ int mars_task_main(const struct mars_tas
/**
* \ingroup group_mars_task
- * \brief [MPU] Exits and terminates task.
+ * \brief <b>[MPU]</b> Exits and terminates task.
*
* This function causes the task to exit and terminate execution. Calling this
* function will cause the task to enter the finished state, and will no
* longer be scheduled to run. This function does not need to be called when
* returning from \ref mars_task_main since it is called automatically.
*
+ * \note This function is a scheduling call and will put the caller task into a
+ * finished state.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e exit_code
+ * - The value passed into here can be obtained when calling \ref mars_task_wait
+ * or \ref mars_task_try_wait.
+ *
* \param[in] exit_code - value to be returned to the task wait call
*/
void mars_task_exit(int32_t exit_code);
/**
* \ingroup group_mars_task
- * \brief [MPU] Yields caller task so other workloads can run.
+ * \brief <b>[MPU]</b> Yields caller task so other workloads can run.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
*
* This function causes the task to yield and allow other tasks to be
* scheduled to run if available. If other tasks are available to be scheduled
@@ -94,6 +111,9 @@ void mars_task_exit(int32_t exit_code);
* the time of this function call, then this function has no effect and will
* return immediately.
*
+ * \note This function is a scheduling call and may cause a task switch and put
+ * the caller task into a waiting state.
+ *
* \return
* MARS_SUCCESS - successfully yielded task
* \n MARS_ERROR_FORMAT - no context save area specified
@@ -102,7 +122,7 @@ int mars_task_yield(void);
/**
* \ingroup group_mars_task
- * \brief [MPU] Schedules a MARS task for execution.
+ * \brief <b>[host/MPU]</b> Schedules a MARS task for execution.
*
* This function schedules the task specified for execution.
* The actual time of execution is determined by the scheduler.
@@ -111,19 +131,23 @@ int mars_task_yield(void);
* You can wait for task completion by calling \ref mars_task_wait or
* \ref mars_task_try_wait.
*
- * - \e args: The task args (\ref mars_task_args) are optional, and only need
- * to be passed in if the task executable expects it. If you specify NULL
- * the task args passed into the task executable's main function will not
- * be initialized.
+ * <b>Key Parameters</b>:
* \n \n
- * - \e priority: This is the priority of the task between 0 to 255, 0 being
- * the lowest priority and 255 being the highest priority. Tasks with
- * higher priority will be prioritized during scheduling if both tasks are
- * ready to run at the time of scheduling.
+ * \e args
+ * - The task args (\ref mars_task_args) are optional, and only
+ * need to be passed in if the task executable expects it.
+ * - If NULL is specified the task args passed into the task executable's main
+ * function will not be initialized.
+ *
+ * \e priority
+ * - This is the priority of the task between 0 to 255, 0 being the lowest
+ * priority and 255 being the highest priority.
+ * - Tasks with higher priority will be prioritized during scheduling if both
+ * tasks are ready to run at the time of scheduling.
*
- * \param[out] id - pointer to task id to schedule
+ * \param[in] id - pointer to task id to schedule
* \param[in] args - pointer to task args to pass into task main
- * \param[in] priority - priority of scheduling for the task
+ * \param[out] priority - priority of scheduling for the task
* \return
* MARS_SUCCESS - successfully scheduled MARS task for execution
* \n MARS_ERROR_NULL - null pointer specified
@@ -135,10 +159,25 @@ int mars_task_schedule(struct mars_task_
/**
* \ingroup group_mars_task
- * \brief [MPU] Waits for task completion. (Blocking)
+ * \brief <b>[host/MPU]</b> Waits for task completion.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
*
* This function will block until the scheduled task specified is finished.
*
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e exit_code
+ * - Pass in a pointer to store the task exit code.
+ * - If NULL is specified, no exit code can be obtained when the task
+ * completes and returns.
+ *
+ * \note This function is a scheduling call and may cause a task switch and put
+ * the caller task into a waiting state.
+ *
* \param[in] id - pointer to task id to wait for
* \param[in] exit_code - pointer to variable to store task exit code
* \return
@@ -152,11 +191,18 @@ int mars_task_wait(struct mars_task_id *
/**
* \ingroup group_mars_task
- * \brief [MPU] Waits for a task completion. (Non-Blocking)
+ * \brief <b>[host/MPU]</b> Waits for a task completion.
*
* This function will check whether the scheduled task specified is finished
* or not and return immediately without blocking.
*
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e exit_code
+ * - Pass in a pointer to store the task exit code.
+ * - If NULL is specified, no exit code can be obtained when the task
+ * completes and returns.
+ *
* \param[in] id - pointer to task id to wait for
* \param[in] exit_code - pointer to variable to store task exit code
* \return
@@ -170,7 +216,7 @@ int mars_task_try_wait(struct mars_task_
/**
* \ingroup group_mars_task
- * \brief [MPU] Gets id of kernel that task is currently being executed on.
+ * \brief <b>[MPU]</b> Gets id of kernel that the task is being executed on.
*
* \return
* id of MARS kernel [0 to number of MPUS used by MARS context]
@@ -179,7 +225,7 @@ uint32_t mars_task_get_kernel_id(void);
/**
* \ingroup group_mars_task
- * \brief [MPU] Gets id of caller task.
+ * \brief <b>[MPU]</b> Gets id of caller task.
*
* \return
* pointer to task id in MPU storage
@@ -188,7 +234,7 @@ const struct mars_task_id *mars_task_get
/**
* \ingroup group_mars_task
- * \brief [MPU] Gets name of caller task.
+ * \brief <b>[MPU]</b> Gets name of caller task.
*
* \return
* pointer to task name in MPU storage
--- a/include/mpu/mars/task_barrier.h
+++ b/include/mpu/mars/task_barrier.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_barrier
- * \brief [MPU] MARS Task Barrier API
+ * \brief <b>[MPU]</b> MARS Task Barrier API
*/
#include <mars/task_barrier_types.h>
@@ -52,7 +52,21 @@ extern "C" {
/**
* \ingroup group_mars_task_barrier
- * \brief [MPU] Notifies a task barrier. (Blocking)
+ * \brief <b>[MPU]</b> Notifies a task barrier.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function notifies the barrier that the caller task has reached the
+ * synchronization point. Once a task reaches the synchronization point and
+ * notifies the barrier, it may handle other processing before calling the
+ * required \ref mars_task_barrier_wait.
+ *
+ * If all tasks from the previous barrier cycle have not reached the
+ * synchronization point and notified the barrier yet, the caller task will
+ * enter a waiting state until the previous barrier cycle is released.
*
* \param[in] barrier_ea - ea of initialized barrier instance
* \return
@@ -66,7 +80,16 @@ int mars_task_barrier_notify(uint64_t ba
/**
* \ingroup group_mars_task_barrier
- * \brief [MPU] Notifies a task barrier. (Non-Blocking)
+ * \brief <b>[MPU]</b> Notifies a task barrier.
+ *
+ * This function notifies the barrier that the caller task has reached the
+ * synchronization point. Once a task reaches the synchronization point and
+ * notifies the barrier, it may handle other processing before calling the
+ * required \ref mars_task_barrier_wait.
+ *
+ * If all tasks from the previous barrier cycle have not reached the
+ * synchronization point and notified the barrier yet, this function will
+ * return immediately with \ref MARS_ERROR_BUSY.
*
* \param[in] barrier_ea - ea of initialized barrier instance
* \return
@@ -79,7 +102,22 @@ int mars_task_barrier_try_notify(uint64_
/**
* \ingroup group_mars_task_barrier
- * \brief [MPU] Waits on a task barrier. (Blocking)
+ * \brief <b>[MPU]</b> Waits on a task barrier.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function should be called after the caller task has previously called
+ * \ref mars_task_barrier_notify. This function should be called when the task
+ * that reached the synchronization point is ready to wait for others to arrive
+ * at the synchronization point.
+ *
+ * If not all tasks associated with the barrier have reached the synchronization
+ * point and notified the barrier at the time of this call, the caller task will
+ * enter a waiting state until all notifications are received from the other
+ * tasks and the barrier is released.
*
* \param[in] barrier_ea - ea of initialized barrier instance
* \return
@@ -93,7 +131,16 @@ int mars_task_barrier_wait(uint64_t barr
/**
* \ingroup group_mars_task_barrier
- * \brief [MPU] Waits on a task barrier. (Non-Blocking)
+ * \brief <b>[MPU]</b> Waits on a task barrier.
+ *
+ * This function should be called after the caller task has previously called
+ * \ref mars_task_barrier_notify. This function should be called when the task
+ * that reached the synchronization point is ready to wait for others to arrive
+ * at the synchronization point.
+ *
+ * If not all tasks associated with the barrier have reached the synchronization
+ * point and notified the barrier at the time of this call, this function will
+ * return immediately with \ref MARS_ERROR_BUSY.
*
* \param[in] barrier_ea - ea of initialized barrier instance
* \return
--- a/include/mpu/mars/task_event_flag.h
+++ b/include/mpu/mars/task_event_flag.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_event_flag
- * \brief [MPU] MARS Task Event Flag API
+ * \brief <b>[MPU]</b> MARS Task Event Flag API
*/
#include <mars/task_event_flag_types.h>
@@ -52,7 +52,15 @@ extern "C" {
/**
* \ingroup group_mars_task_event_flag
- * \brief [MPU] Clears the bits specified in the task event flag.
+ * \brief <b>[MPU]</b> Clears the bits specified in the task event flag.
+ *
+ * This function will clear all bits currently set in the event flag.
+ * Tasks waiting on some events will remain in the waiting state.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e bits
+ * - Specify only the bits you want to be cleared from the event flag bits.
*
* \param[in] event_flag_ea - ea of initialized event flag instance
* \param[in] bits - bits to clear
@@ -65,7 +73,18 @@ int mars_task_event_flag_clear(uint64_t
/**
* \ingroup group_mars_task_event_flag
- * \brief [MPU] Sets the bits specified in the task event flag.
+ * \brief <b>[MPU]</b> Sets the bits specified in the task event flag.
+ *
+ * This function will set the bits specified. The bits are OR'd with bits
+ * already set in the event flag at the time of this call.
+ * If there are any tasks in the waiting state, and this call satisfies the
+ * release condition of those tasks, all those tasks will be returned to the
+ * ready state.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e bits
+ * - Specify only the bits you want to set in the event flag bits.
*
* \param[in] event_flag_ea - ea of initialized event flag instance
* \param[in] bits - bits to set
@@ -79,7 +98,36 @@ int mars_task_event_flag_set(uint64_t ev
/**
* \ingroup group_mars_task_event_flag
- * \brief [MPU] Waits on a task event flag. (Blocking)
+ * \brief <b>[MPU]</b> Waits on a task event flag.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This call will put the task into a waiting state until the specified event
+ * flag condition is met.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e mask
+ * - Specify only the bits you want to test against in the event flag bits set.
+ * - Whether the test condition is satisfied or not will depend on \e mask_mode.
+ *
+ * \e mask_mode
+ * - Specify how to test the mask bits against the event flag bits set.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_OR (\e mask | event flag bits), so
+ * the condition is satisfied if any bits specified in \e mask is set in the
+ * event flag bits.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_AND (\e mask & event flag bits) so
+ * the condition is satisfied if all bits specified in \e mask are set in the
+ * event flag bits.
+ *
+ * \e bits
+ * - Specify a pointer to a variable where the event flag bits can be returned.
+ * - The resulting bits will be the state of bits in the event flag prior to any
+ * automatic clearing of bits (if \ref MARS_TASK_EVENT_FLAG_CLEAR_AUTO was
+ * specified at creation).
*
* \param[in] event_flag_ea - ea of initialized event flag instance
* \param[in] mask - bit mask to test event flag bits against
@@ -100,7 +148,31 @@ int mars_task_event_flag_wait(uint64_t e
/**
* \ingroup group_mars_task_event_flag
- * \brief [MPU] Waits on a task event flag. (Non-Blocking)
+ * \brief <b>[MPU]</b> Waits on a task event flag.
+ *
+ * This call will test to see if the specified event flag condition is met
+ * returns immediately with \ref MARS_ERROR_BUSY if it did not.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e mask
+ * - Specify only the bits you want to test against in the event flag bits set.
+ * - Whether the test condition is satisfied or not will depend on \e mask_mode.
+ *
+ * \e mask_mode
+ * - Specify how to test the mask bits against the event flag bits set.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_OR (\e mask | event flag bits), so
+ * the condition is satisfied if any bits specified in \e mask is set in the
+ * event flag bits.
+ * - Specify \ref MARS_TASK_EVENT_FLAG_MASK_AND (\e mask & event flag bits) so
+ * the condition is satisfied if all bits specified in \e mask are set in the
+ * event flag bits.
+ *
+ * \e bits
+ * - Specify a pointer to a variable where the event flag bits can be returned.
+ * - The resulting bits will be the state of bits in the event flag prior to any
+ * automatic clearing of bits (if \ref MARS_TASK_EVENT_FLAG_CLEAR_AUTO was
+ * specified at creation).
*
* \param[in] event_flag_ea - ea of initialized event flag instance
* \param[in] mask - bit mask to test event flag bits against
--- a/include/mpu/mars/task_queue.h
+++ b/include/mpu/mars/task_queue.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_queue
- * \brief [MPU] MARS Task Queue API
+ * \brief <b>[MPU]</b> MARS Task Queue API
*/
#include <mars/task_queue_types.h>
@@ -52,7 +52,10 @@ extern "C" {
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Returns the number of items in the task queue.
+ * \brief <b>[MPU]</b> Returns the number of data items in the task queue.
+ *
+ * This function will return the total number of data items in the queue at the
+ * time of the call.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[out] count - pointer to variable to store return count
@@ -65,7 +68,11 @@ int mars_task_queue_count(uint64_t queue
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Clears the items in the task queue.
+ * \brief <b>[MPU]</b> Clears the data items in the task queue.
+ *
+ * This function will clear all data items currently in the queue.
+ * Entities waiting to pop data from the queue will remain waiting.
+ * Entities waiting to push data into the queue will resume.
*
* \param[in] queue_ea - ea of initialized queue instance
* \return
@@ -77,7 +84,25 @@ int mars_task_queue_clear(uint64_t queue
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pushes the data specified into the task queue. (Blocking)
+ * \brief <b>[MPU]</b> Pushes the data specified into the task queue.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will push the data specified into the queue.
+ * The entity waiting longest to pop data from the queue can resume.
+ *
+ * If the queue is full at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is room in the queue to push
+ * the data.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be pushed into queue
@@ -87,12 +112,38 @@ int mars_task_queue_clear(uint64_t queue
* \n MARS_ERROR_ALIGN - ea not aligned properly
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_push(uint64_t queue_ea, const void *data);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins push operation on a task queue. (Blocking)
+ * \brief <b>[MPU]</b> Begins push operation on a task queue.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will begin pushing the data specified into the queue.
+ * This only initiates the memory transfer of data into the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_push_end to guarantee the completion of the push.
+ *
+ * If the queue is full at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is room in the queue to push
+ * the data.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
+ *
+ * \e tag
+ * - Specify a memory transfer tag value between 0-31.
+ * - Multiple push operations can be initiated concurrently, and each can be
+ * waited for independently if different memory tranfer tags are specified.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be pushed into queue
@@ -104,13 +155,27 @@ int mars_task_queue_push(uint64_t queue_
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
* \n MARS_ERROR_PARAMS - invalid tag
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_push_begin(uint64_t queue_ea, const void *data,
uint32_t tag);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Completes push operation on a task queue.
+ * \brief <b>[MPU]</b> Completes push operation on a task queue.
+ *
+ * This function will complete a push operation initiated with
+ * \ref mars_task_queue_push_begin or \ref mars_task_queue_try_push_begin.
+ * This function must be called in pair for each call to
+ * \ref mars_task_queue_push_begin or \ref mars_task_queue_try_push_begin to
+ * guarantee the completion of the initiated push operation.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e tag
+ * - Specify the memory transfer tag specified at push operation initialization.
+ * - If multiple push operations were initiated concurrently, this call must
+ * wait for all memory transfers initiated with the same tag to complete.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] tag - tag identifier for memory transfer
@@ -125,7 +190,19 @@ int mars_task_queue_push_end(uint64_t qu
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pushes the data specified into the task queue. (Non-Blocking)
+ * \brief <b>[MPU]</b> Pushes the data specified into the task queue.
+ *
+ * This function will push the data specified into the queue.
+ * The entity waiting longest to pop data from the queue can resume.
+ *
+ * If the queue is full at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be pushed into queue
@@ -140,7 +217,26 @@ int mars_task_queue_try_push(uint64_t qu
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins push operation on a task queue. (Non-Blocking)
+ * \brief <b>[MPU]</b> Begins push operation on a task queue.
+ *
+ * This function will begin pushing the data specified into the queue.
+ * This only initiates the memory transfer of data into the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_push_end to guarantee the completion of the push.
+ *
+ * If the queue is full at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to user data to copy into the queue.
+ * - The size of data should be equal to the size specified at queue creation.
+ *
+ * \e tag
+ * - Specify a memory transfer tag value between 0-31.
+ * - Multiple push operations can be initiated concurrently, and each can be
+ * waited for independently if different memory tranfer tags are specified.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be pushed into queue
@@ -158,7 +254,25 @@ int mars_task_queue_try_push_begin(uint6
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pops data from a task queue. (Blocking)
+ * \brief <b>[MPU]</b> Pops data from a task queue.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will pop data from the queue.
+ *
+ * If the queue is empty at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is data in the queue to
+ * pop.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -168,12 +282,34 @@ int mars_task_queue_try_push_begin(uint6
* \n MARS_ERROR_ALIGN - ea or data not aligned properly
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_pop(uint64_t queue_ea, void *data);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins pop operation on a task queue. (Blocking)
+ * \brief <b>[MPU]</b> Begins pop operation on a task queue.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will begin popping data from the queue.
+ * This only initiates the memory transfer of data from the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_pop_end to guarantee the completion of the pop.
+ *
+ * If the queue is empty at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is data in the queue to
+ * pop.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -185,12 +321,26 @@ int mars_task_queue_pop(uint64_t queue_e
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
* \n MARS_ERROR_PARAMS - invalid tag
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_pop_begin(uint64_t queue_ea, void *data, uint32_t tag);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Completes pop operation on a task queue.
+ * \brief <b>[MPU]</b> Completes pop operation on a task queue.
+ *
+ * This function will complete a pop operation initiated with
+ * \ref mars_task_queue_pop_begin or \ref mars_task_queue_try_pop_begin.
+ * This function must be called in pair for each call to
+ * \ref mars_task_queue_pop_begin or \ref mars_task_queue_try_pop_begin to
+ * guarantee the completion of the initiated pop operation.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e tag
+ * - Specify the memory transfer tag specified at pop operation initialization.
+ * - If multiple pop operations were initiated concurrently, this call must
+ * wait for all memory transfers initiated with the same tag to complete.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] tag - tag identifier for memory transfer
@@ -205,7 +355,19 @@ int mars_task_queue_pop_end(uint64_t que
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pops data from a task queue. (Non-Blocking)
+ * \brief <b>[MPU]</b> Pops data from a task queue.
+ *
+ * This function will pop data from the queue.
+ *
+ * If the queue is empty at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address for data to be popped from queue
@@ -220,7 +382,23 @@ int mars_task_queue_try_pop(uint64_t que
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins pop operation on a task queue. (Non-Blocking)
+ * \brief <b>[MPU]</b> Begins pop operation on a task queue.
+ *
+ * This function will begin popping data from the queue.
+ * This only initiates the memory transfer of data from the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_pop_end to guarantee the completion of the pop.
+ *
+ * If the queue is empty at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
+ *
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address for data to be popped from queue
@@ -237,7 +415,26 @@ int mars_task_queue_try_pop_begin(uint64
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pops data from a task queue without removing it. (Blocking)
+ * \brief <b>[MPU]</b> Pops data from a task queue without removing it.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will retrieve data from the queue without removing it from the
+ * queue.
+ *
+ * If the queue is empty at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is data in the queue to
+ * be retrieved.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -247,12 +444,35 @@ int mars_task_queue_try_pop_begin(uint64
* \n MARS_ERROR_ALIGN - ea or data not aligned properly
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_peek(uint64_t queue_ea, void *data);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins peek operation on a task queue. (Blocking)
+ * \brief <b>[MPU]</b> Begins peek operation on a task queue.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will begin retriveing data from the queue without removing the
+ * data from the queue.
+ * This only initiates the memory transfer of data from the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_peek_end to guarantee the completion of the peek.
+ *
+ * If the queue is empty at the time of this call, this function will cause the
+ * caller task to enter a waiting state until there is data in the queue to
+ * be retrived.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -264,12 +484,26 @@ int mars_task_queue_peek(uint64_t queue_
* \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
* \n MARS_ERROR_STATE - invalid direction
* \n MARS_ERROR_PARAMS - invalid tag
+ * \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_queue_peek_begin(uint64_t queue_ea, void *data, uint32_t tag);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Completes peek operation on a task queue.
+ * \brief <b>[MPU]</b> Completes peek operation on a task queue.
+ *
+ * This function will complete a peek operation initiated with
+ * \ref mars_task_queue_peek_begin or \ref mars_task_queue_try_peek_begin.
+ * This function must be called in pair for each call to
+ * \ref mars_task_queue_peek_begin or \ref mars_task_queue_try_peek_begin to
+ * guarantee the completion of the initiated peek operation.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e tag
+ * - Specify the memory transfer tag specified at peek operation initialization.
+ * - If multiple peek operations were initiated concurrently, this call must
+ * wait for all memory transfers initiated with the same tag to complete.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] tag - tag identifier for memory transfer
@@ -284,7 +518,20 @@ int mars_task_queue_peek_end(uint64_t qu
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Pops data from a task queue without removing it. (Non-Blocking)
+ * \brief <b>[MPU]</b> Pops data from a task queue without removing it.
+ *
+ * This function will retrieve data from the queue without removing it from the
+ * queue.
+ *
+ * If the queue is empty at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -292,14 +539,30 @@ int mars_task_queue_peek_end(uint64_t qu
* MARS_SUCCESS - successfully popped data from queue
* \n MARS_ERROR_NULL - ea or data is 0
* \n MARS_ERROR_ALIGN - ea or data not aligned properly
- * \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
+ * \n MARS_ERROR_BUSY - queue is empty
* \n MARS_ERROR_STATE - invalid direction
*/
int mars_task_queue_try_peek(uint64_t queue_ea, void *data);
/**
* \ingroup group_mars_task_queue
- * \brief [MPU] Begins peek operation on a task queue. (Non-Blocking)
+ * \brief <b>[MPU]</b> Begins peek operation on a task queue.
+ *
+ * This function will begin retriveing data from the queue without removing the
+ * data from the queue.
+ * This only initiates the memory transfer of data from the queue.
+ * This function must be completed with a matching call to
+ * \ref mars_task_queue_peek_end to guarantee the completion of the peek.
+ *
+ * If the queue is empty at the time of this call, this function will return
+ * immedately with \ref MARS_ERROR_BUSY.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e data
+ * - Specify the pointer to some allocated memory to copy the popped data.
+ * - The size of the allocated memory area should be equal to the size specified
+ * at queue creation.
*
* \param[in] queue_ea - ea of initialized queue instance
* \param[in] data - address of data to be popped from queue
@@ -308,7 +571,7 @@ int mars_task_queue_try_peek(uint64_t qu
* MARS_SUCCESS - successfully popped data from queue
* \n MARS_ERROR_NULL - ea or data is 0
* \n MARS_ERROR_ALIGN - ea or data not aligned properly
- * \n MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
+ * \n MARS_ERROR_BUSY - queue is empty
* \n MARS_ERROR_STATE - invalid direction
* \n MARS_ERROR_PARAMS - invalid tag
*/
--- a/include/mpu/mars/task_semaphore.h
+++ b/include/mpu/mars/task_semaphore.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_semaphore
- * \brief [MPU] MARS Task Semaphore API
+ * \brief <b>[MPU]</b> MARS Task Semaphore API
*/
#include <mars/task_semaphore_types.h>
@@ -52,7 +52,18 @@ extern "C" {
/**
* \ingroup group_mars_task_semaphore
- * \brief [MPU] Acquires a task semaphore. (Blocking)
+ * \brief <b>[MPU]</b> Acquires a task semaphore.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
+ *
+ * This function will attempt to acquire the semaphore.
+ * If the total number of current accesses of the semaphore is greater than or
+ * equal to the total allowed specified at semaphore creation, the caller task
+ * will enter a waiting state until some other tasks release the semaphore and
+ * becomes available for acquiring.
*
* \param[in] semaphore_ea - ea of initialized semaphore instance
* \return
@@ -66,7 +77,12 @@ int mars_task_semaphore_acquire(uint64_t
/**
* \ingroup group_mars_task_semaphore
- * \brief [MPU] Releases a task semaphore.
+ * \brief <b>[MPU]</b> Releases a task semaphore.
+ *
+ * This function will release a previously acquired semaphore.
+ * If their are other tasks currently waiting to acquire a semaphore, calling
+ * this function will resume a waiting task to allow it to acquire the
+ * semaphore.
*
* \param[in] semaphore_ea - ea of initialized semaphore instance
* \return
--- a/include/mpu/mars/task_signal.h
+++ b/include/mpu/mars/task_signal.h
@@ -41,7 +41,7 @@
/**
* \file
* \ingroup group_mars_task_signal
- * \brief [MPU] MARS Task Signal API
+ * \brief <b>[MPU]</b> MARS Task Signal API
*/
#include <mars/task_types.h>
@@ -52,7 +52,7 @@ extern "C" {
/**
* \ingroup group_mars_task_signal
- * \brief [MPU] Sends a signal to the specified task.
+ * \brief <b>[host/MPU]</b> Sends a signal to the specified task.
*
* This function sends a signal to the task specified. If the task had
* previously called \ref mars_task_signal_wait and was in the waiting state,
@@ -68,13 +68,19 @@ extern "C" {
* \return
* MARS_SUCCESS - successfully yielded task
* \n MARS_ERROR_NULL - null pointer specified
+ * \n MARS_ERROR_PARAMS - bad task id specified
* \n MARS_ERROR_STATE - task is in an invalid state
*/
int mars_task_signal_send(struct mars_task_id *id);
/**
* \ingroup group_mars_task_signal
- * \brief [MPU] Waits and yields caller task until receiving signal. (Blocking)
+ * \brief <b>[MPU]</b> Waits and yields caller task until receiving signal.
+ * <b>(Task Switch Call)</b>
+ *
+ * \note The <b>[MPU]</b> call may result in a task switch and put this
+ * task into the waiting state. Understand all the limitations before calling
+ * a <b>Task Switch Call</b> (<b>See</b> \ref sec_6_5).
*
* This function will cause the task to enter a waiting state until some other
* entity calls \ref mars_task_signal_send to this task to return it to the
@@ -89,7 +95,7 @@ int mars_task_signal_wait(void);
/**
* \ingroup group_mars_task_signal
- * \brief [MPU] Waits for task until receiving signal. (Non-Blocking)
+ * \brief <b>[MPU]</b> Waits for task until receiving signal.
*
* This function will check the state of a task to see if some other entity
* has called \ref mars_task_signal_send to this task and returns immediately
More information about the cbe-oss-dev
mailing list