Changeset 21e0fcd in rtems-docs


Ignore:
Timestamp:
Oct 11, 2017, 11:41:41 PM (22 months ago)
Author:
Joel Sherrill <joel@…>
Branches:
master
Children:
d36d685
Parents:
d8f7bdc
Message:

c-user: Update to reflect rtems_clock_get() being obsoleted.

Closes #2693.

Location:
c-user
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • c-user/clock_manager.rst

    rd8f7bdc r21e0fcd  
    1818
    1919- rtems_clock_set_ - Set date and time
    20 
    21 - rtems_clock_get_ - Get date and time information
    2220
    2321- rtems_clock_get_tod_ - Get date and time in TOD format
     
    8785applications expect to operate on a *UNIX-style* date and time data structure.
    8886The ``rtems_clock_get_tod_timeval`` always returns the date and time in
    89 ``struct timeval`` format.  The ``rtems_clock_get`` directive can optionally
    90 return the current date and time in this format.
     87``struct timeval`` format.
    9188
    9289The ``struct timeval`` data structure has two fields: ``tv_sec`` and
     
    167164------------------
    168165
    169 The ``rtems_clock_get`` directive allows a task or an ISR to obtain the current
    170 date and time or date and time related information.  The current date and time
    171 can be returned in either native or *UNIX-style* format.  Additionally, the
    172 application can obtain date and time related information such as the number of
    173 seconds since the RTEMS epoch, the number of ticks since the executive was
    174 initialized, and the number of ticks per second.  The information returned by
    175 the ``rtems_clock_get`` directive is dependent on the option selected by the
    176 caller.  This is specified using one of the following constants associated with
    177 the enumerated type ``rtems_clock_get_options``:
    178 
    179 .. index:: rtems_clock_get_options
    180 
    181 ``RTEMS_CLOCK_GET_TOD``
     166RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information.  These directives allow 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 following directives are available:
     167
     168``rtems_clock_get_tod``
    182169  obtain native style date and time
    183170
    184 ``RTEMS_CLOCK_GET_TIME_VALUE``
     171``rtems_clock_get_time_value``
    185172  obtain *UNIX-style* date and time
    186173
    187 ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``
     174``rtems_clock_get_ticks_since_boot``
    188175  obtain number of ticks since RTEMS was initialized
    189176
    190 ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``
     177``rtems_clock_get_seconds_since_epoch``
    191178  obtain number of seconds since RTEMS epoch
    192179
    193 ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``
     180``rtems_clock_get_ticks_per_second``
    194181  obtain number of clock ticks per second
    195182
    196183Calendar time operations will return an error code if invoked before the date
    197184and time have been set.
     185
     186Transition Advice for the Obsolete rtems_clock_get
     187--------------------------------------------------
     188
     189.. index:: rtems_clock_get
     190
     191The method ``rtems_clock_get`` took an untyped pointer with an
     192options argument to indicate the time information desired. This has
     193been replaced with a set of typed directives whose name is of the form
     194``rtems_clock_get_INFORMATION`` where INFORMATION indicates the type of
     195information and possibly the format.  These methods directly correspond to
     196what were previously referred to ask "clock options." These strongly typed
     197were available for multiple releases in parallel with ``rtems_clock_get``
     198until that method was removed.
     199
    198200
    199201Directives
     
    248250    be preempted after the next clock tick.
    249251
    250     Re-initializing RTEMS causes the system date and time to be reset to an
    251     uninitialized state.  Another call to ``rtems_clock_set`` is required to
    252     re-initialize the system date and time to application specific
    253     specifications.
    254 
    255 .. raw:: latex
    256 
    257    \clearpage
    258 
    259 .. _rtems_clock_get:
    260 
    261 CLOCK_GET - Get date and time information
    262 -----------------------------------------
    263 .. index:: obtain the time of day
    264 .. index:: rtems_clock_get
    265 
    266 .. warning::
    267 
    268   This directive is deprecated and will be removed.
    269 
    270 CALLING SEQUENCE:
    271     .. code-block:: c
    272 
    273         rtems_status_code rtems_clock_get(
    274            rtems_clock_get_options  option,
    275            void                    *time_buffer
    276         );
    277 
    278 DIRECTIVE STATUS CODES:
    279     .. list-table::
    280       :class: rtems-table
    281 
    282       * - ``RTEMS_SUCCESSFUL``
    283         - current time obtained successfully
    284       * - ``RTEMS_NOT_DEFINED``
    285         - system date and time is not set
    286       * - ``RTEMS_INVALID_ADDRESS``
    287         - ``time_buffer`` is NULL
    288 
    289 DESCRIPTION:
    290     This directive obtains the system date and time.  If the caller is
    291     attempting to obtain the date and time (i.e.  option is set to either
    292     ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
    293     ``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with
    294     a previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED``
    295     status code is returned.  The caller can always obtain the number of ticks
    296     per second (option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number
    297     of ticks since the executive was initialized option is
    298     ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
    299 
    300     The ``option`` argument may taken on any value of the enumerated type
    301     ``rtems_clock_get_options``.  The data type expected for ``time_buffer`` is
    302     based on the value of ``option`` as indicated below:
    303 
    304     .. index:: rtems_clock_get_options
    305 
    306     +-----------------------------------------+---------------------------+
    307     | Option                                  | Return type               |
    308     +=========================================+===========================+
    309     | ``RTEMS_CLOCK_GET_TOD``                 | ``(rtems_time_of_day *)`` |
    310     +-----------------------------------------+---------------------------+
    311     | ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)``    |
    312     +-----------------------------------------+---------------------------+
    313     | ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``    | ``(rtems_interval *)``    |
    314     +-----------------------------------------+---------------------------+
    315     |``RTEMS_CLOCK_GET_TICKS_PER_SECOND``     | ``(rtems_interval *)``    |
    316     +-----------------------------------------+---------------------------+
    317     | ``RTEMS_CLOCK_GET_TIME_VALUE``          | ``(struct timeval *)``    |
    318     +-----------------------------------------+---------------------------+
    319 
    320 NOTES:
    321     This directive is callable from an ISR.
    322 
    323     This directive will not cause the running task to be preempted.
    324252    Re-initializing RTEMS causes the system date and time to be reset to an
    325253    uninitialized state.  Another call to ``rtems_clock_set`` is required to
  • c-user/interrupt_manager.rst

    rd8f7bdc r21e0fcd  
    189189
    190190  - rtems_clock_set
    191   - rtems_clock_get
    192191  - rtems_clock_get_tod
    193192  - rtems_clock_get_tod_timeval
Note: See TracChangeset for help on using the changeset viewer.