C user guide clean up. Up to timer manager.

1 files changed, 317 insertions, 259 deletions

diff --git a/c_user/clock_manager.rst b/c_user/clock_manager.rst
index 5ea889f..40d984f 100644
--- a/c_user/clock_manager.rst
+++ b/c_user/clock_manager.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Clock Manager
 #############
 
@@ -10,37 +14,37 @@ 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_set_ - Set date and time
 
-- ``rtems_clock_get`` - Get date and time information
+- rtems_clock_get_ - Get date and time information
 
-- ``rtems_clock_get_tod`` - Get date and time in TOD format
+- 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_tod_timeval_ - Get date and time in timeval format
 
-- ``rtems_clock_get_seconds_since_epoch`` - Get seconds since epoch
+- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch
 
-- ``rtems_clock_get_ticks_per_second`` - Get ticks per second
+- rtems_clock_get_ticks_per_second_ - Get ticks per second
 
-- ``rtems_clock_get_ticks_since_boot`` - Get current ticks counter value
+- 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_ - Get tick value in the future
 
-- ``rtems_clock_tick_later_usec`` - Get tick value in the future in microseconds
+- 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_tick_before_ - Is tick value is before a point in time
 
-- ``rtems_clock_get_uptime`` - Get time since boot
+- rtems_clock_get_uptime_ - Get time since boot
 
-- ``rtems_clock_get_uptime_timeval`` - Get time since boot in timeval format
+- 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_seconds_ - Get seconds since boot
 
-- ``rtems_clock_get_uptime_nanoseconds`` - Get nanoseconds 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_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler
 
-- ``rtems_clock_tick`` - Announce a clock tick
+- rtems_clock_tick_ - Announce a clock tick
 
 Background
 ==========
@@ -48,93 +52,89 @@ 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.
+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
 -----------------------------
 
-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:
+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:: 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 \*/
+        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 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.
+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.
+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.
+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.
+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
 ==========
@@ -142,71 +142,67 @@ 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.
+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.
+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
+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_TOD``
+  obtain native style date and time
 
-- ``RTEMS_CLOCK_GET_TIME_VALUE`` - obtain UNIX-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_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_SECONDS_SINCE_EPOCH``
+  obtain number of seconds since RTEMS epoch
 
-- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock
-  ticks per second
+``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.
+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.
+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
 -----------------------------
@@ -220,42 +216,51 @@ CLOCK_SET - Set date and time
 .. code:: c
 
     rtems_status_code rtems_clock_set(
-    rtems_time_of_day \*time_buffer
+        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
+``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.
+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).
+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.
 
-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.
 
-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
@@ -263,49 +268,62 @@ CLOCK_GET - Get date and time information
 .. code:: c
 
     rtems_status_code rtems_clock_get(
-    rtems_clock_get_options  option,
-    void                    \*time_buffer
+       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
+``RTEMS_SUCCESSFUL``
+  current time obtained successfully
 
-**DESCRIPTION:**
+``RTEMS_NOT_DEFINED``
+  system date and time is not set
 
-This directive is deprecated.
+``RTEMS_INVALID_ADDRESS``
+  ``time_buffer`` is NULL
 
-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
-
-- ``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 \*)
+**DESCRIPTION:**
 
-- ``RTEMS_CLOCK_GET_TIME_VALUE`` - (struct timeval \*)
+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.
+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
 -----------------------------------------------
@@ -318,28 +336,36 @@ CLOCK_GET_TOD - Get date and time in TOD format
 .. code:: c
 
     rtems_status_code rtems_clock_get_tod(
-    rtems_time_of_day \*time_buffer
+        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
+``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.
+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.
+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
 -----------------------------------------------------------
@@ -351,29 +377,37 @@ CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
 
 .. code:: c
 
-    rtems_status_code rtems_clock_get_tod(
-    struct timeval  \*time
+    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
+``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.
+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.
+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
 -------------------------------------------------------
@@ -386,29 +420,37 @@ CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
 .. code:: c
 
     rtems_status_code rtems_clock_get_seconds_since_epoch(
-    rtems_interval \*the_interval
+        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
+``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.
+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.
+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
 -------------------------------------------------
@@ -428,9 +470,8 @@ 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.
+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:**
 
@@ -438,6 +479,8 @@ 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
@@ -459,8 +502,9 @@ NONE
 
 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.
+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:**
 
@@ -468,6 +512,8 @@ 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
 -----------------------------------------------
 
@@ -478,7 +524,7 @@ CLOCK_TICK_LATER - Get tick value in the future
 .. code:: c
 
     rtems_interval rtems_clock_tick_later(
-    rtems_interval delta
+        rtems_interval delta
     );
 
 **DESCRIPTION:**
@@ -491,6 +537,8 @@ 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
 --------------------------------------------------------------------
 
@@ -501,7 +549,7 @@ CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
 .. code:: c
 
     rtems_interval rtems_clock_tick_later_usec(
-    rtems_interval delta_in_usec
+        rtems_interval delta_in_usec
     );
 
 **DESCRIPTION:**
@@ -514,6 +562,8 @@ 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
 -----------------------------------------------------------
 
@@ -524,7 +574,7 @@ CLOCK_TICK_BEFORE - Is tick value is before a point in time
 .. code:: c
 
     rtems_interval rtems_clock_tick_before(
-    rtems_interval tick
+        rtems_interval tick
     );
 
 **DESCRIPTION:**
@@ -544,15 +594,17 @@ This directive will not cause the running task to be preempted.
 
     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_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
@@ -565,28 +617,32 @@ CLOCK_GET_UPTIME - Get the time since boot
 .. code:: c
 
     rtems_status_code rtems_clock_get_uptime(
-    struct timespec \*uptime
+        struct timespec *uptime
     );
 
 **DIRECTIVE STATUS CODES:**
 
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
+``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.
+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
+.. index:: clock get uptime interval
 .. index:: uptime
 
 **CALLING SEQUENCE:**
@@ -596,7 +652,7 @@ CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
 .. code:: c
 
     void rtems_clock_get_uptime_timeval(
-    struct timeval \*uptime
+        struct timeval *uptime
     );
 
 **DIRECTIVE STATUS CODES:**
@@ -605,18 +661,19 @@ 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.
+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
+.. index:: clock get uptime seconds
 .. index:: uptime
 
 **CALLING SEQUENCE:**
@@ -639,6 +696,8 @@ This directive returns the seconds since the system was booted.
 
 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
@@ -664,6 +723,8 @@ This directive returns the nanoseconds since the system was booted.
 
 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
@@ -677,32 +738,37 @@ CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handle
 .. code:: c
 
     rtems_status_code rtems_clock_set_nanoseconds_extension(
-    rtems_nanoseconds_extension_routine routine
+        rtems_nanoseconds_extension_routine routine
     );
 
 **DIRECTIVE STATUS CODES:**
 
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
-``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
+``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.
+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.
+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.
+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
 ----------------------------------
@@ -718,29 +784,21 @@ CLOCK_TICK - Announce a clock tick
 
 **DIRECTIVE STATUS CODES:**
 
-``RTEMS_SUCCESSFUL`` - clock tick processed successfully
+``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
+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.
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+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.