doxygen: Update documentation

Signed-off-by: Yuji Mano <yuji.mano@am.sony.com>

6 files changed, 59 insertions, 22 deletions

diff --git a/RELEASES b/RELEASES
index 7158fa8..0114782 100644
--- a/RELEASES
+++ b/RELEASES
@@ -2,6 +2,24 @@ RELEASES
 --------
 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 @@ int mars_module_host_signal_send(uint64_t watch_point_ea);
  * \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 @@ This section will describe the MARS API.
   - \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 @@ This section will describe the MARS API.
   - \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 @@ struct mars_task_args {
 	} 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 @@ void mars_task_exit(int32_t exit_code);
  * 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 @@ int mars_task_try_wait(const struct mars_task_id *id, int32_t *exit_code);
 /**
  * \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,