source: rtems/cpukit/score/include/rtems/score/object.h @ 3235ad9

4.104.114.84.95
Last change on this file since 3235ad9 was 3235ad9, checked in by Joel Sherrill <joel.sherrill@…>, on 08/23/95 at 19:30:23

Support for variable length names added to Object Handler. This supports
both fixed length "raw" names and strings from the API's point of view.

Both inline and macro implementations were tested.

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