source: rtems/doc/user/object.t @ e25611d

4.104.11
Last change on this file since e25611d was e25611d, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 23, 2009 at 2:53:28 PM

2009-11-23 Joel Sherrill <joel.sherrill@…>

PR 1460/cpukit

  • user/object.t: Change return type on methods accessing portions of RTEMS Ids to int. This allows -1 to be return on error.
  • Property mode set to 100644
File size: 20.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Object Services
10
11@cindex object manipulation
12
13@section Introduction
14
15RTEMS provides a collection of services to assist in the
16management and usage of the objects created and utilized
17via other managers.  These services assist in the
18manipulation of RTEMS objects independent of the API used
19to create them.  The object related services provided by
20RTEMS are:
21
22@itemize @bullet
23@c build_id
24@item @code{@value{DIRPREFIX}build_name} - build object name from characters
25@item @code{@value{DIRPREFIX}object_get_classic_name} - lookup name from Id
26@item @code{@value{DIRPREFIX}object_get_name} - obtain object name as string
27@item @code{@value{DIRPREFIX}object_set_name} - set object name
28@item @code{@value{DIRPREFIX}object_id_get_api} - obtain API from Id
29@item @code{@value{DIRPREFIX}object_id_get_class} - obtain class from Id
30@item @code{@value{DIRPREFIX}object_id_get_node} - obtain node from Id
31@item @code{@value{DIRPREFIX}object_id_get_index} - obtain index from Id
32@item @code{@value{DIRPREFIX}build_id} - build object id from components
33@item @code{@value{DIRPREFIX}object_id_api_minimum} - obtain minimum API value
34@item @code{@value{DIRPREFIX}object_id_api_maximum} - obtain maximum API value
35@item @code{@value{DIRPREFIX}object_id_api_minimum_class} - obtain minimum class value
36@item @code{@value{DIRPREFIX}object_id_api_maximum_class} - obtain maximum class value
37@item @code{@value{DIRPREFIX}object_get_api_name} - obtain API name
38@item @code{@value{DIRPREFIX}object_get_api_class_name} - obtain class name
39@item @code{@value{DIRPREFIX}object_get_class_information} - obtain class information
40@end itemize
41
42@section Background
43
44@subsection APIs
45
46RTEMS implements multiple APIs including an Internal API,
47the Classic API, the POSIX API, and the uITRON API.  These
48APIs share the common foundation of SuperCore objects and
49thus share object management code. This includes a common
50scheme for object Ids and for managing object names whether
51those names be in the thirty-two bit form used by the Classic
52API or C strings.
53
54The object Id contains a field indicating the API that
55an object instance is associated with.  This field
56holds a numerically small non-zero integer.
57
58@subsection Object Classes
59
60Each API consists of a collection of managers.  Each manager
61is responsible for instances of a particular object class.
62Classic API Tasks and POSIX Mutexes example classes. 
63
64The object Id contains a field indicating the class that
65an object instance is associated with.  This field
66holds a numerically small non-zero integer.  In all APIs,
67a class value of one is reserved for tasks or threads.
68
69@subsection Object Names
70
71Every RTEMS object which has an Id may also have a
72name associated with it.  Depending on the API, names
73may be either thirty-two bit integers as in the Classic
74API or strings as in the POSIX API. 
75
76Some objects have Ids but do not have a defined way to associate
77a name with them.  For example, POSIX threads have
78Ids but per POSIX do not have names. In RTEMS, objects
79not defined to have thirty-two bit names may have string
80names assigned to them via the @code{@value{DIRPREFIX}object_set_name}
81service.  The original impetus in providing this service
82was so the normally anonymous POSIX threads could have
83a user defined name in CPU Usage Reports.
84
85@section Operations
86
87@subsection Decomposing and Recomposing an Object Id
88
89Services are provided to decompose an object Id into its
90subordinate components. The following services are used
91to do this:
92
93@itemize @bullet
94@item @code{@value{DIRPREFIX}object_id_get_api}
95@item @code{@value{DIRPREFIX}object_id_get_class}
96@item @code{@value{DIRPREFIX}object_id_get_node}
97@item @code{@value{DIRPREFIX}object_id_get_index}
98@end itemize
99
100The following C language example illustrates the
101decomposition of an Id and printing the values.
102
103@example
104void printObjectId(rtems_id id)
105@{
106  printf(
107    "API=%d Class=%d Node=%d Index=%d\n",
108    rtems_object_id_get_api(id),
109    rtems_object_id_get_class(id),
110    rtems_object_id_get_node(id),
111    rtems_object_id_get_index(id)
112  );
113@}
114@end example
115
116This prints the components of the Ids as integers.
117
118It is also possible to construct an arbitrary Id using
119the @code{@value{DIRPREFIX}build_id} service.  The following
120C language example illustrates how to construct the
121"next Id."
122
123@example
124rtems_id nextObjectId(rtems_id id)
125@{
126  return rtems_build_id(
127    rtems_object_id_get_api(id),
128    rtems_object_id_get_class(id),
129    rtems_object_id_get_node(id),
130    rtems_object_id_get_index(id) + 1
131  );
132@}
133@end example
134
135Note that this Id may not be valid in this
136system or associated with an allocated object.
137
138@subsection Printing an Object Id
139
140RTEMS also provides services to associate the API and Class
141portions of an Object Id with strings.  This allows the
142application developer to provide more information about
143an object in diagnostic messages.
144
145In the following C language example, an Id is decomposed into
146its constituent parts and "pretty-printed."
147
148@example
149void prettyPrintObjectId(rtems_id id)
150@{
151  int tmpAPI, tmpClass;
152
153  tmpAPI   = rtems_object_id_get_api(id),
154  tmpClass = rtems_object_id_get_class(id),
155
156  printf(
157    "API=%s Class=%s Node=%d Index=%d\n",
158    rtems_object_get_api_name(tmpAPI),
159    rtems_object_get_api_class_name(tmpAPI, tmpClass),
160    rtems_object_id_get_node(id),
161    rtems_object_id_get_index(id)
162  );
163@}
164@end example
165
166@section Directives
167
168@c
169@c
170@c
171@page
172@subsection BUILD_NAME - Build object name from characters
173
174@cindex build object name
175
176@subheading CALLING SEQUENCE:
177
178@ifset is-C
179@findex rtems_build_name
180@example
181rtems_name rtems_build_name(
182  uint8_t c1,
183  uint8_t c2,
184  uint8_t c3,
185  uint8_t c4
186);
187@end example
188@end ifset
189
190@ifset is-Ada
191@example
192procedure Build_Name(
193   c1   : in     RTEMS.Unsigned8;
194   c2   : in     RTEMS.Unsigned8;
195   c3   : in     RTEMS.Unsigned8;
196   c4   : in     RTEMS.Unsigned8;
197   Name :    out RTEMS.Name
198);
199@end example
200@end ifset
201
202@subheading DIRECTIVE STATUS CODES
203
204Returns a name constructed from the four characters.
205
206@subheading DESCRIPTION:
207
208This service takes the four characters provided as arguments
209and constructs a thirty-two bit object name with @code{c1}
210in the most significant byte and @code{c4} in the least
211significant byte.
212
213@subheading NOTES:
214
215This directive is strictly local and does not impact task scheduling.
216
217@c
218@c
219@c
220@page
221@subsection OBJECT_GET_CLASSIC_NAME - Lookup name from id
222
223@cindex get name from id
224@cindex obtain name from id
225
226@subheading CALLING SEQUENCE:
227
228@ifset is-C
229@findex rtems_build_name
230@example
231rtems_status_code rtems_object_get_classic_name(
232  rtems_id      id,
233  rtems_name   *name
234);
235@end example
236@end ifset
237
238@ifset is-Ada
239@example
240procedure Object_Get_Classic_Name(
241   ID     : in     RTEMS.ID;
242   Name   :    out RTEMS.Name;
243   Result :    out RTEMS.Status_Codes
244);
245@end example
246@end ifset
247
248@subheading DIRECTIVE STATUS CODES
249
250@code{@value{RPREFIX}SUCCESSFUL} - name looked up successfully@*
251@code{@value{RPREFIX}INVALID_ADDRESS} - invalid name pointer@*
252@code{@value{RPREFIX}INVALID_ID} - invalid object id@*
253
254@subheading DESCRIPTION:
255
256This service looks up the name for the object @code{id} specified
257and, if found, places the result in @code{*name}.
258
259@subheading NOTES:
260
261This directive is strictly local and does not impact task scheduling.
262
263@c
264@c
265@c
266@page
267@subsection OBJECT_GET_NAME - Obtain object name as string
268
269@cindex get object name as string
270@cindex obtain object name as string
271
272@subheading CALLING SEQUENCE:
273
274@ifset is-C
275@findex rtems_object_get_name
276@example
277char *rtems_object_get_name(
278  rtems_id       id,
279  size_t         length,
280  char          *name
281);
282@end example
283@end ifset
284
285@ifset is-Ada
286@example
287procedure Object_Get_Name(
288   ID     : in     RTEMS.ID;
289   Name   :    out RTEMS.Name;
290   Result :    out RTEMS.Status_Codes
291);
292@end example
293@end ifset
294
295@subheading DIRECTIVE STATUS CODES
296
297Returns a pointer to the name if successful or @code{NULL}
298otherwise.
299
300@subheading DESCRIPTION:
301
302This service looks up the name of the object specified by
303@code{id} and places it in the memory pointed to by @code{name}.
304Every attempt is made to return name as a printable string even
305if the object has the Classic API thirty-two bit style name.
306
307@subheading NOTES:
308
309This directive is strictly local and does not impact task scheduling.
310
311@c
312@c
313@c
314@page
315@subsection OBJECT_SET_NAME - Set object name
316
317@cindex set object name
318
319@subheading CALLING SEQUENCE:
320
321@ifset is-C
322@findex rtems_object_set_name
323@example
324rtems_status_code rtems_object_set_name(
325  rtems_id       id,
326  const char    *name
327);
328@end example
329@end ifset
330
331@ifset is-Ada
332@example
333procedure Object_Set_Name(
334   ID     : in     RTEMS.ID;
335   Name   : in     String;
336   Result :    out RTEMS.Status_Codes
337);
338@end example
339@end ifset
340
341@subheading DIRECTIVE STATUS CODES
342
343@code{@value{RPREFIX}SUCCESSFUL} - name looked up successfully@*
344@code{@value{RPREFIX}INVALID_ADDRESS} - invalid name pointer@*
345@code{@value{RPREFIX}INVALID_ID} - invalid object id@*
346
347@subheading DESCRIPTION:
348
349This service sets the name of @code{id} to that specified
350by the string located at @code{name}.
351
352@subheading NOTES:
353
354This directive is strictly local and does not impact task scheduling.
355
356If the object specified by @code{id} is of a class that
357has a string name, this method will free the existing
358name to the RTEMS Workspace and allocate enough memory
359from the RTEMS Workspace to make a copy of the string
360located at @code{name}.
361
362If the object specified by @code{id} is of a class that
363has a thirty-two bit integer style name, then the first
364four characters in @code{*name} will be used to construct
365the name.
366name to the RTEMS Workspace and allocate enough memory
367from the RTEMS Workspace to make a copy of the string
368
369
370@c
371@c
372@c
373@page
374@subsection OBJECT_ID_GET_API - Obtain API from Id
375
376@cindex obtain API from id
377
378@subheading CALLING SEQUENCE:
379
380@ifset is-C
381@findex rtems_object_id_get_api
382@example
383int rtems_object_id_get_api(
384  rtems_id id
385);
386@end example
387@end ifset
388
389@ifset is-Ada
390@example
391procedure Object_Id_Get_API(
392   ID  : in     RTEMS.ID;
393   API :    out RTEMS.Unsigned32
394);
395@end example
396@end ifset
397
398@subheading DIRECTIVE STATUS CODES
399
400Returns the API portion of the object Id.
401
402@subheading DESCRIPTION:
403
404This directive returns the API portion of the provided object @code{id}.
405
406@subheading NOTES:
407
408This directive is strictly local and does not impact task scheduling.
409
410This directive does NOT validate the @code{id} provided.
411
412@c
413@c
414@c
415@page
416@subsection OBJECT_ID_GET_CLASS - Obtain Class from Id
417
418@cindex obtain class from object id
419
420@subheading CALLING SEQUENCE:
421
422@ifset is-C
423@findex rtems_object_id_get_class
424@example
425int rtems_object_id_get_class(
426  rtems_id id
427);
428@end example
429@end ifset
430
431@ifset is-Ada
432@example
433procedure Object_Id_Get_Class(
434   ID        : in     RTEMS.ID;
435   The_Class :    out RTEMS.Unsigned32
436);
437@end example
438@end ifset
439
440@subheading DIRECTIVE STATUS CODES
441
442Returns the class portion of the object Id.
443
444@subheading DESCRIPTION:
445
446This directive returns the class portion of the provided object @code{id}.
447
448@subheading NOTES:
449
450This directive is strictly local and does not impact task scheduling.
451
452This directive does NOT validate the @code{id} provided.
453
454@c
455@c
456@c
457@page
458@subsection OBJECT_ID_GET_NODE - Obtain Node from Id
459
460@cindex obtain node from object id
461
462@subheading CALLING SEQUENCE:
463
464@ifset is-C
465@findex rtems_object_id_get_node
466@example
467int rtems_object_id_get_node(
468  rtems_id id
469);
470@end example
471@end ifset
472
473@ifset is-Ada
474@example
475procedure Object_Id_Get_Node(
476   ID   : in     RTEMS.ID;
477   Node :    out RTEMS.Unsigned32
478);
479@end example
480@end ifset
481
482@subheading DIRECTIVE STATUS CODES
483
484Returns the node portion of the object Id.
485
486@subheading DESCRIPTION:
487
488This directive returns the node portion of the provided object @code{id}.
489
490@subheading NOTES:
491
492This directive is strictly local and does not impact task scheduling.
493
494This directive does NOT validate the @code{id} provided.
495
496@c
497@c
498@c
499@page
500@subsection OBJECT_ID_GET_INDEX - Obtain Index from Id
501
502@cindex obtain index from object id
503
504@subheading CALLING SEQUENCE:
505
506@ifset is-C
507@findex rtems_object_id_get_index
508@example
509int rtems_object_id_get_index(
510  rtems_id id
511);
512@end example
513@end ifset
514
515@ifset is-Ada
516@example
517procedure Object_Id_Get_Index(
518   ID    : in     RTEMS.ID;
519   Index :    out RTEMS.Unsigned32
520);
521@end example
522@end ifset
523
524@subheading DIRECTIVE STATUS CODES
525
526Returns the index portion of the object Id.
527
528@subheading DESCRIPTION:
529
530This directive returns the index portion of the provided object @code{id}.
531
532@subheading NOTES:
533
534This directive is strictly local and does not impact task scheduling.
535
536This directive does NOT validate the @code{id} provided.
537
538@c
539@c
540@c
541@page
542@subsection BUILD_ID - Build Object Id From Components
543
544@cindex build object id from components
545
546@subheading CALLING SEQUENCE:
547
548@ifset is-C
549@findex rtems_build_id
550@example
551rtems_id rtems_build_id(
552  int the_api,
553  int the_class,
554  int the_node,
555  int the_index
556);
557@end example
558@end ifset
559
560@ifset is-Ada
561@example
562function Build_Id(
563   the_api   : in     RTEMS.Unsigned32;
564   the_class : in     RTEMS.Unsigned32;
565   the_node  : in     RTEMS.Unsigned32;
566   the_index : in     RTEMS.Unsigned32
567) return RTEMS.Id;
568@end example
569@end ifset
570
571@subheading DIRECTIVE STATUS CODES
572
573Returns an object Id constructed from the provided arguments.
574
575@subheading DESCRIPTION:
576
577This service constructs an object Id from the provided
578@code{the_api}, @code{the_class}, @code{the_node}, and @code{the_index}.
579
580
581@subheading NOTES:
582
583This directive is strictly local and does not impact task scheduling.
584
585This directive does NOT validate the arguments provided
586or the Object id returned.
587
588@c
589@c
590@c
591@page
592@subsection OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
593
594@cindex obtain minimum API value
595
596@subheading CALLING SEQUENCE:
597
598@ifset is-C
599@findex rtems_object_id_api_minimum
600@example
601int rtems_object_id_api_minimum(void);
602@end example
603@end ifset
604
605@ifset is-Ada
606@example
607function Object_Id_API_Minimum return RTEMS.Unsigned32;
608@end example
609@end ifset
610
611@subheading DIRECTIVE STATUS CODES
612
613Returns the minimum valid for the API portion of an object Id.
614
615@subheading DESCRIPTION:
616
617This service returns the minimum valid for the API portion of
618an object Id.
619
620@subheading NOTES:
621
622This directive is strictly local and does not impact task scheduling.
623
624@c
625@c
626@c
627@page
628@subsection OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
629
630@cindex obtain maximum API value
631
632@subheading CALLING SEQUENCE:
633
634@ifset is-C
635@findex rtems_object_id_api_maximum
636@example
637int rtems_object_id_api_maximum(void);
638@end example
639@end ifset
640
641@ifset is-Ada
642@example
643function Object_Id_API_Maximum return RTEMS.Unsigned32;
644@end example
645@end ifset
646
647@subheading DIRECTIVE STATUS CODES
648
649Returns the maximum valid for the API portion of an object Id.
650
651@subheading DESCRIPTION:
652
653This service returns the maximum valid for the API portion of
654an object Id.
655
656@subheading NOTES:
657
658This directive is strictly local and does not impact task scheduling.
659
660@c
661@c
662@c
663@page
664@subsection OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
665
666@cindex obtain minimum class value
667
668@subheading CALLING SEQUENCE:
669
670@ifset is-C
671@findex rtems_object_api_minimum_class
672@example
673int rtems_object_api_minimum_class(
674  int api
675);
676@end example
677@end ifset
678
679@ifset is-Ada
680@example
681procedure Object_API_Minimum_Class(
682   API     : in     RTEMS.Unsigned32;
683   Minimum :    out RTEMS.Unsigned32
684);
685@end example
686@end ifset
687
688@subheading DIRECTIVE STATUS CODES
689
690If @code{api} is not valid, -1 is returned.
691
692If successful, this service returns the minimum valid for the class
693portion of an object Id for the specified @code{api}.
694
695@subheading DESCRIPTION:
696
697This service returns the minimum valid for the class portion of
698an object Id for the specified @code{api}.
699
700@subheading NOTES:
701
702This directive is strictly local and does not impact task scheduling.
703
704@c
705@c
706@c
707@page
708@subsection OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
709
710@cindex obtain maximum class value
711
712@subheading CALLING SEQUENCE:
713
714@ifset is-C
715@findex rtems_object_api_maximum_class
716@example
717int rtems_object_api_maximum_class(
718  int api
719);
720@end example
721@end ifset
722
723@ifset is-Ada
724@example
725procedure Object_API_Maximum_Class(
726   API     : in     RTEMS.Unsigned32;
727   Maximum :    out RTEMS.Unsigned32
728);
729@end example
730@end ifset
731
732@subheading DIRECTIVE STATUS CODES
733
734If @code{api} is not valid, -1 is returned.
735
736If successful, this service returns the maximum valid for the class
737portion of an object Id for the specified @code{api}.
738
739@subheading DESCRIPTION:
740
741This service returns the maximum valid for the class portion of
742an object Id for the specified @code{api}.
743
744@subheading NOTES:
745
746This directive is strictly local and does not impact task scheduling.
747
748
749@c
750@c
751@c
752@page
753@subsection OBJECT_GET_API_NAME - Obtain API Name
754
755@cindex obtain API name
756
757@subheading CALLING SEQUENCE:
758
759@ifset is-C
760@findex rtems_object_get_api_name
761@example
762const char *rtems_object_get_api_name(
763  int api
764);
765@end example
766@end ifset
767
768@ifset is-Ada
769@example
770procedure Object_Get_API_Name(
771   API  : in     RTEMS.Unsigned32;
772   Name :    out String
773);
774@end example
775@end ifset
776
777@subheading DIRECTIVE STATUS CODES
778
779If @code{api} is not valid, the string @code{"BAD API"} is returned.
780
781If successful, this service returns a pointer to a string
782containing the name of the specified @code{api}.
783
784@subheading DESCRIPTION:
785
786This service returns the name of the specified @code{api}.
787
788@subheading NOTES:
789
790This directive is strictly local and does not impact task scheduling.
791
792The string returned is from constant space.  Do not modify
793or free it.
794
795@c
796@c
797@c
798@page
799@subsection OBJECT_GET_API_CLASS_NAME - Obtain Class Name
800
801@cindex obtain class name
802
803@subheading CALLING SEQUENCE:
804
805@ifset is-C
806@findex rtems_object_get_api_class_name
807@example
808const char *rtems_object_get_api_class_name(
809  int the_api,
810  int the_class
811);
812@end example
813@end ifset
814
815@ifset is-Ada
816@example
817procedure Object_Get_API_Class_Name(
818   The_API   : in     RTEMS.Unsigned32;
819   The_Class : in     RTEMS.Unsigned32;
820   Name      :    out String
821);
822@end example
823@end ifset
824
825@subheading DIRECTIVE STATUS CODES
826
827If @code{the_api} is not valid, the string @code{"BAD API"} is returned.
828
829If @code{the_class} is not valid, the string @code{"BAD CLASS"} is returned.
830
831If successful, this service returns a pointer to a string
832containing the name of the specified @code{the_api}/@code{the_class} pair.
833
834@subheading DESCRIPTION:
835
836This service returns the name of the object class indicated by the
837specified @code{the_api} and @code{the_class}.
838
839@subheading NOTES:
840
841This directive is strictly local and does not impact task scheduling.
842
843The string returned is from constant space.  Do not modify
844or free it.
845
846@c
847@c
848@c
849@page
850@subsection OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
851
852@cindex obtain class information
853
854@subheading CALLING SEQUENCE:
855
856@ifset is-C
857@findex rtems_object_get_class_information
858@example
859rtems_status_code rtems_object_get_class_information(
860  int                                 the_api,
861  int                                 the_class,
862  rtems_object_api_class_information *info
863);
864@end example
865@end ifset
866
867@ifset is-Ada
868@example
869procedure Object_Get_Class_Information(
870   The_API   : in     RTEMS.Unsigned32;
871   The_Class : in     RTEMS.Unsigned32;
872   Info      :    out RTEMS.Object_API_Class_Information;
873   Result    :    out RTEMS.Status_Codes
874);
875@end example
876@end ifset
877
878@subheading DIRECTIVE STATUS CODES
879@code{@value{RPREFIX}SUCCESSFUL} - information obtained successfully@*
880@code{@value{RPREFIX}INVALID_ADDRESS} - @code{info} is NULL@*
881@code{@value{RPREFIX}INVALID_NUMBER} - invalid @code{api} or @code{the_class}
882
883If successful, the structure located at @code{info} will be filled
884in with information about the specified @code{api}/@code{the_class} pairing.
885
886@subheading DESCRIPTION:
887
888This service returns information about the object class indicated by the
889specified @code{api} and @code{the_class}. This structure is defined as
890follows:
891
892@ifset is-C
893@example
894typedef struct @{
895  rtems_id  minimum_id;
896  rtems_id  maximum_id;
897  int       maximum;
898  bool      auto_extend;
899  int       unallocated;
900@} rtems_object_api_class_information;
901@end example
902@end ifset
903
904@ifset is-Ada
905@example
906
907@end example
908@end ifset
909
910
911@subheading NOTES:
912
913This directive is strictly local and does not impact task scheduling.
914
Note: See TracBrowser for help on using the repository browser.