[PATCH 2/3] c-user: Add removed directive rtems_clock_get()

Gedare Bloom gedare at rtems.org
Wed Apr 15 13:55:01 UTC 2020


On Tue, Apr 14, 2020 at 9:13 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> Be in line with Task Manager chapter.
>
> Update #2693.
> ---
>  c-user/clock_manager.rst | 128 +++++++++++++++++++++++++++++++++++++++--------
>  1 file changed, 107 insertions(+), 21 deletions(-)
>
> diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst
> index 905d327..9ece420 100644
> --- a/c-user/clock_manager.rst
> +++ b/c-user/clock_manager.rst
> @@ -184,20 +184,28 @@ RTEMS provides multiple directives which can be used by an application to obtain
>  Calendar time operations will return an error code if invoked before the date
>  and time have been set.
>
> -.. index:: rtems_clock_get
> +.. _ClockManagerAdviceClockGet:
> +
> +Transition Advice for the Removed rtems_clock_get()
> +---------------------------------------------------
> +
> +The method :ref:`rtems_clock_get` took an untyped pointer with an options
> +argument to indicate the time information desired. This has been replaced with
> +a set of typed directives:
> +
> +* :ref:`rtems_clock_get_seconds_since_epoch`
>
> -Transition Advice for the Obsolete rtems_clock_get
> ---------------------------------------------------
> +* :ref:`rtems_clock_get_ticks_per_second`
>
> -The method ``rtems_clock_get`` took an untyped pointer with an
> -options argument to indicate the time information desired. This has
> -been replaced with a set of typed directives whose name is of the form
> -``rtems_clock_get_INFORMATION`` where INFORMATION indicates the type of
> -information and possibly the format.  These methods directly correspond to
> -what were previously referred to ask "clock options." These strongly typed
> -were available for multiple releases in parallel with ``rtems_clock_get``
> -until that method was removed.
> +* :ref:`rtems_clock_get_ticks_since_boot`
>
> +* :ref:`rtems_clock_get_tod`
> +
> +* :ref:`rtems_clock_get_tod_timeval`
> +
> +These methods directly correspond to what were previously referred to ask
s/ask/as

> +*clock options*.  These strongly typed were available for multiple releases in
add "methods" after typed

> +parallel with :c:func:`rtems_clock_get` until that method was removed.
>
>  Directives
>  ==========
> @@ -260,11 +268,11 @@ NOTES:
>
>     \clearpage
>
> -.. _rtems_clock_get_tod:
> -
>  .. index:: obtain the time of day
>  .. index:: rtems_clock_get_tod
>
> +.. _rtems_clock_get_tod:
> +
>  CLOCK_GET_TOD - Get date and time in TOD format
>  -----------------------------------------------
>
> @@ -304,11 +312,11 @@ NOTES:
>
>     \clearpage
>
> -.. _rtems_clock_get_tod_timeval:
> -
>  .. index:: obtain the time of day
>  .. index:: rtems_clock_get_tod_timeval
>
> +.. _rtems_clock_get_tod_timeval:
> +
>  CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
>  -----------------------------------------------------------
>
> @@ -348,11 +356,11 @@ NOTES:
>
>     \clearpage
>
> -.. _rtems_clock_get_seconds_since_epoch:
> -
>  .. index:: obtain seconds since epoch
>  .. index:: rtems_clock_get_seconds_since_epoch
>
> +.. _rtems_clock_get_seconds_since_epoch:
> +
>  CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
>  -------------------------------------------------------
>
> @@ -392,11 +400,11 @@ NOTES:
>
>     \clearpage
>
> -.. _rtems_clock_get_ticks_per_second:
> -
>  .. index:: obtain seconds since epoch
>  .. index:: rtems_clock_get_ticks_per_second
>
> +.. _rtems_clock_get_ticks_per_second:
> +
>  CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
>  -------------------------------------------------
>
> @@ -422,12 +430,12 @@ NOTES:
>
>     \clearpage
>
> -.. _rtems_clock_get_ticks_since_boot:
> -
>  .. index:: obtain ticks since boot
>  .. index:: get current ticks counter value
>  .. index:: rtems_clock_get_ticks_since_boot
>
> +.. _rtems_clock_get_ticks_since_boot:
> +
>  CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
>  ------------------------------------------------------------
>
> @@ -666,3 +674,81 @@ DESCRIPTION:
>
>  NOTES:
>      This directive may be called from an ISR.
> +
> +Removed Directives
> +==================
> +
> +.. raw:: latex
> +
> +   \clearpage
> +
> +.. _rtems_clock_get:
> +
> +CLOCK_GET - Get date and time information
> +-----------------------------------------
> +.. index:: obtain the time of day
> +.. index:: rtems_clock_get
> +
> +.. warning::
> +
> +    This directive was removed in RTEMS 5.1.  See also
> +    :ref:`ClockManagerAdviceClockGet`.
> +
> +CALLING SEQUENCE:
> +    .. code-block:: c
> +
> +        rtems_status_code rtems_clock_get(
> +           rtems_clock_get_options  option,
> +           void                    *time_buffer
> +        );
> +
> +DIRECTIVE STATUS CODES:
> +    .. list-table::
> +      :class: rtems-table
> +
> +      * - ``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.
> --
> 2.16.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel


More information about the devel mailing list