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

Last change on this file since 7038271 was 7038271, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 25, 2018 at 10:05:53 AM

Remove RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES

Enable support for string objects names unconditionally. Add const
qualifier throughout. Split _Objects_Namespace_remove() into
_Objects_Namespace_remove_u32() and _Objects_Namespace_remove_string()
to avoid an unnecessary dependency on _Workspace_Free().

Update #2514.

  • Property mode set to 100644
File size: 11.7 KB
Line 
1/**
2 * @file  rtems/score/object.h
3 *
4 * @brief Constants and Structures Associated with the Object Handler
5 *
6 * This include file contains all the constants and structures associated
7 * with the Object Handler.  This Handler provides mechanisms which
8 * can be used to initialize and manipulate all objects which have ids.
9 */
10
11/*
12 *  COPYRIGHT (c) 1989-2011.
13 *  On-Line Applications Research Corporation (OAR).
14 *
15 *  The license and distribution terms for this file may be
16 *  found in the file LICENSE in this distribution or at
17 *  http://www.rtems.org/license/LICENSE.
18 */
19
20#ifndef _RTEMS_SCORE_OBJECT_H
21#define _RTEMS_SCORE_OBJECT_H
22
23#include <rtems/score/basedefs.h>
24#include <rtems/score/cpu.h>
25#include <rtems/score/chain.h>
26#include <rtems/score/rbtree.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/**
33 * @defgroup Score SuperCore
34 *
35 * @brief Provides services for all APIs.
36 */
37/**@{*/
38
39/**
40 * @defgroup ScoreCPU CPU Architecture Support
41 *
42 * @ingroup Score
43 *
44 * @brief Provides CPU architecture dependent services.
45 */
46/**@{*/
47
48/**
49 *  @defgroup ScoreObject Object Handler
50 *
51 *  @ingroup Score
52 */
53/**@{*/
54
55/**
56 *  The following type defines the control block used to manage
57 *  object names.
58 */
59typedef union {
60  /** This is a pointer to a string name. */
61  const char *name_p;
62  /** This is the actual 32-bit "raw" integer name. */
63  uint32_t    name_u32;
64} Objects_Name;
65
66#if defined(RTEMS_USE_16_BIT_OBJECT)
67/**
68 *  The following type defines the control block used to manage
69 *  object IDs.  The format is as follows (0=LSB):
70 *
71 *     Bits  0 ..  7    = index  (up to 254 objects of a type)
72 *     Bits  8 .. 10    = API    (up to 7 API classes)
73 *     Bits 11 .. 15    = class  (up to 31 object types per API)
74 */
75typedef uint16_t   Objects_Id;
76
77/**
78 * This type is used to store the maximum number of allowed objects
79 * of each type.
80 */
81typedef uint8_t    Objects_Maximum;
82
83#define OBJECTS_INDEX_START_BIT  0U
84#define OBJECTS_API_START_BIT    8U
85#define OBJECTS_CLASS_START_BIT 11U
86
87#define OBJECTS_INDEX_MASK      (Objects_Id)0x00ffU
88#define OBJECTS_API_MASK        (Objects_Id)0x0700U
89#define OBJECTS_CLASS_MASK      (Objects_Id)0xF800U
90
91#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x00ffU
92#define OBJECTS_API_VALID_BITS    (Objects_Id)0x0007U
93/* OBJECTS_NODE_VALID_BITS should not be used with 16 bit Ids */
94#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x001fU
95
96#define OBJECTS_UNLIMITED_OBJECTS 0x8000U
97
98#define OBJECTS_ID_INITIAL_INDEX  (0)
99#define OBJECTS_ID_FINAL_INDEX    (0xff)
100
101#else
102/**
103 *  The following type defines the control block used to manage
104 *  object IDs.  The format is as follows (0=LSB):
105 *
106 *     Bits  0 .. 15    = index  (up to 65535 objects of a type)
107 *     Bits 16 .. 23    = node   (up to 255 nodes)
108 *     Bits 24 .. 26    = API    (up to 7 API classes)
109 *     Bits 27 .. 31    = class  (up to 31 object types per API)
110 */
111typedef uint32_t   Objects_Id;
112
113/**
114 * This type is used to store the maximum number of allowed objects
115 * of each type.
116 */
117typedef uint16_t   Objects_Maximum;
118
119/**
120 *  This is the bit position of the starting bit of the index portion of
121 *  the object Id.
122 */
123#define OBJECTS_INDEX_START_BIT  0U
124/**
125 *  This is the bit position of the starting bit of the node portion of
126 *  the object Id.
127 */
128#define OBJECTS_NODE_START_BIT  16U
129
130/**
131 *  This is the bit position of the starting bit of the API portion of
132 *  the object Id.
133 */
134#define OBJECTS_API_START_BIT   24U
135
136/**
137 *  This is the bit position of the starting bit of the class portion of
138 *  the object Id.
139 */
140#define OBJECTS_CLASS_START_BIT 27U
141
142/**
143 *  This mask is used to extract the index portion of an object Id.
144 */
145#define OBJECTS_INDEX_MASK      (Objects_Id)0x0000ffffU
146
147/**
148 *  This mask is used to extract the node portion of an object Id.
149 */
150#define OBJECTS_NODE_MASK       (Objects_Id)0x00ff0000U
151
152/**
153 *  This mask is used to extract the API portion of an object Id.
154 */
155#define OBJECTS_API_MASK        (Objects_Id)0x07000000U
156
157/**
158 *  This mask is used to extract the class portion of an object Id.
159 */
160#define OBJECTS_CLASS_MASK      (Objects_Id)0xf8000000U
161
162/**
163 *  This mask represents the bits that is used to ensure no extra bits
164 *  are set after shifting to extract the index portion of an object Id.
165 */
166#define OBJECTS_INDEX_VALID_BITS  (Objects_Id)0x0000ffffU
167
168/**
169 *  This mask represents the bits that is used to ensure no extra bits
170 *  are set after shifting to extract the node portion of an object Id.
171 */
172#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ffU
173
174/**
175 *  This mask represents the bits that is used to ensure no extra bits
176 *  are set after shifting to extract the API portion of an object Id.
177 */
178#define OBJECTS_API_VALID_BITS    (Objects_Id)0x00000007U
179
180/**
181 *  This mask represents the bits that is used to ensure no extra bits
182 *  are set after shifting to extract the class portion of an object Id.
183 */
184#define OBJECTS_CLASS_VALID_BITS  (Objects_Id)0x0000001fU
185
186/**
187 *  Mask to enable unlimited objects.  This is used in the configuration
188 *  table when specifying the number of configured objects.
189 */
190#define OBJECTS_UNLIMITED_OBJECTS 0x80000000U
191
192/**
193 *  This is the lowest value for the index portion of an object Id.
194 */
195#define OBJECTS_ID_INITIAL_INDEX  (0)
196
197/**
198 *  This is the highest value for the index portion of an object Id.
199 */
200#define OBJECTS_ID_FINAL_INDEX    (0xffffU)
201#endif
202
203/**
204 *  This enumerated type is used in the class field of the object ID.
205 */
206typedef enum {
207  OBJECTS_NO_API       = 0,
208  OBJECTS_INTERNAL_API = 1,
209  OBJECTS_CLASSIC_API  = 2,
210  OBJECTS_POSIX_API    = 3,
211  OBJECTS_FAKE_OBJECTS_API = 7
212} Objects_APIs;
213
214/** This macro is used to generically specify the last API index. */
215#define OBJECTS_APIS_LAST OBJECTS_POSIX_API
216
217/**
218 *  The following defines the Object Control Block used to manage
219 *  each object local to this node.
220 */
221typedef struct {
222  /** This is the chain node portion of an object. */
223  Chain_Node     Node;
224  /** This is the object's ID. */
225  Objects_Id     id;
226  /** This is the object's name. */
227  Objects_Name   name;
228} Objects_Control;
229
230#if defined( RTEMS_MULTIPROCESSING )
231/**
232 * @brief This defines the Global Object Control Block used to manage objects
233 * resident on other nodes.
234 */
235typedef struct {
236  /**
237   * @brief Nodes to manage active and inactive global objects.
238   */
239  union {
240    /**
241     * @brief Inactive global objects reside on a chain.
242     */
243    Chain_Node Inactive;
244
245    struct {
246      /**
247       * @brief Node to lookup an active global object by identifier.
248       */
249      RBTree_Node Id_lookup;
250
251      /**
252       * @brief Node to lookup an active global object by name.
253       */
254      RBTree_Node Name_lookup;
255    } Active;
256  } Nodes;
257
258  /**
259   * @brief The global object identifier.
260   */
261  Objects_Id id;
262
263  /**
264   * @brief The global object name.
265   *
266   * Using an unsigned thirty two bit value is broken but works.  If any API is
267   * MP with variable length names .. BOOM!!!!
268   */
269  uint32_t name;
270} Objects_MP_Control;
271#endif
272
273/**
274 *  No object can have this ID.
275 */
276#define OBJECTS_ID_NONE 0
277
278/**
279 *  The following defines the constant which may be used
280 *  to manipulate the calling task.
281 */
282#define OBJECTS_ID_OF_SELF ((Objects_Id) 0)
283
284/**
285 *  The following constant is used to specify that a name to ID search
286 *  should search through all nodes.
287 */
288#define OBJECTS_SEARCH_ALL_NODES   0
289
290/**
291 *  The following constant is used to specify that a name to ID search
292 *  should search through all nodes except the current node.
293 */
294#define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE
295
296/**
297 *  The following constant is used to specify that a name to ID search
298 *  should search only on this node.
299 */
300#define OBJECTS_SEARCH_LOCAL_NODE  0x7FFFFFFF
301
302/**
303 *  The following constant is used to specify that a name to ID search
304 *  is being asked for the ID of the currently executing task.
305 */
306#define OBJECTS_WHO_AM_I           0
307
308/**
309 *  This macros calculates the lowest ID for the specified api, class,
310 *  and node.
311 */
312#define OBJECTS_ID_INITIAL(_api, _class, _node) \
313  _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
314
315/**
316 *  This macro specifies the highest object ID value
317 */
318#define OBJECTS_ID_FINAL           ((Objects_Id)~0)
319
320/**
321 *  This macro is used to build a thirty-two bit style name from
322 *  four characters.  The most significant byte will be the
323 *  character @a _C1.
324 *
325 *  @param[in] _C1 is the first character of the name
326 *  @param[in] _C2 is the second character of the name
327 *  @param[in] _C3 is the third character of the name
328 *  @param[in] _C4 is the fourth character of the name
329 */
330#define  _Objects_Build_name( _C1, _C2, _C3, _C4 ) \
331  ( (uint32_t)(_C1) << 24 | \
332    (uint32_t)(_C2) << 16 | \
333    (uint32_t)(_C3) << 8 | \
334    (uint32_t)(_C4) )
335
336/**
337 * This function returns the API portion of the ID.
338 *
339 * @param[in] id is the object Id to be processed.
340 *
341 * @return This method returns an object Id constructed from the arguments.
342 */
343RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API(
344  Objects_Id id
345)
346{
347  return (Objects_APIs) ((id >> OBJECTS_API_START_BIT) & OBJECTS_API_VALID_BITS);
348}
349
350/**
351 * This function returns the class portion of the ID.
352 *
353 * @param[in] id is the object Id to be processed
354 */
355RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class(
356  Objects_Id id
357)
358{
359  return (uint32_t)
360    ((id >> OBJECTS_CLASS_START_BIT) & OBJECTS_CLASS_VALID_BITS);
361}
362
363/**
364 * This function returns the node portion of the ID.
365 *
366 * @param[in] id is the object Id to be processed
367 *
368 * @return This method returns the node portion of an object ID.
369 */
370RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node(
371  Objects_Id id
372)
373{
374  /*
375   * If using 16-bit Ids, then there is no node field and it MUST
376   * be a single processor system.
377   */
378  #if defined(RTEMS_USE_16_BIT_OBJECT)
379    return 1;
380  #else
381    return (id >> OBJECTS_NODE_START_BIT) & OBJECTS_NODE_VALID_BITS;
382  #endif
383}
384
385/**
386 * This function returns the index portion of the ID.
387 *
388 * @param[in] id is the Id to be processed
389 *
390 * @return This method returns the class portion of the specified object ID.
391 */
392RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Get_index(
393  Objects_Id id
394)
395{
396  return
397    (Objects_Maximum)((id >> OBJECTS_INDEX_START_BIT) &
398                                          OBJECTS_INDEX_VALID_BITS);
399}
400
401/**
402 * This function builds an object's id from the processor node and index
403 * values specified.
404 *
405 * @param[in] the_api indicates the API associated with this Id.
406 * @param[in] the_class indicates the class of object.
407 *            It is specific to @a the_api.
408 * @param[in] node is the node where this object resides.
409 * @param[in] index is the instance number of this object.
410 *
411 * @return This method returns an object Id constructed from the arguments.
412 */
413RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id(
414  Objects_APIs     the_api,
415  uint16_t         the_class,
416  uint8_t          node,
417  uint16_t         index
418)
419{
420  return (( (Objects_Id) the_api )   << OBJECTS_API_START_BIT)   |
421         (( (Objects_Id) the_class ) << OBJECTS_CLASS_START_BIT) |
422         #if !defined(RTEMS_USE_16_BIT_OBJECT)
423           (( (Objects_Id) node )    << OBJECTS_NODE_START_BIT)  |
424         #endif
425         (( (Objects_Id) index )     << OBJECTS_INDEX_START_BIT);
426}
427
428/**
429 * Returns if the object maximum specifies unlimited objects.
430 *
431 * @param[in] maximum The object maximum specification.
432 *
433 * @retval true Unlimited objects are available.
434 * @retval false The object count is fixed.
435 */
436RTEMS_INLINE_ROUTINE bool _Objects_Is_unlimited( uint32_t maximum )
437{
438  return (maximum & OBJECTS_UNLIMITED_OBJECTS) != 0;
439}
440
441/*
442 * We cannot use an inline function for this since it may be evaluated at
443 * compile time.
444 */
445#define _Objects_Maximum_per_allocation( maximum ) \
446  ((Objects_Maximum) ((maximum) & ~OBJECTS_UNLIMITED_OBJECTS))
447
448/**@}*/
449/**@}*/
450/**@}*/
451
452#ifdef __cplusplus
453}
454#endif
455
456#endif
457/* end of include file */
Note: See TracBrowser for help on using the repository browser.