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

4.104.114.84.95
Last change on this file since dd687d97 was dd687d97, checked in by Joel Sherrill <joel.sherrill@…>, on 09/04/03 at 18:56:05

2003-09-04 Joel Sherrill <joel@…>

  • include/rtems/debug.h, include/rtems/seterr.h, include/rtems/system.h, include/rtems/score/address.h, include/rtems/score/apiext.h, include/rtems/score/apimutex.h, include/rtems/score/bitfield.h, include/rtems/score/chain.h, include/rtems/score/context.h, include/rtems/score/copyrt.h, include/rtems/score/coremsg.h, include/rtems/score/coremutex.h, include/rtems/score/coresem.h, include/rtems/score/heap.h, include/rtems/score/interr.h, include/rtems/score/isr.h, include/rtems/score/mpci.h, include/rtems/score/mppkt.h, include/rtems/score/object.h, include/rtems/score/objectmp.h, include/rtems/score/priority.h, include/rtems/score/stack.h, include/rtems/score/states.h, include/rtems/score/sysstate.h, include/rtems/score/thread.h, include/rtems/score/threadmp.h, include/rtems/score/threadq.h, include/rtems/score/tod.h, include/rtems/score/tqdata.h, include/rtems/score/userext.h, include/rtems/score/watchdog.h, include/rtems/score/wkspace.h, inline/rtems/score/address.inl, inline/rtems/score/chain.inl, inline/rtems/score/coremsg.inl, inline/rtems/score/coremutex.inl, inline/rtems/score/coresem.inl, inline/rtems/score/heap.inl, inline/rtems/score/isr.inl, inline/rtems/score/mppkt.inl, inline/rtems/score/object.inl, inline/rtems/score/objectmp.inl, inline/rtems/score/priority.inl, inline/rtems/score/stack.inl, inline/rtems/score/states.inl, inline/rtems/score/sysstate.inl, inline/rtems/score/thread.inl, inline/rtems/score/threadmp.inl, inline/rtems/score/tod.inl, inline/rtems/score/tqdata.inl, inline/rtems/score/userext.inl, inline/rtems/score/watchdog.inl, inline/rtems/score/wkspace.inl, macros/rtems/score/address.inl, macros/rtems/score/chain.inl, macros/rtems/score/coremsg.inl, macros/rtems/score/coremutex.inl, macros/rtems/score/coresem.inl, macros/rtems/score/heap.inl, macros/rtems/score/isr.inl, macros/rtems/score/mppkt.inl, macros/rtems/score/object.inl, macros/rtems/score/objectmp.inl, macros/rtems/score/priority.inl, macros/rtems/score/stack.inl, macros/rtems/score/states.inl, macros/rtems/score/sysstate.inl, macros/rtems/score/thread.inl, macros/rtems/score/threadmp.inl, macros/rtems/score/tod.inl, macros/rtems/score/tqdata.inl, macros/rtems/score/userext.inl, macros/rtems/score/watchdog.inl, macros/rtems/score/wkspace.inl, src/apiext.c, src/chain.c, src/coremsg.c, src/coremsgbroadcast.c, src/coremsgclose.c, src/coremsgflush.c, src/coremsgflushsupp.c, src/coremsgflushwait.c, src/coremsginsert.c, src/coremsgseize.c, src/coremsgsubmit.c, src/coremutex.c, src/coremutexflush.c, src/coremutexseize.c, src/coremutexsurrender.c, src/coresem.c, src/coresemflush.c, src/coresemseize.c, src/coresemsurrender.c, src/coretod.c, src/coretodset.c, src/coretodtickle.c, src/coretodtoseconds.c, src/coretodvalidate.c, src/heap.c, src/heapallocate.c, src/heapextend.c, src/heapfree.c, src/heapgetinfo.c, src/heapsizeofuserarea.c, src/heapwalk.c, src/interr.c, src/isr.c, src/iterateoverthreads.c, src/mpci.c, src/object.c, src/objectallocate.c, src/objectallocatebyindex.c, src/objectclearname.c, src/objectcomparenameraw.c, src/objectcomparenamestring.c, src/objectcopynameraw.c, src/objectcopynamestring.c, src/objectextendinformation.c, src/objectfree.c, src/objectget.c, src/objectgetbyindex.c, src/objectgetisr.c, src/objectgetnext.c, src/objectgetnoprotection.c, src/objectidtoname.c, src/objectinitializeinformation.c, src/objectmp.c, src/objectnametoid.c, src/objectshrinkinformation.c, src/thread.c, src/threadchangepriority.c, src/threadclearstate.c, src/threadclose.c, src/threadcreateidle.c, src/threaddelayended.c, src/threaddispatch.c, src/threadevaluatemode.c, src/threadget.c, src/threadhandler.c, src/threadidlebody.c, src/threadinitialize.c, src/threadloadenv.c, src/threadmp.c, src/threadq.c, src/threadqdequeue.c, src/threadqdequeuefifo.c, src/threadqdequeuepriority.c, src/threadqenqueue.c, src/threadqenqueuefifo.c, src/threadqenqueuepriority.c, src/threadqextract.c, src/threadqextractfifo.c, src/threadqextractpriority.c, src/threadqextractwithproxy.c, src/threadqfirst.c, src/threadqfirstfifo.c, src/threadqfirstpriority.c, src/threadqflush.c, src/threadqtimeout.c, src/threadready.c, src/threadreset.c, src/threadresettimeslice.c, src/threadrestart.c, src/threadresume.c, src/threadrotatequeue.c, src/threadsetpriority.c, src/threadsetstate.c, src/threadsettransient.c, src/threadstackallocate.c, src/threadstackfree.c, src/threadstart.c, src/threadstartmultitasking.c, src/threadsuspend.c, src/threadtickletimeslice.c, src/threadyieldprocessor.c, src/userext.c, src/watchdog.c, src/watchdogadjust.c, src/watchdoginsert.c, src/watchdogremove.c, src/watchdogtickle.c, src/wkspace.c: URL for license changed.
  • Property mode set to 100644
File size: 14.3 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/*
442 *  _Objects_Name_to_id
443 *
444 *  DESCRIPTION:
445 *
446 *  This function implements the common portion of the object
447 *  identification directives.  This directive returns the object
448 *  id associated with name.  If more than one object of this class
449 *  is named name, then the object to which the id belongs is
450 *  arbitrary.  Node indicates the extent of the search for the
451 *  id of the object named name.  If the object class supports global
452 *  objects, then the search can be limited to a particular node
453 *  or allowed to encompass all nodes.
454 *
455 */
456
457typedef enum {
458  OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL,
459  OBJECTS_INVALID_NAME,
460  OBJECTS_INVALID_ID,
461  OBJECTS_INVALID_NODE
462} Objects_Name_or_id_lookup_errors;
463
464#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL
465#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
466
467Objects_Name_or_id_lookup_errors _Objects_Name_to_id(
468  Objects_Information *information,
469  Objects_Name         name,
470  unsigned32           node,
471  Objects_Id          *id
472);
473
474/*
475 *  _Objects_Id_to_Name
476 *
477 *  DESCRIPTION:
478 *
479 *  This function implements the common portion of the object Id
480 *  to name directives.  This function returns the name
481 *  associated with object id. 
482 *
483 *  NOTE:
484 *
485 *  This function currently does not support string names.
486 */
487
488Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
489  Objects_Id      id,
490  Objects_Name   *name
491);
492
493/*
494 *  _Objects_Get
495 *
496 *  DESCRIPTION:
497 *
498 *  This function maps object ids to object control blocks.
499 *  If id corresponds to a local object, then it returns
500 *  the_object control pointer which maps to id and location
501 *  is set to OBJECTS_LOCAL.  If the object class supports global
502 *  objects and the object id is global and resides on a remote
503 *  node, then location is set to OBJECTS_REMOTE, and the_object
504 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
505 *  and the_object is undefined.
506 *
507 *  NOTE: _Objects_Get returns with dispatching disabled for
508 *        local and remote objects.
509 *        _Objects_Get_isr_disable returns with dispatching
510 *        disabled for remote objects and interrupts for local
511 *        objects.
512 */
513
514Objects_Control *_Objects_Get (
515  Objects_Information *information,
516  Objects_Id           id,
517  Objects_Locations   *location
518);
519
520Objects_Control *_Objects_Get_isr_disable(
521  Objects_Information *information,
522  Objects_Id           id,
523  Objects_Locations   *location,
524  ISR_Level           *level
525);
526
527Objects_Control *_Objects_Get_by_index (
528  Objects_Information *information,
529  Objects_Id           id,
530  Objects_Locations   *location
531);
532
533Objects_Control *_Objects_Get_no_protection(
534  Objects_Information *information,
535  Objects_Id           id,
536  Objects_Locations   *location
537);
538
539/*
540 *  _Objects_Get_next
541 *
542 *  DESCRIPTION:
543 *
544 *  Like _Objects_Get, but is used to find "next" open object.
545 *
546 */
547
548Objects_Control *_Objects_Get_next(
549    Objects_Information *information,
550    Objects_Id           id,
551    Objects_Locations   *location_p,
552    Objects_Id          *next_id_p
553);
554
555/*
556 *  Pieces of object.inl are promoted out to the user
557 */
558
559#include <rtems/score/object.inl>
560#if defined(RTEMS_MULTIPROCESSING)
561#include <rtems/score/objectmp.h>
562#endif
563
564#ifdef __cplusplus
565}
566#endif
567
568#endif
569/* end of include file */
Note: See TracBrowser for help on using the repository browser.