source: rtems/cpukit/score/include/rtems/score/object.h @ 5e9b32b

4.104.114.84.95
Last change on this file since 5e9b32b was 5e9b32b, checked in by Joel Sherrill <joel.sherrill@…>, on 09/26/95 at 19:27:15

posix support initially added

  • Property mode set to 100644
File size: 12.6 KB
Line 
1/*  object.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Object Handler.  This Handler provides mechanisms which
5 *  can be used to initialize and manipulate all objects which have
6 *  ids.
7 *
8 *  COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994.
9 *  On-Line Applications Research Corporation (OAR).
10 *  All rights assigned to U.S. Government, 1994.
11 *
12 *  This material may be reproduced by or for the U.S. Government pursuant
13 *  to the copyright license under the clause at DFARS 252.227-7013.  This
14 *  notice must appear in all copies of this file and its derivatives.
15 *
16 *  $Id$
17 */
18
19#ifndef __OBJECTS_h
20#define __OBJECTS_h
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26#include <rtems/score/chain.h>
27
28/*
29 *  The following type defines the control block used to manage
30 *  object names.
31 */
32
33typedef void * Objects_Name;
34
35/*
36 *  Space for object names is allocated in multiples of this.
37 *
38 *  NOTE:  Must be a power of 2.  Matches the name manipulation routines.
39 */
40
41#define OBJECTS_NAME_ALIGNMENT     4
42
43/*
44 *  Functions which compare names are prototyped like this.
45 */
46
47typedef boolean (*Objects_Name_comparators)(
48  void       * /* name_1 */,
49  void       * /* name_2 */,
50  unsigned32   /* length */
51);
52
53/*
54 *  The following type defines the control block used to manage
55 *  object IDs.  The format is as follows (0=LSB):
56 *
57 *     Bits  0 .. 15    = index
58 *     Bits 16 .. 25    = node
59 *     Bits 26 .. 31    = class
60 */
61
62typedef unsigned32 Objects_Id;
63
64#define OBJECTS_INDEX_START_BIT  0
65#define OBJECTS_NODE_START_BIT  16
66#define OBJECTS_CLASS_START_BIT 26
67
68#define OBJECTS_INDEX_MASK      0x0000ffff
69#define OBJECTS_NODE_MASK       0x03ff0000
70#define OBJECTS_CLASS_MASK      0xfc000000
71
72#define OBJECTS_INDEX_VALID_BITS  0x0000ffff
73#define OBJECTS_NODE_VALID_BITS   0x000003ff
74#define OBJECTS_CLASS_VALID_BITS  0x000000cf
75
76/*
77 *  This enumerated type is used in the class field of the object ID.
78 */
79
80typedef enum {
81  OBJECTS_NO_CLASS                  =  0,
82  OBJECTS_INTERNAL_THREADS          =  1,
83  OBJECTS_RTEMS_TASKS               =  2,
84  OBJECTS_POSIX_THREADS             =  3,
85  OBJECTS_RTEMS_TIMERS              =  4,
86  OBJECTS_RTEMS_SEMAPHORES          =  5,
87  OBJECTS_RTEMS_MESSAGE_QUEUES      =  6,
88  OBJECTS_RTEMS_PARTITIONS          =  7,
89  OBJECTS_RTEMS_REGIONS             =  8,
90  OBJECTS_RTEMS_PORTS               =  9,
91  OBJECTS_RTEMS_PERIODS             = 10,
92  OBJECTS_RTEMS_EXTENSIONS          = 11,
93  OBJECTS_POSIX_KEYS                = 12,
94  OBJECTS_POSIX_INTERRUPTS          = 13,
95  OBJECTS_POSIX_MESSAGE_QUEUES      = 14,
96  OBJECTS_POSIX_MUTEXES             = 15,
97  OBJECTS_POSIX_SEMAPHORES          = 16,
98  OBJECTS_POSIX_CONDITION_VARIABLES = 17
99} Objects_Classes;
100 
101#define OBJECTS_CLASSES_FIRST               OBJECTS_NO_CLASS
102#define OBJECTS_CLASSES_LAST                OBJECTS_POSIX_CONDITION_VARIABLES
103#define OBJECTS_CLASSES_FIRST_THREAD_CLASS  OBJECTS_INTERNAL_THREADS
104#define OBJECTS_CLASSES_LAST_THREAD_CLASS   OBJECTS_POSIX_THREADS
105
106/*
107 *  This enumerated type lists the locations which may be returned
108 *  by _Objects_Get.  These codes indicate the success of locating
109 *  an object with the specified ID.
110 */
111
112typedef enum {
113  OBJECTS_LOCAL  = 0,         /* object is local */
114  OBJECTS_REMOTE = 1,         /* object is remote */
115  OBJECTS_ERROR  = 2          /* id was invalid */
116}  Objects_Locations;
117
118/*
119 *  The following defines the Object Control Block used to manage
120 *  each object local to this node.
121 */
122
123typedef struct {
124  Chain_Node    Node;
125  Objects_Id    id;
126  Objects_Name  name;
127}   Objects_Control;
128
129/*
130 *  The following defines the structure for the information used to
131 *  manage each class of objects.
132 */
133
134typedef struct {
135  Objects_Classes   the_class;       /* Class of this object */
136  Objects_Id        minimum_id;      /* minimum valid id of this type */
137  Objects_Id        maximum_id;      /* maximum valid id of this type */
138  unsigned32        maximum;         /* maximum number of objects */
139  Objects_Control **local_table;     /* table of local object pointers */
140  Objects_Name     *name_table;      /* table of local object names */
141  Chain_Control    *global_table;    /* pointer to global table */
142  Chain_Control     Inactive;        /* chain of inactive ctl blocks */
143  boolean           is_string;       /* TRUE if names are strings */
144  unsigned32        name_length;     /* maximum length of names */
145  boolean           is_thread;       /* TRUE if these are threads */
146                                     /*   irregardless of API */
147}   Objects_Information;
148
149/*
150 *  The following defines the data storage which contains the
151 *  node number of the local node.
152 */
153
154EXTERN unsigned32  _Objects_Local_node;
155EXTERN unsigned32  _Objects_Maximum_nodes;
156
157/*
158 *  The following is the list of information blocks for each object
159 *  class.  From the ID, we can go to one of these information blocks,
160 *  and obtain a pointer to the appropriate object control block.
161 */
162
163EXTERN Objects_Information
164    *_Objects_Information_table[OBJECTS_CLASSES_LAST + 1];
165
166/*
167 *  The following defines the constant which may be used
168 *  with _Objects_Get to manipulate the calling task.
169 *
170 */
171
172#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
173
174/*
175 *  The following define the constants which may be used in name searches.
176 */
177
178#define OBJECTS_SEARCH_ALL_NODES   0
179#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
180#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
181#define OBJECTS_WHO_AM_I           0
182
183/*
184 * Parameters and return id's for _Objects_Get_next
185 */
186
187#define OBJECTS_ID_INITIAL_INDEX   (0)
188#define OBJECTS_ID_FINAL_INDEX     (0xffff)
189
190#define OBJECTS_ID_INITIAL(node)   (_Objects_Build_id(      \
191                                      OBJECTS_NO_CLASS, \
192                                      node, \
193                                      OBJECTS_ID_INITIAL_INDEX))
194#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
195
196/*
197 *  _Objects_Handler_initialization
198 *
199 *  DESCRIPTION:
200 *
201 *  This function performs the initialization necessary for this handler.
202 *
203 */
204
205void _Objects_Handler_initialization(
206  unsigned32 node,
207  unsigned32 maximum_nodes,
208  unsigned32 maximum_global_objects
209);
210
211/*
212 *  _Objects_Initialize_information
213 *
214 *  DESCRIPTION:
215 *
216 *  This function initializes an object class information record.
217 *  SUPPORTS_GLOBAL is TRUE if the object class supports global
218 *  objects, and FALSE otherwise.  Maximum indicates the number
219 *  of objects required in this class and size indicates the size
220 *  in bytes of each control block for this object class.  The
221 *  name length and string designator are also set.  In addition,
222 *  the class may be a task, therefore this information is also included.
223 */
224
225void _Objects_Initialize_information (
226  Objects_Information *information,
227  Objects_Classes      the_class,
228  boolean              supports_global,
229  unsigned32           maximum,
230  unsigned32           size,
231  boolean              is_string,
232  unsigned32           maximum_name_length,
233  boolean              is_task
234);
235
236/*
237 *  _Objects_Clear_name
238 *
239 *  DESCRIPTION:
240 *
241 *  XXX
242 */
243 
244void _Objects_Clear_name(
245  void       *name,
246  unsigned32  length
247);
248
249/*
250 *  _Objects_Copy_name_string
251 *
252 *  DESCRIPTION:
253 *
254 *  XXX
255 */
256
257void _Objects_Copy_name_string(
258  void       *source,
259  void       *destination
260);
261
262/*
263 *  _Objects_Copy_name_raw
264 *
265 *  DESCRIPTION:
266 *
267 *  XXX
268 */
269
270void _Objects_Copy_name_raw(
271  void       *source,
272  void       *destination,
273  unsigned32  length
274);
275
276/*
277 *  _Objects_Compare_name_string
278 *
279 *  DESCRIPTION:
280 *
281 *  XXX
282 */
283
284boolean _Objects_Compare_name_string(
285  void       *name_1,
286  void       *name_2,
287  unsigned32  length
288);
289
290/*
291 *  _Objects_Compare_name_raw
292 *
293 *  DESCRIPTION:
294 *
295 *  XXX
296 */
297
298boolean _Objects_Compare_name_raw(
299  void       *name_1,
300  void       *name_2,
301  unsigned32  length
302);
303/*
304 *  _Objects_Name_to_id
305 *
306 *  DESCRIPTION:
307 *
308 *  This function implements the common portion of the object
309 *  identification directives.  This directive returns the object
310 *  id associated with name.  If more than one object of this class
311 *  is named name, then the object to which the id belongs is
312 *  arbitrary.  Node indicates the extent of the search for the
313 *  id of the object named name.  If the object class supports global
314 *  objects, then the search can be limited to a particular node
315 *  or allowed to encompass all nodes.
316 *
317 */
318
319typedef enum {
320  OBJECTS_SUCCESSFUL,
321  OBJECTS_INVALID_NAME,
322  OBJECTS_INVALID_NODE
323} Objects_Name_to_id_errors;
324
325#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_SUCCESSFUL
326#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
327
328Objects_Name_to_id_errors _Objects_Name_to_id(
329  Objects_Information *information,
330  Objects_Name         name,
331  unsigned32           node,
332  Objects_Id          *id
333);
334
335/*
336 *  _Objects_Get
337 *
338 *  DESCRIPTION:
339 *
340 *  This function maps object ids to object control blocks.
341 *  If id corresponds to a local object, then it returns
342 *  the_object control pointer which maps to id and location
343 *  is set to OBJECTS_LOCAL.  If the object class supports global
344 *  objects and the object id is global and resides on a remote
345 *  node, then location is set to OBJECTS_REMOTE, and the_object
346 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
347 *  and the_object is undefined.
348 *
349 */
350
351Objects_Control *_Objects_Get (
352  Objects_Information *information,
353  Objects_Id           id,
354  Objects_Locations   *location
355);
356
357/*
358 *  _Objects_Get_next
359 *
360 *  DESCRIPTION:
361 *
362 *  Like _Objects_Get, but is used to find "next" open object.
363 *
364 */
365
366Objects_Control *_Objects_Get_next(
367    Objects_Information *information,
368    Objects_Id           id,
369    unsigned32          *location_p,
370    Objects_Id          *next_id_p
371);
372
373/*
374 *  _Objects_Get_information
375 *
376 *  DESCRIPTION:
377 *
378 *  Returns the information control block for the class of objects
379 *  corresponding to this id.
380 */
381
382Objects_Information *_Objects_Get_information(
383  Objects_Id  id
384);
385 
386/*
387 *  _Objects_Build_id
388 *
389 *  DESCRIPTION:
390 *
391 *  This function builds an object's id from the processor node and index
392 *  values specified.
393 *
394 */
395
396STATIC INLINE Objects_Id _Objects_Build_id(
397  Objects_Classes  the_class,
398  unsigned32       node,
399  unsigned32       index
400);
401
402/*
403 *  _Objects_Get_class
404 *
405 *  DESCRIPTION:
406 *
407 *  This function returns the class portion of the ID.
408 *
409 */
410 
411STATIC INLINE Objects_Classes _Objects_Get_class(
412  Objects_Id id
413);
414
415/*
416 *  _Objects_Get_node
417 *
418 *  DESCRIPTION:
419 *
420 *  This function returns the node portion of the ID.
421 *
422 */
423
424STATIC INLINE unsigned32 _Objects_Get_node(
425  Objects_Id id
426);
427
428/*
429 *  _Objects_Get_index
430 *
431 *  DESCRIPTION:
432 *
433 *  This function returns the index portion of the ID.
434 *
435 */
436
437STATIC INLINE unsigned32 _Objects_Get_index(
438  Objects_Id id
439);
440
441/*
442 *  _Objects_Is_class_valid
443 *
444 *  DESCRIPTION:
445 *
446 *  This function returns TRUE if the class is valid.
447 *
448 */
449 
450STATIC INLINE boolean _Objects_Is_class_valid(
451  Objects_Classes the_class
452);
453
454/*
455 *  _Objects_Is_local_node
456 *
457 *  DESCRIPTION:
458 *
459 *  This function returns TRUE if the node is of the local object, and
460 *  FALSE otherwise.
461 *
462 */
463
464STATIC INLINE boolean _Objects_Is_local_node(
465  unsigned32 node
466);
467
468/*
469 *  _Objects_Is_local_id
470 *
471 *  DESCRIPTION:
472 *
473 *  This function returns TRUE if the id is of a local object, and
474 *  FALSE otherwise.
475 *
476 */
477
478STATIC INLINE boolean _Objects_Is_local_id(
479  Objects_Id id
480);
481
482/*
483 *  _Objects_Are_ids_equal
484 *
485 *  DESCRIPTION:
486 *
487 *  This function returns TRUE if left and right are equal,
488 *  and FALSE otherwise.
489 *
490 */
491
492STATIC INLINE boolean _Objects_Are_ids_equal(
493  Objects_Id left,
494  Objects_Id right
495);
496
497/*
498 *  _Objects_Allocate
499 *
500 *  DESCRIPTION:
501 *
502 *  This function allocates a object control block from
503 *  the inactive chain of free object control blocks.
504 *
505 */
506
507STATIC INLINE Objects_Control *_Objects_Allocate(
508  Objects_Information *information
509);
510
511/*
512 *  _Objects_Free
513 *
514 *  DESCRIPTION:
515 *
516 *  This function frees a object control block to the
517 *  inactive chain of free object control blocks.
518 *
519 */
520
521STATIC INLINE void _Objects_Free(
522  Objects_Information *information,
523  Objects_Control     *the_object
524);
525
526/*
527 *  _Objects_Open
528 *
529 *  DESCRIPTION:
530 *
531 *  This function places the_object control pointer and object name
532 *  in the Local Pointer and Local Name Tables, respectively.
533 *
534 */
535
536STATIC INLINE void _Objects_Open(
537  Objects_Information *information,
538  Objects_Control     *the_object,
539  Objects_Name         name
540);
541
542/*
543 *  _Objects_Close
544 *
545 *  DESCRIPTION:
546 *
547 *  This function removes the_object control pointer and object name
548 *  in the Local Pointer and Local Name Tables.
549 *
550 */
551
552STATIC INLINE void _Objects_Close(
553  Objects_Information *information,
554  Objects_Control     *the_object
555);
556
557#include <rtems/score/object.inl>
558#include <rtems/score/objectmp.h>
559
560#ifdef __cplusplus
561}
562#endif
563
564#endif
565/* end of include file */
Note: See TracBrowser for help on using the repository browser.