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

Last change on this file since df54012 was df54012, checked in by Joel Sherrill <joel.sherrill@…>, on 05/06/04 at 19:20:44

2004-05-06 Joel Sherrill <joel@…>

PR 618/rtems

  • include/rtems/score/object.h, src/coretodvalidate.c, src/objectnametoid.c: Add NULL checks.
  • Property mode set to 100644
File size: 13.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-2002.
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.rtems.com/license/LICENSE.
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#include <rtems/score/isr.h>
27
28/*
29 *  Mask to enable unlimited objects.  This is used in the configuration
30 *  table when specifying the number of configured objects.
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  (up to 65535 objects of a type)
65 *     Bits 16 .. 23    = node   (up to 255 nodes)
66 *     Bits 24 .. 26    = API    (up to 7 API classes)
67 *     Bits 27 .. 31    = class  (up to 31 object types per API)
68 */
69
70typedef unsigned32 Objects_Id;
71
72#define OBJECTS_INDEX_START_BIT  0
73#define OBJECTS_NODE_START_BIT  16
74#define OBJECTS_API_START_BIT   24
75#define OBJECTS_CLASS_START_BIT 27
76
77#define OBJECTS_INDEX_MASK      (Objects_Id)0x0000ffff
78#define OBJECTS_NODE_MASK       (Objects_Id)0x00ff0000
79#define OBJECTS_API_MASK        (Objects_Id)0x07000000
80#define OBJECTS_CLASS_MASK      (Objects_Id)0xf8000000
81
82#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x0000ffff
83#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ff
84#define OBJECTS_API_VALID_BITS    (Objects_Id)0x00000007
85#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x0000001f
86
87/*
88 *  This enumerated type is used in the class field of the object ID.
89 */
90
91#define OBJECTS_NO_CLASS 0
92
93typedef enum {
94  OBJECTS_NO_API       = 0,
95  OBJECTS_INTERNAL_API = 1,
96  OBJECTS_CLASSIC_API  = 2,
97  OBJECTS_POSIX_API    = 3,
98  OBJECTS_ITRON_API    = 4
99} Objects_APIs;
100
101#define OBJECTS_APIS_LAST OBJECTS_ITRON_API
102
103typedef enum {
104  OBJECTS_INTERNAL_NO_CLASS =  0,
105  OBJECTS_INTERNAL_THREADS  =  1,
106  OBJECTS_INTERNAL_MUTEXES  =  2
107} Objects_Internal_API;
108
109#define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES
110
111typedef enum {
112  OBJECTS_CLASSIC_NO_CLASS     = 0,
113  OBJECTS_RTEMS_TASKS          = 1,
114  OBJECTS_RTEMS_TIMERS         = 2,
115  OBJECTS_RTEMS_SEMAPHORES     = 3,
116  OBJECTS_RTEMS_MESSAGE_QUEUES = 4,
117  OBJECTS_RTEMS_PARTITIONS     = 5,
118  OBJECTS_RTEMS_REGIONS        = 6,
119  OBJECTS_RTEMS_PORTS          = 7,
120  OBJECTS_RTEMS_PERIODS        = 8,
121  OBJECTS_RTEMS_EXTENSIONS     = 9
122} Objects_Classic_API;
123
124#define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_EXTENSIONS
125
126typedef enum {
127  OBJECTS_POSIX_NO_CLASS            = 0,
128  OBJECTS_POSIX_THREADS             = 1,
129  OBJECTS_POSIX_KEYS                = 2,
130  OBJECTS_POSIX_INTERRUPTS          = 3,
131  OBJECTS_POSIX_MESSAGE_QUEUE_FDS   = 4,
132  OBJECTS_POSIX_MESSAGE_QUEUES      = 5,
133  OBJECTS_POSIX_MUTEXES             = 6,
134  OBJECTS_POSIX_SEMAPHORES          = 7,
135  OBJECTS_POSIX_CONDITION_VARIABLES = 8
136} Objects_POSIX_API;
137
138#define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_CONDITION_VARIABLES
139
140typedef enum {
141  OBJECTS_ITRON_NO_CLASS              = 0,
142  OBJECTS_ITRON_TASKS                 = 1,
143  OBJECTS_ITRON_EVENTFLAGS            = 2,
144  OBJECTS_ITRON_MAILBOXES             = 3,
145  OBJECTS_ITRON_MESSAGE_BUFFERS       = 4,
146  OBJECTS_ITRON_PORTS                 = 5,
147  OBJECTS_ITRON_SEMAPHORES            = 6,
148  OBJECTS_ITRON_VARIABLE_MEMORY_POOLS = 7,
149  OBJECTS_ITRON_FIXED_MEMORY_POOLS    = 8
150} Objects_ITRON_API;
151
152#define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS
153
154/*
155 *  This enumerated type lists the locations which may be returned
156 *  by _Objects_Get.  These codes indicate the success of locating
157 *  an object with the specified ID.
158 */
159
160typedef enum {
161  OBJECTS_LOCAL  = 0,         /* object is local */
162  OBJECTS_REMOTE = 1,         /* object is remote */
163  OBJECTS_ERROR  = 2          /* id was invalid */
164}  Objects_Locations;
165
166/*
167 *  The following type defines the callout used when a local task
168 *  is extracted from a remote thread queue (i.e. it's proxy must
169 *  extracted from the remote queue).
170 */
171
172typedef void ( *Objects_Thread_queue_Extract_callout )( void * );
173
174
175/*
176 *  The following defines the Object Control Block used to manage
177 *  each object local to this node.
178 */
179
180typedef struct {
181  Chain_Node     Node;
182  Objects_Id     id;
183  Objects_Name   name;
184}   Objects_Control;
185
186/*
187 *  The following defines the structure for the information used to
188 *  manage each class of objects.
189 */
190
191typedef struct {
192  Objects_APIs      the_api;            /* API of this object */
193  unsigned32        the_class;          /* class of this object */
194  Objects_Id        minimum_id;         /* minimum valid id of this type */
195  Objects_Id        maximum_id;         /* maximum valid id of this type */
196  unsigned32        maximum;            /* maximum number of objects */
197  boolean           auto_extend;        /* TRUE if unlimited objects */
198  unsigned32        allocation_size;    /* number of objects in a block */
199  unsigned32        size;               /* size of the objects */
200  Objects_Control **local_table;
201  Objects_Name     *name_table;
202  Chain_Control     Inactive;           /* chain of inactive ctl blocks */
203  unsigned32        inactive;           /* number of objects on the InActive list */
204  unsigned32       *inactive_per_block; /* used to release a block */
205  void            **object_blocks;      /* the object memory to remove */
206  boolean           is_string;          /* TRUE if names are strings */
207  unsigned32        name_length;        /* maximum length of names */
208  Objects_Thread_queue_Extract_callout *extract;
209#if defined(RTEMS_MULTIPROCESSING)
210  Chain_Control    *global_table;       /* pointer to global table */
211#endif
212}   Objects_Information;
213
214/*
215 *  The following defines the data storage which contains the
216 *  node number of the local node.
217 */
218
219SCORE_EXTERN unsigned32  _Objects_Local_node;
220SCORE_EXTERN unsigned32  _Objects_Maximum_nodes;
221
222/*
223 *  The following is the list of information blocks per API for each object
224 *  class.  From the ID, we can go to one of these information blocks,
225 *  and obtain a pointer to the appropriate object control block.
226 */
227
228SCORE_EXTERN Objects_Information
229    **_Objects_Information_table[OBJECTS_APIS_LAST + 1];
230
231/*
232 *  The following defines the constant which may be used
233 *  with _Objects_Get to manipulate the calling task.
234 *
235 */
236
237#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
238
239/*
240 *  The following define the constants which may be used in name searches.
241 */
242
243#define OBJECTS_SEARCH_ALL_NODES   0
244#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
245#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
246#define OBJECTS_WHO_AM_I           0
247
248/*
249 * Parameters and return id's for _Objects_Get_next
250 */
251
252#define OBJECTS_ID_INITIAL_INDEX   (0)
253#define OBJECTS_ID_FINAL_INDEX     (0xffff)
254
255#define OBJECTS_ID_INITIAL(_api, _class, _node) \
256  _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
257
258#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
259
260/*
261 *  _Objects_Handler_initialization
262 *
263 *  DESCRIPTION:
264 *
265 *  This function performs the initialization necessary for this handler.
266 *
267 */
268
269void _Objects_Handler_initialization(
270  unsigned32 node,
271  unsigned32 maximum_nodes,
272  unsigned32 maximum_global_objects
273);
274
275/*
276 *  _Objects_Extend_information
277 *
278 *  DESCRIPTION:
279 *
280 *  This function extends an object class information record.
281 */
282
283void _Objects_Extend_information(
284  Objects_Information *information
285);
286
287/*
288 *  _Objects_Shrink_information
289 *
290 *  DESCRIPTION:
291 *
292 *  This function shrink an object class information record.
293 */
294
295void _Objects_Shrink_information(
296  Objects_Information *information
297);
298
299/*
300 *  _Objects_Initialize_information
301 *
302 *  DESCRIPTION:
303 *
304 *  This function initializes an object class information record.
305 *  SUPPORTS_GLOBAL is TRUE if the object class supports global
306 *  objects, and FALSE otherwise.  Maximum indicates the number
307 *  of objects required in this class and size indicates the size
308 *  in bytes of each control block for this object class.  The
309 *  name length and string designator are also set.  In addition,
310 *  the class may be a task, therefore this information is also included.
311 */
312
313void _Objects_Initialize_information (
314  Objects_Information *information,
315  Objects_APIs         the_api,
316  unsigned32           the_class,
317  unsigned32           maximum,
318  unsigned32           size,
319  boolean              is_string,
320  unsigned32           maximum_name_length
321#if defined(RTEMS_MULTIPROCESSING)
322  ,
323  boolean              supports_global,
324  Objects_Thread_queue_Extract_callout *extract
325#endif
326);
327
328/*PAGE
329 *
330 *  _Objects_Allocate
331 *
332 *  DESCRIPTION:
333 *
334 *  This function allocates a object control block from
335 *  the inactive chain of free object control blocks.
336 */
337
338Objects_Control *_Objects_Allocate(
339  Objects_Information *information
340);
341
342/*
343 *  _Objects_Allocate_by_index
344 *
345 *  DESCRIPTION:
346 *
347 *  This function allocates the object control block
348 *  specified by the index from the inactive chain of
349 *  free object control blocks.
350 */
351
352Objects_Control *_Objects_Allocate_by_index(
353  Objects_Information *information,
354  unsigned32           index,
355  unsigned32           sizeof_control
356);
357
358/*PAGE
359 *
360 *  _Objects_Free
361 *
362 *  DESCRIPTION:
363 *
364 *  This function frees a object control block to the
365 *  inactive chain of free object control blocks.
366 */
367
368void _Objects_Free(
369  Objects_Information *information,
370  Objects_Control     *the_object
371);
372
373/*
374 *  _Objects_Clear_name
375 *
376 *  DESCRIPTION:
377 *
378 *  This method zeroes out the name.
379 */
380 
381void _Objects_Clear_name(
382  void       *name,
383  unsigned32  length
384);
385
386/*
387 *  _Objects_Copy_name_string
388 *
389 *  DESCRIPTION:
390 *
391 *  This method copies a string style object name from source to destination.
392 */
393
394void _Objects_Copy_name_string(
395  void       *source,
396  void       *destination
397);
398
399/*
400 *  _Objects_Copy_name_raw
401 *
402 *  DESCRIPTION:
403 *
404 *  This method copies a raw style object name from source to destination.
405 */
406
407void _Objects_Copy_name_raw(
408  void       *source,
409  void       *destination,
410  unsigned32  length
411);
412
413/*
414 *  _Objects_Compare_name_string
415 *
416 *  DESCRIPTION:
417 *
418 *  This method compares two string style object names.
419 */
420
421boolean _Objects_Compare_name_string(
422  void       *name_1,
423  void       *name_2,
424  unsigned32  length
425);
426
427/*
428 *  _Objects_Compare_name_raw
429 *
430 *  DESCRIPTION:
431 *
432 *  This method compares two raw style object names.
433 */
434
435boolean _Objects_Compare_name_raw(
436  void       *name_1,
437  void       *name_2,
438  unsigned32  length
439);
440/*
441 *  _Objects_Name_to_id
442 *
443 *  DESCRIPTION:
444 *
445 *  This function implements the common portion of the object
446 *  identification directives.  This directive returns the object
447 *  id associated with name.  If more than one object of this class
448 *  is named name, then the object to which the id belongs is
449 *  arbitrary.  Node indicates the extent of the search for the
450 *  id of the object named name.  If the object class supports global
451 *  objects, then the search can be limited to a particular node
452 *  or allowed to encompass all nodes.
453 *
454 */
455
456typedef enum {
457  OBJECTS_SUCCESSFUL,
458  OBJECTS_INVALID_NAME,
459  OBJECTS_INVALID_ADDRESS,
460  OBJECTS_INVALID_NODE
461} Objects_Name_to_id_errors;
462
463#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_SUCCESSFUL
464#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
465
466Objects_Name_to_id_errors _Objects_Name_to_id(
467  Objects_Information *information,
468  Objects_Name         name,
469  unsigned32           node,
470  Objects_Id          *id
471);
472
473/*
474 *  _Objects_Get
475 *
476 *  DESCRIPTION:
477 *
478 *  This function maps object ids to object control blocks.
479 *  If id corresponds to a local object, then it returns
480 *  the_object control pointer which maps to id and location
481 *  is set to OBJECTS_LOCAL.  If the object class supports global
482 *  objects and the object id is global and resides on a remote
483 *  node, then location is set to OBJECTS_REMOTE, and the_object
484 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
485 *  and the_object is undefined.
486 *
487 *  NOTE: _Objects_Get returns with dispatching disabled for
488 *        local and remote objects.
489 *        _Objects_Get_isr_disable returns with dispatching
490 *        disabled for remote objects and interrupts for local
491 *        objects.
492 */
493
494Objects_Control *_Objects_Get (
495  Objects_Information *information,
496  Objects_Id           id,
497  Objects_Locations   *location
498);
499
500Objects_Control *_Objects_Get_isr_disable(
501  Objects_Information *information,
502  Objects_Id           id,
503  Objects_Locations   *location,
504  ISR_Level           *level
505);
506
507Objects_Control *_Objects_Get_by_index (
508  Objects_Information *information,
509  Objects_Id           id,
510  Objects_Locations   *location
511);
512
513Objects_Control *_Objects_Get_no_protection(
514  Objects_Information *information,
515  Objects_Id           id,
516  Objects_Locations   *location
517);
518
519/*
520 *  _Objects_Get_next
521 *
522 *  DESCRIPTION:
523 *
524 *  Like _Objects_Get, but is used to find "next" open object.
525 *
526 */
527
528Objects_Control *_Objects_Get_next(
529    Objects_Information *information,
530    Objects_Id           id,
531    Objects_Locations   *location_p,
532    Objects_Id          *next_id_p
533);
534
535/*
536 *  Pieces of object.inl are promoted out to the user
537 */
538
539#include <rtems/score/object.inl>
540#if defined(RTEMS_MULTIPROCESSING)
541#include <rtems/score/objectmp.h>
542#endif
543
544#ifdef __cplusplus
545}
546#endif
547
548#endif
549/* end of include file */
Note: See TracBrowser for help on using the repository browser.