doxygen: Update documentation
Signed-off-by: Yuji Mano <yuji.mano@am.sony.com>
diff --git a/RELEASES b/RELEASES
index 7158fa8..0114782 100644
--- a/RELEASES
+++ b/RELEASES
@@ -2,6 +2,24 @@
--------
This file lists major changes and known major bugs or issues for each release.
+2009-03-25: Yuji Mano <yuji.mano@am.sony.com>
+
+ Release v1.1.2
+ ==============
+ Host Callback Framework, Optimizations, Performance Tests
+
+ Major Changes
+ -------------
+ * add host callback framework API
+ * add performance tests
+ * reduce task stack space required for context switch by 768 bytes
+ * various performance optimizations and minor bug fixes
+
+ Major Bugs
+ ----------
+ * none known
+
+
2009-02-13: Yuji Mano <yuji.mano@am.sony.com>
Release v1.1.1
diff --git a/base/include/mpu/mars/module.h b/base/include/mpu/mars/module.h
index 3a6a0b9..344c2a3 100644
--- a/base/include/mpu/mars/module.h
+++ b/base/include/mpu/mars/module.h
@@ -293,7 +293,7 @@
* \ingroup group_mars_workload_module
* \brief <b>[MPU]</b> Request host to call registered callback.
*
- * \param[in] callback_ea - ea of callback function
+ * \param[in] callback_ea - ea of function of type \ref mars_callback
* \param[in] in - pointer to input args in MPU storage
*
* \return
diff --git a/doxygen/src/doxygen b/doxygen/src/doxygen
index 163abad..ae85c18 100644
--- a/doxygen/src/doxygen
+++ b/doxygen/src/doxygen
@@ -4367,6 +4367,8 @@
- \ref mars_module_workload_yield
- \ref mars_module_workload_finish
- \ref mars_module_host_signal_send
+ - \ref mars_module_host_callback_set
+ - \ref mars_module_host_callback_reset
- \ref mars_module_mutex_lock_get
- \ref mars_module_mutex_unlock_put
- \ref mars_module_dma_get
@@ -4379,6 +4381,7 @@
- \ref mars_task_schedule
- \ref mars_task_wait
- \ref mars_task_try_wait
+ - \ref mars_task_call_host
- \ref mars_task_get_kernel_id
- \ref mars_task_get_id
- \ref mars_task_get_name
diff --git a/task/include/common/mars/task_types.h b/task/include/common/mars/task_types.h
index fe72057..50c0dbd 100644
--- a/task/include/common/mars/task_types.h
+++ b/task/include/common/mars/task_types.h
@@ -46,6 +46,8 @@
#include <stdint.h>
+#include <mars/callback_types.h>
+
/**
* \ingroup group_mars_task
* \brief Base address of task
@@ -103,13 +105,4 @@
} type;
};
-/**
- * \ingroup group_mars_task
- * \brief MARS task host callback function
- *
- * This is the type definition of the host callback function.
- */
-typedef int (*mars_task_host_callback)(struct mars_task_args *in,
- struct mars_task_args *out);
-
#endif
diff --git a/task/include/host/mars/task.h b/task/include/host/mars/task.h
index 5d33d03..ba12cf1 100644
--- a/task/include/host/mars/task.h
+++ b/task/include/host/mars/task.h
@@ -47,7 +47,6 @@
#include <stdint.h>
#include <mars/base.h>
-#include <mars/callback_types.h>
#include <mars/context.h>
#include <mars/error.h>
#include <mars/task_barrier.h>
diff --git a/task/include/mpu/mars/task.h b/task/include/mpu/mars/task.h
index a3f9ffb..cf458fb 100644
--- a/task/include/mpu/mars/task.h
+++ b/task/include/mpu/mars/task.h
@@ -46,7 +46,6 @@
#include <stdint.h>
-#include <mars/callback_types.h>
#include <mars/error.h>
#include <mars/task_barrier.h>
#include <mars/task_event_flag.h>
@@ -108,15 +107,14 @@
* task into the waiting state. Understand all the limitations before calling
* a <b>Task Switch Call</b> (<b>See</b> \ref sec_7_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
- * to run then this task enters the waiting state until the next time it is
- * scheduled to run. If there are no other tasks available to be scheduled at
- * the time of this function call, then this function has no effect and will
- * return immediately.
+ * This function causes the task to yield and allow other workloads to be
+ * scheduled to run if available. The task's context state is saved and the
+ * kernel will reschedule the next available workload. If there are no other
+ * workloads to be scheduled, the task that called to yield will be rescheduled
+ * for resumed execution.
*
* \note This function is a scheduling call and may cause a task switch and put
- * the caller task into a waiting state.
+ * the caller task into a ready state.
*
* \return
* MARS_SUCCESS - successfully yielded task
@@ -234,12 +232,38 @@
/**
* \ingroup group_mars_task
* \brief <b>[MPU]</b> Calls the specified host callback.
+ * <b>(Task Switch Call)</b>
*
- * \param[in] callback_ea - ea of host callback
- * \param[in] in - pointer to args to pass to host callback
- * \param[out] out - pointer to args returned by host callback
+ * \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_7_5).
+ *
+ * This function will block until the requested host callback function returns.
+ *
+ * <b>Key Parameters</b>:
+ * \n \n
+ * \e callback_ea
+ * - Pass in the EA of the host callback function you want called. This function
+ * should be of type \ref mars_callback.
+ * - If an invalid EA is specified, the resulting behavior is undetermined.
+ *
+ * \e in
+ * - Pass in a pointer to an initialized callback argument structure instance.
+ * - If NULL is specified, a pointer to an uninitialized callback argument
+ * structure will be passed into the host callback function.
+ *
+ * \e out
+ * - Pass in a pointer to a callback argument structure instance, which can be
+ * initialized by the host callback function.
+ * - If NULL is specified, the output argument structure initialized by the host
+ * callback function will not be returned to the caller.
+ *
+ * \param[in] callback_ea - ea of host callback of type \ref mars_callback
+ * \param[in] in - pointer to args, passed into to host callback
+ * \param[out] out - pointer to args, initialized by host callback
* \return
* MARS_SUCCESS - host callback successful
+ * \n MARS_ERROR_LIMIT - host callback queue is full
* \n MARS_ERROR_FORMAT - no context save area specified
*/
int mars_task_call_host(uint64_t callback_ea,
