Doxygen added and comment blocks standardized.
---
cpukit/libmisc/capture/capture.c | 216 +--------------
cpukit/libmisc/capture/capture.h | 565 ++++++++++++++++++++++++---------------
2 files changed, 364 insertions(+), 417 deletions(-)
diff --git a/cpukit/libmisc/capture/capture.c b/cpukit/libmisc/capture/capture.c
index cc47a51..f02745a 100644
--- a/cpukit/libmisc/capture/capture.c
+++ b/cpukit/libmisc/capture/capture.c
@@ -109,10 +109,6 @@ static const char* capture_event_text[] =
};
/*
- * rtems_capture_get_time
- *
- * DESCRIPTION:
- *
* This function returns the current time. If a handler is provided
* by the user get the time from that.
*/
@@ -128,14 +124,9 @@ rtems_capture_get_time (rtems_capture_time_t* time)
}
/*
- * rtems_capture_match_names
- *
- * DESCRIPTION:
- *
* This function compares rtems_names. It protects the
* capture engine from a change to the way names are supported
* in RTEMS.
- *
*/
static inline bool
rtems_capture_match_names (rtems_name lhs, rtems_name rhs)
@@ -144,14 +135,9 @@ rtems_capture_match_names (rtems_name lhs, rtems_name rhs)
}
/*
- * rtems_capture_match_id
- *
- * DESCRIPTION:
- *
* This function compares rtems_ids. It protects the
* capture engine from a change to the way id are supported
* in RTEMS.
- *
*/
static inline bool
rtems_capture_match_ids (rtems_id lhs, rtems_id rhs)
@@ -160,10 +146,6 @@ rtems_capture_match_ids (rtems_id lhs, rtems_id rhs)
}
/*
- * rtems_capture_match_name_id
- *
- * DESCRIPTION:
- *
* This function matches a name and/or id.
*/
static inline bool
@@ -186,14 +168,9 @@ rtems_capture_match_name_id (rtems_name lhs_name,
}
/*
- * rtems_capture_dup_name
- *
- * DESCRIPTION:
- *
* This function duplicates an rtems_names. It protects the
* capture engine from a change to the way names are supported
* in RTEMS.
- *
*/
static inline void
rtems_capture_dup_name (rtems_name* dst, rtems_name src)
@@ -202,14 +179,9 @@ rtems_capture_dup_name (rtems_name* dst, rtems_name src)
}
/*
- * rtems_capture_by_in_to
- *
- * DESCRIPTION:
- *
* This function sees if a BY control is in the BY names. The use
* of the valid_mask in this way assumes the number of trigger
* tasks is the number of bits in uint32_t.
- *
*/
static inline bool
rtems_capture_by_in_to (uint32_t events,
@@ -253,12 +225,7 @@ rtems_capture_by_in_to (uint32_t events,
}
/*
- * rtems_capture_refcount_up
- *
- * DESCRIPTION:
- *
* This function raises the reference count.
- *
*/
static inline void
rtems_capture_refcount_up (rtems_capture_task_t* task)
@@ -267,13 +234,8 @@ rtems_capture_refcount_up (rtems_capture_task_t* task)
}
/*
- * rtems_capture_refcount_down
- *
- * DESCRIPTION:
- *
* This function lowers the reference count and if the count
* reaches 0 the task control block is returned to the heap.
- *
*/
static inline void
rtems_capture_refcount_down (rtems_capture_task_t* task)
@@ -283,10 +245,6 @@ rtems_capture_refcount_down (rtems_capture_task_t* task)
}
/*
- * rtems_capture_init_stack_usage
- *
- * DESCRIPTION:
- *
* This function setups a stack so its usage can be monitored.
*/
static inline void
@@ -308,12 +266,7 @@ rtems_capture_init_stack_usage (rtems_capture_task_t* task)
}
/*
- * rtems_capture_find_control
- *
- * DESCRIPTION:
- *
* This function searches for a trigger given a name.
- *
*/
static inline rtems_capture_control_t*
rtems_capture_find_control (rtems_name name, rtems_id id)
@@ -327,12 +280,7 @@ rtems_capture_find_control (rtems_name name, rtems_id id)
}
/*
- * rtems_capture_create_control
- *
- * DESCRIPTION:
- *
* This function creates a capture control for the capture engine.
- *
*/
static inline rtems_capture_control_t*
rtems_capture_create_control (rtems_name name, rtems_id id)
@@ -385,12 +333,7 @@ rtems_capture_create_control (rtems_name name, rtems_id id)
}
/*
- * rtems_capture_create_capture_task
- *
- * DESCRIPTION:
- *
* This function create the task control.
- *
*/
static inline rtems_capture_task_t*
rtems_capture_create_capture_task (rtems_tcb* new_task)
@@ -466,14 +409,9 @@ rtems_capture_create_capture_task (rtems_tcb* new_task)
}
/*
- * rtems_capture_destroy_capture_task
- *
- * DESCRIPTION:
- *
* This function destroy the task structure if the reference count
* is 0 and the tcb has been cleared signalling the task has been
* deleted.
- *
*/
static inline void
rtems_capture_destroy_capture_task (rtems_capture_task_t* task)
@@ -504,12 +442,7 @@ rtems_capture_destroy_capture_task (rtems_capture_task_t*
task)
}
/*
- * rtems_capture_record
- *
- * DESCRIPTION:
- *
* This function records a capture record into the capture buffer.
- *
*/
static inline void
rtems_capture_record (rtems_capture_task_t* task,
@@ -529,11 +462,10 @@ rtems_capture_record (rtems_capture_task_t* task,
control = task->control;
/*
- * Capure the record if we have an event that is always
+ * Capture the record if we have an event that is always
* captured, or the task's real priority is greater than the
* watch ceiling, and the global watch or task watch is enabled.
*/
-
if ((events & RTEMS_CAPTURE_RECORD_EVENTS) ||
((task->tcb->real_priority >= capture_ceiling) &&
(task->tcb->real_priority <= capture_floor) &&
@@ -572,10 +504,6 @@ rtems_capture_record (rtems_capture_task_t* task,
}
/*
- * rtems_capture_trigger
- *
- * DESCRIPTION:
- *
* See if we have triggered and if not see if this event is a
* cause of a trigger.
*/
@@ -645,12 +573,7 @@ rtems_capture_trigger (rtems_capture_task_t* ft,
}
/*
- * rtems_capture_create_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is created.
- *
*/
static bool
rtems_capture_create_task (rtems_tcb* current_task,
@@ -684,12 +607,7 @@ rtems_capture_create_task (rtems_tcb* current_task,
}
/*
- * rtems_capture_start_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is started.
- *
*/
static void
rtems_capture_start_task (rtems_tcb* current_task,
@@ -726,12 +644,7 @@ rtems_capture_start_task (rtems_tcb* current_task,
}
/*
- * rtems_capture_restart_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is restarted.
- *
*/
static void
rtems_capture_restart_task (rtems_tcb* current_task,
@@ -769,12 +682,7 @@ rtems_capture_restart_task (rtems_tcb* current_task,
}
/*
- * rtems_capture_delete_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is deleted.
- *
*/
static void
rtems_capture_delete_task (rtems_tcb* current_task,
@@ -819,12 +727,7 @@ rtems_capture_delete_task (rtems_tcb* current_task,
}
/*
- * rtems_capture_begin_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is begun.
- *
*/
static void
rtems_capture_begin_task (rtems_tcb* begin_task)
@@ -850,13 +753,8 @@ rtems_capture_begin_task (rtems_tcb* begin_task)
}
/*
- * rtems_capture_exitted_task
- *
- * DESCRIPTION:
- *
* This function is called when a task is exitted. That is
* returned rather than was deleted.
- *
*/
static void
rtems_capture_exitted_task (rtems_tcb* exitted_task)
@@ -883,12 +781,18 @@ rtems_capture_exitted_task (rtems_tcb* exitted_task)
rtems_capture_task_stack_usage (et);
}
+/*
+ * This function is called when a termination request is identified.
+ */
static void
rtems_capture_terminated_task (rtems_tcb* terminated_task)
{
- rtems_capture_delete_task (terminated_task, terminated_task );
+ rtems_capture_delete_task (terminated_task, terminated_task);
}
+/*
+ * This function is called when a fatal error occurs.
+ */
static void
rtems_capture_fatal(
Internal_errors_Source source,
@@ -899,12 +803,7 @@ rtems_capture_fatal(
}
/*
- * rtems_capture_switch_task
- *
- * DESCRIPTION:
- *
* This function is called when a context is switched.
- *
*/
static void
rtems_capture_switch_task (rtems_tcb* current_task,
@@ -983,13 +882,8 @@ rtems_capture_switch_task (rtems_tcb* current_task,
}
/*
- * rtems_capture_open
- *
- * DESCRIPTION:
- *
* This function initialises the realtime capture engine allocating the trace
* buffer. It is assumed we have a working heap at stage of initialisation.
- *
*/
rtems_status_code
rtems_capture_open (uint32_t size, rtems_capture_timestamp timestamp
__attribute__((unused)))
@@ -1061,10 +955,6 @@ rtems_capture_open (uint32_t size,
rtems_capture_timestamp timestamp __attribu
}
/*
- * rtems_capture_close
- *
- * DESCRIPTION:
- *
* This function shutdowns the capture engine and release any claimed
* resources.
*/
@@ -1132,10 +1022,6 @@ rtems_capture_close (void)
}
/*
- * rtems_capture_control
- *
- * DESCRIPTION:
- *
* This function allows control of tracing at a global level.
*/
static void
@@ -1170,10 +1056,6 @@ rtems_capture_control (bool enable)
}
/*
- * rtems_capture_monitor
- *
- * DESCRIPTION:
- *
* This function enable the monitor mode. When in the monitor mode
* the tasks are monitored but no data is saved. This can be used
* to profile the load on a system.
@@ -1202,10 +1084,6 @@ rtems_capture_monitor (bool enable)
}
/*
- * rtems_capture_flush
- *
- * DESCRIPTION:
- *
* This function flushes the capture buffer. The prime parameter allows the
* capture engine to also be primed again.
*/
@@ -1247,10 +1125,6 @@ rtems_capture_flush (bool prime)
}
/*
- * rtems_capture_watch_add
- *
- * DESCRIPTION:
- *
* This function defines a watch for a specific task given a name. A watch
* causes it to be traced either in or out of context. The watch can be
* optionally enabled or disabled with the set routine. It is disabled by
@@ -1279,10 +1153,6 @@ rtems_capture_watch_add (rtems_name name, rtems_id id)
}
/*
- * rtems_capture_watch_del
- *
- * DESCRIPTION:
- *
* This function removes a watch for a specific task given a name. The task
* description will still exist if referenced by a trace record in the trace
* buffer or a global watch is defined.
@@ -1335,10 +1205,6 @@ rtems_capture_watch_del (rtems_name name, rtems_id id)
}
/*
- * rtems_capture_watch_set
- *
- * DESCRIPTION:
- *
* This function allows control of a watch. The watch can be enabled or
* disabled.
*/
@@ -1377,10 +1243,6 @@ rtems_capture_watch_ctrl (rtems_name name, rtems_id id,
bool enable)
}
/*
- * rtems_capture_watch_global
- *
- * DESCRIPTION:
- *
* This function allows control of a global watch. The watch can be enabled or
* disabled. A global watch configures all tasks below the ceiling and above
* the floor to be traced.
@@ -1407,10 +1269,6 @@ rtems_capture_watch_global (bool enable)
}
/*
- * rtems_capture_watch_global_on
- *
- * DESCRIPTION:
- *
* This function returns the global watch state.
*/
bool
@@ -1420,10 +1278,6 @@ rtems_capture_watch_global_on (void)
}
/*
- * rtems_capture_watch_ceiling
- *
- * DESCRIPTION:
- *
* This function sets a watch ceiling. Tasks at or greating that the
* ceiling priority are not watched. This is a simple way to monitor
* an application and exclude system tasks running at a higher
@@ -1437,10 +1291,6 @@ rtems_capture_watch_ceiling (rtems_task_priority ceiling)
}
/*
- * rtems_capture_watch_get_ceiling
- *
- * DESCRIPTION:
- *
* This function gets the watch ceiling.
*/
rtems_task_priority
@@ -1450,10 +1300,6 @@ rtems_capture_watch_get_ceiling (void)
}
/*
- * rtems_capture_watch_floor
- *
- * DESCRIPTION:
- *
* This function sets a watch floor. Tasks at or less that the
* floor priority are not watched. This is a simple way to monitor
* an application and exclude system tasks running at a lower
@@ -1467,10 +1313,6 @@ rtems_capture_watch_floor (rtems_task_priority floor)
}
/*
- * rtems_capture_watch_get_floor
- *
- * DESCRIPTION:
- *
* This function gets the watch floor.
*/
rtems_task_priority
@@ -1480,12 +1322,7 @@ rtems_capture_watch_get_floor (void)
}
/*
- * rtems_capture_map_trigger
- *
- * DESCRIPTION:
- *
* Map the trigger to a bit mask.
- *
*/
static uint32_t
rtems_capture_map_trigger (rtems_capture_trigger_t trigger)
@@ -1516,10 +1353,6 @@ rtems_capture_map_trigger (rtems_capture_trigger_t
trigger)
}
/*
- * rtems_capture_set_trigger
- *
- * DESCRIPTION:
- *
* This function sets a trigger.
*
* This set trigger routine will create a capture control for the
@@ -1606,10 +1439,6 @@ rtems_capture_set_trigger (rtems_name
from_name,
}
/*
- * rtems_capture_clear_trigger
- *
- * DESCRIPTION:
- *
* This function clear a trigger.
*/
rtems_status_code
@@ -1680,10 +1509,6 @@ rtems_capture_clear_trigger (rtems_name
from_name,
}
/*
- * rtems_capture_read
- *
- * DESCRIPTION:
- *
* This function reads a number of records from the capture buffer.
* The user can optionally block and wait until the buffer as a
* specific number of records available or a specific time has
@@ -1708,7 +1533,6 @@ rtems_capture_clear_trigger (rtems_name
from_name,
*
* The 'timeout' parameter is in micro-seconds. A value of 0 will disable
* the timeout.
- *
*/
rtems_status_code
rtems_capture_read (uint32_t threshold,
@@ -1804,10 +1628,6 @@ rtems_capture_read (uint32_t threshold,
}
/*
- * rtems_capture_release
- *
- * DESCRIPTION:
- *
* This function releases the requested number of record slots back
* to the capture engine. The count must match the number read.
*/
@@ -1850,10 +1670,6 @@ rtems_capture_release (uint32_t count)
}
/*
- * rtems_capture_time
- *
- * DESCRIPTION:
- *
* This function returns the current time. If a handler is provided
* by the user get the time from that.
*/
@@ -1864,10 +1680,6 @@ rtems_capture_time (rtems_capture_time_t* uptime)
}
/*
- * rtems_capture_event_text
- *
- * DESCRIPTION:
- *
* This function returns a string for an event based on the bit in the
* event. The functions takes the bit offset as a number not the bit
* set in a bit map.
@@ -1881,10 +1693,6 @@ rtems_capture_event_text (int event)
}
/*
- * rtems_capture_get_task_list
- *
- * DESCRIPTION:
- *
* This function returns the head of the list of tasks that the
* capture engine has detected.
*/
@@ -1895,10 +1703,6 @@ rtems_capture_get_task_list (void)
}
/*
- * rtems_capture_task_stack_usage
- *
- * DESCRIPTION:
- *
* This function updates the stack usage. The task control block
* is updated.
*/
@@ -1931,10 +1735,6 @@ rtems_capture_task_stack_usage (rtems_capture_task_t*
task)
}
/*
- * rtems_capture_get_control_list
- *
- * DESCRIPTION:
- *
* This function returns the head of the list of control in the
* capture engine.
*/
diff --git a/cpukit/libmisc/capture/capture.h b/cpukit/libmisc/capture/capture.h
index 7663d8b..0326842 100644
--- a/cpukit/libmisc/capture/capture.h
+++ b/cpukit/libmisc/capture/capture.h
@@ -33,6 +33,14 @@
#ifndef __CAPTURE_H_
#define __CAPTURE_H_
+/**
+ * @defgroup libmisc_capture RTEMS Capture Engine
+ *
+ * @ingroup libmisc
+ *
+ * Capture Engine Component of the RTEMS Measurement and Monitoring System
+ */
+/**@{*/
#ifdef __cplusplus
extern "C" {
#endif
@@ -45,18 +53,14 @@ extern "C" {
#define RTEMS_CAPTURE_TRIGGER_TASKS (32)
/**
- * rtems_capture_time_t
- *
- * DESCRIPTION:
+ * @brief A capture timestamp.
*
- * A capture timestamp.
+ * This is a nanosecond capture timestamp
*/
typedef uint64_t rtems_capture_time_t;
/**
- * rtems_capture_from_t
- *
- * DESCRIPTION:
+ * @brief Task id and mask for the from trigger.
*
* A from capture is a task id and a mask for the type of
* from trigger we are interested in. The mask uses the same
@@ -72,9 +76,7 @@ typedef struct rtems_capture_from_s
} rtems_capture_from_t;
/**
- * rtems_capture_control_t
- *
- * DESCRIPTION:
+ * @brief Capture control structure for a group of tasks.
*
* RTEMS control holds the trigger and watch configuration for a group of
* tasks with the same name. The flags hold global control flags.
@@ -134,9 +136,7 @@ typedef struct rtems_capture_control_s
RTEMS_CAPTURE_EXITTED)
/**
- * rtems_capture_task_t
- *
- * DESCRIPTION:
+ * @brief Catpure task control
*
* RTEMS capture control provdes the information about a task, along
* with its trigger state. The control is referenced by each
@@ -179,11 +179,9 @@ typedef struct rtems_capture_task_s
#define RTEMS_CAPTURE_TRACED (1U << 0)
/*
- * rtems_capture_record_t
+ * @brief Capture record.
*
- * DESCRIPTION:
- *
- * RTEMS capture record. This is a record that is written into
+ * This is a record that is written into
* the buffer. The events includes the priority of the task
* at the time of the context switch.
*/
@@ -218,9 +216,7 @@ typedef struct rtems_capture_record_s
#define RTEMS_CAPTURE_EVENT_END (28)
/**
- * rtems_capture_trigger_mode_t
- *
- * DESCRIPTION:
+ * @brief Capture trigger modes
*
* The types of trigger modes that exist.
*/
@@ -232,9 +228,7 @@ typedef enum rtems_capture_trigger_mode_e
} rtems_capture_trigger_mode_t;
/**
- * rtems_capture_trigger_t
- *
- * DESCRIPTION:
+ * @brief Capture trigger.
*
* The types of triggers that exist.
*/
@@ -251,9 +245,7 @@ typedef enum rtems_capture_trigger_e
} rtems_capture_trigger_t;
/**
- * rtems_capture_timestamp
- *
- * DESCRIPTION:
+ * @brief Capture timestamp callout handler.
*
* This defines the callout handler to obtain a time stamp. The
* value returned is time count since the last read.
@@ -263,95 +255,131 @@ typedef enum rtems_capture_trigger_e
typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
/**
- * rtems_capture_open
- *
- * DESCRIPTION:
+ * @brief Capture open
*
* This function initialises the realtime trace manager allocating the
* capture buffer. It is assumed we have a working heap at stage of
* initialisation.
*
+ * @param[in] size The number of capture records to define.
+ * @param[in] timestamp The timestamp callout handler to use. If the
+ * the handler is NULL a default nano-second timestamp
+ * will be used.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_open (uint32_t size,
rtems_capture_timestamp timestamp);
/**
- * rtems_capture_close
- *
- * DESCRIPTION:
+ * @brief Capture close
*
* This function shutdowns the tracer and release any claimed
* resources.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_close (void);
/**
- * rtems_capture_control
- *
- * DESCRIPTION:
+ * @brief Capture control trace enable/disable.
*
* This function allows control of tracing at a global level.
+ *
+ * @param[in] enable The trace enable/disable flag.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_control (bool enable);
/**
- * rtems_capture_monitor
- *
- * DESCRIPTION:
+ * @brief Capture monitor enable/disable.
*
* This function enable the monitor mode. When in the monitor mode
* the tasks are monitored but no data is saved. This can be used
* to profile the load on a system.
+ *
+ * @param[in] enable The monitor enable/disable flag.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_monitor (bool enable);
/*
- * rtems_capture_flush
- *
- * DESCRIPTION:
+ * @brief Capture flush trace buffer.
*
* This function flushes the trace buffer. The prime parameter allows the
* capture engine to also be primed again.
+ *
+ * @param[in] prime The prime after flush flag.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_flush (bool prime);
/**
- * rtems_capture_watch_add
- *
- * DESCRIPTION:
+ * @brief Capture add watch
*
* This function defines a watch for a specific task given a name. A watch
* causes it to be traced either in or out of context. The watch can be
* optionally enabled or disabled with the set routine. It is disabled by
* default.
+ *
+ * @param[in] name The name of the @a capture_controls entry
+ * @param[in] id The id of the @a capture_controls entry.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_add (rtems_name name, rtems_id id);
/**
- * rtems_capture_watch_del
- *
- * DESCRIPTION:
+ * @brief Capture delete watch.
*
* This function removes a watch for a specific task given a name. The task
* description will still exist if referenced by a trace record in the trace
* buffer or a global watch is defined.
+ *
+ * @param[in] name The name of the @a capture_controls entry
+ * @param[in] id The id of the @a capture_controls entry.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_del (rtems_name name, rtems_id id);
/**
- * rtems_capture_watch_set
- *
- * DESCRIPTION:
+ * @brief Capture enable/disable watch.
*
* This function allows control of a watch. The watch can be enabled or
* disabled.
+ *
+ * @param[in] name The name of the @a capture_controls entry
+ * @param[in] id The id of the @a capture_controls entry.
+ * @param[in] enable The enable/disable flag for the watch.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_ctrl (rtems_name name,
@@ -359,77 +387,92 @@ rtems_capture_watch_ctrl (rtems_name name,
bool enable);
/**
- * rtems_capture_watch_global
- *
- * DESCRIPTION:
+ * @brief Capture enable/disable global watch.
*
* This function allows control of a global watch. The watch can
* be enabled or disabled. A global watch configures all tasks below
* the ceiling and above the floor to be traced.
+ *
+ * @param[in] enable The enable/disable flag for the watch.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_global (bool enable);
/**
- * rtems_capture_watch_global_on
- *
- * DESCRIPTION:
+ * @brief Get global watch state
*
* This function returns the global watch state.
+ *
+ * @retval This method returns true if the global watch
+ * is on. Otherwise, it returns false.
*/
bool
rtems_capture_watch_global_on (void);
/**
- * rtems_capture_watch_ceiling
- *
- * DESCRIPTION:
+ * @brief Set watch ceiling.
*
- * This function sets a watch ceiling. Tasks at or greating that the
- * ceiling priority are not watched. This is a simple way to monitor
- * an application and exclude system tasks running at a higher
+ * This function sets a watch ceiling. Events from tasks at or greater
+ * than the ceiling priority are ignored. This is a simple way to
+ * monitor an application and exclude system tasks running at a higher
* priority level.
+ *
+ * @param[in] ceiling specifies the priority level immediately above
+ * that at which events from tasks are not captured.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_ceiling (rtems_task_priority ceiling);
/**
- * rtems_capture_watch_get_ceiling
- *
- * DESCRIPTION:
+ * @brief Get watch ceiling.
*
* This function gets the watch ceiling.
+ *
+ * @retval The priority level immediately above that at which events
+ * from tasks are not captured.
*/
rtems_task_priority
rtems_capture_watch_get_ceiling (void);
/**
- * rtems_capture_watch_floor
- *
- * DESCRIPTION:
+ * @brief Capture set watch floor.
*
- * This function sets a watch floor. Tasks at or less that the
+ * This function sets a watch floor. Tasks at or less than the
* floor priority are not watched. This is a simple way to monitor
* an application and exclude system tasks running at a lower
* priority level.
+ *
+ * @param[in] floor specifies the priority level immediately below
+ * that at which events from tasks are not captured.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_watch_floor (rtems_task_priority floor);
/**
- * rtems_capture_watch_get_floor
- *
- * DESCRIPTION:
+ * @brief Capture set watch floor
*
* This function gets the watch floor.
+ *
+ * @retval The priority level immediately below
+ * that at which events from tasks are not captured.
*/
rtems_task_priority
rtems_capture_watch_get_floor (void);
/**
- * rtems_capture_set_trigger
- *
- * DESCRIPTION:
+ * @brief Capture set trigger
*
* This function sets a trigger.
*
@@ -440,6 +483,21 @@ rtems_capture_watch_get_floor (void);
* We can have a number of tasks that have the same name so we
* search using names. This means a number of tasks can be
* linked to single control.
+ *
+ * Some events captured such as context switch include two
+ * tasks. These are referred to as being "from" and "to"
+ * Some events may only have one task specified.
+ *
+ * @param[in] from_name specifies the name of the from task.
+ * @param[in] from_id specifies the id of the from task.
+ * @param[in] to_name specifies the name of the to task.
+ * @param[in] to_id specifies the id of the to task.
+ * @param[in] mode specifies the trigger mode.
+ * @param[in] trigger specifies the type of trigger.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_set_trigger (rtems_name from_name,
@@ -450,13 +508,22 @@ rtems_capture_set_trigger (rtems_name
from_name,
rtems_capture_trigger_t trigger);
/**
- * rtems_capture_clear_trigger
- *
- * DESCRIPTION:
+ * @brief Capture clear trigger.
*
* This function clears a trigger.
*
* This clear trigger routine will not clear a watch.
+ *
+ * @param[in] from_name specifies the name of the from task.
+ * @param[in] from_id specifies the id of the from task.
+ * @param[in] to_name specifies the name of the to task.
+ * @param[in] to_id specifies the id of the to task.
+ * @param[in] mode specifies the trigger mode.
+ * @param[in] trigger specifies the type of trigger.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_clear_trigger (rtems_name from_name,
@@ -467,9 +534,7 @@ rtems_capture_clear_trigger (rtems_name
from_name,
rtems_capture_trigger_t trigger);
/**
- * rtems_capture_read
- *
- * DESCRIPTION:
+ * @brief Capture read records from capture buffer
*
* This function reads a number of records from the capture buffer.
* The user can optionally block and wait until the buffer as a
@@ -493,9 +558,17 @@ rtems_capture_clear_trigger (rtems_name
from_name,
* thrashing occuring for a small number of records, yet allows
* a user configured latiency to be applied for single events.
*
- * The 'timeout' parameter is in micro-seconds. A value of 0 will
+ * The @a timeout parameter is in microseconds. A value of 0 will
* disable the timeout.
*
+ * @param[in] threshold The number of records that must be captured
+ * @param[in] timeout The micro-second timeout period
+ * @param[out] read will contain the number of records read
+ * @param[out] recs The capture records that are read.
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_read (uint32_t threshold,
@@ -504,56 +577,66 @@ rtems_capture_read (uint32_t threshold,
rtems_capture_record_t** recs);
/**
- * rtems_capture_release
- *
- * DESCRIPTION:
+ * @brief Capture release records.
*
* This function releases the requested number of record slots back
* to the capture engine. The count must match the number read.
+ *
+ * @param[in] count The number of record slots to release
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ * error. Otherwise, a status code is returned indicating the
+ * source of the error.
*/
rtems_status_code
rtems_capture_release (uint32_t count);
/*
- * rtems_capture_time
- *
- * DESCRIPTION:
+ * @brief Capture nano-second time period.
*
* This function returns the time period in nano-seconds.
+ *
+ * @param[out] uptime The nano-second time period.
*/
void
rtems_capture_time (rtems_capture_time_t* uptime);
/**
- * rtems_capture_event_text
- *
- * DESCRIPTION:
+ * @brief Capture get event text.
*
* This function returns a string for an event based on the bit in the
* event. The functions takes the bit offset as a number not the bit
* set in a bit map.
+ *
+ * @param[in] event specifies the event to describe
+ *
+ * @retval This method returns a string description of the given event.
*/
const char*
rtems_capture_event_text (int event);
/**
- * rtems_capture_get_task_list
- *
- * DESCRIPTION:
+ * @brief Capture get task list.
*
* This function returns the head of the list of tasks that the
* capture engine has detected.
+ *
+ * @retval This function returns the head of the list of tasks that
+ * the capture engine has detected.
*/
rtems_capture_task_t*
rtems_capture_get_task_list (void);
/**
- * rtems_capture_next_task
- *
- * DESCRIPTION:
+ * @brief Capture get next task in list.
*
* This function returns the pointer to the next task in the list. The
* pointer NULL terminates the list.
+ *
+ * @param[in] task The capture task to get the next entry from.
+ *
+ * @retval This function returns the pointer to the next task in the list. The
+ * pointer NULL terminates the list.
*/
static inline rtems_capture_task_t*
rtems_capture_next_task (rtems_capture_task_t* task)
@@ -562,12 +645,15 @@ rtems_capture_next_task (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_valid
- *
- * DESCRIPTION:
+ * @brief Capture is valid task control block
*
* This function returns true if the task control block points to
* a valid task.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns true if the task control block points to
+ * a valid task. Otherwise, it returns false.
*/
static inline bool
rtems_capture_task_valid (rtems_capture_task_t* task)
@@ -576,11 +662,13 @@ rtems_capture_task_valid (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_id
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task id.
+ *
* This function returns the task id.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task id.
*/
static inline rtems_id
rtems_capture_task_id (rtems_capture_task_t* task)
@@ -589,11 +677,13 @@ rtems_capture_task_id (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_state
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task state.
+ *
* This function returns the task state.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task state.
*/
static inline States_Control
rtems_capture_task_state (rtems_capture_task_t* task)
@@ -604,11 +694,13 @@ rtems_capture_task_state (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_name
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task name.
+ *
* This function returns the task name.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task name.
*/
static inline rtems_name
rtems_capture_task_name (rtems_capture_task_t* task)
@@ -617,11 +709,13 @@ rtems_capture_task_name (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_flags
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task flags.
+ *
* This function returns the task flags.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task flags.
*/
static inline uint32_t
rtems_capture_task_flags (rtems_capture_task_t* task)
@@ -630,11 +724,13 @@ rtems_capture_task_flags (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_control
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task control
+ *
* This function returns the task control if present.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task control if present.
*/
static inline rtems_capture_control_t*
rtems_capture_task_control (rtems_capture_task_t* task)
@@ -643,11 +739,13 @@ rtems_capture_task_control (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_control_flags
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task control flags.
+ *
* This function returns the task control flags if a control is present.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task control flags if a control is
present.
*/
static inline uint32_t
rtems_capture_task_control_flags (rtems_capture_task_t* task)
@@ -658,12 +756,15 @@ rtems_capture_task_control_flags (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_switched_in
- *
- * DESCRIPTION:
- *
+ * @brief Capture get number of times task switched in.
+ *
* This function returns the number of times the task has
* been switched into context.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the number of times the task has
+ * been switched into context.
*/
static inline uint32_t
rtems_capture_task_switched_in (rtems_capture_task_t* task)
@@ -672,12 +773,15 @@ rtems_capture_task_switched_in (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_switched_out
- *
- * DESCRIPTION:
- *
+ * @brief Capture get number of times task switched out.
+ *
* This function returns the number of times the task has
* been switched out of context.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the number of times the task has
+ * been switched out of context.
*/
static inline uint32_t
rtems_capture_task_switched_out (rtems_capture_task_t* task)
@@ -686,12 +790,15 @@ rtems_capture_task_switched_out (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_curr_priority
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task start priority.
+ *
* This function returns the tasks start priority. The tracer needs this
* to track where the task's priority goes.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the tasks start priority. The tracer needs
this
+ * to track where the task's priority goes.
*/
static inline rtems_task_priority
rtems_capture_task_start_priority (rtems_capture_task_t* task)
@@ -700,11 +807,13 @@ rtems_capture_task_start_priority (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_real_priority
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task real priority.
+ *
* This function returns the tasks real priority.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the tasks real priority.
*/
static inline rtems_task_priority
rtems_capture_task_real_priority (rtems_capture_task_t* task)
@@ -715,11 +824,13 @@ rtems_capture_task_real_priority (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_curr_priority
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task current priority.
+ *
* This function returns the tasks current priority.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the tasks current priority.
*/
static inline rtems_task_priority
rtems_capture_task_curr_priority (rtems_capture_task_t* task)
@@ -730,22 +841,27 @@ rtems_capture_task_curr_priority (rtems_capture_task_t*
task)
}
/**
- * rtems_capture_task_stack_usage
- *
- * DESCRIPTION:
- *
+ * @brief Capture update stack usage.
+ *
* This function updates the stack usage. The task control block
* is updated.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function updates the stack usage. The task control block
+ * is updated.
*/
uint32_t
rtems_capture_task_stack_usage (rtems_capture_task_t* task);
/**
- * rtems_capture_task_stack_size
- *
- * DESCRIPTION:
- *
+ * @brief Capture get stack size.
+ *
* This function returns the task's stack size.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the task's stack size.
*/
static inline uint32_t
rtems_capture_task_stack_size (rtems_capture_task_t* task)
@@ -754,11 +870,13 @@ rtems_capture_task_stack_size (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_stack_used
- *
- * DESCRIPTION:
- *
+ * @brief Capture get stack used.
+ *
* This function returns the amount of stack used.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the amount of stack used.
*/
static inline uint32_t
rtems_capture_task_stack_used (rtems_capture_task_t* task)
@@ -767,11 +885,13 @@ rtems_capture_task_stack_used (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_time
- *
- * DESCRIPTION:
- *
+ * @brief Capture get task execution time.
+ *
* This function returns the current execution time.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the current execution time.
*/
static inline uint64_t
rtems_capture_task_time (rtems_capture_task_t* task)
@@ -780,12 +900,15 @@ rtems_capture_task_time (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_delta_time
- *
- * DESCRIPTION:
- *
+ * @brief Capture get delta in execution time.
+ *
* This function returns the execution time as a different between the
* last time the detla time was and now.
+ *
+ * @param[in] task The capture task.
+ *
+ * @retval This function returns the execution time as a different between the
+ * last time the detla time was and now.
*/
static inline uint64_t
rtems_capture_task_delta_time (rtems_capture_task_t* task)
@@ -796,12 +919,13 @@ rtems_capture_task_delta_time (rtems_capture_task_t* task)
}
/**
- * rtems_capture_task_count
- *
- * DESCRIPTION:
+ * @brief Capture get task count.
*
* This function returns the number of tasks the capture
* engine knows about.
+ *
+ * @retval This function returns the number of tasks the capture
+ * engine knows about.
*/
static inline uint32_t
rtems_capture_task_count (void)
@@ -819,23 +943,27 @@ rtems_capture_task_count (void)
}
/**
- * rtems_capture_get_control_list
- *
- * DESCRIPTION:
+ * @brief Capture get control list.
*
* This function returns the head of the list of controls in the
* capture engine.
+ *
+ * @retval This function returns the head of the list of controls in the
+ * capture engine.
*/
rtems_capture_control_t*
rtems_capture_get_control_list (void);
/**
- * rtems_capture_next_control
- *
- * DESCRIPTION:
- *
+ * @brief Capture get next capture control.
+ *
* This function returns the pointer to the next control in the list. The
* pointer NULL terminates the list.
+ *
+ * @param[in] control the current capture control.
+ *
+ * @retval This function returns the pointer to the next control in the list.
The
+ * pointer NULL terminates the list.
*/
static inline rtems_capture_control_t*
rtems_capture_next_control (rtems_capture_control_t* control)
@@ -844,11 +972,13 @@ rtems_capture_next_control (rtems_capture_control_t*
control)
}
/**
- * rtems_capture_control_id
- *
- * DESCRIPTION:
- *
+ * @brief Capture get capture control id.
+ *
* This function returns the control id.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the control id.
*/
static inline rtems_id
rtems_capture_control_id (rtems_capture_control_t* control)
@@ -857,11 +987,13 @@ rtems_capture_control_id (rtems_capture_control_t*
control)
}
/**
- * rtems_capture_control_name
- *
- * DESCRIPTION:
+ * @brief Capture get capture control name.
*
* This function returns the control name.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the control name.
*/
static inline rtems_name
rtems_capture_control_name (rtems_capture_control_t* control)
@@ -870,11 +1002,13 @@ rtems_capture_control_name (rtems_capture_control_t*
control)
}
/**
- * rtems_capture_control_flags
- *
- * DESCRIPTION:
+ * @brief Capture get capture control flags.
*
* This function returns the control flags.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the control flags.
*/
static inline uint32_t
rtems_capture_control_flags (rtems_capture_control_t* control)
@@ -883,11 +1017,13 @@ rtems_capture_control_flags (rtems_capture_control_t*
control)
}
/**
- * rtems_capture_control_to_triggers
- *
- * DESCRIPTION:
+ * @brief Capture get capture control to triggers.
*
* This function returns the task control to triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control to triggers.
*/
static inline uint32_t
rtems_capture_control_to_triggers (rtems_capture_control_t* control)
@@ -896,11 +1032,13 @@ rtems_capture_control_to_triggers
(rtems_capture_control_t* control)
}
/**
- * rtems_capture_control_from_triggers
- *
- * DESCRIPTION:
+ * @brief Capture get capture control from triggers.
*
* This function returns the task control from triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control from triggers.
*/
static inline uint32_t
rtems_capture_control_from_triggers (rtems_capture_control_t* control)
@@ -909,11 +1047,13 @@ rtems_capture_control_from_triggers
(rtems_capture_control_t* control)
}
/**
- * rtems_capture_control_all_by_triggers
- *
- * DESCRIPTION:
+ * @brief Capture get capture control by triggers.
*
* This function returns the task control by triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control by triggers.
*/
static inline uint32_t
rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
@@ -922,11 +1062,14 @@ rtems_capture_control_all_by_triggers
(rtems_capture_control_t* control)
}
/**
- * rtems_capture_control_by_valid
- *
- * DESCRIPTION:
+ * @brief Capture get capture control valid by flags.
*
* This function returns the control valid BY flags.
+ *
+ * @param[in] control The capture control.
+ * @param[in] slot The XXX.
+ *
+ * @retval This function returns the control valid BY flags.
*/
static inline int
rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
@@ -935,11 +1078,14 @@ rtems_capture_control_by_valid (rtems_capture_control_t*
control, int slot)
}
/**
- * rtems_capture_control_by_name
+ * @brief Capture get capture control by task name.
*
- * DESCRIPTION:
+ * This function returns the control @a by task name.
*
- * This function returns the control BY task name.
+ * @param[in] control The capture control.
+ * @param[in] by The XXX.
+ *
+ * @retval This function returns the control @a by task name.
*/
static inline rtems_name
rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
@@ -950,11 +1096,11 @@ rtems_capture_control_by_name (rtems_capture_control_t*
control, int by)
}
/**
- * rtems_capture_control_by_id
- *
- * DESCRIPTION:
+ * @brief Capture get capture control by task id.
*
- * This function returns the control BY task id.
+ * This function returns the control @a by task id
+ *
+ * @retval This function returns the control @a by task id.
*/
static inline rtems_id
rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
@@ -965,11 +1111,11 @@ rtems_capture_control_by_id (rtems_capture_control_t*
control, int by)
}
/**
- * rtems_capture_control_by_triggers
+ * @brief Capture get capture control by task triggers.
*
- * DESCRIPTION:
+ * This function returns the control @a by task triggers.
*
- * This function returns the control BY task triggers.
+ * @retval This function returns the control @a by task triggers.
*/
static inline uint32_t
rtems_capture_control_by_triggers (rtems_capture_control_t* control,
@@ -981,12 +1127,13 @@ rtems_capture_control_by_triggers
(rtems_capture_control_t* control,
}
/**
- * rtems_capture_control_count
- *
- * DESCRIPTION:
+ * @brief Capture get capture control count.
*
* This function returns the number of controls the capture
* engine has.
+ *
+ * @retval This function returns the number of controls the capture
+ * engine has.
*/
static inline uint32_t
rtems_capture_control_count (void)
--
1.8.1.4
_______________________________________________
rtems-devel mailing list
rtems-devel@rtems.org
http://www.rtems.org/mailman/listinfo/rtems-devel
