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

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

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