From 235fb7ab8023d8e325fc7446910382187dd8750e Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 1 Feb 2008 21:56:47 +0000 Subject: 2008-02-01 Joel Sherrill * user/object.t: Added some examples. --- doc/ChangeLog | 4 +++ doc/user/object.t | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 81 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index 1d1981e9f0..fcf6da2ff4 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-02-01 Joel Sherrill + + * user/object.t: Added some examples. + 2008-02-01 Joel Sherrill * user/object.t: Add Ada binding for Object Services. diff --git a/doc/user/object.t b/doc/user/object.t index 5982e21f91..73175766ba 100644 --- a/doc/user/object.t +++ b/doc/user/object.t @@ -84,13 +84,86 @@ a user defined name in CPU Usage Reports. @section Operations -@subsection Decomposing an Object Id +@subsection Decomposing and Recomposing an Object Id -TBD +Services are provided to decompose an object Id into its +subordinate components. The following services are used +to do this: -@subsection Building an Object Id +@itemize @bullet +@item @code{@value{DIRPREFIX}object_id_get_api} +@item @code{@value{DIRPREFIX}object_id_get_class} +@item @code{@value{DIRPREFIX}object_id_get_node} +@item @code{@value{DIRPREFIX}object_id_get_index} +@end itemize + +The following C language example illustrates the +decomposition of an Id and printing the values. + +@example +void printObjectId(rtems_id id) +@{ + printf( + "API=%d Class=%d Node=%d Index=%d\n", + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); +@} +@end example + +This prints the components of the Ids as integers. + +It is also possible to construct an arbitrary Id using +the @code{@value{DIRPREFIX}build_id} service. The following +C language example illustrates how to construct the +"next Id." + +@example +rtems_id nextObjectId(rtems_id id) +@{ + return rtems_build_id( + rtems_object_id_get_api(id), + rtems_object_id_get_class(id), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + 1 + ); +@} +@end example + +Note that this Id may not be valid in this +system or associated with an allocated object. + +@subsection Printing an Object Id + +RTEMS also provides services to associate the API and Class +portions of an Object Id with strings. This allows the +application developer to provide more information about +an object in diagnostic messages. + +In the following C language example, an Id is decomposed into +its constituent parts and "pretty-printed." + +@example +void prettyPrintObjectId(rtems_id id) +@{ + uint32_t tmpAPI, tmpClass; + + tmpAPI = rtems_object_id_get_api(id), + tmpClass = rtems_object_id_get_class(id), + + printf( + "API=%s Class=%s Node=%d Index=%d\n", + rtems_object_get_api_name(tmpAPI), + rtems_object_get_api_class_name(tmpAPI, tmpClass), + rtems_object_id_get_node(id), + rtems_object_id_get_index(id) + ); +@} +@end example -TBD +@section Directives @c @c -- cgit v1.2.3