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

4.104.114.84.95
Last change on this file since ef9505a9 was ef9505a9, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 1, 2002 at 10:30:12 PM

2002-07-01 Joel Sherrill <joel@…>

  • Mega patch merge to change the format of the object IDs to loosen the dependency between the SCORE and the various APIs. There was considerable work to simplify the object name management and it appears that the name_table field is no longer needed. This patch also includes the addition of the internal mutex which is currently only used to protect some types of allocation and deallocation. This significantly can reduce context switch latency under certain circumstances. In particular, some heap/region operations were O(n) and had dispatching disabled. This should help enormously. With this merge, the patch is not as clean as it should be. In particular, the documentation has not been modified to reflect the new object ID layout, the IDs in the test screens are not updated, and _Objects_Get_information needs to be a real routine not inlined. As part of this patch a lot of MP code for thread/proxy blocking was made conditional and cleaned up.
  • include/Makefile.am, include/rtems/score/coremsg.h, include/rtems/score/coremutex.h, include/rtems/score/coresem.h, include/rtems/score/object.h, include/rtems/score/threadq.h, inline/rtems/score/object.inl, inline/rtems/score/thread.inl, macros/rtems/score/object.inl, src/Makefile.am, src/coremsg.c, src/coremutex.c, src/coresem.c, src/mpci.c, src/objectcomparenameraw.c, src/objectextendinformation.c, src/objectinitializeinformation.c, src/objectnametoid.c, src/thread.c, src/threadclose.c, src/threadget.c, src/threadq.c, src/threadqextractwithproxy.c: Modified as part of above.
  • include/rtems/score/apimutex.h, src/objectgetnoprotection.c: New files.
  • Property mode set to 100644
File size: 13.7 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.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#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      0x0000ffff
78#define OBJECTS_NODE_MASK       0x00ff0000
79#define OBJECTS_API_MASK        0x07000000
80#define OBJECTS_CLASS_MASK      0xf8000000
81
82#define OBJECTS_INDEX_VALID_BITS  0x0000ffff
83#define OBJECTS_NODE_VALID_BITS   0x000000ff
84#define OBJECTS_API_VALID_BITS    0x00000007
85#define OBJECTS_CLASS_VALID_BITS  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_NODE
460} Objects_Name_to_id_errors;
461
462#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_SUCCESSFUL
463#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
464
465Objects_Name_to_id_errors _Objects_Name_to_id(
466  Objects_Information *information,
467  Objects_Name         name,
468  unsigned32           node,
469  Objects_Id          *id
470);
471
472/*
473 *  _Objects_Get
474 *
475 *  DESCRIPTION:
476 *
477 *  This function maps object ids to object control blocks.
478 *  If id corresponds to a local object, then it returns
479 *  the_object control pointer which maps to id and location
480 *  is set to OBJECTS_LOCAL.  If the object class supports global
481 *  objects and the object id is global and resides on a remote
482 *  node, then location is set to OBJECTS_REMOTE, and the_object
483 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
484 *  and the_object is undefined.
485 *
486 *  NOTE: _Objects_Get returns with dispatching disabled for
487 *        local and remote objects.
488 *        _Objects_Get_isr_disable returns with dispatching
489 *        disabled for remote objects and interrupts for local
490 *        objects.
491 */
492
493Objects_Control *_Objects_Get (
494  Objects_Information *information,
495  Objects_Id           id,
496  Objects_Locations   *location
497);
498
499Objects_Control *_Objects_Get_isr_disable(
500  Objects_Information *information,
501  Objects_Id           id,
502  Objects_Locations   *location,
503  ISR_Level           *level
504);
505
506Objects_Control *_Objects_Get_by_index (
507  Objects_Information *information,
508  Objects_Id           id,
509  Objects_Locations   *location
510);
511
512Objects_Control *_Objects_Get_no_protection(
513  Objects_Information *information,
514  Objects_Id           id,
515  Objects_Locations   *location
516);
517
518/*
519 *  _Objects_Get_next
520 *
521 *  DESCRIPTION:
522 *
523 *  Like _Objects_Get, but is used to find "next" open object.
524 *
525 */
526
527Objects_Control *_Objects_Get_next(
528    Objects_Information *information,
529    Objects_Id           id,
530    Objects_Locations   *location_p,
531    Objects_Id          *next_id_p
532);
533
534/*
535 *  Pieces of object.inl are promoted out to the user
536 */
537
538#include <rtems/score/object.inl>
539#if defined(RTEMS_MULTIPROCESSING)
540#include <rtems/score/objectmp.h>
541#endif
542
543#ifdef __cplusplus
544}
545#endif
546
547#endif
548/* end of include file */
Note: See TracBrowser for help on using the repository browser.