[Cbe-oss-dev] [PATCH 05/10]MARS: Dynamic allocation api change comments update
Yuji Mano
yuji.mano at am.sony.com
Fri Oct 3 04:31:29 EST 2008
This updates doxygen comments for the previous patch that changes the API for
dynamic allocation of objects.
Signed-off-by: Yuji Mano <yuji.mano at am.sony.com>
---
include/host/mars/mars_context.h | 47 +++++++++++++++----------------
include/host/mars/mars_mutex.h | 39 +++++++++++++++++++++----
include/host/mars/mars_task.h | 43 +++++++++++++---------------
include/host/mars/mars_task_barrier.h | 19 +++++++++---
include/host/mars/mars_task_event_flag.h | 27 +++++++++++------
include/host/mars/mars_task_queue.h | 40 +++++++++++++++-----------
6 files changed, 133 insertions(+), 82 deletions(-)
--- a/include/host/mars/mars_context.h
+++ b/include/host/mars/mars_context.h
@@ -69,33 +69,23 @@ struct mars_context {
extern "C" {
#endif
-static inline void *mars_ea_to_ptr(uint64_t ea)
-{
- return (void *)(uintptr_t)ea;
-}
-
-static inline uint64_t mars_ptr_to_ea(void *ptr)
-{
- return (uint64_t)(uintptr_t)ptr;
-}
-
/**
* \ingroup group_mars_context
- * \brief [host] Initializes a single MARS context.
+ * \brief [host] Creates a single MARS context.
*
- * This function initializes a single MARS context. A MARS context must be
- * initialized before any of the MARS functionality can be used. This will
+ * This function creates a single MARS context. A MARS context must be
+ * created before any of the MARS functionality can be used. This will
* create the MPU contexts that are each loaded with and run the MARS kernel.
* The MARS kernel on each MPU will continue to run until the MARS context
- * is finalized through \ref mars_finalize.
+ * is destroyed through \ref mars_context_destroy.
*
- * \note If there are multiple MARS contexts initialized in the system, then
+ * \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.
*
- * \param[out] ctx - address of context instance to initialize
+ * \param[out] mars - address of pointer to MARS context
* \param[in] num_mpus - number of mpus utilized by MARS context
* \return
- * MARS_SUCCESS - successfully initialized MARS context
+ * MARS_SUCCESS - successfully created MARS context
* \n MARS_ERROR_NULL - null pointer specified
* \n MARS_ERROR_PARAMS - bad MARS params specified
* \n MARS_ERROR_MEMORY - not enough memory
@@ -105,21 +95,32 @@ int mars_context_create(struct mars_cont
/**
* \ingroup group_mars_context
- * \brief [host] Finalizes a single MARS context.
+ * \brief [host] Destroys a single MARS context.
*
- * This function finalizes a single MARS context that was previously
- * initialized by \ref mars_initialize. In order to successfully finalize
+ * This function destroys a single MARS context that was previously
+ * created by \ref mars_context_create. In order to successfully destroy
* a MARS context, all workloads added to the workload queue must be
- * completed and finalized so that the workload queue is empty.
+ * completed and destroyed so that the workload queue is empty.
*
- * \param[in] ctx - address of context instance to finalize
+ * \param[in] mars - pointer to MARS context
* \return
- * MARS_SUCCESS - successfully finalized MARS context
+ * MARS_SUCCESS - successfully destroyed MARS context
* \n MARS_ERROR_NULL - null pointer specified
* \n MARS_ERROR_STATE - workload queue is not empty
*/
int mars_context_destroy(struct mars_context *mars);
+
+static inline void *mars_ea_to_ptr(uint64_t ea)
+{
+ return (void *)(uintptr_t)ea;
+}
+
+static inline uint64_t mars_ptr_to_ea(void *ptr)
+{
+ return (uint64_t)(uintptr_t)ptr;
+}
+
#if defined(__cplusplus)
}
#endif
--- a/include/host/mars/mars_mutex.h
+++ b/include/host/mars/mars_mutex.h
@@ -52,21 +52,46 @@ extern "C" {
/**
* \ingroup group_mars_mutex
- * \brief [host] Initializes a mutex.
+ * \brief [host] Creates a mutex.
*
- * This function initializes a mutex instance that can be locked or unlocked
+ * This function creates a mutex instance that can be locked or unlocked
* from both host and MPU to restrict concurrent accesses.
*
- * \param[in] mutex - pointer to mutex instance to initialize
+ * \param[in] mutex - address of pointer to mutex instance
* \return
- * MARS_SUCCESS - successfully initialized mutex
+ * MARS_SUCCESS - successfully created mutex
* \n MARS_ERROR_NULL - null pointer is specified
- * \n MARS_ERROR_ALIGN - instance not aligned properly
+ * \n MARS_ERROR_MEMORY - instance not aligned properly
*/
int mars_mutex_create(struct mars_mutex **mutex);
+/**
+ * \ingroup group_mars_mutex
+ * \brief [host] Destroys a mutex.
+ *
+ * This function destroys a mutex instance.
+ *
+ * \param[in] mutex - address of pointer to mutex instance
+ * \return
+ * MARS_SUCCESS - successfully destroyed mutex
+ * \n MARS_ERROR_NULL - null pointer is specified
+ * \n MARS_ERROR_ALIGN - instance not aligned properly
+ */
int mars_mutex_destroy(struct mars_mutex *mutex);
+/**
+ * \ingroup group_mars_mutex
+ * \brief [host] Resets a mutex.
+ *
+ * This function resets a mutex instance and forces it into an unlocked state
+ * regardless of whether it is locked or unlocked.
+ *
+ * \param[in] mutex - address of pointer to mutex instance
+ * \return
+ * MARS_SUCCESS - successfully reset mutex
+ * \n MARS_ERROR_NULL - null pointer is specified
+ * \n MARS_ERROR_ALIGN - instance not aligned properly
+ */
int mars_mutex_reset(struct mars_mutex *mutex);
/**
@@ -75,7 +100,7 @@ int mars_mutex_reset(struct mars_mutex *
*
* This function locks a mutex and blocks other requests to lock it.
*
- * \param[in] mutex - pointer to mutex instance to lock
+ * \param[in] mutex - pointer to mutex instance
* \return
* MARS_SUCCESS - successfully locked mutex
* \n MARS_ERROR_NULL - null pointer is specified
@@ -89,7 +114,7 @@ int mars_mutex_lock(struct mars_mutex *m
*
* This function unlocks a previously locked mutex to allow other lock requests.
*
- * \param[in] mutex - pointer to mutex instance to unlock
+ * \param[in] mutex - pointer to mutex instance
* \return
* MARS_SUCCESS - successfully unlocked mutex
* \n MARS_ERROR_NULL - null pointer is specified
--- a/include/host/mars/mars_task.h
+++ b/include/host/mars/mars_task.h
@@ -58,18 +58,17 @@ extern "C" {
/**
* \ingroup group_mars_task
- * \brief [host] Initializes a MARS task.
+ * \brief [host] Creates a MARS task.
*
- * This function initializes a single task and adds it the MARS context's
+ * This function creates a single task and adds it the MARS context's
* workload queue.
- * Upon success, the specified id structure params will hold the initilized
- * task's id information.
+ * Upon success, a valid task id will be returned.
* You must call \ref mars_task_schedule in order for it to be scheduled for
* execution by the kernel.
- * The task is in the finished state upon creation and may be finalized by
- * \ref mars_task_finalize without ever being scheduled for execution.
+ * 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 initializing a MARS task, you must specify its parameters:
+ * 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.
@@ -86,13 +85,13 @@ extern "C" {
* that will enter that task into a wait state. Currently either 0 or
* \ref MARS_TASK_CONTEXT_SAVE_SIZE_MAX must be specified.
*
- * \param[in] mars - pointer to initialized MARS context
- * \param[out] id - pointer to task id to be initialized
+ * \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_size - size of context save area allocated for task
* \return
- * MARS_SUCCESS - successfully initialized MARS task
+ * MARS_SUCCESS - successfully created MARS task
* \n MARS_ERROR_NULL - null pointer specified
* \n MARS_ERROR_PARAMS - bad task params specified
* \n MARS_ERROR_MEMORY - not enough memory
@@ -106,19 +105,19 @@ int mars_task_create(struct mars_context
/**
* \ingroup group_mars_task
- * \brief [host] Finalizes a MARS task.
+ * \brief [host] Destroys a MARS task.
*
- * This function finalizes a task initialized by \ref mars_task_initialize.
- * The task will only be finalized if the task is in the finished state.
- * Once this function returns successfully and the task is finalized, the task
- * id should no longer be used.
- * If you want to make sure the task has finished before calling this function,
- * you can wait for task completion by calling \ref mars_task_wait or
+ * 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.
+ * Once this function returns successfully and the task is destroyed, the task
+ * id is no longer valid.
+ * To guarantee the task has finished before calling this function, you should
+ * wait for task completion by calling \ref mars_task_wait or
* \ref mars_task_try_wait.
*
- * \param[in] id - pointer to task id to finalize
+ * \param[in] id - pointer to task id instance
* \return
- * MARS_SUCCESS - successfully finalized MARS task
+ * MARS_SUCCESS - successfully destroyed 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
@@ -146,7 +145,7 @@ int mars_task_destroy(struct mars_task_i
* 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[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
@@ -164,7 +163,7 @@ int mars_task_schedule(struct mars_task_
*
* This function will block until the scheduled task specified is finished.
*
- * \param[in] id - pointer to task id to wait for
+ * \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
@@ -181,7 +180,7 @@ int mars_task_wait(struct mars_task_id *
* 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 to wait for
+ * \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
--- a/include/host/mars/mars_task_barrier.h
+++ b/include/host/mars/mars_task_barrier.h
@@ -54,21 +54,30 @@ extern "C" {
/**
* \ingroup group_mars_task_barrier
- * \brief [host] Initializes a task barrier.
+ * \brief [host] Creates a task barrier.
*
- * \param[in] mars - pointer to initialized MARS context
- * \param[out] barrier - pointer to barrier instance to initialize
+ * \param[in] mars - pointer to MARS context
+ * \param[out] barrier - address of pointer to barrier instance
* \param[in] total - number of notifies before barrier released
* \return
- * MARS_SUCCESS - successfully initialized barrier
+ * MARS_SUCCESS - successfully created barrier
* \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_ALIGN - instance not properly aligned
* \n MARS_ERROR_PARAMS - total exceeds allowed limit
*/
int mars_task_barrier_create(struct mars_context *mars,
struct mars_task_barrier **barrier,
uint32_t total);
+/**
+ * \ingroup group_mars_task_barrier
+ * \brief [host] Destroys a task barrier.
+ *
+ * \param[in] barrier - pointer to barrier instance
+ * \return
+ * MARS_SUCCESS - successfully destroyed barrier
+ * \n MARS_ERROR_NULL - null pointer specified
+ * \n MARS_ERROR_ALIGN - instance not properly aligned
+ */
int mars_task_barrier_destroy(struct mars_task_barrier *barrier);
#if defined(__cplusplus)
--- a/include/host/mars/mars_task_event_flag.h
+++ b/include/host/mars/mars_task_event_flag.h
@@ -54,16 +54,15 @@ extern "C" {
/**
* \ingroup group_mars_task_event_flag
- * \brief [host] Initializes a task event flag.
+ * \brief [host] Creates a task event flag.
*
- * \param[in] mars - pointer to initialized MARS context
- * \param[out] event_flag - pointer to event flag instance to initialize
+ * \param[in] mars - pointer to MARS context
+ * \param[out] event_flag - address of pointer to event flag instance
* \param[in] direction - direction of the event flag
* \param[in] clear_mode - behavior of how the event flag is cleared
* \return
- * MARS_SUCCESS - successfully initialized event flag
+ * MARS_SUCCESS - successfully created event flag
* \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_ALIGN - instance not aligned properly
* \n MARS_ERROR_PARAMS - invalid direction or clear mode specified
*/
int mars_task_event_flag_create(struct mars_context *mars,
@@ -71,13 +70,23 @@ int mars_task_event_flag_create(struct m
uint8_t direction,
uint8_t clear_mode);
+/**
+ * \ingroup group_mars_task_event_flag
+ * \brief [host] Destroys a task event flag.
+ *
+ * \param[in] event_flag - pointer to event flag instance
+ * \return
+ * MARS_SUCCESS - successfully destroyed event flag
+ * \n MARS_ERROR_NULL - null pointer specified
+ * \n MARS_ERROR_ALIGN - instance not properly aligned
+ */
int mars_task_event_flag_destroy(struct mars_task_event_flag *event_flag);
/**
* \ingroup group_mars_task_event_flag
* \brief [host] Clears the bits specified in the task event flag.
*
- * \param[in] event_flag - pointer to initialized event flag instance
+ * \param[in] event_flag - pointer to event flag instance
* \param[in] bits - bits to clear
* \return
* MARS_SUCCESS - successfully cleared event flag bits
@@ -91,7 +100,7 @@ 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.
*
- * \param[in] event_flag - pointer to initialized event flag instance
+ * \param[in] event_flag - pointer to event flag instance
* \param[in] bits - bits to set
* \return
* MARS_SUCCESS - successfully cleared event flag bits
@@ -106,7 +115,7 @@ int mars_task_event_flag_set(struct mars
* \ingroup group_mars_task_event_flag
* \brief [host] Waits on a task event flag. (Blocking)
*
- * \param[in] event_flag - pointer to initialized event flag instance
+ * \param[in] event_flag - pointer to event flag instance
* \param[in] mask - bit mask to test event flag bits against
* \param[in] mask_mode - specifies how to mask bits (AND, OR)
* \param[out] bits - pointer to instance to store bits upon release
@@ -126,7 +135,7 @@ int mars_task_event_flag_wait(struct mar
* \ingroup group_mars_task_event_flag
* \brief [host] Waits on a task event flag. (Non-Blocking)
*
- * \param[in] event_flag - pointer to initialized event flag instance
+ * \param[in] event_flag - pointer to event flag instance
* \param[in] mask - bit mask to test event flag bits against
* \param[in] mask_mode - specifies how to mask bits (AND, OR)
* \param[out] bits - pointer to instance to store bits upon release
--- a/include/host/mars/mars_task_queue.h
+++ b/include/host/mars/mars_task_queue.h
@@ -54,18 +54,16 @@ extern "C" {
/**
* \ingroup group_mars_task_queue
- * \brief [host] Initializes a task queue.
+ * \brief [host] Creates a task queue.
*
- * \param[in] mars - pointer to initialized MARS context
- * \param[out] queue - pointer to queue instance to initialize
- * \param[in] buffer - pointer to data buffer managed by queue
+ * \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] depth - maximum number of data entries in data buffer
* \param[in] direction - direction of the event flag
* \return
- * MARS_SUCCESS - successfully initialized queue
+ * MARS_SUCCESS - successfully created queue
* \n MARS_ERROR_NULL - null pointer specified
- * \n MARS_ERROR_ALIGN - instance not aligned properly
* \n MARS_ERROR_PARAMS - size is not multiple of 16 bytes or is greater
* than 16KB maximum
* \n MARS_ERROR_PARAMS - depth exceeds allowed limit
@@ -77,18 +75,28 @@ int mars_task_queue_create(struct mars_c
uint32_t depth,
uint8_t direction);
+/**
+ * \ingroup group_mars_task_queue
+ * \brief [host] Destroys a task queue.
+ *
+ * \param[in] queue - pointer to queue instance
+ * \return
+ * MARS_SUCCESS - successfully destroyed queue
+ * \n MARS_ERROR_NULL - null pointer specified
+ * \n MARS_ERROR_ALIGN - instance not properly aligned
+ */
int mars_task_queue_destroy(struct mars_task_queue *queue);
/**
* \ingroup group_mars_task_queue
* \brief [host] Returns the number of items in the task queue.
*
- * \param[in] queue - pointer to initialized queue instance
+ * \param[in] queue - pointer to queue instance
* \param[out] count - pointer to variable to store return count
* \return
* MARS_SUCCESS - successfully returned count
- * \n MARS_ERROR_NULL - ea is 0
- * \n MARS_ERROR_ALIGN - ea not aligned properly
+ * \n MARS_ERROR_NULL - null pointer specified
+ * \n MARS_ERROR_ALIGN - instance not aligned properly
*/
int mars_task_queue_count(struct mars_task_queue *queue, uint32_t *count);
@@ -96,7 +104,7 @@ int mars_task_queue_count(struct mars_ta
* \ingroup group_mars_task_queue
* \brief [host] Clears the items in the task queue.
*
- * \param[in] queue - pointer to initialized queue instance
+ * \param[in] queue - pointer to queue instance
* \return
* MARS_SUCCESS - successfully cleared queue
* \n MARS_ERROR_NULL - null pointer specified
@@ -108,7 +116,7 @@ int mars_task_queue_clear(struct mars_ta
* \ingroup group_mars_task_queue
* \brief [host] Pushes the data specified into the task queue. (Blocking)
*
- * \param[in] queue - pointer to initialized queue instance
+ * \param[in] queue - pointer to queue instance
* \param[in] data - address of data to be pushed into queue
* \return
* MARS_SUCCESS - successfully pushed data into queue
@@ -122,7 +130,7 @@ 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)
*
- * \param[in] queue - pointer to initialized queue instance
+ * \param[in] queue - pointer to queue instance
* \param[in] data - address of data to be pushed into queue
* \return
* MARS_SUCCESS - successfully pushed data into queue
@@ -137,7 +145,7 @@ int mars_task_queue_try_push(struct mars
* \ingroup group_mars_task_queue
* \brief [host] Pops data from a task queue. (Blocking)
*
- * \param[in] queue - pointer to initialized task instance
+ * \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
* \return
* MARS_SUCCESS - successfully received event
@@ -151,7 +159,7 @@ int mars_task_queue_pop(struct mars_task
* \ingroup group_mars_task_queue
* \brief [host] Pops data from a task queue. (Non-Blocking)
*
- * \param[in] queue - pointer to initialized task instance
+ * \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
* \return
* MARS_SUCCESS - successfully received event
@@ -166,7 +174,7 @@ 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)
*
- * \param[in] queue - pointer to initialized task instance
+ * \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
* \return
* MARS_SUCCESS - successfully received event
@@ -181,7 +189,7 @@ int mars_task_queue_peek(struct mars_tas
* \ingroup group_mars_task_queue
* \brief [host] Pops data from a task queue without removing it. (Non-Blocking)
*
- * \param[in] queue - pointer to initialized task instance
+ * \param[in] queue - pointer to task instance
* \param[in] data - address of data to be popped from queue
* \return
* MARS_SUCCESS - successfully received event
More information about the cbe-oss-dev
mailing list