source: rtems/cpukit/score/include/rtems/score/object.h @ 6a07436

4.104.114.84.9
Last change on this file since 6a07436 was 6a07436, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 16, 2006 at 3:13:58 PM

2006-01-16 Joel Sherrill <joel@…>

Large patch to improve Doxygen output. As a side-effect, grammar and
spelling errors were corrected, spacing errors were address, and some
variable names were improved.

  • libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS.
  • score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output.
  • score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes.
  • Property mode set to 100644
File size: 25.8 KB
Line 
1/**
2 * @file  rtems/score/object.h
3 */
4 
5/*
6 *  This include file contains all the constants and structures associated
7 *  with the Object Handler.  This Handler provides mechanisms which
8 *  can be used to initialize and manipulate all objects which have
9 *  ids.
10 *
11 *  COPYRIGHT (c) 1989-2006.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.com/license/LICENSE.
17 *
18 *  $Id$
19 */
20
21#ifndef _RTEMS_SCORE_OBJECT_H
22#define _RTEMS_SCORE_OBJECT_H
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28#include <rtems/score/chain.h>
29#include <rtems/score/isr.h>
30
31/**
32 *  The following type defines the control block used to manage
33 *  object names.
34 */
35typedef void * Objects_Name;
36
37/**
38 *  Space for object names is allocated in multiples of this.
39 *
40 *  NOTE:  Must be a power of 2.  Matches the name manipulation routines.
41 */
42#define OBJECTS_NAME_ALIGNMENT     sizeof( uint32_t )
43
44/**
45 *  Functions which compare names are prototyped like this.
46 */
47typedef boolean (*Objects_Name_comparators)(
48  void       * /* name_1 */,
49  void       * /* name_2 */,
50  uint16_t     /* length */
51);
52
53#if defined(RTEMS_USE_16_BIT_OBJECT)
54/**
55 *  The following type defines the control block used to manage
56 *  object IDs.  The format is as follows (0=LSB):
57 *
58 *     Bits  0 ..  7    = index  (up to 254 objects of a type)
59 *     Bits  8 .. 10    = API    (up to 7 API classes)
60 *     Bits 11 .. 15    = class  (up to 31 object types per API)
61 */
62typedef uint16_t   Objects_Id;
63
64/**
65 * This type is used to store the maximum number of allowed objects
66 * of each type.
67 */
68typedef uint8_t    Objects_Maximum;
69
70#define OBJECTS_INDEX_START_BIT  0
71#define OBJECTS_API_START_BIT    8
72#define OBJECTS_CLASS_START_BIT 11
73
74#define OBJECTS_INDEX_MASK      (Objects_Id)0x00ff
75#define OBJECTS_API_MASK        (Objects_Id)0x0700
76#define OBJECTS_CLASS_MASK      (Objects_Id)0xF800
77
78#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x00ff
79#define OBJECTS_API_VALID_BITS    (Objects_Id)0x0007
80/* OBJECTS_NODE_VALID_BITS should not be used with 16 bit Ids */
81#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x001f
82
83#define OBJECTS_UNLIMITED_OBJECTS 0x8000
84
85#define OBJECTS_ID_INITIAL_INDEX  (0)
86#define OBJECTS_ID_FINAL_INDEX    (0xff)
87
88#else
89/**
90 *  The following type defines the control block used to manage
91 *  object IDs.  The format is as follows (0=LSB):
92 *
93 *     Bits  0 .. 15    = index  (up to 65535 objects of a type)
94 *     Bits 16 .. 23    = node   (up to 255 nodes)
95 *     Bits 24 .. 26    = API    (up to 7 API classes)
96 *     Bits 27 .. 31    = class  (up to 31 object types per API)
97 */
98typedef uint32_t   Objects_Id;
99
100/**
101 * This type is used to store the maximum number of allowed objects
102 * of each type.
103 */
104typedef uint16_t   Objects_Maximum;
105
106/**
107 *  This is the bit position of the starting bit of the index portion of
108 *  the object Id.
109 */
110#define OBJECTS_INDEX_START_BIT  0
111
112
113/**
114 *  This is the bit position of the starting bit of the node portion of
115 *  the object Id.
116 */
117#define OBJECTS_NODE_START_BIT  16
118
119/**
120 *  This is the bit position of the starting bit of the API portion of
121 *  the object Id.
122 */
123#define OBJECTS_API_START_BIT   24
124
125/**
126 *  This is the bit position of the starting bit of the class portion of
127 *  the object Id.
128 */
129#define OBJECTS_CLASS_START_BIT 27
130
131/**
132 *  This mask is used to extract the index portion of an object Id.
133 */
134#define OBJECTS_INDEX_MASK      (Objects_Id)0x0000ffff
135
136/**
137 *  This mask is used to extract the node portion of an object Id.
138 */
139#define OBJECTS_NODE_MASK       (Objects_Id)0x00ff0000
140
141/**
142 *  This mask is used to extract the API portion of an object Id.
143 */
144#define OBJECTS_API_MASK        (Objects_Id)0x07000000
145
146/**
147 *  This mask is used to extract the class portion of an object Id.
148 */
149#define OBJECTS_CLASS_MASK      (Objects_Id)0xf8000000
150
151/**
152 *  This mask represents the bits that is used to ensure no extra bits
153 *  are set after shifting to extract the index portion of an object Id.
154 */
155#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x0000ffff
156
157/**
158 *  This mask represents the bits that is used to ensure no extra bits
159 *  are set after shifting to extract the node portion of an object Id.
160 */
161#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ff
162
163/**
164 *  This mask represents the bits that is used to ensure no extra bits
165 *  are set after shifting to extract the API portion of an object Id.
166 */
167#define OBJECTS_API_VALID_BITS    (Objects_Id)0x00000007
168
169/**
170 *  This mask represents the bits that is used to ensure no extra bits
171 *  are set after shifting to extract the class portion of an object Id.
172 */
173#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x0000001f
174
175/**
176 *  Mask to enable unlimited objects.  This is used in the configuration
177 *  table when specifying the number of configured objects.
178 */
179#define OBJECTS_UNLIMITED_OBJECTS 0x80000000
180
181/**
182 *  This is the lowest value for the index portion of an object Id.
183 */
184#define OBJECTS_ID_INITIAL_INDEX  (0)
185
186/**
187 *  This is the highest value for the index portion of an object Id.
188 */
189#define OBJECTS_ID_FINAL_INDEX    (0xff)
190#endif
191
192/**
193 *  This enumerated type is used in the class field of the object ID.
194 */
195typedef enum {
196  OBJECTS_NO_API       = 0,
197  OBJECTS_INTERNAL_API = 1,
198  OBJECTS_CLASSIC_API  = 2,
199  OBJECTS_POSIX_API    = 3,
200  OBJECTS_ITRON_API    = 4
201} Objects_APIs;
202
203/** This macro is used to generically specify the last API index. */
204#define OBJECTS_APIS_LAST OBJECTS_ITRON_API
205
206/**
207 *  This enumerated type is used in the class field of the object ID
208 *  for RTEMS internal object classes.
209 */
210typedef enum {
211  OBJECTS_INTERNAL_NO_CLASS =  0,
212  OBJECTS_INTERNAL_THREADS  =  1,
213  OBJECTS_INTERNAL_MUTEXES  =  2
214} Objects_Internal_API;
215
216/** This macro is used to generically specify the last API index. */
217#define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES
218
219/**
220 *  This enumerated type is used in the class field of the object ID
221 *  for the RTEMS Classic API.
222 */
223typedef enum {
224  OBJECTS_CLASSIC_NO_CLASS     = 0,
225  OBJECTS_RTEMS_TASKS          = 1,
226  OBJECTS_RTEMS_TIMERS         = 2,
227  OBJECTS_RTEMS_SEMAPHORES     = 3,
228  OBJECTS_RTEMS_MESSAGE_QUEUES = 4,
229  OBJECTS_RTEMS_PARTITIONS     = 5,
230  OBJECTS_RTEMS_REGIONS        = 6,
231  OBJECTS_RTEMS_PORTS          = 7,
232  OBJECTS_RTEMS_PERIODS        = 8,
233  OBJECTS_RTEMS_EXTENSIONS     = 9
234} Objects_Classic_API;
235
236/** This macro is used to generically specify the last API index. */
237#define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_EXTENSIONS
238
239/**
240 *  This enumerated type is used in the class field of the object ID
241 *  for the POSIX API.
242 */
243typedef enum {
244  OBJECTS_POSIX_NO_CLASS            = 0,
245  OBJECTS_POSIX_THREADS             = 1,
246  OBJECTS_POSIX_KEYS                = 2,
247  OBJECTS_POSIX_INTERRUPTS          = 3,
248  OBJECTS_POSIX_MESSAGE_QUEUE_FDS   = 4,
249  OBJECTS_POSIX_MESSAGE_QUEUES      = 5,
250  OBJECTS_POSIX_MUTEXES             = 6,
251  OBJECTS_POSIX_SEMAPHORES          = 7,
252  OBJECTS_POSIX_CONDITION_VARIABLES = 8
253} Objects_POSIX_API;
254
255/** This macro is used to generically specify the last API index. */
256#define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_CONDITION_VARIABLES
257
258/**
259 *  This enumerated type is used in the class field of the object ID
260 *  for the ITRON API.
261 */
262typedef enum {
263  OBJECTS_ITRON_NO_CLASS              = 0,
264  OBJECTS_ITRON_TASKS                 = 1,
265  OBJECTS_ITRON_EVENTFLAGS            = 2,
266  OBJECTS_ITRON_MAILBOXES             = 3,
267  OBJECTS_ITRON_MESSAGE_BUFFERS       = 4,
268  OBJECTS_ITRON_PORTS                 = 5,
269  OBJECTS_ITRON_SEMAPHORES            = 6,
270  OBJECTS_ITRON_VARIABLE_MEMORY_POOLS = 7,
271  OBJECTS_ITRON_FIXED_MEMORY_POOLS    = 8
272} Objects_ITRON_API;
273
274/** This macro is used to generically specify the last API index. */
275#define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS
276
277/**
278 *  This enumerated type lists the locations which may be returned
279 *  by _Objects_Get.  These codes indicate the success of locating
280 *  an object with the specified ID.
281 */
282typedef enum {
283  OBJECTS_LOCAL  = 0,         /* object is local */
284  OBJECTS_REMOTE = 1,         /* object is remote */
285  OBJECTS_ERROR  = 2          /* id was invalid */
286} Objects_Locations;
287
288/**
289 *  The following type defines the callout used when a local task
290 *  is extracted from a remote thread queue (i.e. it's proxy must
291 *  extracted from the remote queue).
292 */
293typedef void ( *Objects_Thread_queue_Extract_callout )( void * );
294
295/**
296 *  The following defines the Object Control Block used to manage
297 *  each object local to this node.
298 */
299typedef struct {
300  /** This is the chain node portion of an object. */
301  Chain_Node     Node;
302  /** This is the object's ID. */
303  Objects_Id     id;
304  /** This is the object's name. */
305  Objects_Name   name;
306} Objects_Control;
307
308/**
309 *  The following defines the structure for the information used to
310 *  manage each class of objects.
311 */
312typedef struct {
313  /** This field indicates the API of this object class. */
314  Objects_APIs      the_api;
315  /** This is the class of this object set. */
316  uint16_t          the_class;
317  /** This is the minimum valid id of this object class. */
318  Objects_Id        minimum_id;
319  /** This is the maximum valid id of this object class. */
320  Objects_Id        maximum_id;
321  /** This is the maximum number of objects in this class. */
322  Objects_Maximum   maximum;
323  /** This is the TRUE if unlimited objects in this class. */
324  boolean           auto_extend;
325  /** This is the number of objects in a block. */
326  uint32_t          allocation_size;
327  /** This is the size in bytes of each object instance. */
328  uint32_t          size;
329  /** This points to the table of local objects. */
330  Objects_Control **local_table;
331  /** This points to the table of local object names. */
332  Objects_Name     *name_table;
333  /** This is the chain of inactive control blocks. */
334  Chain_Control     Inactive;
335  /** This is the number of objects on the Inactive list. */
336  Objects_Maximum   inactive;
337  /** This is the number of inactive objects per block. */
338  uint32_t         *inactive_per_block;
339  /** This is a table to the chain of inactive object memory blocks. */
340  void            **object_blocks;
341  /** This is the TRUE if names are strings. */
342  boolean           is_string;
343  /** This is the maximum length of names. */
344  uint16_t          name_length;
345  /** This is this object class' method called when extracting a thread. */
346  Objects_Thread_queue_Extract_callout extract;
347#if defined(RTEMS_MULTIPROCESSING)
348  /** This is this object class' pointer to the global name table */
349  Chain_Control    *global_table;
350#endif
351}   Objects_Information;
352
353/**
354 *  The following is referenced to the node number of the local node.
355 */
356#if defined(RTEMS_MULTIPROCESSING)
357SCORE_EXTERN uint16_t    _Objects_Local_node;
358#else
359#define _Objects_Local_node    1
360#endif
361
362/**
363 *  The following is referenced to the number of nodes in the system.
364 */
365#if defined(RTEMS_MULTIPROCESSING)
366SCORE_EXTERN uint16_t    _Objects_Maximum_nodes;
367#else
368#define _Objects_Maximum_nodes 1
369#endif
370
371/**
372 *  The following is the list of information blocks per API for each object
373 *  class.  From the ID, we can go to one of these information blocks,
374 *  and obtain a pointer to the appropriate object control block.
375 */
376SCORE_EXTERN Objects_Information
377    **_Objects_Information_table[OBJECTS_APIS_LAST + 1];
378
379/**
380 *  The following defines the constant which may be used
381 *  with _Objects_Get to manipulate the calling task.
382 */
383#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
384
385/**
386 *  The following constant is used to specify that a name to ID search
387 *  should search through all nodes.
388 */
389#define OBJECTS_SEARCH_ALL_NODES   0
390
391/**
392 *  The following constant is used to specify that a name to ID search
393 *  should search through all nodes except the current node.
394 */
395#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
396
397/**
398 *  The following constant is used to specify that a name to ID search
399 *  should search only on this node.
400 */
401#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
402
403/**
404 *  The following constant is used to specify that a name to ID search
405 *  is being asked for the ID of the currently executing task.
406 */
407#define OBJECTS_WHO_AM_I           0
408
409/**
410 *  This macros calculates the lowest ID for the specified api, class,
411 *  and node.
412 */
413#define OBJECTS_ID_INITIAL(_api, _class, _node) \
414  _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
415
416/**
417 *  This macro specifies the highest object ID value
418 */
419#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
420
421/**
422 *  This function performs the initialization necessary for this handler.
423 *
424 *  @param[in] node indicates the identifying number of this node.
425 *  @param[in] maximum_nodes is the maximum number of nodes in this system.
426 *  @param[in] maximum_global_objects is maximum number of global objects
427 *             concurrently offered in the system.
428 */
429void _Objects_Handler_initialization(
430  uint32_t   node,
431  uint32_t   maximum_nodes,
432  uint32_t   maximum_global_objects
433);
434
435/**
436 *  This function extends an object class information record.
437 *
438 *  @param[in] information points to an object class information block.
439 */
440void _Objects_Extend_information(
441  Objects_Information *information
442);
443
444/**
445 *  This function shrink an object class information record.
446 *
447 *  @param[in] information points to an object class information block.
448 */
449void _Objects_Shrink_information(
450  Objects_Information *information
451);
452
453/**
454 *  This function initializes an object class information record.
455 *  SUPPORTS_GLOBAL is TRUE if the object class supports global
456 *  objects, and FALSE otherwise.  Maximum indicates the number
457 *  of objects required in this class and size indicates the size
458 *  in bytes of each control block for this object class.  The
459 *  name length and string designator are also set.  In addition,
460 *  the class may be a task, therefore this information is also included.
461 *
462 *  @param[in] information points to an object class information block.
463 *  @param[in] the_api indicates the API associated with this information block.
464 *  @param[in] the_class indicates the class of object being managed
465 *             by this information block.  It is specific to @a the_api.
466 *  @param[in] maximum is the maximum number of instances of this object
467 *             class which may be concurrently active.
468 *  @param[in] size is the size of the data structure for this class.
469 *  @param[in] is_string is TRUE if this object uses string style names.
470 *  @param[in] maximum_name_length is the maximum length of object names.
471 */
472void _Objects_Initialize_information (
473  Objects_Information *information,
474  Objects_APIs         the_api,
475  uint32_t             the_class,
476  uint32_t             maximum,
477  uint16_t             size,
478  boolean              is_string,
479  uint32_t             maximum_name_length
480#if defined(RTEMS_MULTIPROCESSING)
481  ,
482  boolean              supports_global,
483  Objects_Thread_queue_Extract_callout extract
484#endif
485);
486
487/**
488 *  This function allocates a object control block from
489 *  the inactive chain of free object control blocks.
490 *
491 *  @param[in] information points to an object class information block.
492 */
493Objects_Control *_Objects_Allocate(
494  Objects_Information *information
495);
496
497/**
498 *  This function allocates the object control block
499 *  specified by the index from the inactive chain of
500 *  free object control blocks.
501 *
502 *  @param[in] information points to an object class information block.
503 *  @param[in] index is the index of the object to allocate.
504 *  @param[in] sizeof_control is the size of the object control block.
505 */
506Objects_Control *_Objects_Allocate_by_index(
507  Objects_Information *information,
508  uint16_t             index,
509  uint16_t             sizeof_control
510);
511
512/**
513 *
514 *  This function frees a object control block to the
515 *  inactive chain of free object control blocks.
516 *
517 *  @param[in] information points to an object class information block.
518 *  @param[in] the_object points to the object to deallocate.
519 */
520void _Objects_Free(
521  Objects_Information *information,
522  Objects_Control     *the_object
523);
524
525/**
526 *  This method zeroes out the name.
527 *
528 *  @param[in] name points to the name to be zeroed out.
529 *  @param[in] length is the length of the object name field.
530 */
531void _Objects_Clear_name(
532  void       *name,
533  uint16_t    length
534);
535
536/**
537 *  This method copies a string style object name from source to destination.
538 *
539 *  @param[in] source is the source name to copy.
540 *  @param[in] destination is the destination of the copy.
541 *  @param[in] length is the number of bytes to copy.
542 */
543void _Objects_Copy_name_string(
544  void       *source,
545  void       *destination,
546  uint16_t    length
547);
548
549/**
550 *  This method copies a raw style object name from source to destination.
551 *
552 *  @param[in] source is the source name to copy.
553 *  @param[in] destination is the destination of the copy.
554 *  @param[in] length is the number of bytes to copy.
555 */
556void _Objects_Copy_name_raw(
557  void       *source,
558  void       *destination,
559  uint16_t    length
560);
561
562/**
563 *  This method compares two string style object names.
564 *
565 *  @param[in] name_1 is the left hand name to compare.
566 *  @param[in] name_2 is the right hand name to compare.
567 *  @param[in] length is the length of the names to compare.
568 */
569boolean _Objects_Compare_name_string(
570  void       *name_1,
571  void       *name_2,
572  uint16_t    length
573);
574
575/**
576 *  This method compares two raw style object names.
577 *
578 *  @param[in] name_1 is the left hand name to compare.
579 *  @param[in] name_2 is the right hand name to compare.
580 *  @param[in] length is the length of the names to compare.
581 */
582boolean _Objects_Compare_name_raw(
583  void       *name_1,
584  void       *name_2,
585  uint16_t    length
586);
587
588/**
589 *  This function implements the common portion of the object
590 *  identification directives.  This directive returns the object
591 *  id associated with name.  If more than one object of this class
592 *  is named name, then the object to which the id belongs is
593 *  arbitrary.  Node indicates the extent of the search for the
594 *  id of the object named name.  If the object class supports global
595 *  objects, then the search can be limited to a particular node
596 *  or allowed to encompass all nodes.
597 */
598typedef enum {
599  OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL,
600  OBJECTS_INVALID_NAME,
601  OBJECTS_INVALID_ADDRESS,
602  OBJECTS_INVALID_ID,
603  OBJECTS_INVALID_NODE
604} Objects_Name_or_id_lookup_errors;
605
606/** This macro defines the first entry in the
607 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
608 */
609#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL
610
611/** This macro defines the last entry in the
612 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
613 */
614#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
615
616/**
617 *  This method converts an object name to an Id.  It performs a look up
618 *  using the object information block for this object class.
619 *
620 *  @param[in] information points to an object class information block.
621 *  @param[in] name is the name of the object to find.
622 *  @param[in] node is the set of nodes to search.
623 *  @param[in] id will contain the Id if the search is successful.
624 *
625 *  @return This method returns one of the values from the
626 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
627 *          successful or failure.  On success @a id will contain the Id of
628 *          the requested object.
629 */
630Objects_Name_or_id_lookup_errors _Objects_Name_to_id(
631  Objects_Information *information,
632  Objects_Name         name,
633  uint32_t             node,
634  Objects_Id          *id
635);
636
637/**
638 *  This function implements the common portion of the object Id
639 *  to name directives.  This function returns the name
640 *  associated with object id.
641 *
642 *  @param[in] id is the Id of the object whose name we are locating.
643 *  @param[in] name will contain the name of the object, if found.
644 *
645 *  @return This method returns one of the values from the
646 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
647 *          successful or failure.  On success @a name will contain the name of
648 *          the requested object.
649 *
650 *  @note This function currently does not support string names.
651 */
652Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
653  Objects_Id      id,
654  Objects_Name   *name
655);
656
657/**
658 *  This function maps object ids to object control blocks.
659 *  If id corresponds to a local object, then it returns
660 *  the_object control pointer which maps to id and location
661 *  is set to OBJECTS_LOCAL.  If the object class supports global
662 *  objects and the object id is global and resides on a remote
663 *  node, then location is set to OBJECTS_REMOTE, and the_object
664 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
665 *  and the_object is undefined.
666 *
667 *  @param[in] information points to an object class information block.
668 *  @param[in] id is the Id of the object whose name we are locating.
669 *  @param[in] location will contain an indication of success or failure.
670 *
671 *  @return This method returns one of the values from the
672 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
673 *          successful or failure.  On success @a id will contain the Id of
674 *          the requested object.
675 *
676 *  @note _Objects_Get returns with dispatching disabled for
677 *  local and remote objects.  _Objects_Get_isr_disable returns with
678 *  dispatching disabled for remote objects and interrupts for local
679 *  objects.
680 */
681Objects_Control *_Objects_Get (
682  Objects_Information *information,
683  Objects_Id           id,
684  Objects_Locations   *location
685);
686
687/**
688 *  This function maps object ids to object control blocks.
689 *  If id corresponds to a local object, then it returns
690 *  the_object control pointer which maps to id and location
691 *  is set to OBJECTS_LOCAL.  If the object class supports global
692 *  objects and the object id is global and resides on a remote
693 *  node, then location is set to OBJECTS_REMOTE, and the_object
694 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
695 *  and the_object is undefined.
696 *
697 *  @param[in] information points to an object class information block.
698 *  @param[in] id is the Id of the object whose name we are locating.
699 *  @param[in] location will contain an indication of success or failure.
700 *  @param[in] level is the interrupt level being turned.
701 *
702 *  @return This method returns one of the values from the
703 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
704 *          successful or failure.  On success @a name will contain the name of
705 *          the requested object.
706 *
707 *  @note _Objects_Get returns with dispatching disabled for
708 *  local and remote objects.  _Objects_Get_isr_disable returns with
709 *  dispatching disabled for remote objects and interrupts for local
710 *  objects.
711 */
712Objects_Control *_Objects_Get_isr_disable(
713  Objects_Information *information,
714  Objects_Id           id,
715  Objects_Locations   *location,
716  ISR_Level           *level
717);
718
719/**
720 *  This function maps object index to object control blocks which must.
721 *  be local.  The parameter the_object control pointer which maps to id
722 *  and location is set to OBJECTS_LOCAL.  Otherwise, location is set to
723    OBJECTS_ERROR and the_object is undefined.
724 *
725 *  @param[in] information points to an object class information block.
726 *  @param[in] id is the Id of the object whose name we are locating.
727 *  @param[in] location will contain an indication of success or failure.
728 *
729 *  @return This method returns a pointer to the object associated with ID.
730 *
731 *  @return This method returns one of the values from the
732 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
733 *          successful or failure.  On success @a id will contain the id of
734 *          the requested object.
735 *
736 *  @note _Objects_Get returns with dispatching disabled for
737 *  local and remote objects.  _Objects_Get_isr_disable returns with
738 *  dispatching disabled for remote objects and interrupts for local
739 *  objects.
740 */
741Objects_Control *_Objects_Get_by_index (
742  Objects_Information *information,
743  Objects_Id           id,
744  Objects_Locations   *location
745);
746
747/**
748 *  This function maps object ids to object control blocks.
749 *  If id corresponds to a local object, then it returns
750 *  the_object control pointer which maps to id and location
751 *  is set to OBJECTS_LOCAL.  If the object class supports global
752 *  objects and the object id is global and resides on a remote
753 *  node, then location is set to OBJECTS_REMOTE, and the_object
754 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
755 *  and the_object is undefined.
756 *
757 *  @param[in] information points to an object class information block.
758 *  @param[in] id is the Id of the object whose name we are locating.
759 *  @param[in] location will contain an indication of success or failure.
760 *
761 *  @return This method returns one of the values from the
762 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
763 *          successful or failure.  On success @a id will contain the Id of
764 *          the requested object.
765 *
766 *  @note _Objects_Get returns with dispatching disabled for
767 *  local and remote objects.  _Objects_Get_isr_disable returns with
768 *  dispatching disabled for remote objects and interrupts for local
769 *  objects.
770 */
771Objects_Control *_Objects_Get_no_protection(
772  Objects_Information *information,
773  Objects_Id           id,
774  Objects_Locations   *location
775);
776
777/**
778 *  Like @ref _Objects_Get, but is used to find "next" open object.
779 *
780 *  @param[in] information points to an object class information block.
781 *  @param[in] id is the Id of the object whose name we are locating.
782 *  @param[in] location_p will contain an indication of success or failure.
783 *  @param[in] next_id_p is the Id of the next object we will look at.
784 *
785 *  @return This method returns the pointer to the object located or
786 *          NULL on error.
787 */
788Objects_Control *_Objects_Get_next(
789    Objects_Information *information,
790    Objects_Id           id,
791    Objects_Locations   *location_p,
792    Objects_Id          *next_id_p
793);
794
795/*
796 *  Pieces of object.inl are promoted out to the user
797 */
798
799#include <rtems/score/object.inl>
800#if defined(RTEMS_MULTIPROCESSING)
801#include <rtems/score/objectmp.h>
802#endif
803
804#ifdef __cplusplus
805}
806#endif
807
808#endif
809/* end of include file */
Note: See TracBrowser for help on using the repository browser.