source: rtems/cpukit/include/rtems/score/objectimpl.h @ 0f5b2c09

5
Last change on this file since 0f5b2c09 was 8b0e752f, checked in by Sebastian Huber <sebastian.huber@…>, on 12/10/18 at 12:44:53

score: Remove Objects_Information::auto_extend

Use Objects_Information::objects_per_block to provide this information.
Add and use _Objects_Is_auto_extend().

Update #3621.

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