source: rtems/cpukit/include/rtems/score/objectimpl.h @ 2afb22b

Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 29.4 KB
Line 
1/**
2 * @file
3 *
4 * @brief Inlined Routines in the Object Handler
5 *
6 * This include file contains the static inline implementation of all
7 * of the inlined routines in the Object Handler.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2011.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.org/license/LICENSE.
17 */
18
19#ifndef _RTEMS_SCORE_OBJECTIMPL_H
20#define _RTEMS_SCORE_OBJECTIMPL_H
21
22#include <rtems/score/object.h>
23#include <rtems/score/apimutex.h>
24#include <rtems/score/isrlock.h>
25#include <rtems/score/threaddispatch.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31/**
32 * @addtogroup ScoreObject
33 *
34 * @{
35 */
36
37/**
38 *  Functions which compare names are prototyped like this.
39 */
40typedef bool    (*Objects_Name_comparators)(
41  void       * /* name_1 */,
42  void       * /* name_2 */,
43  uint16_t     /* length */
44);
45
46/**
47 *  This enumerated type is used in the class field of the object ID
48 *  for RTEMS internal object classes.
49 */
50typedef enum {
51  OBJECTS_INTERNAL_NO_CLASS =  0,
52  OBJECTS_INTERNAL_THREADS  =  1
53} Objects_Internal_API;
54
55/** This macro is used to generically specify the last API index. */
56#define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_THREADS
57
58/**
59 *  This enumerated type is used in the class field of the object ID
60 *  for the RTEMS Classic API.
61 */
62typedef enum {
63  OBJECTS_CLASSIC_NO_CLASS     = 0,
64  OBJECTS_RTEMS_TASKS          = 1,
65  OBJECTS_RTEMS_TIMERS         = 2,
66  OBJECTS_RTEMS_SEMAPHORES     = 3,
67  OBJECTS_RTEMS_MESSAGE_QUEUES = 4,
68  OBJECTS_RTEMS_PARTITIONS     = 5,
69  OBJECTS_RTEMS_REGIONS        = 6,
70  OBJECTS_RTEMS_PORTS          = 7,
71  OBJECTS_RTEMS_PERIODS        = 8,
72  OBJECTS_RTEMS_EXTENSIONS     = 9,
73  OBJECTS_RTEMS_BARRIERS       = 10
74} Objects_Classic_API;
75
76/** This macro is used to generically specify the last API index. */
77#define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_BARRIERS
78
79/**
80 *  This enumerated type is used in the class field of the object ID
81 *  for the POSIX API.
82 */
83typedef enum {
84  OBJECTS_POSIX_NO_CLASS            = 0,
85  OBJECTS_POSIX_THREADS             = 1,
86  OBJECTS_POSIX_KEYS                = 2,
87  OBJECTS_POSIX_INTERRUPTS          = 3,
88  OBJECTS_POSIX_MESSAGE_QUEUES      = 5,
89  OBJECTS_POSIX_SEMAPHORES          = 7,
90  OBJECTS_POSIX_TIMERS              = 9,
91  OBJECTS_POSIX_SHMS                = 12
92} Objects_POSIX_API;
93
94/** This macro is used to generically specify the last API index. */
95#define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_SHMS
96
97/*
98 * For fake objects, which have an object identifier, but no objects
99 * information block.
100 */
101typedef enum {
102  OBJECTS_FAKE_OBJECTS_NO_CLASS   = 0,
103  OBJECTS_FAKE_OBJECTS_SCHEDULERS = 1
104} Objects_Fake_objects_API;
105
106#if defined(RTEMS_MULTIPROCESSING)
107/**
108 *  The following type defines the callout used when a local task
109 *  is extracted from a remote thread queue (i.e. it's proxy must
110 *  extracted from the remote queue).
111 */
112typedef void ( *Objects_Thread_queue_Extract_callout )(
113  Thread_Control *,
114  Objects_Id
115);
116#endif
117
118/**
119 *  The following defines the structure for the information used to
120 *  manage each class of objects.
121 */
122typedef struct {
123  /** This field indicates the API of this object class. */
124  Objects_APIs      the_api;
125  /** This is the class of this object set. */
126  uint16_t          the_class;
127  /** This is the minimum valid id of this object class. */
128  Objects_Id        minimum_id;
129  /** This is the maximum valid id of this object class. */
130  Objects_Id        maximum_id;
131  /** This is the maximum number of objects in this class. */
132  Objects_Maximum   maximum;
133  /** This is the true if unlimited objects in this class. */
134  bool              auto_extend;
135  /** This is the number of objects in a block. */
136  Objects_Maximum   allocation_size;
137  /** This is the size in bytes of each object instance. */
138  size_t            size;
139  /** This points to the table of local objects. */
140  Objects_Control **local_table;
141  /** This is the chain of inactive control blocks. */
142  Chain_Control     Inactive;
143  /** This is the number of objects on the Inactive list. */
144  Objects_Maximum   inactive;
145  /** This is the number of inactive objects per block. */
146  uint32_t         *inactive_per_block;
147  /** This is a table to the chain of inactive object memory blocks. */
148  void            **object_blocks;
149  #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES)
150    /** This is true if names are strings. */
151    bool              is_string;
152  #endif
153  /** This is the maximum length of names. */
154  uint16_t          name_length;
155  #if defined(RTEMS_MULTIPROCESSING)
156    /** This is this object class' method called when extracting a thread. */
157    Objects_Thread_queue_Extract_callout extract;
158
159    /**
160     * @brief The global objects of this object information sorted by object
161     * identifier.
162     */
163    RBTree_Control   Global_by_id;
164
165    /**
166     * @brief The global objects of this object information sorted by object
167     * name.
168     *
169     * Objects with the same name are sorted according to their identifier.
170     */
171    RBTree_Control   Global_by_name;
172  #endif
173}   Objects_Information;
174
175/**
176 *  The following is referenced to the node number of the local node.
177 */
178#if defined(RTEMS_MULTIPROCESSING)
179extern uint16_t _Objects_Local_node;
180#else
181#define _Objects_Local_node ((uint16_t)1)
182#endif
183
184/**
185 *  The following is referenced to the number of nodes in the system.
186 */
187#if defined(RTEMS_MULTIPROCESSING)
188extern uint16_t _Objects_Maximum_nodes;
189#else
190#define _Objects_Maximum_nodes 1
191#endif
192
193/**
194 *  The following is the list of information blocks per API for each object
195 *  class.  From the ID, we can go to one of these information blocks,
196 *  and obtain a pointer to the appropriate object control block.
197 */
198extern Objects_Information ** const
199_Objects_Information_table[ OBJECTS_APIS_LAST + 1 ];
200
201/**
202 *  This function extends an object class information record.
203 *
204 *  @param[in] information points to an object class information block.
205 */
206void _Objects_Extend_information(
207  Objects_Information *information
208);
209
210/**
211 *  @brief Shrink an object class information record
212 *
213 *  This function shrink an object class information record.
214 *  The object's name and object space are released. The local_table
215 *  etc block does not shrink. The InActive list needs to be scanned
216 *  to find the objects are remove them.
217 *
218 *  @param[in] information points to an object class information block.
219 */
220void _Objects_Shrink_information(
221  Objects_Information *information
222);
223
224void _Objects_Do_initialize_information(
225  Objects_Information *information,
226  Objects_APIs         the_api,
227  uint16_t             the_class,
228  uint32_t             maximum,
229  uint16_t             size,
230  bool                 is_string,
231  uint32_t             maximum_name_length
232#if defined(RTEMS_MULTIPROCESSING)
233  ,
234  Objects_Thread_queue_Extract_callout extract
235#endif
236);
237
238/**
239 *  @brief Initialize object Information
240 *
241 *  This function initializes an object class information record.
242 *  SUPPORTS_GLOBAL is true if the object class supports global
243 *  objects, and false otherwise.  Maximum indicates the number
244 *  of objects required in this class and size indicates the size
245 *  in bytes of each control block for this object class.  The
246 *  name length and string designator are also set.  In addition,
247 *  the class may be a task, therefore this information is also included.
248 *
249 *  @param[in] information points to an object class information block.
250 *  @param[in] the_api indicates the API associated with this information block.
251 *  @param[in] the_class indicates the class of object being managed
252 *             by this information block.  It is specific to @a the_api.
253 *  @param[in] maximum is the maximum number of instances of this object
254 *             class which may be concurrently active.
255 *  @param[in] size is the size of the data structure for this class.
256 *  @param[in] is_string is true if this object uses string style names.
257 *  @param[in] maximum_name_length is the maximum length of object names.
258 */
259#if defined(RTEMS_MULTIPROCESSING)
260  #define _Objects_Initialize_information( \
261    information, \
262    the_api, \
263    the_class, \
264    maximum, \
265    size, \
266    is_string, \
267    maximum_name_length, \
268    extract \
269  ) \
270    _Objects_Do_initialize_information( \
271      information, \
272      the_api, \
273      the_class, \
274      maximum, \
275      size, \
276      is_string, \
277      maximum_name_length, \
278      extract \
279    )
280#else
281  #define _Objects_Initialize_information( \
282    information, \
283    the_api, \
284    the_class, \
285    maximum, \
286    size, \
287    is_string, \
288    maximum_name_length, \
289    extract \
290  ) \
291    _Objects_Do_initialize_information( \
292      information, \
293      the_api, \
294      the_class, \
295      maximum, \
296      size, \
297      is_string, \
298      maximum_name_length \
299    )
300#endif
301
302/**
303 *  @brief Object API Maximum Class
304 *
305 *  This function returns the highest numeric value of a valid
306 *  API for the specified @a api.
307 *
308 *  @param[in] api is the API of interest
309 *
310 *  @retval A positive integer on success and 0 otherwise.
311 */
312unsigned int _Objects_API_maximum_class(
313  uint32_t api
314);
315
316/**
317 * @brief Allocates an object without locking the allocator mutex.
318 *
319 * This function can be called in two contexts
320 * - the executing thread is the owner of the object allocator mutex, or
321 * - in case the system state is not up, e.g. during sequential system
322 *   initialization.
323 *
324 * @param[in] information The object information block.
325 *
326 * @retval NULL No object available.
327 * @retval object The allocated object.
328 *
329 * @see _Objects_Allocate() and _Objects_Free().
330 */
331Objects_Control *_Objects_Allocate_unprotected(
332  Objects_Information *information
333);
334
335/**
336 * @brief Allocates an object.
337 *
338 * This function locks the object allocator mutex via
339 * _Objects_Allocator_lock().  The caller must later unlock the object
340 * allocator mutex via _Objects_Allocator_unlock().  The caller must unlock the
341 * mutex in any case, even if the allocation failed due to resource shortage.
342 *
343 * A typical object allocation code looks like this:
344 * @code
345 * rtems_status_code some_create( rtems_id *id )
346 * {
347 *   rtems_status_code  sc;
348 *   Some_Control      *some;
349 *
350 *   // The object allocator mutex protects the executing thread from
351 *   // asynchronous thread restart and deletion.
352 *   some = (Some_Control *) _Objects_Allocate( &_Some_Information );
353 *
354 *   if ( some != NULL ) {
355 *     _Some_Initialize( some );
356 *     sc = RTEMS_SUCCESSFUL;
357 *   } else {
358 *     sc = RTEMS_TOO_MANY;
359 *   }
360 *
361 *   _Objects_Allocator_unlock();
362 *
363 *   return sc;
364 * }
365 * @endcode
366 *
367 * @param[in] information The object information block.
368 *
369 * @retval NULL No object available.
370 * @retval object The allocated object.
371 *
372 * @see _Objects_Free().
373 */
374Objects_Control *_Objects_Allocate( Objects_Information *information );
375
376/**
377 * @brief Frees an object.
378 *
379 * Appends the object to the chain of inactive objects.
380 *
381 * @param[in] information The object information block.
382 * @param[in] the_object The object to free.
383 *
384 * @see _Objects_Allocate().
385 *
386 * A typical object deletion code looks like this:
387 * @code
388 * rtems_status_code some_delete( rtems_id id )
389 * {
390 *   Some_Control      *some;
391 *
392 *   // The object allocator mutex protects the executing thread from
393 *   // asynchronous thread restart and deletion.
394 *   _Objects_Allocator_lock();
395 *
396 *   // Get the object under protection of the object allocator mutex.
397 *   some = (Semaphore_Control *)
398 *     _Objects_Get_no_protection( id, &_Some_Information );
399 *
400 *   if ( some == NULL ) {
401 *     _Objects_Allocator_unlock();
402 *     return RTEMS_INVALID_ID;
403 *   }
404 *
405 *   // After the object close an object get with this identifier will
406 *   // fail.
407 *   _Objects_Close( &_Some_Information, &some->Object );
408 *
409 *   _Some_Delete( some );
410 *
411 *   // Thread dispatching is enabled.  The object free is only protected
412 *   // by the object allocator mutex.
413 *   _Objects_Free( &_Some_Information, &some->Object );
414 *
415 *   _Objects_Allocator_unlock();
416 *   return RTEMS_SUCCESSFUL;
417 * }
418 * @endcode
419 */
420void _Objects_Free(
421  Objects_Information *information,
422  Objects_Control     *the_object
423);
424
425/**
426 *  This function implements the common portion of the object
427 *  identification directives.  This directive returns the object
428 *  id associated with name.  If more than one object of this class
429 *  is named name, then the object to which the id belongs is
430 *  arbitrary.  Node indicates the extent of the search for the
431 *  id of the object named name.  If the object class supports global
432 *  objects, then the search can be limited to a particular node
433 *  or allowed to encompass all nodes.
434 */
435typedef enum {
436  OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL,
437  OBJECTS_INVALID_NAME,
438  OBJECTS_INVALID_ADDRESS,
439  OBJECTS_INVALID_ID,
440  OBJECTS_INVALID_NODE
441} Objects_Name_or_id_lookup_errors;
442
443/**
444 *  This macro defines the first entry in the
445 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
446 */
447#define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL
448
449/**
450 *  This macro defines the last entry in the
451 *  @ref Objects_Name_or_id_lookup_errors enumerated list.
452 */
453#define OBJECTS_NAME_ERRORS_LAST  OBJECTS_INVALID_NODE
454
455/**
456 *  @brief Converts an object name to an Id.
457 *
458 *  This method converts an object name to an Id.  It performs a look up
459 *  using the object information block for this object class.
460 *
461 *  @param[in] information points to an object class information block.
462 *  @param[in] name is the name of the object to find.
463 *  @param[in] node is the set of nodes to search.
464 *  @param[in] id will contain the Id if the search is successful.
465 *
466 *  @retval This method returns one of the values from the
467 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
468 *          successful or failure.  On success @a id will contain the Id of
469 *          the requested object.
470 */
471Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32(
472  Objects_Information *information,
473  uint32_t             name,
474  uint32_t             node,
475  Objects_Id          *id
476);
477
478typedef enum {
479  OBJECTS_GET_BY_NAME_INVALID_NAME,
480  OBJECTS_GET_BY_NAME_NAME_TOO_LONG,
481  OBJECTS_GET_BY_NAME_NO_OBJECT
482} Objects_Get_by_name_error;
483
484/**
485 * @brief Gets an object control block identified by its name.
486 *
487 * The object information must use string names.
488 *
489 * @param information The object information.  Must not be NULL.
490 * @param name The object name.
491 * @param name_length_p Optional parameter to return the name length.
492 * @param error The error indication in case of failure.  Must not be NULL.
493 *
494 * @retval NULL No object exists for this name or invalid parameters.
495 * @retval other The first object according to object index associated with
496 * this name.
497 */
498Objects_Control *_Objects_Get_by_name(
499  const Objects_Information *information,
500  const char                *name,
501  size_t                    *name_length_p,
502  Objects_Get_by_name_error *error
503);
504
505/**
506 *  @brief Implements the common portion of the object Id to name directives.
507 *
508 *  This function implements the common portion of the object Id
509 *  to name directives.  This function returns the name
510 *  associated with object id.
511 *
512 *  @param[in] id is the Id of the object whose name we are locating.
513 *  @param[in] name will contain the name of the object, if found.
514 *
515 *  @retval This method returns one of the values from the
516 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
517 *          successful or failure.  On success @a name will contain the name of
518 *          the requested object.
519 *
520 *  @note This function currently does not support string names.
521 */
522Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
523  Objects_Id      id,
524  Objects_Name   *name
525);
526
527/**
528 * @brief Maps the specified object identifier to the associated local object
529 * control block.
530 *
531 * In this function interrupts are disabled during the object lookup.  In case
532 * an associated object exists, then interrupts remain disabled, otherwise the
533 * previous interrupt state is restored.
534 *
535 * @param id The object identifier.  This is the first parameter since usual
536 *   callers get the object identifier as the first parameter themself.
537 * @param lock_context The interrupt lock context.  This is the second
538 *   parameter since usual callers get the interrupt lock context as the second
539 *   parameter themself.
540 * @param information The object class information block.
541 *
542 * @retval NULL No associated object exists.
543 * @retval other The pointer to the associated object control block.
544 * Interrupts are now disabled and must be restored using the specified lock
545 * context via _ISR_lock_ISR_enable() or _ISR_lock_Release_and_ISR_enable().
546 */
547Objects_Control *_Objects_Get(
548  Objects_Id                 id,
549  ISR_lock_Context          *lock_context,
550  const Objects_Information *information
551);
552
553/**
554 *  @brief  Maps object ids to object control blocks.
555 *
556 *  This function maps object ids to object control blocks.
557 *  If id corresponds to a local object, then it returns
558 *  the_object control pointer which maps to id and location
559 *  is set to OBJECTS_LOCAL.  If the object class supports global
560 *  objects and the object id is global and resides on a remote
561 *  node, then location is set to OBJECTS_REMOTE, and the_object
562 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
563 *  and the_object is undefined.
564 *
565 *  @param[in] id is the Id of the object whose name we are locating.
566 *    This is the first parameter since usual callers get the object identifier
567 *    as the first parameter themself.
568 *  @param[in] information points to an object class information block.
569 *
570 *  @retval This method returns one of the values from the
571 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
572 *          successful or failure.  On success @a id will contain the Id of
573 *          the requested object.
574 */
575Objects_Control *_Objects_Get_no_protection(
576  Objects_Id                 id,
577  const Objects_Information *information
578);
579
580/**
581 *  Gets the next open object after the specified object identifier.
582 *
583 *  Locks the object allocator mutex in case a next object exists.
584 *
585 *  @param[in] id is the Id of the object whose name we are locating.
586 *    This is the first parameter since usual callers get the object identifier
587 *    as the first parameter themself.
588 *  @param[in] information points to an object class information block.
589 *  @param[in] next_id_p is the Id of the next object we will look at.
590 *
591 *  @retval This method returns the pointer to the object located or
592 *          NULL on error.
593 */
594Objects_Control *_Objects_Get_next(
595  Objects_Id                 id,
596  const Objects_Information *information,
597  Objects_Id                *next_id_p
598);
599
600/**
601 *  @brief Get object information.
602 *
603 *  This function return the information structure given
604 *  an the API and Class.  This can be done independent of
605 *  the existence of any objects created by the API.
606 *
607 *  @param[in] the_api indicates the API for the information we want
608 *  @param[in] the_class indicates the Class for the information we want
609 *
610 *  @retval This method returns a pointer to the Object Information Table
611 *          for the class of objects which corresponds to this object ID.
612 */
613Objects_Information *_Objects_Get_information(
614  Objects_APIs   the_api,
615  uint16_t       the_class
616);
617
618/**
619 *  @brief Get information of an object from an ID.
620 *
621 *  This function return the information structure given
622 *  an @a id of an object.
623 *
624 *  @param[in] id is the object ID to get the information from
625 *
626 *  @retval This method returns a pointer to the Object Information Table
627 *          for the class of objects which corresponds to this object ID.
628 */
629Objects_Information *_Objects_Get_information_id(
630  Objects_Id  id
631);
632
633/**
634 *  @brief Gets object name in the form of a C string.
635 *
636 *  This method objects the name of an object and returns its name
637 *  in the form of a C string.  It attempts to be careful about
638 *  overflowing the user's string and about returning unprintable characters.
639 *
640 *  @param[in] id is the object to obtain the name of
641 *  @param[in] length indicates the length of the caller's buffer
642 *  @param[in] name points a string which will be filled in.
643 *
644 *  @retval This method returns @a name or NULL on error. @a *name will
645 *          contain the name if successful.
646 */
647char *_Objects_Get_name_as_string(
648  Objects_Id   id,
649  size_t       length,
650  char        *name
651);
652
653/**
654 * @brief Converts the specified object name to a text representation.
655 *
656 * Non-printable characters according to isprint() are converted to '*'.
657 *
658 * @param[in] name The object name.
659 * @param[in] is_string Indicates if the object name is a string or a four
660 *   character array (32-bit unsigned integer).
661 * @param[in] buffer The string buffer for the text representation.
662 * @param[in] buffer_size The buffer size in characters.
663 *
664 * @retval The length of the text representation.  May be greater than or equal
665 * to the buffer size if truncation occurred.
666 */
667size_t _Objects_Name_to_string(
668  Objects_Name  name,
669  bool          is_string,
670  char         *buffer,
671  size_t        buffer_size
672);
673
674/**
675 *  @brief Set objects name.
676 *
677 *  This method sets the object name to either a copy of a string
678 *  or up to the first four characters of the string based upon
679 *  whether this object class uses strings for names.
680 *
681 *  @param[in] information points to the object information structure
682 *  @param[in] the_object is the object to operate upon
683 *  @param[in] name is a pointer to the name to use
684 *
685 *  @retval If successful, true is returned.  Otherwise false is returned.
686 */
687bool _Objects_Set_name(
688  Objects_Information *information,
689  Objects_Control     *the_object,
690  const char          *name
691);
692
693/**
694 *  @brief Removes object from namespace.
695 *
696 *  This function removes @a the_object from the namespace.
697 *
698 *  @param[in] information points to an Object Information Table.
699 *  @param[in] the_object is a pointer to an object.
700 */
701void _Objects_Namespace_remove(
702  Objects_Information  *information,
703  Objects_Control      *the_object
704);
705
706/**
707 *  @brief Close object.
708 *
709 *  This function removes the_object control pointer and object name
710 *  in the Local Pointer and Local Name Tables.
711 *
712 *  @param[in] information points to an Object Information Table
713 *  @param[in] the_object is a pointer to an object
714 */
715void _Objects_Close(
716  Objects_Information  *information,
717  Objects_Control      *the_object
718);
719
720/**
721 * @brief Returns the count of active objects.
722 *
723 * @param[in] information The object information table.
724 *
725 * @retval The count of active objects.
726 */
727Objects_Maximum _Objects_Active_count(
728  const Objects_Information *information
729);
730
731RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Extend_size(
732  const Objects_Information *information
733)
734{
735  return information->auto_extend ? information->allocation_size : 0;
736}
737
738/**
739 * This function returns true if the api is valid.
740 *
741 * @param[in] the_api is the api portion of an object ID.
742 *
743 * @return This method returns true if the specified api value is valid
744 *         and false otherwise.
745 */
746RTEMS_INLINE_ROUTINE bool _Objects_Is_api_valid(
747  uint32_t   the_api
748)
749{
750  if ( !the_api || the_api > OBJECTS_APIS_LAST )
751   return false;
752  return true;
753}
754
755/**
756 * This function returns true if the node is of the local object, and
757 * false otherwise.
758 *
759 * @param[in] node is the node number and corresponds to the node number
760 *        portion of an object ID.
761 *
762 * @return This method returns true if the specified node is the local node
763 *         and false otherwise.
764 */
765RTEMS_INLINE_ROUTINE bool _Objects_Is_local_node(
766  uint32_t   node
767)
768{
769  return ( node == _Objects_Local_node );
770}
771
772/**
773 * This function returns true if the id is of a local object, and
774 * false otherwise.
775 *
776 * @param[in] id is an object ID
777 *
778 * @return This method returns true if the specified object Id is local
779 *         and false otherwise.
780 *
781 * @note On a single processor configuration, this always returns true.
782 */
783RTEMS_INLINE_ROUTINE bool _Objects_Is_local_id(
784#if defined(RTEMS_MULTIPROCESSING)
785  Objects_Id id
786#else
787  Objects_Id id RTEMS_UNUSED
788#endif
789)
790{
791#if defined(RTEMS_MULTIPROCESSING)
792  return _Objects_Is_local_node( _Objects_Get_node(id) );
793#else
794  return true;
795#endif
796}
797
798/**
799 * This function returns true if left and right are equal,
800 * and false otherwise.
801 *
802 * @param[in] left is the Id on the left hand side of the comparison
803 * @param[in] right is the Id on the right hand side of the comparison
804 *
805 * @return This method returns true if the specified object IDs are equal
806 *         and false otherwise.
807 */
808RTEMS_INLINE_ROUTINE bool _Objects_Are_ids_equal(
809  Objects_Id left,
810  Objects_Id right
811)
812{
813  return ( left == right );
814}
815
816/**
817 * This function sets the pointer to the local_table object
818 * referenced by the index.
819 *
820 * @param[in] information points to an Object Information Table
821 * @param[in] index is the index of the object the caller wants to access
822 * @param[in] the_object is the local object pointer
823 *
824 * @note This routine is ONLY to be called in places where the
825 *       index portion of the Id is known to be good.  This is
826 *       OK since it is normally called from object create/init
827 *       or delete/destroy operations.
828 */
829
830RTEMS_INLINE_ROUTINE void _Objects_Set_local_object(
831  Objects_Information *information,
832  uint32_t             index,
833  Objects_Control     *the_object
834)
835{
836  /*
837   *  This routine is ONLY to be called from places in the code
838   *  where the Id is known to be good.  Therefore, this should NOT
839   *  occur in normal situations.
840   */
841  #if defined(RTEMS_DEBUG)
842    if ( index > information->maximum )
843      return;
844  #endif
845
846  information->local_table[ index ] = the_object;
847}
848
849/**
850 * This function sets the pointer to the local_table object
851 * referenced by the index to a NULL so the object Id is invalid
852 * after this call.
853 *
854 * @param[in] information points to an Object Information Table
855 * @param[in] the_object is the local object pointer
856 *
857 * @note This routine is ONLY to be called in places where the
858 *       index portion of the Id is known to be good.  This is
859 *       OK since it is normally called from object create/init
860 *       or delete/destroy operations.
861 */
862
863RTEMS_INLINE_ROUTINE void _Objects_Invalidate_Id(
864  Objects_Information  *information,
865  Objects_Control      *the_object
866)
867{
868  _Assert( information != NULL );
869  _Assert( the_object != NULL );
870
871  _Objects_Set_local_object(
872    information,
873    _Objects_Get_index( the_object->id ),
874    NULL
875  );
876}
877
878/**
879 * This function places the_object control pointer and object name
880 * in the Local Pointer and Local Name Tables, respectively.
881 *
882 * @param[in] information points to an Object Information Table
883 * @param[in] the_object is a pointer to an object
884 * @param[in] name is the name of the object to make accessible
885 */
886RTEMS_INLINE_ROUTINE void _Objects_Open(
887  Objects_Information *information,
888  Objects_Control     *the_object,
889  Objects_Name         name
890)
891{
892  _Assert( information != NULL );
893  _Assert( the_object != NULL );
894
895  the_object->name = name;
896
897  _Objects_Set_local_object(
898    information,
899    _Objects_Get_index( the_object->id ),
900    the_object
901  );
902}
903
904/**
905 * This function places the_object control pointer and object name
906 * in the Local Pointer and Local Name Tables, respectively.
907 *
908 * @param[in] information points to an Object Information Table
909 * @param[in] the_object is a pointer to an object
910 * @param[in] name is the name of the object to make accessible
911 */
912RTEMS_INLINE_ROUTINE void _Objects_Open_u32(
913  Objects_Information *information,
914  Objects_Control     *the_object,
915  uint32_t             name
916)
917{
918  /* ASSERT: information->is_string == false */
919  the_object->name.name_u32 = name;
920
921  _Objects_Set_local_object(
922    information,
923    _Objects_Get_index( the_object->id ),
924    the_object
925  );
926}
927
928/**
929 * This function places the_object control pointer and object name
930 * in the Local Pointer and Local Name Tables, respectively.
931 *
932 * @param[in] information points to an Object Information Table
933 * @param[in] the_object is a pointer to an object
934 * @param[in] name is the name of the object to make accessible
935 */
936RTEMS_INLINE_ROUTINE void _Objects_Open_string(
937  Objects_Information *information,
938  Objects_Control     *the_object,
939  const char          *name
940)
941{
942  #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES)
943    /* ASSERT: information->is_string */
944    the_object->name.name_p = name;
945  #endif
946
947  _Objects_Set_local_object(
948    information,
949    _Objects_Get_index( the_object->id ),
950    the_object
951  );
952}
953
954/**
955 * @brief Locks the object allocator mutex.
956 *
957 * While holding the allocator mutex the executing thread is protected from
958 * asynchronous thread restart and deletion.
959 *
960 * The usage of the object allocator mutex with the thread life protection
961 * makes it possible to allocate and free objects without thread dispatching
962 * disabled.  The usage of a unified workspace and unlimited objects may lead
963 * to heap fragmentation.  Thus the execution time of the _Objects_Allocate()
964 * function may increase during system run-time.
965 *
966 * @see _Objects_Allocator_unlock() and _Objects_Allocate().
967 */
968RTEMS_INLINE_ROUTINE void _Objects_Allocator_lock( void )
969{
970  _RTEMS_Lock_allocator();
971}
972
973/**
974 * @brief Unlocks the object allocator mutex.
975 *
976 * In case the mutex is fully unlocked, then this function restores the
977 * previous thread life protection state and thus may not return if the
978 * executing thread was restarted or deleted in the mean-time.
979 */
980RTEMS_INLINE_ROUTINE void _Objects_Allocator_unlock( void )
981{
982  _RTEMS_Unlock_allocator();
983}
984
985RTEMS_INLINE_ROUTINE bool _Objects_Allocator_is_owner( void )
986{
987  return _RTEMS_Allocator_is_owner();
988}
989
990/** @} */
991
992#ifdef __cplusplus
993}
994#endif
995
996#if defined(RTEMS_MULTIPROCESSING)
997#include <rtems/score/objectmp.h>
998#endif
999
1000
1001#endif
1002/* end of include file */
Note: See TracBrowser for help on using the repository browser.