diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-01-25 09:27:22 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-01-27 06:01:48 +0100 |
commit | b35ac9901caac823c5aa4aeeb81c4bb2c6bc58fd (patch) | |
tree | fe1061be42fa3aa4c18182e1d91c7ec7a83fe7f0 /cpukit/include/rtems/rtems/timer.h | |
parent | heap: Fix _Heap_Area_overhead() (diff) | |
download | rtems-b35ac9901caac823c5aa4aeeb81c4bb2c6bc58fd.tar.bz2 |
rtems: Add "Notes" paragraph header
Place the paragraphs in the same order as the directive documentation in
the RTEMS Classic API Guide.
Update #3993.
Diffstat (limited to '')
-rw-r--r-- | cpukit/include/rtems/rtems/timer.h | 207 |
1 files changed, 114 insertions, 93 deletions
diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h index fe22eef39d..23a69b5b87 100644 --- a/cpukit/include/rtems/rtems/timer.h +++ b/cpukit/include/rtems/rtems/timer.h @@ -190,22 +190,23 @@ typedef struct { * * @brief Gets information about the timer. * - * This directive returns information about the timer. - * - * This directive will not cause the running task to be preempted. - * * @param id is the timer identifier. * * @param[out] the_info is the pointer to a timer information variable. The * information about the timer will be stored in this variable, in case of a * successful operation. * + * This directive returns information about the timer. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_get_information( rtems_id id, @@ -254,26 +255,16 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * * @brief Creates a timer. * - * This directive creates a timer. The assigned object identifier is returned - * in ``id``. This identifier is used to access the timer with other timer - * related directives. - * - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. - * - * For control and maintenance of the timer, RTEMS allocates a TMCB from the - * local TMCB free pool and initializes it. - * - * In SMP configurations, the processor of the currently executing thread - * determines the processor used for the created timer. During the life-time - * of the timer this processor is used to manage the timer internally. - * * @param name is the name of the timer. * * @param[out] id is the pointer to an object identifier variable. The * identifier of the created timer object will be stored in this variable, in * case of a successful operation. * + * This directive creates a timer. The assigned object identifier is returned + * in ``id``. This identifier is used to access the timer with other timer + * related directives. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_NAME The timer name was invalid. @@ -283,6 +274,19 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * new timer. The number of timers available to the application is * configured through the #CONFIGURE_MAXIMUM_TIMERS configuration option. + * + * @par Notes + * @parblock + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. + * + * For control and maintenance of the timer, RTEMS allocates a TMCB from the + * local TMCB free pool and initializes it. + * + * In SMP configurations, the processor of the currently executing thread + * determines the processor used for the created timer. During the life-time + * of the timer this processor is used to manage the timer internally. + * @endparblock */ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); @@ -293,23 +297,15 @@ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); * * @brief Identifies a timer by the object name. * - * This directive obtains the timer identifier associated with the timer name - * specified in ``name``. - * - * If the timer name is not unique, then the timer identifier will match the - * first timer with that name in the search order. However, this timer - * identifier is not guaranteed to correspond to the desired timer. The timer - * identifier is used with other timer related directives to access the timer. - * - * The objects are searched from lowest to the highest index. Only the local - * node is searched. - * * @param name is the object name to look up. * * @param[out] id is the pointer to an object identifier variable. The object * identifier of an object with the specified name will be stored in this * variable, in case of a successful operation. * + * This directive obtains the timer identifier associated with the timer name + * specified in ``name``. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. @@ -318,6 +314,17 @@ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); * * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on * the local node. + * + * @par Notes + * @parblock + * If the timer name is not unique, then the timer identifier will match the + * first timer with that name in the search order. However, this timer + * identifier is not guaranteed to correspond to the desired timer. The timer + * identifier is used with other timer related directives to access the timer. + * + * The objects are searched from lowest to the highest index. Only the local + * node is searched. + * @endparblock */ rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id ); @@ -328,19 +335,20 @@ rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id ); * * @brief Cancels the timer. * + * @param id is the timer identifier. + * * This directive cancels the timer specified in the ``id`` parameter. This * timer will be reinitiated by the next invocation of rtems_timer_reset(), * rtems_timer_fire_after(), or rtems_timer_fire_when() with the same timer * identifier. * - * This directive will not cause the running task to be preempted. - * - * @param id is the timer identifier. - * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_cancel( rtems_id id ); @@ -351,9 +359,18 @@ rtems_status_code rtems_timer_cancel( rtems_id id ); * * @brief Deletes the timer. * + * @param id is the timer identifier. + * * This directive deletes the timer specified by the ``id`` parameter. If the * timer is running, it is automatically canceled. * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. + * + * @par Notes + * @parblock * This directive may cause the calling task to be preempted due to an obtain * and release of the object allocator mutex. * @@ -361,13 +378,7 @@ rtems_status_code rtems_timer_cancel( rtems_id id ); * * A timer can be deleted by a task other than the task which created the * timer. - * - * @param id is the timer identifier. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier - * specified by ``id``. + * @endparblock */ rtems_status_code rtems_timer_delete( rtems_id id ); @@ -378,15 +389,6 @@ rtems_status_code rtems_timer_delete( rtems_id id ); * * @brief Fires the timer after the interval. * - * This directive initiates the timer specified by ``id``. If the timer is - * running, it is automatically canceled before being initiated. The timer is - * scheduled to fire after an interval of clock ticks has passed specified by - * ``ticks``. When the timer fires, the timer service routine ``routine`` will - * be invoked with the argument ``user_data`` in the context of the clock tick - * ISR. - * - * This directive will not cause the running task to be preempted. - * * @param id is the timer identifier. * * @param ticks is the interval until the routine is fired in clock ticks. @@ -395,6 +397,13 @@ rtems_status_code rtems_timer_delete( rtems_id id ); * * @param user_data is the argument passed to the routine when it is fired. * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire after an interval of clock ticks has passed specified by + * ``ticks``. When the timer fires, the timer service routine ``routine`` will + * be invoked with the argument ``user_data`` in the context of the clock tick + * ISR. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0. @@ -403,6 +412,9 @@ rtems_status_code rtems_timer_delete( rtems_id id ); * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_fire_after( rtems_id id, @@ -418,14 +430,6 @@ rtems_status_code rtems_timer_fire_after( * * @brief Fires the timer at the time of day. * - * This directive initiates the timer specified by ``id``. If the timer is - * running, it is automatically canceled before being initiated. The timer is - * scheduled to fire at the time of day specified by ``wall_time``. When the - * timer fires, the timer service routine ``routine`` will be invoked with the - * argument ``user_data`` in the context of the clock tick ISR. - * - * This directive will not cause the running task to be preempted. - * * @param id is the timer identifier. * * @param wall_time is the time of day when the routine is fired. @@ -434,6 +438,12 @@ rtems_status_code rtems_timer_fire_after( * * @param user_data is the argument passed to the routine when it is fired. * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire at the time of day specified by ``wall_time``. When the + * timer fires, the timer service routine ``routine`` will be invoked with the + * argument ``user_data`` in the context of the clock tick ISR. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_NOT_DEFINED The system date and time was not set. @@ -446,6 +456,9 @@ rtems_status_code rtems_timer_fire_after( * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_fire_when( rtems_id id, @@ -461,22 +474,16 @@ rtems_status_code rtems_timer_fire_when( * * @brief Initiates the Timer Server. * - * This directive initiates the Timer Server task. This task is responsible - * for executing all timers initiated via the rtems_timer_server_fire_after() - * or rtems_timer_server_fire_when() directives. - * - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. - * - * The Timer Server task is created using the rtems_task_create() directive and - * must be accounted for when configuring the system. - * * @param priority is the task priority. * * @param stack_size is the task stack size in bytes. * * @param attribute_set is the task attribute set. * + * This directive initiates the Timer Server task. This task is responsible + * for executing all timers initiated via the rtems_timer_server_fire_after() + * or rtems_timer_server_fire_when() directives. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INCORRECT_STATE The Timer Server was already initiated. @@ -492,6 +499,15 @@ rtems_status_code rtems_timer_fire_when( * * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to * create the Timer Server task. + * + * @par Notes + * @parblock + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. + * + * The Timer Server task is created using the rtems_task_create() directive and + * must be accounted for when configuring the system. + * @endparblock */ rtems_status_code rtems_timer_initiate_server( rtems_task_priority priority, @@ -506,15 +522,6 @@ rtems_status_code rtems_timer_initiate_server( * * @brief Fires the timer after the interval using the Timer Server. * - * This directive initiates the timer specified by ``id``. If the timer is - * running, it is automatically canceled before being initiated. The timer is - * scheduled to fire after an interval of clock ticks has passed specified by - * ``ticks``. When the timer fires, the timer service routine ``routine`` will - * be invoked with the argument ``user_data`` in the context of the Timer - * Server task. - * - * This directive will not cause the running task to be preempted. - * * @param id is the timer identifier. * * @param ticks is the interval until the routine is fired in clock ticks. @@ -523,6 +530,13 @@ rtems_status_code rtems_timer_initiate_server( * * @param user_data is the argument passed to the routine when it is fired. * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire after an interval of clock ticks has passed specified by + * ``ticks``. When the timer fires, the timer service routine ``routine`` will + * be invoked with the argument ``user_data`` in the context of the Timer + * Server task. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated. @@ -533,6 +547,9 @@ rtems_status_code rtems_timer_initiate_server( * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_server_fire_after( rtems_id id, @@ -548,14 +565,6 @@ rtems_status_code rtems_timer_server_fire_after( * * @brief Fires the timer at the time of day using the Timer Server. * - * This directive initiates the timer specified by ``id``. If the timer is - * running, it is automatically canceled before being initiated. The timer is - * scheduled to fire at the time of day specified by ``wall_time``. When the - * timer fires, the timer service routine ``routine`` will be invoked with the - * argument ``user_data`` in the context of the Timer Server task. - * - * This directive will not cause the running task to be preempted. - * * @param id is the timer identifier. * * @param wall_time is the time of day when the routine is fired. @@ -564,6 +573,12 @@ rtems_status_code rtems_timer_server_fire_after( * * @param user_data is the argument passed to the routine when it is fired. * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire at the time of day specified by ``wall_time``. When the + * timer fires, the timer service routine ``routine`` will be invoked with the + * argument ``user_data`` in the context of the Timer Server task. + * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated. @@ -578,6 +593,9 @@ rtems_status_code rtems_timer_server_fire_after( * * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier * specified by ``id``. + * + * @par Notes + * This directive will not cause the running task to be preempted. */ rtems_status_code rtems_timer_server_fire_when( rtems_id id, @@ -593,6 +611,8 @@ rtems_status_code rtems_timer_server_fire_when( * * @brief Resets the timer. * + * @param id is the timer identifier. + * * This directive resets the timer specified by ``id``. This timer must have * been previously initiated with either the rtems_timer_fire_after() or * rtems_timer_server_fire_after() directive. If active the timer is canceled, @@ -600,6 +620,15 @@ rtems_status_code rtems_timer_server_fire_when( * service routine which the original rtems_timer_fire_after() or * rtems_timer_server_fire_after() directive used. * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class. + * + * @par Notes + * @parblock * This directive will not cause the running task to be preempted. * * If the timer has not been used or the last usage of this timer was by a @@ -608,15 +637,7 @@ rtems_status_code rtems_timer_server_fire_when( * * Restarting a cancelled after timer results in the timer being reinitiated * with its previous timer service routine and interval. - * - * @param id is the timer identifier. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier - * specified by ``id``. - * - * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class. + * @endparblock */ rtems_status_code rtems_timer_reset( rtems_id id ); |