Ticket #2693: 0002-doc-user-clock.t-Remove-obsolete-rtems_clock_get.patch

File 0002-doc-user-clock.t-Remove-obsolete-rtems_clock_get.patch, 8.0 KB (added by Joel Sherrill, on 04/14/16 at 21:53:01)

  • doc/user/clock.t 

    From 22bb7378b77f97c04ca9a5f9bdb02c9116c8aa6f Mon Sep 17 00:00:00 2001
From: Joel Sherrill <joel@rtems.org>
Date: Thu, 14 Apr 2016 16:37:37 -0500
Subject: [PATCH 2/2] doc/user/clock.t: Remove obsolete rtems_clock_get()

---
 doc/user/clock.t |  167 +++++++++++-------------------------------------------
 1 files changed, 33 insertions(+), 134 deletions(-)

diff --git a/doc/user/clock.t b/doc/user/clock.t
index f67003c..451337d 100644
    a b the clock manager are: 
    1515
    1616@itemize @bullet
    1717@item @code{@value{DIRPREFIX}clock_set} - Set date and time
    18 @item @code{@value{DIRPREFIX}clock_get} - Get date and time information
    1918@item @code{@value{DIRPREFIX}clock_get_tod} - Get date and time in TOD format
    2019@item @code{@value{DIRPREFIX}clock_get_tod_timeval} - Get date and time in timeval format
    2120@item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch} - Get seconds since epoch
    … … supported when setting the system date and time using the 
    9190@code{@value{DIRPREFIX}clock_set} directive.  Some applications
    9291expect to operate on a "UNIX-style" date and time data structure.  The
    9392@code{@value{DIRPREFIX}clock_get_tod_timeval} always returns
    94 the date and time in @code{struct timeval} format.  The
    95 @code{@value{DIRPREFIX}clock_get} directive can optionally return
    96 the current date and time in this format.
     93the date and time in @code{struct timeval} format.
    9794
    9895The @code{struct timeval} data structure has two fields: @code{tv_sec}
    9996and @code{tv_usec} which are seconds and microseconds, respectively.
    … … the @code{@value{DIRPREFIX}clock_set} directive. 
    182179
    183180@subsection Obtaining the Time
    184181
    185 The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to
    186 obtain the current date and time or date and time related
    187 information.  The current date and time can be returned in
    188 either native or UNIX-style format.  Additionally, the
    189 application can obtain date and time related information such as
    190 the number of seconds since the RTEMS epoch, the number of ticks
    191 since the executive was initialized, and the number of ticks per
    192 second.  The information returned by the
    193 @code{@value{DIRPREFIX}clock_get} directive is
    194 dependent on the option selected by the caller.  This
    195 is specified using one of the following constants
    196 associated with the enumerated type
    197 @code{@value{DIRPREFIX}clock_get_options}:
    198 
    199 @findex rtems_clock_get_options
     182RTEMS provides a variety of methods to allot a task or an ISR to obtain
     183the current time or time related information in various formats.
     184
     185The @code{@value{DIRPREFIX}clock_get_tod} directive allows a task or an ISR to
     186obtain the current date and time in Classic API format.
     187
     188The @code{@value{DIRPREFIX}clock_get_tod_timeval} directive can be used
     189to obtain the date and time in either UNIX-style @code{struct timeval} format.
     190
     191Additionally, the application can obtain date and time related
     192information such as the number of seconds since the RTEMS epoch
     193(@code{@value{DIRPREFIX}clock_get_seconds_since_epoch}, the number
     194of ticks since RTEMS was initialized
     195(@code{@value{DIRPREFIX}clock_get_ticks_since_boot}), and the number of ticks
     196per second (@code{@value{DIRPREFIX}clock_get_ticks_since_boot}).
     197
     198Calendar time operations will return an error code if invoked before
     199the date and time have been set.
     200
     201The @code{@value{DIRPREFIX}clock_get} directive was removed after
     202the RTEMS 4.11 release series. All uses of this directive can be
     203replaced with a corresponding strongly typed method:
    200204
    201205@itemize @bullet
    202 @item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
     206@item @code{@value{RPREFIX}CLOCK_GET_TOD} -
     207  @code{@value{DIRPREFIX}clock_get_tod}
    203208
    204 @item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style
    205 date and time
     209@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} -
     210  @code{@value{DIRPREFIX}clock_get_tod_timeval}
    206211
    207 @item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
    208 since RTEMS was initialized
     212@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} -
     213  @item @code{@value{DIRPREFIX}clock_get_ticks_since_boot}
    209214
    210 @item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number
    211 of seconds since RTEMS epoch
     215@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} -
     216  @item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch}
    212217
    213 @item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock
    214 ticks per second
     218@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} -
     219@item @code{@value{DIRPREFIX}clock_get_ticks_per_second}
    215220
    216221@end itemize
    217222
    218 Calendar time operations will return an error code if
    219 invoked before the date and time have been set.
    220 
    221223@section Directives
    222224
    223225This section details the clock manager's directives.
    … … the system date and time to application specific specifications. 
    286288@c
    287289@c
    288290@page
    289 @subsection CLOCK_GET - Get date and time information
    290 
    291 @cindex obtain the time of day
    292 
    293 @subheading CALLING SEQUENCE:
    294 
    295 @ifset is-C
    296 @findex rtems_clock_get
    297 @example
    298 rtems_status_code rtems_clock_get(
    299   rtems_clock_get_options  option,
    300   void                    *time_buffer
    301 );
    302 @end example
    303 @end ifset
    304 
    305 @ifset is-Ada
    306 @example
    307 procedure Clock_Get (
    308    Option      : in     RTEMS.Clock_Get_Options;
    309    Time_Buffer : in     RTEMS.Address;
    310    Result      :    out RTEMS.Status_Codes
    311 );
    312 @end example
    313 @end ifset
    314 
    315 @subheading DIRECTIVE STATUS CODES:
    316 @code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
    317 @code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
    318 @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
    319 
    320 @subheading DESCRIPTION:
    321 
    322 This directive is deprecated.
    323 
    324 This directive obtains the system date and time.  If
    325 the caller is attempting to obtain the date and time (i.e.
    326 option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
    327 @code{@value{RPREFIX}CLOCK_GET_TOD}, or
    328 @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
    329 has not been set with a previous call to
    330 @code{@value{DIRPREFIX}clock_set}, then the
    331 @code{@value{RPREFIX}NOT_DEFINED} status code is returned.
    332 The caller can always obtain the number of ticks per second (option is
    333 @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of
    334 ticks since the executive was initialized option is
    335 @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
    336 
    337 The @code{option} argument may taken on any value of the enumerated
    338 type @code{rtems_clock_get_options}.  The data type expected for
    339 @code{time_buffer} is based on the value of @code{option} as
    340 indicated below:
    341 
    342 @findex rtems_clock_get_options
    343 @ifset is-C
    344 @itemize @bullet
    345 @item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)
    346 
    347 @item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *)
    348 
    349 @item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *)
    350 
    351 @item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *)
    352 
    353 @item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (struct timeval *)
    354 
    355 @end itemize
    356 @end ifset
    357 
    358 @ifset is-Ada
    359 @itemize @bullet
    360 @item @code{@value{RPREFIX}Clock_Get_TOD} - Address of an variable of
    361 type RTEMS.Time_Of_Day
    362 
    363 @item @code{@value{RPREFIX}Clock_Get_Seconds_Since_Epoch} - Address of an
    364 variable of type RTEMS.Interval
    365 
    366 @item @code{@value{RPREFIX}Clock_Get_Ticks_Since_Boot} - Address of an
    367 variable of type RTEMS.Interval
    368 
    369 @item @code{@value{RPREFIX}Clock_Get_Ticks_Per_Second} - Address of an
    370 variable of type RTEMS.Interval
    371 
    372 @item @code{@value{RPREFIX}Clock_Get_Time_Value} - Address of an variable of
    373 type RTEMS.Clock_Time_Value
    374 
    375 @end itemize
    376 @end ifset
    377 
    378 @subheading NOTES:
    379 
    380 This directive is callable from an ISR.
    381 
    382 This directive will not cause the running task to be
    383 preempted.  Re-initializing RTEMS causes the system date and
    384 time to be reset to an uninitialized state.  Another call to
    385 @code{@value{DIRPREFIX}clock_set} is required to re-initialize the
    386 system date and time to application specific specifications.
    387 
    388 @c
    389 @c
    390 @c
    391 @page
    392291@subsection CLOCK_GET_TOD - Get date and time in TOD format
    393292
    394293@cindex obtain the time of day