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

4.115
Last change on this file since f7f1d77 was f7f1d77, checked in by Alex Ivanov <alexivanov97@…>, on 11/28/12 at 14:11:31

score misc: Clean up Doxygen (GCI 2012)

This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.
https://google-melange.appspot.com/gci/task/view/google/gci2012/7978208

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