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

4.104.114.84.95
Last change on this file since f41dd23 was f41dd23, checked in by Chris Johns <chrisj@…>, on 08/13/07 at 03:36:48

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
RevLine 
[11874561]1/**
2 * @file  rtems/score/object.h
[9c191ee]3 *
4 *
[ac7d5ef0]5 *  This include file contains all the constants and structures associated
[3a4ae6c]6 *  with the Object Handler.  This Handler provides mechanisms which
[a0ed4ed]7 *  can be used to initialize and manipulate all objects which have
[3a4ae6c]8 *  ids.
[9c191ee]9 */
10
11/*
[6a07436]12 *  COPYRIGHT (c) 1989-2006.
[ac7d5ef0]13 *  On-Line Applications Research Corporation (OAR).
14 *
[98e4ebf5]15 *  The license and distribution terms for this file may be
16 *  found in the file LICENSE in this distribution or at
[dd687d97]17 *  http://www.rtems.com/license/LICENSE.
[ac7d5ef0]18 *
19 *  $Id$
20 */
21
[092f142a]22#ifndef _RTEMS_SCORE_OBJECT_H
23#define _RTEMS_SCORE_OBJECT_H
[ac7d5ef0]24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
[5e9b32b]29#include <rtems/score/chain.h>
[c6f111b]30#include <rtems/score/isr.h>
[ac7d5ef0]31
[6a07436]32/**
[ac7d5ef0]33 *  The following type defines the control block used to manage
34 *  object names.
35 */
[3235ad9]36typedef void * Objects_Name;
37
[6a07436]38/**
[3235ad9]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 */
[50269c46]43#define OBJECTS_NAME_ALIGNMENT     sizeof( uint32_t )
[3235ad9]44
[6a07436]45/**
[3235ad9]46 *  Functions which compare names are prototyped like this.
47 */
48typedef boolean (*Objects_Name_comparators)(
49  void       * /* name_1 */,
50  void       * /* name_2 */,
[712fe15]51  uint16_t     /* length */
[3235ad9]52);
[ac7d5ef0]53
[85b7605]54#if defined(RTEMS_USE_16_BIT_OBJECT)
[6a07436]55/**
[85b7605]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;
[6a07436]64
65/**
66 * This type is used to store the maximum number of allowed objects
67 * of each type.
68 */
[85b7605]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
[50269c46]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
[85b7605]85
[6a07436]86#define OBJECTS_ID_INITIAL_INDEX  (0)
87#define OBJECTS_ID_FINAL_INDEX    (0xff)
88
[85b7605]89#else
[6a07436]90/**
[ac7d5ef0]91 *  The following type defines the control block used to manage
[95fbca1]92 *  object IDs.  The format is as follows (0=LSB):
93 *
[ef9505a9]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)
[ac7d5ef0]98 */
[d6154c7]99typedef uint32_t   Objects_Id;
[6a07436]100
101/**
102 * This type is used to store the maximum number of allowed objects
103 * of each type.
104 */
[85b7605]105typedef uint16_t   Objects_Maximum;
[ac7d5ef0]106
[6a07436]107/**
108 *  This is the bit position of the starting bit of the index portion of
109 *  the object Id.
110 */
[95fbca1]111#define OBJECTS_INDEX_START_BIT  0
[6a07436]112
113
114/**
115 *  This is the bit position of the starting bit of the node portion of
116 *  the object Id.
117 */
[95fbca1]118#define OBJECTS_NODE_START_BIT  16
[6a07436]119
120/**
121 *  This is the bit position of the starting bit of the API portion of
122 *  the object Id.
123 */
[ef9505a9]124#define OBJECTS_API_START_BIT   24
[6a07436]125
126/**
127 *  This is the bit position of the starting bit of the class portion of
128 *  the object Id.
129 */
[ef9505a9]130#define OBJECTS_CLASS_START_BIT 27
[95fbca1]131
[6a07436]132/**
133 *  This mask is used to extract the index portion of an object Id.
134 */
[2728d9cf]135#define OBJECTS_INDEX_MASK      (Objects_Id)0x0000ffff
[6a07436]136
137/**
138 *  This mask is used to extract the node portion of an object Id.
139 */
[2728d9cf]140#define OBJECTS_NODE_MASK       (Objects_Id)0x00ff0000
[6a07436]141
142/**
143 *  This mask is used to extract the API portion of an object Id.
144 */
[2728d9cf]145#define OBJECTS_API_MASK        (Objects_Id)0x07000000
[6a07436]146
147/**
148 *  This mask is used to extract the class portion of an object Id.
149 */
[2728d9cf]150#define OBJECTS_CLASS_MASK      (Objects_Id)0xf8000000
151
[6a07436]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 */
[2728d9cf]156#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x0000ffff
[6a07436]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 */
[2728d9cf]162#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ff
[6a07436]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 */
[2728d9cf]168#define OBJECTS_API_VALID_BITS    (Objects_Id)0x00000007
[6a07436]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 */
[2728d9cf]174#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x0000001f
[50269c46]175
[6a07436]176/**
[50269c46]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
[6a07436]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)
[85b7605]191#endif
[95fbca1]192
[6a07436]193/**
[95fbca1]194 *  This enumerated type is used in the class field of the object ID.
195 */
196typedef enum {
[ef9505a9]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
[6a07436]204/** This macro is used to generically specify the last API index. */
[ef9505a9]205#define OBJECTS_APIS_LAST OBJECTS_ITRON_API
206
[6a07436]207/**
208 *  This enumerated type is used in the class field of the object ID
209 *  for RTEMS internal object classes.
210 */
[ef9505a9]211typedef enum {
212  OBJECTS_INTERNAL_NO_CLASS =  0,
213  OBJECTS_INTERNAL_THREADS  =  1,
214  OBJECTS_INTERNAL_MUTEXES  =  2
215} Objects_Internal_API;
216
[6a07436]217/** This macro is used to generically specify the last API index. */
[ef9505a9]218#define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES
219
[6a07436]220/**
221 *  This enumerated type is used in the class field of the object ID
222 *  for the RTEMS Classic API.
223 */
[ef9505a9]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,
[9c191ee]234  OBJECTS_RTEMS_EXTENSIONS     = 9,
235  OBJECTS_RTEMS_BARRIERS       = 10
[ef9505a9]236} Objects_Classic_API;
237
[6a07436]238/** This macro is used to generically specify the last API index. */
[f41dd23]239#define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_BARRIERS
[ef9505a9]240
[6a07436]241/**
242 *  This enumerated type is used in the class field of the object ID
243 *  for the POSIX API.
244 */
[ef9505a9]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,
[0243b0d]254  OBJECTS_POSIX_CONDITION_VARIABLES = 8,
[9c191ee]255  OBJECTS_POSIX_TIMERS              = 9,
256  OBJECTS_POSIX_BARRIERS            = 10,
257  OBJECTS_POSIX_SPINLOCKS           = 11,
258  OBJECTS_POSIX_RWLOCKS             = 12
[ef9505a9]259} Objects_POSIX_API;
260
[6a07436]261/** This macro is used to generically specify the last API index. */
[9c191ee]262#define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_RWLOCKS
[ef9505a9]263
[6a07436]264/**
265 *  This enumerated type is used in the class field of the object ID
266 *  for the ITRON API.
267 */
[ef9505a9]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
[6a07436]280/** This macro is used to generically specify the last API index. */
[ef9505a9]281#define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS
[5250ff39]282
[6a07436]283/**
[ac7d5ef0]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 */
[85b7605]292} Objects_Locations;
[ac7d5ef0]293
[6a07436]294/**
[ef9505a9]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
[6a07436]301/**
[ac7d5ef0]302 *  The following defines the Object Control Block used to manage
303 *  each object local to this node.
304 */
305typedef struct {
[6a07436]306  /** This is the chain node portion of an object. */
[f4a8ee1]307  Chain_Node     Node;
[6a07436]308  /** This is the object's ID. */
[f4a8ee1]309  Objects_Id     id;
[6a07436]310  /** This is the object's name. */
[f4a8ee1]311  Objects_Name   name;
[85b7605]312} Objects_Control;
[ac7d5ef0]313
[6a07436]314/**
[ac7d5ef0]315 *  The following defines the structure for the information used to
316 *  manage each class of objects.
317 */
318typedef struct {
[6a07436]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. */
[7a5e8fb6]334  size_t            size;
[6a07436]335  /** This points to the table of local objects. */
[f4a8ee1]336  Objects_Control **local_table;
[6a07436]337  /** This points to the table of local object names. */
[f4a8ee1]338  Objects_Name     *name_table;
[6a07436]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. */
[9b3f187]352  Objects_Thread_queue_Extract_callout extract;
[ef9505a9]353#if defined(RTEMS_MULTIPROCESSING)
[6a07436]354  /** This is this object class' pointer to the global name table */
355  Chain_Control    *global_table;
[ef9505a9]356#endif
[ac7d5ef0]357}   Objects_Information;
358
[6a07436]359/**
360 *  The following is referenced to the node number of the local node.
[ac7d5ef0]361 */
[85b7605]362#if defined(RTEMS_MULTIPROCESSING)
[0337a9c5]363SCORE_EXTERN uint16_t       _Objects_Local_node;
[85b7605]364#else
[0337a9c5]365#define _Objects_Local_node ((uint16_t)1)
[6a07436]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
[85b7605]374#define _Objects_Maximum_nodes 1
375#endif
[ac7d5ef0]376
[6a07436]377/**
[ef9505a9]378 *  The following is the list of information blocks per API for each object
[5250ff39]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 */
[ef9505a9]382SCORE_EXTERN Objects_Information
383    **_Objects_Information_table[OBJECTS_APIS_LAST + 1];
[5250ff39]384
[6a07436]385/**
[ac7d5ef0]386 *  The following defines the constant which may be used
387 *  with _Objects_Get to manipulate the calling task.
388 */
[95fbca1]389#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
[ac7d5ef0]390
[6a07436]391/**
392 *  The following constant is used to specify that a name to ID search
393 *  should search through all nodes.
[ac7d5ef0]394 */
[3a4ae6c]395#define OBJECTS_SEARCH_ALL_NODES   0
[6a07436]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 */
[3a4ae6c]401#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
[ac7d5ef0]402
[6a07436]403/**
404 *  The following constant is used to specify that a name to ID search
405 *  should search only on this node.
[b06e68ef]406 */
[6a07436]407#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
[b06e68ef]408
[6a07436]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
[b06e68ef]414
[6a07436]415/**
416 *  This macros calculates the lowest ID for the specified api, class,
417 *  and node.
418 */
[ef9505a9]419#define OBJECTS_ID_INITIAL(_api, _class, _node) \
420  _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
[6a07436]421
422/**
423 *  This macro specifies the highest object ID value
424 */
[3a4ae6c]425#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
[b06e68ef]426
[6a07436]427/**
[ac7d5ef0]428 *  This function performs the initialization necessary for this handler.
429 *
[6a07436]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.
[ac7d5ef0]434 */
435void _Objects_Handler_initialization(
[d6154c7]436  uint32_t   node,
437  uint32_t   maximum_nodes,
438  uint32_t   maximum_global_objects
[ac7d5ef0]439);
440
[6a07436]441/**
[f4a8ee1]442 *  This function extends an object class information record.
[6a07436]443 *
444 *  @param[in] information points to an object class information block.
[f4a8ee1]445 */
446void _Objects_Extend_information(
447  Objects_Information *information
448);
449
[6a07436]450/**
[f4a8ee1]451 *  This function shrink an object class information record.
[6a07436]452 *
453 *  @param[in] information points to an object class information block.
[f4a8ee1]454 */
455void _Objects_Shrink_information(
456  Objects_Information *information
457);
458
[6a07436]459/**
[ac7d5ef0]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
[5e9b32b]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.
[6a07436]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.
[ac7d5ef0]477 */
478void _Objects_Initialize_information (
479  Objects_Information *information,
[ef9505a9]480  Objects_APIs         the_api,
[d6154c7]481  uint32_t             the_class,
[50269c46]482  uint32_t             maximum,
[85b7605]483  uint16_t             size,
[3235ad9]484  boolean              is_string,
[d6154c7]485  uint32_t             maximum_name_length
[ef9505a9]486#if defined(RTEMS_MULTIPROCESSING)
487  ,
488  boolean              supports_global,
[9b3f187]489  Objects_Thread_queue_Extract_callout extract
[ef9505a9]490#endif
[3235ad9]491);
492
[6a07436]493/**
[f4a8ee1]494 *  This function allocates a object control block from
495 *  the inactive chain of free object control blocks.
[6a07436]496 *
497 *  @param[in] information points to an object class information block.
[f4a8ee1]498 */
499Objects_Control *_Objects_Allocate(
500  Objects_Information *information
501);
502
[6a07436]503/**
[352c9b2]504 *  This function allocates the object control block
505 *  specified by the index from the inactive chain of
506 *  free object control blocks.
[6a07436]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.
[352c9b2]511 */
512Objects_Control *_Objects_Allocate_by_index(
513  Objects_Information *information,
[85b7605]514  uint16_t             index,
515  uint16_t             sizeof_control
[352c9b2]516);
517
[6a07436]518/**
[f4a8ee1]519 *
520 *  This function frees a object control block to the
521 *  inactive chain of free object control blocks.
[6a07436]522 *
523 *  @param[in] information points to an object class information block.
524 *  @param[in] the_object points to the object to deallocate.
[f4a8ee1]525 */
526void _Objects_Free(
527  Objects_Information *information,
528  Objects_Control     *the_object
529);
530
[6a07436]531/**
[c6f111b]532 *  This method zeroes out the name.
[6a07436]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.
[3235ad9]536 */
537void _Objects_Clear_name(
[f5c5a1db]538  void         *name,
539  const size_t  length
[3235ad9]540);
541
[6a07436]542/**
[c6f111b]543 *  This method copies a string style object name from source to destination.
[6a07436]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.
[3235ad9]548 */
549void _Objects_Copy_name_string(
[f5c5a1db]550  const void   *source,
551  void         *destination,
552  const size_t  length
[3235ad9]553);
554
[6a07436]555/**
[c6f111b]556 *  This method copies a raw style object name from source to destination.
[6a07436]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.
[3235ad9]561 */
562void _Objects_Copy_name_raw(
[f5c5a1db]563  const void   *source,
564  void         *destination,
565  const size_t  length
[3235ad9]566);
567
[6a07436]568/**
[c6f111b]569 *  This method compares two string style object names.
[6a07436]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.
[3235ad9]574 */
575boolean _Objects_Compare_name_string(
576  void       *name_1,
577  void       *name_2,
[85b7605]578  uint16_t    length
[ac7d5ef0]579);
580
[6a07436]581/**
[c6f111b]582 *  This method compares two raw style object names.
[6a07436]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.
[3235ad9]587 */
588boolean _Objects_Compare_name_raw(
589  void       *name_1,
590  void       *name_2,
[85b7605]591  uint16_t    length
[3235ad9]592);
[ff08b808]593
[6a07436]594/**
[ac7d5ef0]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 */
[3a4ae6c]604typedef enum {
[ff08b808]605  OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL,
[3a4ae6c]606  OBJECTS_INVALID_NAME,
[e980b219]607  OBJECTS_INVALID_ADDRESS,
[ff08b808]608  OBJECTS_INVALID_ID,
[3a4ae6c]609  OBJECTS_INVALID_NODE
[ff08b808]610} Objects_Name_or_id_lookup_errors;
[3a4ae6c]611
[6a07436]612/** This macro defines the first entry in the
613 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
614 */
[ff08b808]615#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL
[6a07436]616
617/** This macro defines the last entry in the
618 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
619 */
[3a4ae6c]620#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
621
[6a07436]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 */
[ff08b808]636Objects_Name_or_id_lookup_errors _Objects_Name_to_id(
[ac7d5ef0]637  Objects_Information *information,
638  Objects_Name         name,
[d6154c7]639  uint32_t             node,
[ac7d5ef0]640  Objects_Id          *id
641);
642
[6a07436]643/**
[ff08b808]644 *  This function implements the common portion of the object Id
645 *  to name directives.  This function returns the name
[a0ed4ed]646 *  associated with object id.
[ff08b808]647 *
[6a07436]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.
[ff08b808]655 *
[6a07436]656 *  @note This function currently does not support string names.
[ff08b808]657 */
658Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
659  Objects_Id      id,
660  Objects_Name   *name
661);
662
[6a07436]663/**
[ac7d5ef0]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 *
[6a07436]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.
[ac7d5ef0]686 */
687Objects_Control *_Objects_Get (
688  Objects_Information *information,
689  Objects_Id           id,
690  Objects_Locations   *location
691);
692
[6a07436]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 */
[c6f111b]718Objects_Control *_Objects_Get_isr_disable(
719  Objects_Information *information,
720  Objects_Id           id,
721  Objects_Locations   *location,
722  ISR_Level           *level
723);
724
[6a07436]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 */
[c31c15c]747Objects_Control *_Objects_Get_by_index (
748  Objects_Information *information,
749  Objects_Id           id,
750  Objects_Locations   *location
751);
[ef9505a9]752
[6a07436]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 */
[ef9505a9]777Objects_Control *_Objects_Get_no_protection(
778  Objects_Information *information,
779  Objects_Id           id,
780  Objects_Locations   *location
781);
782
[6a07436]783/**
784 *  Like @ref _Objects_Get, but is used to find "next" open object.
[b06e68ef]785 *
[6a07436]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.
[b06e68ef]790 *
[6a07436]791 *  @return This method returns the pointer to the object located or
792 *          NULL on error.
[b06e68ef]793 */
794Objects_Control *_Objects_Get_next(
795    Objects_Information *information,
796    Objects_Id           id,
[4944b5bf]797    Objects_Locations   *location_p,
[b06e68ef]798    Objects_Id          *next_id_p
799);
800
[e1bce86]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
[ac7d5ef0]819/*
[1a8fde6c]820 *  Pieces of object.inl are promoted out to the user
[ac7d5ef0]821 */
822
[5e9b32b]823#include <rtems/score/object.inl>
[97e2729d]824#if defined(RTEMS_MULTIPROCESSING)
[5e9b32b]825#include <rtems/score/objectmp.h>
[97e2729d]826#endif
[ac7d5ef0]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.