source: rtems/cpukit/include/rtems/score/objectimpl.h @ 1c2d178

Last change on this file since 1c2d178 was 1c2d178, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 25, 2018 at 7:15:26 PM

score: Remove Objects_Information::maximum

This information is already present in Objects_Information::maximum_id.
Add and use _Objects_Get_maximum_index().

Update #3621.

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