source: rtems/c/src/exec/score/include/rtems/score/object.h @ 7d573e9

Last change on this file since 7d573e9 was 7d573e9, checked in by Joel Sherrill <joel.sherrill@…>, on 11/07/01 at 22:51:28

2001-11-07 Joel Sherrill <joel@…>

  • include/rtems/score/object.h: Added prototype for _Objects_Get_by_index().
  • src/objectget.c: Corrected procedure for getting index from Id so it is correct and optimal for both single and multiprocessor configurations.
  • Property mode set to 100644
File size: 11.8 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-1999.
9 *  On-Line Applications Research Corporation (OAR).
10 *
11 *  The license and distribution terms for this file may be
12 *  found in the file LICENSE in this distribution or at
13 *  http://www.OARcorp.com/rtems/license.html.
14 *
15 *  $Id$
16 */
17
18#ifndef __OBJECTS_h
19#define __OBJECTS_h
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25#include <rtems/score/chain.h>
26
27/*
28 *  Mask to enable unlimited objects
29 *
30 *  XXX - needs to be moved to the API some-where
31 */
32
33#define OBJECTS_UNLIMITED_OBJECTS 0x80000000
34
35/*
36 *  The following type defines the control block used to manage
37 *  object names.
38 */
39
40typedef void * Objects_Name;
41
42/*
43 *  Space for object names is allocated in multiples of this.
44 *
45 *  NOTE:  Must be a power of 2.  Matches the name manipulation routines.
46 */
47
48#define OBJECTS_NAME_ALIGNMENT     sizeof( unsigned32 )
49
50/*
51 *  Functions which compare names are prototyped like this.
52 */
53
54typedef boolean (*Objects_Name_comparators)(
55  void       * /* name_1 */,
56  void       * /* name_2 */,
57  unsigned32   /* length */
58);
59
60/*
61 *  The following type defines the control block used to manage
62 *  object IDs.  The format is as follows (0=LSB):
63 *
64 *     Bits  0 .. 15    = index
65 *     Bits 16 .. 25    = node
66 *     Bits 26 .. 31    = class
67 */
68
69typedef unsigned32 Objects_Id;
70
71#define OBJECTS_INDEX_START_BIT  0
72#define OBJECTS_NODE_START_BIT  16
73#define OBJECTS_CLASS_START_BIT 26
74
75#define OBJECTS_INDEX_MASK      0x0000ffff
76#define OBJECTS_NODE_MASK       0x03ff0000
77#define OBJECTS_CLASS_MASK      0xfc000000
78
79#define OBJECTS_INDEX_VALID_BITS  0x0000ffff
80#define OBJECTS_NODE_VALID_BITS   0x000003ff
81#define OBJECTS_CLASS_VALID_BITS  0x000000cf
82
83/*
84 *  This enumerated type is used in the class field of the object ID.
85 */
86
87typedef enum {
88  OBJECTS_NO_CLASS                    =  0,
89  OBJECTS_INTERNAL_THREADS            =  1,
90  OBJECTS_RTEMS_TASKS                 =  2,
91  OBJECTS_POSIX_THREADS               =  3,
92  OBJECTS_ITRON_TASKS                 =  4,
93  OBJECTS_RTEMS_TIMERS                =  5,
94  OBJECTS_RTEMS_SEMAPHORES            =  6,
95  OBJECTS_RTEMS_MESSAGE_QUEUES        =  7,
96  OBJECTS_RTEMS_PARTITIONS            =  8,
97  OBJECTS_RTEMS_REGIONS               =  9,
98  OBJECTS_RTEMS_PORTS                 = 10,
99  OBJECTS_RTEMS_PERIODS               = 11,
100  OBJECTS_RTEMS_EXTENSIONS            = 12,
101  OBJECTS_POSIX_KEYS                  = 13,
102  OBJECTS_POSIX_INTERRUPTS            = 14,
103  OBJECTS_POSIX_MESSAGE_QUEUES        = 15,
104  OBJECTS_POSIX_MUTEXES               = 16,
105  OBJECTS_POSIX_SEMAPHORES            = 17,
106  OBJECTS_POSIX_CONDITION_VARIABLES   = 18,
107  OBJECTS_ITRON_EVENTFLAGS            = 19,
108  OBJECTS_ITRON_MAILBOXES             = 20,
109  OBJECTS_ITRON_MESSAGE_BUFFERS       = 21,
110  OBJECTS_ITRON_PORTS                 = 22,
111  OBJECTS_ITRON_SEMAPHORES            = 23,
112  OBJECTS_ITRON_VARIABLE_MEMORY_POOLS = 24,
113  OBJECTS_ITRON_FIXED_MEMORY_POOLS    = 25
114} Objects_Classes;
115 
116#define OBJECTS_CLASSES_FIRST               OBJECTS_NO_CLASS
117#define OBJECTS_CLASSES_LAST                OBJECTS_ITRON_FIXED_MEMORY_POOLS
118#define OBJECTS_CLASSES_FIRST_THREAD_CLASS  OBJECTS_INTERNAL_THREADS
119#define OBJECTS_CLASSES_LAST_THREAD_CLASS   OBJECTS_ITRON_TASKS
120
121/*
122 *  This enumerated type lists the locations which may be returned
123 *  by _Objects_Get.  These codes indicate the success of locating
124 *  an object with the specified ID.
125 */
126
127typedef enum {
128  OBJECTS_LOCAL  = 0,         /* object is local */
129  OBJECTS_REMOTE = 1,         /* object is remote */
130  OBJECTS_ERROR  = 2          /* id was invalid */
131}  Objects_Locations;
132
133/*
134 *  The following defines the Object Control Block used to manage
135 *  each object local to this node.
136 */
137
138typedef struct {
139  Chain_Node     Node;
140  Objects_Id     id;
141  Objects_Name   name;
142}   Objects_Control;
143
144/*
145 *  The following defines the structure for the information used to
146 *  manage each class of objects.
147 */
148
149typedef struct {
150  Objects_Classes   the_class;          /* Class of this object */
151  Objects_Id        minimum_id;         /* minimum valid id of this type */
152  Objects_Id        maximum_id;         /* maximum valid id of this type */
153  unsigned32        maximum;            /* maximum number of objects */
154  boolean           auto_extend;        /* TRUE if unlimited objects */
155  unsigned32        allocation_size;    /* number of objects in a block */
156  unsigned32        size;               /* size of the objects */
157  Objects_Control **local_table;
158  Objects_Name     *name_table;
159  Chain_Control    *global_table;       /* pointer to global table */
160  Chain_Control     Inactive;           /* chain of inactive ctl blocks */
161  unsigned32        inactive;           /* number of objects on the InActive list */
162  unsigned32       *inactive_per_block; /* used to release a block */
163  void            **object_blocks;      /* the object memory to remove */
164  boolean           is_string;          /* TRUE if names are strings */
165  unsigned32        name_length;        /* maximum length of names */
166  boolean           is_thread;          /* TRUE if these are threads */
167                                        /*   irregardless of API */
168}   Objects_Information;
169
170/*
171 *  The following defines the data storage which contains the
172 *  node number of the local node.
173 */
174
175SCORE_EXTERN unsigned32  _Objects_Local_node;
176SCORE_EXTERN unsigned32  _Objects_Maximum_nodes;
177
178/*
179 *  The following is the list of information blocks for each object
180 *  class.  From the ID, we can go to one of these information blocks,
181 *  and obtain a pointer to the appropriate object control block.
182 */
183
184SCORE_EXTERN Objects_Information
185    *_Objects_Information_table[OBJECTS_CLASSES_LAST + 1];
186
187/*
188 *  The following defines the constant which may be used
189 *  with _Objects_Get to manipulate the calling task.
190 *
191 */
192
193#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
194
195/*
196 *  The following define the constants which may be used in name searches.
197 */
198
199#define OBJECTS_SEARCH_ALL_NODES   0
200#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
201#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
202#define OBJECTS_WHO_AM_I           0
203
204/*
205 * Parameters and return id's for _Objects_Get_next
206 */
207
208#define OBJECTS_ID_INITIAL_INDEX   (0)
209#define OBJECTS_ID_FINAL_INDEX     (0xffff)
210
211#define OBJECTS_ID_INITIAL(_class, _node) \
212  _Objects_Build_id( (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
213
214#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
215
216/*
217 *  _Objects_Handler_initialization
218 *
219 *  DESCRIPTION:
220 *
221 *  This function performs the initialization necessary for this handler.
222 *
223 */
224
225void _Objects_Handler_initialization(
226  unsigned32 node,
227  unsigned32 maximum_nodes,
228  unsigned32 maximum_global_objects
229);
230
231/*
232 *  _Objects_Extend_information
233 *
234 *  DESCRIPTION:
235 *
236 *  This function extends an object class information record.
237 */
238
239void _Objects_Extend_information(
240  Objects_Information *information
241);
242
243/*
244 *  _Objects_Shrink_information
245 *
246 *  DESCRIPTION:
247 *
248 *  This function shrink an object class information record.
249 */
250
251void _Objects_Shrink_information(
252  Objects_Information *information
253);
254
255/*
256 *  _Objects_Initialize_information
257 *
258 *  DESCRIPTION:
259 *
260 *  This function initializes an object class information record.
261 *  SUPPORTS_GLOBAL is TRUE if the object class supports global
262 *  objects, and FALSE otherwise.  Maximum indicates the number
263 *  of objects required in this class and size indicates the size
264 *  in bytes of each control block for this object class.  The
265 *  name length and string designator are also set.  In addition,
266 *  the class may be a task, therefore this information is also included.
267 */
268
269void _Objects_Initialize_information (
270  Objects_Information *information,
271  Objects_Classes      the_class,
272  boolean              supports_global,
273  unsigned32           maximum,
274  unsigned32           size,
275  boolean              is_string,
276  unsigned32           maximum_name_length,
277  boolean              is_task
278);
279
280/*PAGE
281 *
282 *  _Objects_Allocate
283 *
284 *  DESCRIPTION:
285 *
286 *  This function allocates a object control block from
287 *  the inactive chain of free object control blocks.
288 */
289
290Objects_Control *_Objects_Allocate(
291  Objects_Information *information
292);
293
294/*
295 *  _Objects_Allocate_by_index
296 *
297 *  DESCRIPTION:
298 *
299 *  This function allocates the object control block
300 *  specified by the index from the inactive chain of
301 *  free object control blocks.
302 */
303
304Objects_Control *_Objects_Allocate_by_index(
305  Objects_Information *information,
306  unsigned32           index,
307  unsigned32           sizeof_control
308);
309
310/*PAGE
311 *
312 *  _Objects_Free
313 *
314 *  DESCRIPTION:
315 *
316 *  This function frees a object control block to the
317 *  inactive chain of free object control blocks.
318 */
319
320void _Objects_Free(
321  Objects_Information *information,
322  Objects_Control     *the_object
323);
324
325/*
326 *  _Objects_Clear_name
327 *
328 *  DESCRIPTION:
329 *
330 *  XXX
331 */
332 
333void _Objects_Clear_name(
334  void       *name,
335  unsigned32  length
336);
337
338/*
339 *  _Objects_Copy_name_string
340 *
341 *  DESCRIPTION:
342 *
343 *  XXX
344 */
345
346void _Objects_Copy_name_string(
347  void       *source,
348  void       *destination
349);
350
351/*
352 *  _Objects_Copy_name_raw
353 *
354 *  DESCRIPTION:
355 *
356 *  XXX
357 */
358
359void _Objects_Copy_name_raw(
360  void       *source,
361  void       *destination,
362  unsigned32  length
363);
364
365/*
366 *  _Objects_Compare_name_string
367 *
368 *  DESCRIPTION:
369 *
370 *  XXX
371 */
372
373boolean _Objects_Compare_name_string(
374  void       *name_1,
375  void       *name_2,
376  unsigned32  length
377);
378
379/*
380 *  _Objects_Compare_name_raw
381 *
382 *  DESCRIPTION:
383 *
384 *  XXX
385 */
386
387boolean _Objects_Compare_name_raw(
388  void       *name_1,
389  void       *name_2,
390  unsigned32  length
391);
392/*
393 *  _Objects_Name_to_id
394 *
395 *  DESCRIPTION:
396 *
397 *  This function implements the common portion of the object
398 *  identification directives.  This directive returns the object
399 *  id associated with name.  If more than one object of this class
400 *  is named name, then the object to which the id belongs is
401 *  arbitrary.  Node indicates the extent of the search for the
402 *  id of the object named name.  If the object class supports global
403 *  objects, then the search can be limited to a particular node
404 *  or allowed to encompass all nodes.
405 *
406 */
407
408typedef enum {
409  OBJECTS_SUCCESSFUL,
410  OBJECTS_INVALID_NAME,
411  OBJECTS_INVALID_NODE
412} Objects_Name_to_id_errors;
413
414#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_SUCCESSFUL
415#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
416
417Objects_Name_to_id_errors _Objects_Name_to_id(
418  Objects_Information *information,
419  Objects_Name         name,
420  unsigned32           node,
421  Objects_Id          *id
422);
423
424/*
425 *  _Objects_Get
426 *
427 *  DESCRIPTION:
428 *
429 *  This function maps object ids to object control blocks.
430 *  If id corresponds to a local object, then it returns
431 *  the_object control pointer which maps to id and location
432 *  is set to OBJECTS_LOCAL.  If the object class supports global
433 *  objects and the object id is global and resides on a remote
434 *  node, then location is set to OBJECTS_REMOTE, and the_object
435 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
436 *  and the_object is undefined.
437 *
438 */
439
440Objects_Control *_Objects_Get (
441  Objects_Information *information,
442  Objects_Id           id,
443  Objects_Locations   *location
444);
445
446Objects_Control *_Objects_Get_by_index (
447  Objects_Information *information,
448  Objects_Id           id,
449  Objects_Locations   *location
450);
451
452/*
453 *  _Objects_Get_next
454 *
455 *  DESCRIPTION:
456 *
457 *  Like _Objects_Get, but is used to find "next" open object.
458 *
459 */
460
461Objects_Control *_Objects_Get_next(
462    Objects_Information *information,
463    Objects_Id           id,
464    Objects_Locations   *location_p,
465    Objects_Id          *next_id_p
466);
467
468/*
469 *  Pieces of object.inl are promoted out to the user
470 */
471
472#include <rtems/score/object.inl>
473#if defined(RTEMS_MULTIPROCESSING)
474#include <rtems/score/objectmp.h>
475#endif
476
477#ifdef __cplusplus
478}
479#endif
480
481#endif
482/* end of include file */
Note: See TracBrowser for help on using the repository browser.