RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

timespec: Add documentation for struct timespec Helpers

Browse Source 
Joel editted the documentation for clarity, grammar and technical
correctness. I also moved it in the manual and added @findex
entries. The core work was just polished.

Author: Krzysztof Mięsowicz <krzysztof.miesowicz@gmail.com>
This commit is contained in:
Joel Sherrill joel.sherrill@oarcorp.com
2012-08-30 18:38:50 -05:00
parent a6eaa5489c
commit 66dacbfb8e
4 changed files with 565 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/ada_user/ada_user.texi
View File

@@ -109,6 +109,7 @@
@include user/cpuuse.texi
@include user/object.texi
@include user/chains.texi
@include user/timespec.texi
@include user/cbs.texi
@include user/dirstat.texi
@include example.texi
@@ -147,6 +148,7 @@
* CPU Usage Statistics::
* Object Services::
* Chains::
* Timespec Helpers::
* Constant Bandwidth Server Scheduler API::
* Directive Status Codes::
* Example Application::

10
doc/user/Makefile.am
View File

@@ -14,7 +14,8 @@ GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \
task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \
signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \
schedule.texi rtmon.texi barrier.texi bsp.texi userext.texi conf.texi \
mp.texi stackchk.texi cpuuse.texi object.texi chains.texi cbs.texi
mp.texi stackchk.texi cpuuse.texi object.texi chains.texi timespec.texi \
cbs.texi
COMMON_FILES += $(top_srcdir)/common/cpright.texi
@@ -179,11 +180,16 @@ object.texi: object.t
chains.texi: chains.t
$(BMENU2) -p "Object Services OBJECT_GET_CLASS_INFORMATION - Obtain Class Information" \
-u "Top" \
-n "Timespec Helpers" < $< > $@
timespec.texi: timespec.t
$(BMENU2) -p "Chains Prepend a Node" \
-u "Top" \
-n "Constant Bandwidth Server Scheduler API" < $< > $@
cbs.texi: cbs.t
$(BMENU2) -p "Chains Prepend a Node" \
$(BMENU2) -p "Timespec Helpers TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation" \
-u "Top" \
-n "Directive Status Codes" < $< > $@

2
doc/user/c_user.texi
View File

@@ -108,6 +108,7 @@
@include cpuuse.texi
@include object.texi
@include chains.texi
@include timespec.texi
@include cbs.texi
@include dirstat.texi
@include example.texi
@@ -146,6 +147,7 @@
* CPU Usage Statistics::
* Object Services::
* Chains::
* Timespec Helpers::
* Constant Bandwidth Server Scheduler API::
* Directive Status Codes::
* Example Application::

553
doc/user/timespec.t Normal file
View File

@@ -0,0 +1,553 @@
@c
@c COPYRIGHT (c) 1988-2012.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@chapter Timespec Helpers
@section Introduction
The Timespec helpers manager provides directives to assist in manipulating
instances of the POSIX @code{struct timespec} structure.
The directives provided by the timespec helpers manager are:
@itemize @bullet
@item @code{rtems_timespec_set} - Set timespec's value
@item @code{rtems_timespec_zero} - Zero timespec's value
@item @code{rtems_timespec_is_valid} - Check if timespec is valid
@item @code{rtems_timespec_add_to} - Add two timespecs
@item @code{rtems_timespec_subtract} - Subtract two timespecs
@item @code{rtems_timespec_divide} - Divide two timespecs
@item @code{rtems_timespec_divide_by_integer} - Divide timespec by integer
@item @code{rtems_timespec_less_than} - Less than operator
@item @code{rtems_timespec_greater_than} - Greater than operator
@item @code{rtems_timespec_equal_to} - Check if two timespecs are equal
@item @code{rtems_timespec_get_seconds} - Obtain seconds portion of timespec
@item @code{rtems_timespec_get_nanoseconds} - Obtain nanoseconds portion of timespec
@item @code{rtems_timespec_to_ticks} - Convert timespec to number of ticks
@item @code{rtems_timespec_from_ticks} - Convert ticks to timespec
@end itemize
@section Background
@subsection Time Storage Conventions
Time can be stored in many ways. One of them is the @code{struct timespec}
format which is a structure that consists of the fields @code{tv_sec}
to represent seconds and @code{tv_nsec} to represent nanoseconds. The
@code{struct timeval} structure is simular and consists of seconds (stored
in @code{tv_sec}) and microseconds (stored in @code{tv_usec}). Either
@code{struct timespec} or @code{struct timeval} can be used to represent
elapsed time, time of executing some operations, or time of day.
@section Operations
@subsection Set and Obtain Timespec Value
A user may write a specific time by passing the desired seconds and
nanoseconds values and the destination @code{struct timespec} using the
@code{rtems_timespec_set} directive.
The @code{rtems_timespec_zero} directive is used to zero the seconds
and nanoseconds portions of a @code{struct timespec} instance.
Users may obtain the seconds or nanoseconds portions of a @code{struct
timespec} instance with the @code{rtems_timespec_get_seconds} or
@code{rtems_timespec_get_nanoseconds} methods, respectively.
@subsection Timespec Math
A user can perform multiple operations on @code{struct timespec}
instances. The helpers in this manager assist in adding, subtracting, and
performing divison on @code{struct timespec} instances.
@itemize @bullet
@item Adding two @code{struct timespec} can be done using the
@code{rtems_timespec_add_to} directive. This directive is used mainly
to calculate total amount of time consumed by multiple operations.
@item The @code{rtems_timespec_subtract} is used to subtract two
@code{struct timespecs} instances and determine the elapsed time between
those two points in time.
@item The @code{rtems_timespec_divide} is used to use to divide one
@code{struct timespec} instance by another. This calculates the percentage
with a precision to three decimal points.
@item The @code{rtems_timespec_divide_by_integer} is used to divide a
@code{struct timespec} instance by an integer. It is commonly used in
benchmark calculations to dividing duration by the number of iterations
performed.
@end itemize
@subsection Comparing struct timespec Instances
A user can compare two @code{struct timespec} instances using the
@code{rtems_timespec_less_than}, @code{rtems_timespec_greater_than}
or @code{rtems_timespec_equal_to} routines.
@subsection Conversions and Validity Check
Conversion to and from clock ticks may be performed by using the
@code{rtems_timespec_to_ticks} and @code{rtems_timespec_from_ticks}
directives.
User can also check validity of timespec with
@code{rtems_timespec_is_valid} routine.
@section Directives
This section details the Timespec Helpers 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.
@page
@subsection TIMESPEC_SET - Set struct timespec Instance
@subheading CALLING SEQUENCE:
@ifset is-C
@example
void rtems_timespec_set(
struct timespec *time,
time_t seconds,
uint32_t nanoseconds
);
@end example
@findex rtems_timespec_set
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This directive sets the @code{struct timespec} @code{time} value to the
desired @code{seconds} and @code{nanoseconds} values.
@subheading NOTES:
This method does NOT check if @code{nanoseconds} is less than the
maximum number of nanoseconds in a second.
@page
@subsection TIMESPEC_ZERO - Zero struct timespec Instance
@subheading CALLING SEQUENCE:
@ifset is-C
@example
void rtems_timespec_zero(
struct timespec *time
);
@end example
@findex rtems_timespec_zero
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This routine sets the contents of the @code{struct timespec} instance
@code{time} to zero.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_IS_VALID - Check validity of a struct timespec instance
@subheading CALLING SEQUENCE:
@ifset is-C
@example
bool rtems_timespec_is_valid(
const struct timespec *time
);
@end example
@findex rtems_timespec_is_valid
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns @code{true} if the instance is valid, and @code{false}
otherwise.
@subheading DESCRIPTION:
This routine check validity of a @code{struct timespec} instance. It
checks if the nanoseconds portion of the @code{struct timespec} instanceis
in allowed range (less than the maximum number of nanoseconds per second).
@subheading NOTES:
@page
@subsection TIMESPEC_ADD_TO - Add Two struct timespec Instances
@subheading CALLING SEQUENCE:
@ifset is-C
@example
uint32_t rtems_timespec_add_to(
struct timespec *time,
const struct timespec *add
);
@end example
@findex rtems_timespec_add_to
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
The method returns the number of seconds @code{time} increased by.
@subheading DESCRIPTION:
This routine adds two @code{struct timespec} instances. The second argument is added to the first. The parameter @code{time} is the base time to which the @code{add} parameter is added.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
@subheading CALLING SEQUENCE:
@ifset is-C
@example
void rtems_timespec_subtract(
const struct timespec *start,
const struct timespec *end,
struct timespec *result
);
@end example
@findex rtems_timespec_subtract
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This routine subtracts @code{start} from @code{end} saves the difference
in @code{result}. The primary use of this directive is to calculate
elapsed time.
@subheading NOTES:
It is possible to subtract when @code{end} is less than @code{start}
and it produce negative @code{result}. When doing this you should be
careful and remember that only the seconds portion of a @code{struct
timespec} instance is signed, which means that nanoseconds portion is
always increasing. Due to that when your timespec has seconds = -1 and
nanoseconds=500,000,000 it means that result is -0.5 second, NOT the
expected -1.5!
@page
@subsection TIMESPEC_DIVIDE - Divide Two struct timespec Instances
@subheading CALLING SEQUENCE:
@ifset is-C
@example
void rtems_timespec_divide(
const struct timespec *lhs,
const struct timespec *rhs,
uint32_t *ival_percentage,
uint32_t *fval_percentage
);
@end example
@findex rtems_timespec_divide
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This routine divides the @code{struct timespec} instance @code{lhs} by
the @code{struct timespec} instance @code{rhs}. The result is returned
in the @code{ival_percentage} and @code{fval_percentage}, representing
the integer and fractional results of the division respectively.
The @code{ival_percentage} is integer value of calculated percentage and @code{fval_percentage} is fractional part of calculated percentage.
@subheading NOTES:
The intended use is calculating percentges to three decimal points.
When dividing by zero, this routine return both @code{ival_percentage}
and @code{fval_percentage} equal zero.
The division is performed using exclusively integer operations.
@page
@subsection TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
@subheading CALLING SEQUENCE:
@ifset is-C
@example
int rtems_timespec_divide_by_integer(
const struct timespec *time,
uint32_t iterations,
struct timespec *result
);
@end example
@findex rtems_timespec_divide_by_integer
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This routine divides the @code{struct timespec} instance @code{time} by the integer value @code{iterations}.
The result is saved in @code{result}.
@subheading NOTES:
The expected use is to assist in benchmark calculations where you
typically divide a duration (@code{time}) by a number of iterations what
gives average time.
@page
@subsection TIMESPEC_LESS_THAN - Less than operator
@subheading CALLING SEQUENCE:
@ifset is-C
@example
bool rtems_timespec_less_than(
const struct timespec *lhs,
const struct timespec *rhs
);
@end example
@findex rtems_timespec_less_than
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns @code{struct true} if @code{lhs} is less than
@code{rhs} and @code{struct false} otherwise.
@subheading DESCRIPTION:
This method is the less than operator for @code{struct timespec} instances. The first parameter is the left hand side and the second is the right hand side of the comparison.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_GREATER_THAN - Greater than operator
@subheading CALLING SEQUENCE:
@ifset is-C
@example
bool rtems_timespec_greater_than(
const struct timespec *_lhs,
const struct timespec *_rhs
);
@end example
@findex rtems_timespec_greater_than
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns @code{struct true} if @code{lhs} is greater than
@code{rhs} and @code{struct false} otherwise.
@subheading DESCRIPTION:
This method is greater than operator for @code{struct timespec} instances.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_EQUAL_TO - Check equality of timespecs
@subheading CALLING SEQUENCE:
@ifset is-C
@example
bool rtems_timespec_equal_to(
const struct timespec *lhs,
const struct timespec *rhs
);
@end example
@findex rtems_timespec_equal_to
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns @code{struct true} if @code{lhs} is equal to
@code{rhs} and @code{struct false} otherwise.
@subheading DESCRIPTION:
This method is equality operator for @code{struct timespec} instances.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
@subheading CALLING SEQUENCE:
@ifset is-C
@example
time_t rtems_timespec_get_seconds(
struct timespec *time
);
@end example
@findex rtems_timespec_get_seconds
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns the seconds portion of the specified @code{struct
timespec} instance.
@subheading DESCRIPTION:
This method returns the seconds portion of the specified @code{struct timespec} instance @code{time}.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
@subheading CALLING SEQUENCE:
@ifset is-C
@example
uint32_t rtems_timespec_get_nanoseconds(
struct timespec *_time
);
@end example
@findex rtems_timespec_get_nanoseconds
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This method returns the nanoseconds portion of the specified @code{struct
timespec} instance.
@subheading DESCRIPTION:
This method returns the nanoseconds portion of the specified timespec
which is pointed by @code{_time}.
@subheading NOTES:
@page
@subsection TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
@subheading CALLING SEQUENCE:
@ifset is-C
@example
uint32_t rtems_timespec_to_ticks(
const struct timespec *time
);
@end example
@findex rtems_timespec_to_ticks
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
This directive returns the number of ticks computed.
@subheading DESCRIPTION:
This directive converts the @code{time} timespec to the corresponding number of clock ticks.
@subheading NOTES:
NONE
@page
@subsection TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
@subheading CALLING SEQUENCE:
@ifset is-C
@example
void rtems_timespec_from_ticks(
uint32_t ticks,
struct timespec *time
);
@end example
@findex rtems_timespec_from_ticks
@end ifset
@ifset is-Ada
Not Currently Supported In Ada
@end ifset
@subheading STATUS CODES:
NONE
@subheading DESCRIPTION:
This routine converts the @code{ticks} to the corresponding @code{struct timespec} representation and stores it in @code{time}.
@subheading NOTES:
NONE