Changeset 1af8634 in rtems


Ignore:
Timestamp:
Apr 11, 2014, 3:18:20 PM (5 years ago)
Author:
Jennifer Averett <jennifer.averett@…>
Branches:
4.11, master
Children:
463de59
Parents:
f0c8501
git-author:
Jennifer Averett <jennifer.averett@…> (04/11/14 15:18:20)
git-committer:
Jennifer Averett <jennifer.averett@…> (07/11/14 14:48:35)
Message:

capture: Update comment block style in capture engine.

Doxygen added and comment blocks standardized.

Location:
cpukit/libmisc/capture
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • cpukit/libmisc/capture/capture.c

    rf0c8501 r1af8634  
    110110
    111111/*
    112  * rtems_capture_get_time
    113  *
    114  *  DESCRIPTION:
    115  *
    116112 * This function returns the current time. If a handler is provided
    117113 * by the user get the time from that.
     
    129125
    130126/*
    131  * rtems_capture_match_names
    132  *
    133  *  DESCRIPTION:
    134  *
    135127 * This function compares rtems_names. It protects the
    136128 * capture engine from a change to the way names are supported
    137129 * in RTEMS.
    138  *
    139130 */
    140131static inline bool
     
    145136
    146137/*
    147  * rtems_capture_match_id
    148  *
    149  *  DESCRIPTION:
    150  *
    151138 * This function compares rtems_ids. It protects the
    152139 * capture engine from a change to the way id are supported
    153140 * in RTEMS.
    154  *
    155141 */
    156142static inline bool
     
    161147
    162148/*
    163  * rtems_capture_match_name_id
    164  *
    165  *  DESCRIPTION:
    166  *
    167149 * This function matches a name and/or id.
    168150 */
     
    187169
    188170/*
    189  * rtems_capture_dup_name
    190  *
    191  *  DESCRIPTION:
    192  *
    193171 * This function duplicates an rtems_names. It protects the
    194172 * capture engine from a change to the way names are supported
    195173 * in RTEMS.
    196  *
    197174 */
    198175static inline void
     
    203180
    204181/*
    205  * rtems_capture_by_in_to
    206  *
    207  *  DESCRIPTION:
    208  *
    209182 * This function sees if a BY control is in the BY names. The use
    210183 * of the valid_mask in this way assumes the number of trigger
    211184 * tasks is the number of bits in uint32_t.
    212  *
    213185 */
    214186static inline bool
     
    254226
    255227/*
    256  * rtems_capture_refcount_up
    257  *
    258  *  DESCRIPTION:
    259  *
    260228 * This function raises the reference count.
    261  *
    262229 */
    263230static inline void
     
    268235
    269236/*
    270  * rtems_capture_refcount_down
    271  *
    272  *  DESCRIPTION:
    273  *
    274237 * This function lowers the reference count and if the count
    275238 * reaches 0 the task control block is returned to the heap.
    276  *
    277239 */
    278240static inline void
     
    284246
    285247/*
    286  * rtems_capture_init_stack_usage
    287  *
    288  *  DESCRIPTION:
    289  *
    290248 * This function setups a stack so its usage can be monitored.
    291249 */
     
    309267
    310268/*
    311  * rtems_capture_find_control
    312  *
    313  *  DESCRIPTION:
    314  *
    315269 * This function searches for a trigger given a name.
    316  *
    317270 */
    318271static inline rtems_capture_control_t*
     
    328281
    329282/*
    330  * rtems_capture_create_control
    331  *
    332  *  DESCRIPTION:
    333  *
    334283 * This function creates a capture control for the capture engine.
    335  *
    336284 */
    337285static inline rtems_capture_control_t*
     
    386334
    387335/*
    388  * rtems_capture_create_capture_task
    389  *
    390  *  DESCRIPTION:
    391  *
    392336 * This function create the task control.
    393  *
    394337 */
    395338static inline rtems_capture_task_t*
     
    467410
    468411/*
    469  * rtems_capture_destroy_capture_task
    470  *
    471  *  DESCRIPTION:
    472  *
    473412 * This function destroy the task structure if the reference count
    474413 * is 0 and the tcb has been cleared signalling the task has been
    475414 * deleted.
    476  *
    477415 */
    478416static inline void
     
    505443
    506444/*
    507  * rtems_capture_record
    508  *
    509  *  DESCRIPTION:
    510  *
    511445 * This function records a capture record into the capture buffer.
    512  *
    513446 */
    514447static inline void
     
    530463
    531464    /*
    532      * Capure the record if we have an event that is always
     465     * Capture the record if we have an event that is always
    533466     * captured, or the task's real priority is greater than the
    534467     * watch ceiling, and the global watch or task watch is enabled.
    535468     */
    536 
    537469    if ((events & RTEMS_CAPTURE_RECORD_EVENTS) ||
    538470        ((task->tcb->real_priority >= capture_ceiling) &&
     
    573505
    574506/*
    575  * rtems_capture_trigger
    576  *
    577  *  DESCRIPTION:
    578  *
    579507 * See if we have triggered and if not see if this event is a
    580508 * cause of a trigger.
     
    646574
    647575/*
    648  * rtems_capture_create_task
    649  *
    650  *  DESCRIPTION:
    651  *
    652576 * This function is called when a task is created.
    653  *
    654577 */
    655578static bool
     
    685608
    686609/*
    687  * rtems_capture_start_task
    688  *
    689  *  DESCRIPTION:
    690  *
    691610 * This function is called when a task is started.
    692  *
    693611 */
    694612static void
     
    727645
    728646/*
    729  * rtems_capture_restart_task
    730  *
    731  *  DESCRIPTION:
    732  *
    733647 * This function is called when a task is restarted.
    734  *
    735648 */
    736649static void
     
    770683
    771684/*
    772  * rtems_capture_delete_task
    773  *
    774  *  DESCRIPTION:
    775  *
    776685 * This function is called when a task is deleted.
    777  *
    778686 */
    779687static void
     
    820728
    821729/*
    822  * rtems_capture_begin_task
    823  *
    824  *  DESCRIPTION:
    825  *
    826730 * This function is called when a task is begun.
    827  *
    828731 */
    829732static void
     
    851754
    852755/*
    853  * rtems_capture_exitted_task
    854  *
    855  *  DESCRIPTION:
    856  *
    857756 * This function is called when a task is exitted. That is
    858757 * returned rather than was deleted.
    859  *
    860758 */
    861759static void
     
    885783
    886784/*
    887  * rtems_capture_switch_task
    888  *
    889  *  DESCRIPTION:
    890  *
     785 * This function is called when a termination request is identified.
     786 */
     787static void
     788rtems_capture_terminated_task (rtems_tcb* terminated_task)
     789{
     790  rtems_capture_delete_task (terminated_task, terminated_task);
     791}
     792
     793/*
     794 * This function is called when a fatal error occurs.
     795 */
     796static void
     797rtems_capture_fatal(
     798  Internal_errors_Source source,
     799  bool                   is_internal,
     800  Internal_errors_t      code
     801)
     802{
     803}
     804 
     805/*
    891806 * This function is called when a context is switched.
    892  *
    893807 */
    894808static void
     
    968882
    969883/*
    970  * rtems_capture_open
    971  *
    972  *  DESCRIPTION:
    973  *
    974884 * This function initialises the realtime capture engine allocating the trace
    975885 * buffer. It is assumed we have a working heap at stage of initialisation.
    976  *
    977886 */
    978887rtems_status_code
     
    1042951
    1043952/*
    1044  * rtems_capture_close
    1045  *
    1046  *  DESCRIPTION:
    1047  *
    1048953 * This function shutdowns the capture engine and release any claimed
    1049954 * resources.
     
    11131018
    11141019/*
    1115  * rtems_capture_control
    1116  *
    1117  *  DESCRIPTION:
    1118  *
    11191020 * This function allows control of tracing at a global level.
    11201021 */
     
    11511052
    11521053/*
    1153  * rtems_capture_monitor
    1154  *
    1155  *  DESCRIPTION:
    1156  *
    11571054 * This function enable the monitor mode. When in the monitor mode
    11581055 * the tasks are monitored but no data is saved. This can be used
     
    11831080
    11841081/*
    1185  * rtems_capture_flush
    1186  *
    1187  *  DESCRIPTION:
    1188  *
    11891082 * This function flushes the capture buffer. The prime parameter allows the
    11901083 * capture engine to also be primed again.
     
    12281121
    12291122/*
    1230  * rtems_capture_watch_add
    1231  *
    1232  *  DESCRIPTION:
    1233  *
    12341123 * This function defines a watch for a specific task given a name. A watch
    12351124 * causes it to be traced either in or out of context. The watch can be
     
    12601149
    12611150/*
    1262  * rtems_capture_watch_del
    1263  *
    1264  *  DESCRIPTION:
    1265  *
    12661151 * This function removes a watch for a specific task given a name. The task
    12671152 * description will still exist if referenced by a trace record in the trace
     
    13161201
    13171202/*
    1318  * rtems_capture_watch_set
    1319  *
    1320  *  DESCRIPTION:
    1321  *
    13221203 * This function allows control of a watch. The watch can be enabled or
    13231204 * disabled.
     
    13581239
    13591240/*
    1360  * rtems_capture_watch_global
    1361  *
    1362  *  DESCRIPTION:
    1363  *
    13641241 * This function allows control of a global watch. The watch can be enabled or
    13651242 * disabled. A global watch configures all tasks below the ceiling and above
     
    13881265
    13891266/*
    1390  * rtems_capture_watch_global_on
    1391  *
    1392  *  DESCRIPTION:
    1393  *
    13941267 * This function returns the global watch state.
    13951268 */
     
    14011274
    14021275/*
    1403  * rtems_capture_watch_ceiling
    1404  *
    1405  *  DESCRIPTION:
    1406  *
    14071276 * This function sets a watch ceiling. Tasks at or greating that the
    14081277 * ceiling priority are not watched. This is a simple way to monitor
     
    14181287
    14191288/*
    1420  * rtems_capture_watch_get_ceiling
    1421  *
    1422  *  DESCRIPTION:
    1423  *
    14241289 * This function gets the watch ceiling.
    14251290 */
     
    14311296
    14321297/*
    1433  * rtems_capture_watch_floor
    1434  *
    1435  *  DESCRIPTION:
    1436  *
    14371298 * This function sets a watch floor. Tasks at or less that the
    14381299 * floor priority are not watched. This is a simple way to monitor
     
    14481309
    14491310/*
    1450  * rtems_capture_watch_get_floor
    1451  *
    1452  *  DESCRIPTION:
    1453  *
    14541311 * This function gets the watch floor.
    14551312 */
     
    14611318
    14621319/*
    1463  * rtems_capture_map_trigger
    1464  *
    1465  *  DESCRIPTION:
    1466  *
    14671320 * Map the trigger to a bit mask.
    1468  *
    14691321 */
    14701322static uint32_t
     
    14971349
    14981350/*
    1499  * rtems_capture_set_trigger
    1500  *
    1501  *  DESCRIPTION:
    1502  *
    15031351 * This function sets a trigger.
    15041352 *
     
    15871435
    15881436/*
    1589  * rtems_capture_clear_trigger
    1590  *
    1591  *  DESCRIPTION:
    1592  *
    15931437 * This function clear a trigger.
    15941438 */
     
    16611505
    16621506/*
    1663  * rtems_capture_read
    1664  *
    1665  *  DESCRIPTION:
    1666  *
    16671507 * This function reads a number of records from the capture buffer.
    16681508 * The user can optionally block and wait until the buffer as a
     
    16891529 * The 'timeout' parameter is in micro-seconds. A value of 0 will disable
    16901530 * the timeout.
    1691  *
    16921531 */
    16931532rtems_status_code
     
    17851624
    17861625/*
    1787  * rtems_capture_release
    1788  *
    1789  *  DESCRIPTION:
    1790  *
    17911626 * This function releases the requested number of record slots back
    17921627 * to the capture engine. The count must match the number read.
     
    18311666
    18321667/*
    1833  * rtems_capture_time
    1834  *
    1835  *  DESCRIPTION:
    1836  *
    18371668 * This function returns the current time. If a handler is provided
    18381669 * by the user get the time from that.
     
    18451676
    18461677/*
    1847  * rtems_capture_event_text
    1848  *
    1849  *  DESCRIPTION:
    1850  *
    18511678 * This function returns a string for an event based on the bit in the
    18521679 * event. The functions takes the bit offset as a number not the bit
     
    18621689
    18631690/*
    1864  * rtems_capture_get_task_list
    1865  *
    1866  *  DESCRIPTION:
    1867  *
    18681691 * This function returns the head of the list of tasks that the
    18691692 * capture engine has detected.
     
    18761699
    18771700/*
    1878  * rtems_capture_task_stack_usage
    1879  *
    1880  *  DESCRIPTION:
    1881  *
    18821701 * This function updates the stack usage. The task control block
    18831702 * is updated.
     
    19121731
    19131732/*
    1914  * rtems_capture_get_control_list
    1915  *
    1916  *  DESCRIPTION:
    1917  *
    19181733 * This function returns the head of the list of control in the
    19191734 * capture engine.
  • cpukit/libmisc/capture/capture.h

    rf0c8501 r1af8634  
    3434#define __CAPTURE_H_
    3535
     36/**
     37 *  @defgroup libmisc_capture RTEMS Capture Engine
     38 *
     39 *  @ingroup libmisc
     40 *
     41 *  Capture Engine Component of the RTEMS Measurement and Monitoring System
     42 */
     43/**@{*/
    3644#ifdef __cplusplus
    3745extern "C" {
     
    4654
    4755/**
    48  * rtems_capture_time_t
    49  *
    50  * DESCRIPTION:
    51  *
    52  * A capture timestamp.
     56 * @brief A capture timestamp.
     57 *
     58 * This is a nanosecond capture timestamp
    5359 */
    5460typedef uint64_t rtems_capture_time_t;
    5561
    5662/**
    57  * rtems_capture_from_t
    58  *
    59  *  DESCRIPTION:
     63 * @brief Task id and mask for the from trigger.
    6064 *
    6165 * A from capture is a task id and a mask for the type of
     
    7377
    7478/**
    75  * rtems_capture_control_t
    76  *
    77  *  DESCRIPTION:
     79 * @brief Capture control structure for a group of tasks.
    7880 *
    7981 * RTEMS control holds the trigger and watch configuration for a group of
     
    135137
    136138/**
    137  * rtems_capture_task_t
    138  *
    139  *  DESCRIPTION:
     139 * @brief Catpure task control
    140140 *
    141141 * RTEMS capture control provdes the information about a task, along
     
    180180
    181181/*
    182  * rtems_capture_record_t
    183  *
    184  *  DESCRIPTION:
    185  *
    186  * RTEMS capture record. This is a record that is written into
     182 * @brief Capture record.
     183 *
     184 * This is a record that is written into
    187185 * the buffer. The events includes the priority of the task
    188186 * at the time of the context switch.
     
    219217
    220218/**
    221  * rtems_capture_trigger_mode_t
    222  *
    223  *  DESCRIPTION:
     219 * @brief Capture trigger modes
    224220 *
    225221 * The types of trigger modes that exist.
     
    233229
    234230/**
    235  * rtems_capture_trigger_t
    236  *
    237  *  DESCRIPTION:
     231 * @brief Capture trigger.
    238232 *
    239233 * The types of triggers that exist.
     
    251245
    252246/**
    253  * rtems_capture_timestamp
    254  *
    255  *  DESCRIPTION:
     247 * @brief Capture timestamp callout handler.
    256248 *
    257249 * This defines the callout handler to obtain a time stamp. The
     
    263255
    264256/**
    265  * rtems_capture_open
    266  *
    267  *  DESCRIPTION:
     257 * @brief Capture open
    268258 *
    269259 * This function initialises the realtime trace manager allocating the
     
    271261 * initialisation.
    272262 *
     263 * @param[in] size The number of capture records to define.
     264 * @param[in] timestamp The timestamp callout handler to use. If the
     265 *            the handler is NULL a default  nano-second timestamp
     266 *            will be used.
     267 *
     268 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     269 *         error. Otherwise, a status code is returned indicating the
     270 *         source of the error.
    273271 */
    274272rtems_status_code
     
    277275
    278276/**
    279  * rtems_capture_close
    280  *
    281  *  DESCRIPTION:
     277 * @brief Capture close
    282278 *
    283279 * This function shutdowns the tracer and release any claimed
    284280 * resources.
     281 *
     282 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     283 *         error. Otherwise, a status code is returned indicating the
     284 *         source of the error.
    285285 */
    286286rtems_status_code
     
    288288
    289289/**
    290  * rtems_capture_control
    291  *
    292  *  DESCRIPTION:
     290 * @brief Capture control trace enable/disable.
    293291 *
    294292 * This function allows control of tracing at a global level.
     293 *
     294 * @param[in]  enable The trace enable/disable flag.
     295 *
     296 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     297 *         error. Otherwise, a status code is returned indicating the
     298 *         source of the error.
    295299 */
    296300rtems_status_code
     
    298302
    299303/**
    300  * rtems_capture_monitor
    301  *
    302  *  DESCRIPTION:
     304 * @brief Capture monitor enable/disable.
    303305 *
    304306 * This function enable the monitor mode. When in the monitor mode
    305307 * the tasks are monitored but no data is saved. This can be used
    306308 * to profile the load on a system.
     309 *
     310 * @param[in]  enable The monitor enable/disable flag.
     311 *
     312 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     313 *         error. Otherwise, a status code is returned indicating the
     314 *         source of the error.
    307315 */
    308316rtems_status_code
     
    310318
    311319/*
    312  * rtems_capture_flush
    313  *
    314  *  DESCRIPTION:
     320 * @brief Capture flush trace buffer.
    315321 *
    316322 * This function flushes the trace buffer. The prime parameter allows the
    317323 * capture engine to also be primed again.
     324 *
     325 * @param[in]  prime The prime after flush flag.
     326 *
     327 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     328 *         error. Otherwise, a status code is returned indicating the
     329 *         source of the error.
    318330 */
    319331rtems_status_code
     
    321333
    322334/**
    323  * rtems_capture_watch_add
    324  *
    325  *  DESCRIPTION:
     335 * @brief Capture add watch
    326336 *
    327337 * This function defines a watch for a specific task given a name. A watch
     
    329339 * optionally enabled or disabled with the set routine. It is disabled by
    330340 * default.
     341 *
     342 * @param[in]  name The name of the @a capture_controls entry
     343 * @param[in]  id The id of the @a capture_controls entry.
     344 *
     345 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     346 *         error. Otherwise, a status code is returned indicating the
     347 *         source of the error.
    331348 */
    332349rtems_status_code
     
    334351
    335352/**
    336  * rtems_capture_watch_del
    337  *
    338  *  DESCRIPTION:
     353 * @brief Capture delete watch.
    339354 *
    340355 * This function removes a watch for a specific task given a name. The task
    341356 * description will still exist if referenced by a trace record in the trace
    342357 * buffer or a global watch is defined.
     358 *
     359 * @param[in]  name The name of the @a capture_controls entry
     360 * @param[in]  id The id of the @a capture_controls entry.
     361 *
     362 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     363 *         error. Otherwise, a status code is returned indicating the
     364 *         source of the error.
    343365 */
    344366rtems_status_code
     
    346368
    347369/**
    348  * rtems_capture_watch_set
    349  *
    350  *  DESCRIPTION:
     370 * @brief Capture enable/disable watch.
    351371 *
    352372 * This function allows control of a watch. The watch can be enabled or
    353373 * disabled.
     374 *
     375 * @param[in]  name The name of the @a capture_controls entry
     376 * @param[in]  id The id of the @a capture_controls entry.
     377 * @param[in]  enable The enable/disable flag for the watch.
     378 *
     379 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     380 *         error. Otherwise, a status code is returned indicating the
     381 *         source of the error.
    354382 */
    355383rtems_status_code
     
    359387
    360388/**
    361  * rtems_capture_watch_global
    362  *
    363  *  DESCRIPTION:
     389 * @brief Capture enable/disable global watch.
    364390 *
    365391 * This function allows control of a global watch. The watch can
    366392 * be enabled or disabled. A global watch configures all tasks below
    367393 * the ceiling and above the floor to be traced.
     394 *
     395 * @param[in]  enable The enable/disable flag for the watch.
     396 *
     397 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     398 *         error. Otherwise, a status code is returned indicating the
     399 *         source of the error.
    368400 */
    369401rtems_status_code
     
    371403
    372404/**
    373  * rtems_capture_watch_global_on
    374  *
    375  *  DESCRIPTION:
     405 * @brief Get global watch state
    376406 *
    377407 * This function returns the global watch state.
     408 *
     409 * @retval This method returns true  if the global watch
     410 *         is on.  Otherwise, it returns false.
    378411 */
    379412bool
     
    381414
    382415/**
    383  * rtems_capture_watch_ceiling
    384  *
    385  *  DESCRIPTION:
    386  *
    387  * This function sets a watch ceiling. Tasks at or greating that the
    388  * ceiling priority are not watched. This is a simple way to monitor
    389  * an application and exclude system tasks running at a higher
     416 * @brief Set watch ceiling.
     417 *
     418 * This function sets a watch ceiling. Events from tasks at or greater
     419 * than the ceiling priority are ignored. This is a simple way to
     420 * monitor an application and exclude system tasks running at a higher
    390421 * priority level.
     422 *
     423 * @param[in] ceiling specifies the priority level immediately above
     424 *     that at which events from tasks are not captured.
     425 *
     426 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     427 *         error. Otherwise, a status code is returned indicating the
     428 *         source of the error.
    391429 */
    392430rtems_status_code
     
    394432
    395433/**
    396  * rtems_capture_watch_get_ceiling
    397  *
    398  *  DESCRIPTION:
     434 * @brief Get watch ceiling.
    399435 *
    400436 * This function gets the watch ceiling.
     437 *
     438 * @retval The priority level immediately above that at which events
     439 *         from tasks are not captured.
    401440 */
    402441rtems_task_priority
     
    404443
    405444/**
    406  * rtems_capture_watch_floor
    407  *
    408  *  DESCRIPTION:
    409  *
    410  * This function sets a watch floor. Tasks at or less that the
     445 * @brief Capture set watch floor.
     446 *
     447 * This function sets a watch floor. Tasks at or less than the
    411448 * floor priority are not watched. This is a simple way to monitor
    412449 * an application and exclude system tasks running at a lower
    413450 * priority level.
     451 *
     452 * @param[in] floor specifies the priority level immediately below
     453 *     that at which events from tasks are not captured.
     454 *
     455 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     456 *         error. Otherwise, a status code is returned indicating the
     457 *         source of the error.
    414458 */
    415459rtems_status_code
     
    417461
    418462/**
    419  * rtems_capture_watch_get_floor
    420  *
    421  *  DESCRIPTION:
     463 * @brief Capture set watch floor
    422464 *
    423465 * This function gets the watch floor.
     466 *
     467 * @retval The priority level immediately below
     468 *     that at which events from tasks are not captured.
    424469 */
    425470rtems_task_priority
     
    427472
    428473/**
    429  * rtems_capture_set_trigger
    430  *
    431  *  DESCRIPTION:
     474 * @brief Capture set trigger
    432475 *
    433476 * This function sets a trigger.
     
    440483 * search using names. This means a number of tasks can be
    441484 * linked to single control.
     485 *
     486 * Some events captured such as context switch include two
     487 * tasks. These are referred to as being "from" and "to"
     488 * Some events may only have one task specified.
     489 *
     490 * @param[in] from_name specifies the name of the from task.
     491 * @param[in] from_id specifies the id of the from task.
     492 * @param[in] to_name specifies the name of the to task.
     493 * @param[in] to_id specifies the id of the to task.
     494 * @param[in] mode specifies the trigger mode.
     495 * @param[in] trigger specifies the type of trigger.
     496 *
     497 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     498 *         error. Otherwise, a status code is returned indicating the
     499 *         source of the error.
    442500 */
    443501rtems_status_code
     
    450508
    451509/**
    452  * rtems_capture_clear_trigger
    453  *
    454  *  DESCRIPTION:
     510 * @brief Capture clear trigger.
    455511 *
    456512 * This function clears a trigger.
    457513 *
    458514 * This clear trigger routine will not clear a watch.
     515 *
     516 * @param[in] from_name specifies the name of the from task.
     517 * @param[in] from_id specifies the id of the from task.
     518 * @param[in] to_name specifies the name of the to task.
     519 * @param[in] to_id specifies the id of the to task.
     520 * @param[in] mode specifies the trigger mode.
     521 * @param[in] trigger specifies the type of trigger.
     522 *
     523 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     524 *         error. Otherwise, a status code is returned indicating the
     525 *         source of the error.
    459526 */
    460527rtems_status_code
     
    467534
    468535/**
    469  * rtems_capture_read
    470  *
    471  *  DESCRIPTION:
     536 * @brief Capture read records from capture buffer
    472537 *
    473538 * This function reads a number of records from the capture buffer.
     
    493558 * a user configured latiency to be applied for single events.
    494559 *
    495  * The 'timeout' parameter is in micro-seconds. A value of 0 will
     560 * The @a timeout parameter is in microseconds. A value of 0 will
    496561 * disable the timeout.
    497562 *
     563 * @param[in] threshold The number of records that must be captured
     564 * @param[in] timeout The micro-second timeout period
     565 * @param[out] read will contain the number of records read
     566 * @param[out] recs The capture records that are read.
     567 *
     568 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     569 *         error. Otherwise, a status code is returned indicating the
     570 *         source of the error.
    498571 */
    499572rtems_status_code
     
    504577
    505578/**
    506  * rtems_capture_release
    507  *
    508  *  DESCRIPTION:
     579 * @brief Capture release records.
    509580 *
    510581 * This function releases the requested number of record slots back
    511582 * to the capture engine. The count must match the number read.
     583 *
     584 * @param[in] count The number of record slots to release
     585 *
     586 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
     587 *         error. Otherwise, a status code is returned indicating the
     588 *         source of the error.
    512589 */
    513590rtems_status_code
     
    515592
    516593/*
    517  * rtems_capture_time
    518  *
    519  *  DESCRIPTION:
     594 * @brief Capture nano-second time period.
    520595 *
    521596 * This function returns the time period in nano-seconds.
     597 *
     598 * @param[out] uptime The nano-second time period.
    522599 */
    523600void
     
    525602
    526603/**
    527  * rtems_capture_event_text
    528  *
    529  *  DESCRIPTION:
     604 * @brief Capture get event text.
    530605 *
    531606 * This function returns a string for an event based on the bit in the
    532607 * event. The functions takes the bit offset as a number not the bit
    533608 * set in a bit map.
     609 *
     610 * @param[in] event specifies the event to describe
     611 *
     612 * @retval This method returns a string description of the given event.
    534613 */
    535614const char*
     
    537616
    538617/**
    539  * rtems_capture_get_task_list
    540  *
    541  *  DESCRIPTION:
     618 * @brief Capture get task list.
    542619 *
    543620 * This function returns the head of the list of tasks that the
    544621 * capture engine has detected.
     622 *
     623 * @retval  This function returns the head of the list of tasks that
     624 *          the capture engine has detected.
    545625 */
    546626rtems_capture_task_t*
     
    548628
    549629/**
    550  * rtems_capture_next_task
    551  *
    552  *  DESCRIPTION:
     630 * @brief Capture get next task in list.
    553631 *
    554632 * This function returns the pointer to the next task in the list. The
    555633 * pointer NULL terminates the list.
     634 *
     635 * @param[in] task The capture task to get the next entry from.
     636 *
     637 * @retval This function returns the pointer to the next task in the list. The
     638 * pointer NULL terminates the list.
    556639 */
    557640static inline rtems_capture_task_t*
     
    562645
    563646/**
    564  * rtems_capture_task_valid
    565  *
    566  *  DESCRIPTION:
     647 * @brief Capture is valid task control block
    567648 *
    568649 * This function returns true if the task control block points to
    569650 * a valid task.
     651 *
     652 * @param[in] task The capture task.
     653 *
     654 * @retval This function returns true if the task control block points to
     655 * a valid task. Otherwise, it returns false.
    570656 */
    571657static inline bool
     
    576662
    577663/**
    578  * rtems_capture_task_id
    579  *
    580  *  DESCRIPTION:
    581  *
     664 * @brief Capture get task id.
     665 *
    582666 * This function returns the task id.
     667 *
     668 * @param[in] task The capture task.
     669 *
     670 * @retval This function returns the task id.
    583671 */
    584672static inline rtems_id
     
    589677
    590678/**
    591  * rtems_capture_task_state
    592  *
    593  *  DESCRIPTION:
    594  *
     679 * @brief Capture get task state.
     680 *
    595681 * This function returns the task state.
     682 *
     683 * @param[in] task The capture task.
     684 *
     685 * @retval This function returns the task state.
    596686 */
    597687static inline States_Control
     
    604694
    605695/**
    606  * rtems_capture_task_name
    607  *
    608  *  DESCRIPTION:
    609  *
     696 * @brief Capture get task name.
     697 *
    610698 * This function returns the task name.
     699 *
     700 * @param[in] task The capture task.
     701 *
     702 * @retval This function returns the task name.
    611703 */
    612704static inline rtems_name
     
    617709
    618710/**
    619  * rtems_capture_task_flags
    620  *
    621  *  DESCRIPTION:
    622  *
     711 * @brief Capture get task flags.
     712 *
    623713 * This function returns the task flags.
     714 *
     715 * @param[in] task The capture task.
     716 *
     717 * @retval This function returns the task flags.
    624718 */
    625719static inline uint32_t
     
    630724
    631725/**
    632  * rtems_capture_task_control
    633  *
    634  *  DESCRIPTION:
    635  *
     726 * @brief Capture get task control
     727 *
    636728 * This function returns the task control if present.
     729 *
     730 * @param[in] task The capture task.
     731 *
     732 * @retval This function returns the task control if present.
    637733 */
    638734static inline rtems_capture_control_t*
     
    643739
    644740/**
    645  * rtems_capture_task_control_flags
    646  *
    647  *  DESCRIPTION:
    648  *
     741 * @brief Capture get task control flags.
     742 *
    649743 * This function returns the task control flags if a control is present.
     744 *
     745 * @param[in] task The capture task.
     746 *
     747 * @retval This function returns the task control flags if a control is present.
    650748 */
    651749static inline uint32_t
     
    658756
    659757/**
    660  * rtems_capture_task_switched_in
    661  *
    662  *  DESCRIPTION:
    663  *
     758 * @brief Capture get number of times task switched in.
     759 *
    664760 * This function returns the number of times the task has
    665761 * been switched into context.
     762 *
     763 * @param[in] task The capture task.
     764 *
     765 * @retval This function returns the number of times the task has
     766 * been switched into context.
    666767 */
    667768static inline uint32_t
     
    672773
    673774/**
    674  * rtems_capture_task_switched_out
    675  *
    676  *  DESCRIPTION:
    677  *
     775 * @brief Capture get number of times task switched out.
     776 *
    678777 * This function returns the number of times the task has
    679778 * been switched out of context.
     779 *
     780 * @param[in] task The capture task.
     781 *
     782 * @retval This function returns the number of times the task has
     783 * been switched out of context.
    680784 */
    681785static inline uint32_t
     
    686790
    687791/**
    688  * rtems_capture_task_curr_priority
    689  *
    690  *  DESCRIPTION:
    691  *
     792 * @brief Capture get task start priority.
     793 *
    692794 * This function returns the tasks start priority. The tracer needs this
    693795 * to track where the task's priority goes.
     796 *
     797 * @param[in] task The capture task.
     798 *
     799 * @retval This function returns the tasks start priority. The tracer needs this
     800 * to track where the task's priority goes.
    694801 */
    695802static inline rtems_task_priority
     
    700807
    701808/**
    702  * rtems_capture_task_real_priority
    703  *
    704  *  DESCRIPTION:
    705  *
     809 * @brief Capture get task real priority.
     810 *
    706811 * This function returns the tasks real priority.
     812 *
     813 * @param[in] task The capture task.
     814 *
     815 * @retval This function returns the tasks real priority.
    707816 */
    708817static inline rtems_task_priority
     
    715824
    716825/**
    717  * rtems_capture_task_curr_priority
    718  *
    719  *  DESCRIPTION:
    720  *
     826 * @brief Capture get task current priority.
     827 *
    721828 * This function returns the tasks current priority.
     829 *
     830 * @param[in] task The capture task.
     831 *
     832 * @retval This function returns the tasks current priority.
    722833 */
    723834static inline rtems_task_priority
     
    730841
    731842/**
    732  * rtems_capture_task_stack_usage
    733  *
    734  *  DESCRIPTION:
    735  *
     843 * @brief Capture update stack usage.
     844 *
    736845 * This function updates the stack usage. The task control block
    737846 * is updated.
     847 *
     848 * @param[in] task The capture task.
     849 *
     850 * @retval This function updates the stack usage. The task control block
     851 * is updated.
    738852 */
    739853uint32_t
     
    741855
    742856/**
    743  * rtems_capture_task_stack_size
    744  *
    745  *  DESCRIPTION:
    746  *
     857 * @brief Capture get stack size.
     858 *
    747859 * This function returns the task's stack size.
     860 *
     861 * @param[in] task The capture task.
     862 *
     863 * @retval This function returns the task's stack size.
    748864 */
    749865static inline uint32_t
     
    754870
    755871/**
    756  * rtems_capture_task_stack_used
    757  *
    758  *  DESCRIPTION:
    759  *
     872 * @brief Capture get stack used.
     873 *
    760874 * This function returns the amount of stack used.
     875 *
     876 * @param[in] task The capture task.
     877 *
     878 * @retval This function returns the amount of stack used.
    761879 */
    762880static inline uint32_t
     
    767885
    768886/**
    769  * rtems_capture_task_time
    770  *
    771  *  DESCRIPTION:
    772  *
     887 * @brief Capture get task execution time.
     888 *
    773889 * This function returns the current execution time.
     890 *
     891 * @param[in] task The capture task.
     892 *
     893 * @retval This function returns the current execution time.
    774894 */
    775895static inline uint64_t
     
    780900
    781901/**
    782  * rtems_capture_task_delta_time
    783  *
    784  *  DESCRIPTION:
    785  *
     902 * @brief Capture get delta in execution time.
     903 *
    786904 * This function returns the execution time as a different between the
     905 * last time the detla time was and now.
     906 *
     907 * @param[in] task The capture task.
     908 *
     909 * @retval This function returns the execution time as a different between the
    787910 * last time the detla time was and now.
    788911 */
     
    796919
    797920/**
    798  * rtems_capture_task_count
    799  *
    800  *  DESCRIPTION:
     921 * @brief Capture get task count.
    801922 *
    802923 * This function returns the number of tasks the capture
     924 * engine knows about.
     925 *
     926 * @retval This function returns the number of tasks the capture
    803927 * engine knows about.
    804928 */
     
    819943
    820944/**
    821  * rtems_capture_get_control_list
    822  *
    823  *  DESCRIPTION:
     945 * @brief Capture get control list.
    824946 *
    825947 * This function returns the head of the list of controls in the
    826948 * capture engine.
     949 *
     950 * @retval This function returns the head of the list of controls in the
     951 * capture engine.
    827952 */
    828953rtems_capture_control_t*
     
    830955
    831956/**
    832  * rtems_capture_next_control
    833  *
    834  *  DESCRIPTION:
    835  *
     957 * @brief Capture get next capture control.
     958 *
    836959 * This function returns the pointer to the next control in the list. The
    837960 * pointer NULL terminates the list.
     961 *
     962 * @param[in] control the current capture control.
     963 *
     964 * @retval This function returns the pointer to the next control in the list. The
     965 * pointer NULL terminates the list.
    838966 */
    839967static inline rtems_capture_control_t*
     
    844972
    845973/**
    846  * rtems_capture_control_id
    847  *
    848  *  DESCRIPTION:
    849  *
     974 * @brief Capture get capture control id.
     975 *
    850976 * This function returns the control id.
     977 *
     978 * @param[in] control the capture control.
     979 *
     980 * @retval This function returns the control id.
    851981 */
    852982static inline rtems_id
     
    857987
    858988/**
    859  * rtems_capture_control_name
    860  *
    861  *  DESCRIPTION:
     989 * @brief Capture get capture control name.
    862990 *
    863991 * This function returns the control name.
     992 *
     993 * @param[in] control the capture control.
     994 *
     995 * @retval This function returns the control name.
    864996 */
    865997static inline rtems_name
     
    8701002
    8711003/**
    872  * rtems_capture_control_flags
    873  *
    874  *  DESCRIPTION:
     1004 * @brief Capture get capture control flags.
    8751005 *
    8761006 * This function returns the control flags.
     1007 *
     1008 * @param[in] control the capture control.
     1009 *
     1010 * @retval This function returns the control flags.
    8771011 */
    8781012static inline uint32_t
     
    8831017
    8841018/**
    885  * rtems_capture_control_to_triggers
    886  *
    887  *  DESCRIPTION:
     1019 * @brief Capture get capture control to triggers.
    8881020 *
    8891021 * This function returns the task control to triggers.
     1022 *
     1023 * @param[in] control the capture control.
     1024 *
     1025 * @retval This function returns the task control to triggers.
    8901026 */
    8911027static inline uint32_t
     
    8961032
    8971033/**
    898  * rtems_capture_control_from_triggers
    899  *
    900  *  DESCRIPTION:
     1034 * @brief Capture get capture control from triggers.
    9011035 *
    9021036 * This function returns the task control from triggers.
     1037 *
     1038 * @param[in] control the capture control.
     1039 *
     1040 * @retval This function returns the task control from triggers.
    9031041 */
    9041042static inline uint32_t
     
    9091047
    9101048/**
    911  * rtems_capture_control_all_by_triggers
    912  *
    913  *  DESCRIPTION:
     1049 * @brief Capture get capture control by triggers.
    9141050 *
    9151051 * This function returns the task control by triggers.
     1052 *
     1053 * @param[in] control the capture control.
     1054 *
     1055 * @retval This function returns the task control by triggers.
    9161056 */
    9171057static inline uint32_t
     
    9221062
    9231063/**
    924  * rtems_capture_control_by_valid
    925  *
    926  *  DESCRIPTION:
     1064 * @brief Capture get capture control valid by flags.
    9271065 *
    9281066 * This function returns the control valid BY flags.
     1067 *
     1068 * @param[in] control The capture control.
     1069 * @param[in] slot The XXX.
     1070 *
     1071 * @retval This function returns the control valid BY flags.
    9291072 */
    9301073static inline int
     
    9351078
    9361079/**
    937  * rtems_capture_control_by_name
    938  *
    939  *  DESCRIPTION:
    940  *
    941  * This function returns the control BY task name.
     1080 * @brief Capture get capture control by task name.
     1081 *
     1082 * This function returns the control @a by task name.
     1083 *
     1084 * @param[in] control The capture control.
     1085 * @param[in] by The XXX.
     1086 *
     1087 * @retval This function returns the control @a by task name.
    9421088 */
    9431089static inline rtems_name
     
    9501096
    9511097/**
    952  * rtems_capture_control_by_id
    953  *
    954  *  DESCRIPTION:
    955  *
    956  * This function returns the control BY task id.
     1098 * @brief Capture get capture control by task id.
     1099 *
     1100 * This function returns the control @a by task id
     1101 * 
     1102 * @retval This function returns the control @a by task id.
    9571103 */
    9581104static inline rtems_id
     
    9651111
    9661112/**
    967  * rtems_capture_control_by_triggers
    968  *
    969  *  DESCRIPTION:
    970  *
    971  * This function returns the control BY task triggers.
     1113 * @brief Capture get capture control by task triggers.
     1114 *
     1115 * This function returns the control @a by task triggers.
     1116 *
     1117 * @retval This function returns the control @a by task triggers.
    9721118 */
    9731119static inline uint32_t
     
    9811127
    9821128/**
    983  * rtems_capture_control_count
    984  *
    985  *  DESCRIPTION:
     1129 * @brief Capture get capture control count.
    9861130 *
    9871131 * This function returns the number of controls the capture
     1132 * engine has.
     1133 *
     1134 * @retval This function returns the number of controls the capture
    9881135 * engine has.
    9891136 */
Note: See TracChangeset for help on using the changeset viewer.