source: rtems/cpukit/score/include/rtems/score/object.h @ f41dd23

4.104.114.84.9
Last change on this file since f41dd23 was f41dd23, checked in by Chris Johns <chrisj@…>, on Aug 13, 2007 at 3:36:48 AM

2007-08-13 Chris Johns <chrisj@…>

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