10.4. Directives¶

This section details the directives of the Timer Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

10.4.1. rtems_timer_create()¶

Creates a timer.

CALLING SEQUENCE:

rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );

PARAMETERS:

name: This parameter is the object name of the timer.
id: This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the created timer will be stored in this object.

DESCRIPTION:

This directive creates a timer which resides on the local node. The timer has the user-defined object name specified in name. The assigned object identifier is returned in id. This identifier is used to access the timer with other timer related directives.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_NAME: The name parameter was invalid.
RTEMS_INVALID_ADDRESS: The id parameter was NULL.
RTEMS_TOO_MANY: There was no inactive object available to create a timer. The number of timers available to the application is configured through the CONFIGURE_MAXIMUM_TIMERS application configuration option.

NOTES:

The processor used to maintain the timer is the processor of the calling task at some point during the timer creation.

For control and maintenance of the timer, RTEMS allocates a TMCB from the local TMCB free pool and initializes it.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
The number of timers available to the application is configured through the CONFIGURE_MAXIMUM_TIMERS application configuration option.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

10.4.2. rtems_timer_ident()¶

Identifies a timer by the object name.

CALLING SEQUENCE:

rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );

PARAMETERS:

name: This parameter is the object name to look up.
id: This parameter is the pointer to an rtems_id object. When the directive call is successful, the object identifier of an object with the specified name will be stored in this object.

DESCRIPTION:

This directive obtains a timer identifier associated with the timer name specified in name.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The id parameter was NULL.
RTEMS_INVALID_NAME: The name parameter was 0.
RTEMS_INVALID_NAME: There was no object with the specified name on the local node.

NOTES:

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 objects are searched from lowest to the highest index. Only the local node is searched.

The timer identifier is used with other timer related directives to access the timer.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

10.4.3. rtems_timer_cancel()¶

Cancels the timer.

CALLING SEQUENCE:

rtems_status_code rtems_timer_cancel( rtems_id id );

PARAMETERS:

id: This parameter is the timer identifier.

DESCRIPTION:

This directive cancels the timer specified by id. This timer will be reinitiated by the next invocation of rtems_timer_reset(), rtems_timer_fire_after(), rtems_timer_fire_when(), rtems_timer_server_fire_after(), or rtems_timer_server_fire_when() with the same timer identifier.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.4. rtems_timer_delete()¶

Deletes the timer.

CALLING SEQUENCE:

rtems_status_code rtems_timer_delete( rtems_id id );

PARAMETERS:

id: This parameter is the timer identifier.

DESCRIPTION:

This directive deletes the timer specified by id. If the timer is running, it is automatically canceled.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

NOTES:

The TMCB for the deleted timer is reclaimed by RTEMS.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
The calling task does not have to be the task that created the object. Any local task that knows the object identifier can delete the object.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may free memory to the RTEMS Workspace.

10.4.5. rtems_timer_fire_after()¶

Fires the timer after the interval.

CALLING SEQUENCE:

rtems_status_code rtems_timer_fire_after(
  rtems_id                          id,
  rtems_interval                    ticks,
  rtems_timer_service_routine_entry routine,
  void                             *user_data
);

PARAMETERS:

id: This parameter is the timer identifier.
ticks: This parameter is the interval until the routine is fired in clock ticks.
routine: This parameter is the routine to schedule.
user_data: This parameter is the argument passed to the routine when it is fired.

DESCRIPTION:

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.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_NUMBER: The ticks parameter was 0.
RTEMS_INVALID_ADDRESS: The routine parameter was NULL.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.6. rtems_timer_fire_when()¶

Fires the timer at the time of day.

CALLING SEQUENCE:

rtems_status_code rtems_timer_fire_when(
  rtems_id                          id,
  const rtems_time_of_day          *wall_time,
  rtems_timer_service_routine_entry routine,
  void                             *user_data
);

PARAMETERS:

id: This parameter is the timer identifier.
wall_time: This parameter is the time of day when the routine is fired.
routine: This parameter is the routine to schedule.
user_data: This parameter is the argument passed to the routine when it is fired.

DESCRIPTION:

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.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_NOT_DEFINED: The system date and time was not set.
RTEMS_INVALID_ADDRESS: The routine parameter was NULL.
RTEMS_INVALID_ADDRESS: The wall_time parameter was NULL.
RTEMS_INVALID_CLOCK: The time of day was invalid.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.7. rtems_timer_initiate_server()¶

Initiates the Timer Server.

CALLING SEQUENCE:

rtems_status_code rtems_timer_initiate_server(
  rtems_task_priority priority,
  size_t              stack_size,
  rtems_attribute     attribute_set
);

PARAMETERS:

priority: This parameter is the task priority.
stack_size: This parameter is the task stack size in bytes.
attribute_set: This parameter is the task attribute set.

DESCRIPTION:

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.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INCORRECT_STATE: The Timer Server was already initiated.
RTEMS_INVALID_PRIORITY: The task priority was invalid.
RTEMS_TOO_MANY: There was no inactive task object available to create the Timer Server task.
RTEMS_UNSATISFIED: There was not enough memory to allocate the task storage area. The task storage area contains the task stack, the thread-local storage, and the floating point context.
RTEMS_UNSATISFIED: One of the task create extensions failed to create the Timer Server task.

NOTES:

The Timer Server task is created using the rtems_task_create() directive and must be accounted for when configuring the system.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The number of timers available to the application is configured through the CONFIGURE_MAXIMUM_TIMERS application configuration option.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

10.4.8. rtems_timer_server_fire_after()¶

Fires the timer after the interval using the Timer Server.

CALLING SEQUENCE:

rtems_status_code rtems_timer_server_fire_after(
  rtems_id                          id,
  rtems_interval                    ticks,
  rtems_timer_service_routine_entry routine,
  void                             *user_data
);

PARAMETERS:

id: This parameter is the timer identifier.
ticks: This parameter is the interval until the routine is fired in clock ticks.
routine: This parameter is the routine to schedule.
user_data: This parameter is the argument passed to the routine when it is fired.

DESCRIPTION:

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.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INCORRECT_STATE: The Timer Server was not initiated.
RTEMS_INVALID_NUMBER: The ticks parameter was 0.
RTEMS_INVALID_ADDRESS: The routine parameter was NULL.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.9. rtems_timer_server_fire_when()¶

Fires the timer at the time of day using the Timer Server.

CALLING SEQUENCE:

rtems_status_code rtems_timer_server_fire_when(
  rtems_id                          id,
  const rtems_time_of_day          *wall_time,
  rtems_timer_service_routine_entry routine,
  void                             *user_data
);

PARAMETERS:

id: This parameter is the timer identifier.
wall_time: This parameter is the time of day when the routine is fired.
routine: This parameter is the routine to schedule.
user_data: This parameter is the argument passed to the routine when it is fired.

DESCRIPTION:

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.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INCORRECT_STATE: The Timer Server was not initiated.
RTEMS_NOT_DEFINED: The system date and time was not set.
RTEMS_INVALID_ADDRESS: The routine parameter was NULL.
RTEMS_INVALID_ADDRESS: The wall_time parameter was NULL.
RTEMS_INVALID_CLOCK: The time of day was invalid.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.10. rtems_timer_reset()¶

Resets the timer.

CALLING SEQUENCE:

rtems_status_code rtems_timer_reset( rtems_id id );

PARAMETERS:

id: This parameter is the timer identifier.

DESCRIPTION:

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, after which the timer is reinitiated using the same interval and timer service routine which the original rtems_timer_fire_after() or rtems_timer_server_fire_after() directive used.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.
RTEMS_NOT_DEFINED: The timer was not of the interval class.

NOTES:

If the timer has not been used or the last usage of this timer was by a rtems_timer_fire_when() or rtems_timer_server_fire_when() directive, then the RTEMS_NOT_DEFINED error is returned.

Restarting a cancelled after timer results in the timer being reinitiated with its previous timer service routine and interval.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

10.4.11. rtems_timer_get_information()¶

Gets information about the timer.

CALLING SEQUENCE:

rtems_status_code rtems_timer_get_information(
  rtems_id                 id,
  rtems_timer_information *the_info
);

PARAMETERS:

id: This parameter is the timer identifier.
the_info: This parameter is the pointer to an rtems_timer_information object. When the directive call is successful, the information about the timer will be stored in this object.

DESCRIPTION:

This directive returns information about the timer.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The the_info parameter was NULL.
RTEMS_INVALID_ID: There was no timer associated with the identifier specified by id.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.