summaryrefslogtreecommitdiffstats
path: root/c-user/clock_manager.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c-user/clock_manager.rst')
-rw-r--r--c-user/clock_manager.rst807
1 files changed, 807 insertions, 0 deletions
diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst
new file mode 100644
index 0000000..559864f
--- /dev/null
+++ b/c-user/clock_manager.rst
@@ -0,0 +1,807 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+Clock Manager
+#############
+
+.. index:: clock
+
+Introduction
+============
+
+The clock manager provides support for time of day
+and other time related capabilities. The directives provided by
+the clock manager are:
+
+- rtems_clock_set_ - Set date and time
+
+- rtems_clock_get_ - Get date and time information
+
+- rtems_clock_get_tod_ - Get date and time in TOD format
+
+- rtems_clock_get_tod_timeval_ - Get date and time in timeval format
+
+- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch
+
+- rtems_clock_get_ticks_per_second_ - Get ticks per second
+
+- rtems_clock_get_ticks_since_boot_ - Get current ticks counter value
+
+- rtems_clock_tick_later_ - Get tick value in the future
+
+- rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds
+
+- rtems_clock_tick_before_ - Is tick value is before a point in time
+
+- rtems_clock_get_uptime_ - Get time since boot
+
+- rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format
+
+- rtems_clock_get_uptime_seconds_ - Get seconds since boot
+
+- rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot
+
+- rtems_clock_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler
+
+- rtems_clock_tick_ - Announce a clock tick
+
+Background
+==========
+
+Required Support
+----------------
+
+For the features provided by the clock manager to be utilized, periodic timer
+interrupts are required. Therefore, a real-time clock or hardware timer is
+necessary to create the timer interrupts. The ``rtems_clock_tick`` directive
+is normally called by the timer ISR to announce to RTEMS that a system clock
+tick has occurred. Elapsed time is measured in ticks. A tick is defined to be
+an integral number of microseconds which is specified by the user in the
+Configuration Table.
+
+.. _Time and Date Data Structures:
+
+Time and Date Data Structures
+-----------------------------
+
+The clock facilities of the clock manager operate upon calendar time. These
+directives utilize the following date and time structure for the native time
+and date format:
+
+.. index:: rtems_time_of_day
+
+.. code-block:: c
+
+ struct rtems_tod_control {
+ uint32_t year; /* greater than 1987 */
+ uint32_t month; /* 1 - 12 */
+ uint32_t day; /* 1 - 31 */
+ uint32_t hour; /* 0 - 23 */
+ uint32_t minute; /* 0 - 59 */
+ uint32_t second; /* 0 - 59 */
+ uint32_t ticks; /* elapsed between seconds */
+ };
+ typedef struct rtems_tod_control rtems_time_of_day;
+
+The native date and time format is the only format supported when setting the
+system date and time using the ``rtems_clock_set`` directive. Some
+applications expect to operate on a *UNIX-style* date and time data structure.
+The ``rtems_clock_get_tod_timeval`` always returns the date and time in
+``struct timeval`` format. The ``rtems_clock_get`` directive can optionally
+return the current date and time in this format.
+
+The ``struct timeval`` data structure has two fields: ``tv_sec`` and
+``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec``
+field in this data structure is the number of seconds since the POSIX epoch of
+*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1,
+1988*.
+
+Clock Tick and Timeslicing
+--------------------------
+.. index:: timeslicing
+
+Timeslicing is a task scheduling discipline in which tasks of equal priority
+are executed for a specific period of time before control of the CPU is passed
+to another task. It is also sometimes referred to as the automatic round-robin
+scheduling algorithm. The length of time allocated to each task is known as
+the quantum or timeslice.
+
+The system's timeslice is defined as an integral number of ticks, and is
+specified in the Configuration Table. The timeslice is defined for the entire
+system of tasks, but timeslicing is enabled and disabled on a per task basis.
+
+The ``rtems_clock_tick`` directive implements timeslicing by decrementing the
+running task's time-remaining counter when both timeslicing and preemption are
+enabled. If the task's timeslice has expired, then that task will be preempted
+if there exists a ready task of equal priority.
+
+Delays
+------
+.. index:: delays
+
+A sleep timer allows a task to delay for a given interval or up until a given
+time, and then wake and continue execution. This type of timer is created
+automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when``
+directives and, as a result, does not have an RTEMS ID. Once activated, a
+sleep timer cannot be explicitly deleted. Each task may activate one and only
+one sleep timer at a time.
+
+Timeouts
+--------
+.. index:: timeouts
+
+Timeouts are a special type of timer automatically created when the timeout
+option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``,
+``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each
+task may have one and only one timeout active at a time. When a timeout
+expires, it unblocks the task with a timeout status code.
+
+Operations
+==========
+
+Announcing a Tick
+-----------------
+
+RTEMS provides the ``rtems_clock_tick`` directive which is called from the
+user's real-time clock ISR to inform RTEMS that a tick has elapsed. The tick
+frequency value, defined in microseconds, is a configuration parameter found in
+the Configuration Table. RTEMS divides one million microseconds (one second)
+by the number of microseconds per tick to determine the number of calls to the
+``rtems_clock_tick`` directive per second. The frequency of
+``rtems_clock_tick`` calls determines the resolution (granularity) for all time
+dependent RTEMS actions. For example, calling ``rtems_clock_tick`` ten times
+per second yields a higher resolution than calling ``rtems_clock_tick`` two
+times per second. The ``rtems_clock_tick`` directive is responsible for
+maintaining both calendar time and the dynamic set of timers.
+
+Setting the Time
+----------------
+
+The ``rtems_clock_set`` directive allows a task or an ISR to set the date and
+time maintained by RTEMS. If setting the date and time causes any outstanding
+timers to pass their deadline, then the expired timers will be fired during the
+invocation of the ``rtems_clock_set`` directive.
+
+Obtaining the Time
+------------------
+
+The ``rtems_clock_get`` directive allows a task or an ISR to obtain the current
+date and time or date and time related information. The current date and time
+can be returned in either native or *UNIX-style* format. Additionally, the
+application can obtain date and time related information such as the number of
+seconds since the RTEMS epoch, the number of ticks since the executive was
+initialized, and the number of ticks per second. The information returned by
+the ``rtems_clock_get`` directive is dependent on the option selected by the
+caller. This is specified using one of the following constants associated with
+the enumerated type ``rtems_clock_get_options``:
+
+.. index:: rtems_clock_get_options
+
+``RTEMS_CLOCK_GET_TOD``
+ obtain native style date and time
+
+``RTEMS_CLOCK_GET_TIME_VALUE``
+ obtain *UNIX-style* date and time
+
+``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``
+ obtain number of ticks since RTEMS was initialized
+
+``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``
+ obtain number of seconds since RTEMS epoch
+
+``RTEMS_CLOCK_GET_TICKS_PER_SECOND``
+ obtain number of clock ticks per second
+
+Calendar time operations will return an error code if invoked before the date
+and time have been set.
+
+Directives
+==========
+
+This section details the clock manager's directives. A subsection is dedicated
+to each of this manager's directives and describes the calling sequence,
+related constants, usage, and status codes.
+
+.. _rtems_clock_set:
+
+CLOCK_SET - Set date and time
+-----------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: set the time of day
+
+.. index:: rtems_clock_set
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_set(
+ rtems_time_of_day *time_buffer
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ date and time set successfully
+
+``RTEMS_INVALID_ADDRESS``
+ ``time_buffer`` is NULL
+
+``RTEMS_INVALID_CLOCK``
+ invalid time of day
+
+**DESCRIPTION:**
+
+This directive sets the system date and time. The date, time, and ticks in the
+time_buffer structure are all range-checked, and an error is returned if any
+one is out of its valid range.
+
+**NOTES:**
+
+Years before 1988 are invalid.
+
+The system date and time are based on the configured tick rate (number of
+microseconds in a tick).
+
+Setting the time forward may cause a higher priority task, blocked waiting on a
+specific time, to be made ready. In this case, the calling task will be
+preempted after the next clock tick.
+
+Re-initializing RTEMS causes the system date and time to be reset to an
+uninitialized state. Another call to ``rtems_clock_set`` is required to
+re-initialize the system date and time to application specific specifications.
+
+.. _rtems_clock_get:
+
+CLOCK_GET - Get date and time information
+-----------------------------------------
+.. index:: obtain the time of day
+
+.. warning::
+
+ This directive is deprecated and will be removed.
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get(
+ rtems_clock_get_options option,
+ void *time_buffer
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ current time obtained successfully
+
+``RTEMS_NOT_DEFINED``
+ system date and time is not set
+
+``RTEMS_INVALID_ADDRESS``
+ ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive obtains the system date and time. If the caller is attempting
+to obtain the date and time (i.e. option is set to either
+``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
+``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with a
+previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
+code is returned. The caller can always obtain the number of ticks per second
+(option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of ticks since
+the executive was initialized option is ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
+
+The ``option`` argument may taken on any value of the enumerated type
+``rtems_clock_get_options``. The data type expected for ``time_buffer`` is
+based on the value of ``option`` as indicated below:
+
+.. index:: rtems_clock_get_options
+
++-----------------------------------------+---------------------------+
+| Option | Return type |
++=========================================+===========================+
+| ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` |
++-----------------------------------------+---------------------------+
+| ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` |
++-----------------------------------------+---------------------------+
+| ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` |
++-----------------------------------------+---------------------------+
+|``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` |
++-----------------------------------------+---------------------------+
+| ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` |
++-----------------------------------------+---------------------------+
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+Re-initializing RTEMS causes the system date and time to be reset to an
+uninitialized state. Another call to ``rtems_clock_set`` is required to
+re-initialize the system date and time to application specific specifications.
+
+.. _rtems_clock_get_tod:
+
+CLOCK_GET_TOD - Get date and time in TOD format
+-----------------------------------------------
+.. index:: obtain the time of day
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_tod
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_tod(
+ rtems_time_of_day *time_buffer
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ current time obtained successfully
+
+``RTEMS_NOT_DEFINED``
+ system date and time is not set
+
+``RTEMS_INVALID_ADDRESS``
+ ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive obtains the system date and time. If the date and time has not
+been set with a previous call to ``rtems_clock_set``, then the
+``RTEMS_NOT_DEFINED`` status code is returned.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+Re-initializing RTEMS causes the system date and time to be reset to an
+uninitialized state. Another call to ``rtems_clock_set`` is required to
+re-initialize the system date and time to application specific specifications.
+
+.. _rtems_clock_get_tod_timeval:
+
+CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
+-----------------------------------------------------------
+.. index:: obtain the time of day
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_tod_timeval
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_tod_interval(
+ struct timeval *time
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ current time obtained successfully
+
+``RTEMS_NOT_DEFINED``
+ system date and time is not set
+
+``RTEMS_INVALID_ADDRESS``
+ ``time`` is NULL
+
+**DESCRIPTION:**
+
+This directive obtains the system date and time in POSIX ``struct timeval``
+format. If the date and time has not been set with a previous call to
+``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is returned.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+Re-initializing RTEMS causes the system date and time to be reset to an
+uninitialized state. Another call to ``rtems_clock_set`` is required to
+re-initialize the system date and time to application specific specifications.
+
+.. _rtems_clock_get_seconds_since_epoch:
+
+CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
+-------------------------------------------------------
+.. index:: obtain seconds since epoch
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_seconds_since_epoch
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_seconds_since_epoch(
+ rtems_interval *the_interval
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ current time obtained successfully
+
+``RTEMS_NOT_DEFINED``
+ system date and time is not set
+
+``RTEMS_INVALID_ADDRESS``
+ ``the_interval`` is NULL
+
+**DESCRIPTION:**
+
+This directive returns the number of seconds since the RTEMS epoch and the
+current system date and time. If the date and time has not been set with a
+previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
+code is returned.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+Re-initializing RTEMS causes the system date and time to be reset to an
+uninitialized state. Another call to ``rtems_clock_set`` is required to
+re-initialize the system date and time to application specific specifications.
+
+.. _rtems_clock_get_ticks_per_second:
+
+CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
+-------------------------------------------------
+.. index:: obtain seconds since epoch
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_ticks_per_second
+
+.. code-block:: c
+
+ rtems_interval rtems_clock_get_ticks_per_second(void);
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the number of clock ticks per second. This is strictly
+based upon the microseconds per clock tick that the application has configured.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+.. _rtems_clock_get_ticks_since_boot:
+
+CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
+------------------------------------------------------------
+.. index:: obtain ticks since boot
+.. index:: get current ticks counter value
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_ticks_since_boot
+
+.. code-block:: c
+
+ rtems_interval rtems_clock_get_ticks_since_boot(void);
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the current tick counter value. With a 1ms clock tick,
+this counter overflows after 50 days since boot. This is the historical
+measure of uptime in an RTEMS system. The newer service
+``rtems_clock_get_uptime`` is another and potentially more accurate way of
+obtaining similar information.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+.. _rtems_clock_tick_later:
+
+CLOCK_TICK_LATER - Get tick value in the future
+-----------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_tick_later
+
+.. code-block:: c
+
+ rtems_interval rtems_clock_tick_later(
+ rtems_interval delta
+ );
+
+**DESCRIPTION:**
+
+Returns the ticks counter value delta ticks in the future.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+.. _rtems_clock_tick_later_usec:
+
+CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
+--------------------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_tick_later_usec
+
+.. code-block:: c
+
+ rtems_interval rtems_clock_tick_later_usec(
+ rtems_interval delta_in_usec
+ );
+
+**DESCRIPTION:**
+
+Returns the ticks counter value at least delta microseconds in the future.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+.. _rtems_clock_tick_before:
+
+CLOCK_TICK_BEFORE - Is tick value is before a point in time
+-----------------------------------------------------------
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_tick_before
+
+.. code-block:: c
+
+ rtems_interval rtems_clock_tick_before(
+ rtems_interval tick
+ );
+
+**DESCRIPTION:**
+
+Returns true if the current ticks counter value indicates a time before the
+time specified by the tick value and false otherwise.
+
+**NOTES:**
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be preempted.
+
+**EXAMPLE:**
+
+.. code-block:: c
+
+ status busy( void )
+ {
+ rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
+ do {
+ if ( ok() ) {
+ return success;
+ }
+ } while ( rtems_clock_tick_before( timeout ) );
+ return timeout;
+ }
+
+.. _rtems_clock_get_uptime:
+
+CLOCK_GET_UPTIME - Get the time since boot
+------------------------------------------
+.. index:: clock get uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_uptime
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_uptime(
+ struct timespec *uptime
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ clock tick processed successfully
+
+``RTEMS_INVALID_ADDRESS``
+ ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive returns the seconds and nanoseconds since the system was booted.
+If the BSP supports nanosecond clock accuracy, the time reported will probably
+be different on every call.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+.. _rtems_clock_get_uptime_timeval:
+
+CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
+--------------------------------------------------------------------
+.. index:: clock get uptime interval
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_uptime_timeval
+
+.. code-block:: c
+
+ void rtems_clock_get_uptime_timeval(
+ struct timeval *uptime
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive returns the seconds and microseconds since the system was
+booted. If the BSP supports nanosecond clock accuracy, the time reported will
+probably be different on every call.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+.. _rtems_clock_get_uptime_seconds:
+
+CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
+-----------------------------------------------------
+.. index:: clock get uptime seconds
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_uptime_seconds
+
+.. code-block:: c
+
+ time_t rtems_clock_get_uptime_seconds(void);
+
+**DIRECTIVE STATUS CODES:**
+
+The system uptime in seconds.
+
+**DESCRIPTION:**
+
+This directive returns the seconds since the system was booted.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+.. _rtems_clock_get_uptime_nanoseconds:
+
+CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
+-------------------------------------------------------------
+.. index:: clock get nanoseconds uptime
+.. index:: uptime
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_get_uptime_nanoseconds
+
+.. code-block:: c
+
+ uint64_t rtems_clock_get_uptime_nanoseconds(void);
+
+**DIRECTIVE STATUS CODES:**
+
+The system uptime in nanoseconds.
+
+**DESCRIPTION:**
+
+This directive returns the nanoseconds since the system was booted.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+.. _rtems_clock_set_nanoseconds_extension:
+
+CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
+---------------------------------------------------------------------------------
+.. index:: clock set nanoseconds extension
+.. index:: nanoseconds extension
+.. index:: nanoseconds time accuracy
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_set_nanoseconds_extension
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_set_nanoseconds_extension(
+ rtems_nanoseconds_extension_routine routine
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ clock tick processed successfully
+
+``RTEMS_INVALID_ADDRESS``
+ ``time_buffer`` is NULL
+
+**DESCRIPTION:**
+
+This directive is used by the Clock device driver to install the ``routine``
+which will be invoked by the internal RTEMS method used to obtain a highly
+accurate time of day. It is usually called during the initialization of the
+driver.
+
+When the ``routine`` is invoked, it will determine the number of nanoseconds
+which have elapsed since the last invocation of the ``rtems_clock_tick``
+directive. It should do this as quickly as possible with as little impact as
+possible on the device used as a clock source.
+
+**NOTES:**
+
+This directive may be called from an ISR.
+
+This directive is called as part of every service to obtain the current date
+and time as well as timestamps.
+
+.. _rtems_clock_tick:
+
+CLOCK_TICK - Announce a clock tick
+----------------------------------
+.. index:: clock tick
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_clock_tick
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_tick( void );
+
+**DIRECTIVE STATUS CODES:**
+
+``RTEMS_SUCCESSFUL``
+ clock tick processed successfully
+
+**DESCRIPTION:**
+
+This directive announces to RTEMS that a system clock tick has occurred. The
+directive is usually called from the timer interrupt ISR of the local
+processor. This directive maintains the system date and time, decrements
+timers for delayed tasks, timeouts, rate monotonic periods, and implements
+timeslicing.
+
+**NOTES:**
+
+This directive is typically called from an ISR.
+
+The ``microseconds_per_tick`` and ``ticks_per_timeslice`` parameters in the
+Configuration Table contain the number of microseconds per tick and number of
+ticks per timeslice, respectively.