source: rtems/c/src/exec/score/headers/object.h @ be650a84

4.104.114.84.95
Last change on this file since be650a84 was be650a84, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 21, 1995 at 4:22:25 PM

moving files around

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