source: rtems/cpukit/score/include/rtems/score/objectimpl.h @ 77e6eba7

5
Last change on this file since 77e6eba7 was 77e6eba7, checked in by Sebastian Huber <sebastian.huber@…>, on 03/07/16 at 15:01:57

score: Add and use _Objects_Get_local()

This simplifies the handling with local-only objects.

Update #2555.

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