source: rtems/cpukit/score/include/rtems/score/objectimpl.h @ 6db5e650

4.115
Last change on this file since 6db5e650 was 6db5e650, checked in by Sebastian Huber <sebastian.huber@…>, on 03/15/15 at 09:16:24

score: Add _Objects_ISR_disable_and_acquire()

  • Property mode set to 100644
File size: 34.8 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/isrlevel.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)
181SCORE_EXTERN 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)
190SCORE_EXTERN 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 */
200SCORE_EXTERN 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] level is the interrupt level 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_Level           *level
559);
560
561/**
562 *  @brief  Maps object ids to object control blocks.
563 *
564 *  This function maps object ids to object control blocks.
565 *  If id corresponds to a local object, then it returns
566 *  the_object control pointer which maps to id and location
567 *  is set to OBJECTS_LOCAL.  If the object class supports global
568 *  objects and the object id is global and resides on a remote
569 *  node, then location is set to OBJECTS_REMOTE, and the_object
570 *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
571 *  and the_object is undefined.
572 *
573 *  @param[in] information points to an object class information block.
574 *  @param[in] id is the Id of the object whose name we are locating.
575 *  @param[in] location will contain an indication of success or failure.
576 *
577 *  @retval This method returns one of the values from the
578 *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
579 *          successful or failure.  On success @a id will contain the Id of
580 *          the requested object.
581 *
582 *  @note _Objects_Get returns with dispatching disabled for
583 *  local and remote objects.  _Objects_Get_isr_disable returns with
584 *  dispatching disabled for remote objects and interrupts for local
585 *  objects.
586 */
587Objects_Control *_Objects_Get_no_protection(
588  Objects_Information *information,
589  Objects_Id           id,
590  Objects_Locations   *location
591);
592
593/**
594 * @brief Acquires an object by its identifier.
595 *
596 * This function is similar to _Objects_Get_isr_disable().  It disables
597 * interrupts and acquires the object specific ISR lock for local objects.
598 * Thread dispatching is not disabled for local objects.  For remote objects
599 * thread dispatching is disabled.
600 *
601 * @param[in] information The object information.
602 * @param[in] id The object identifier.
603 * @param[in] location The location of the object.
604 * @param[in] lock_context The lock context for local objects.
605 *
606 * @retval object The object corresponding to the identifier.
607 * @retval NULL No object exists in this domain for this identifier.
608 *
609 * @see _Objects_ISR_disable_and_acquire(), _Objects_Release(),
610 *   _Objects_Release_and_ISR_enable(), and
611 *   _Objects_Release_and_thread_dispatch_disable().
612 */
613Objects_Control *_Objects_Acquire(
614  const Objects_Information *information,
615  Objects_Id                 id,
616  Objects_Locations         *location,
617  ISR_lock_Context          *lock_context
618);
619
620/**
621 * @brief Acquires a local object and disables interrupts.
622 *
623 * @param[in] the_object The local object to acquire.
624 * @param[in] lock_context The lock context.
625 */
626RTEMS_INLINE_ROUTINE void _Objects_ISR_disable_and_acquire(
627  Objects_Control  *the_object,
628  ISR_lock_Context *lock_context
629)
630{
631  _ISR_lock_ISR_disable_and_acquire( &the_object->Lock, lock_context );
632}
633
634/**
635 * @brief Releases a local object.
636 *
637 * @param[in] the_object The local object acquired by _Objects_Acquire().
638 * @param[in] lock_context The lock context initialized by _Objects_Acquire().
639 */
640RTEMS_INLINE_ROUTINE void _Objects_Release(
641  Objects_Control  *the_object,
642  ISR_lock_Context *lock_context
643)
644{
645  _ISR_lock_Release( &the_object->Lock, lock_context );
646}
647
648/**
649 * @brief Releases a local object and restores the interrupt level.
650 *
651 * @param[in] the_object The local object acquired by _Objects_Acquire().
652 * @param[in] lock_context The lock context initialized by _Objects_Acquire().
653 */
654RTEMS_INLINE_ROUTINE void _Objects_Release_and_ISR_enable(
655  Objects_Control  *the_object,
656  ISR_lock_Context *lock_context
657)
658{
659  _ISR_lock_Release_and_ISR_enable( &the_object->Lock, lock_context );
660}
661
662/**
663 * @brief Releases a local object, disables thread dispatching and restores the
664 * interrupt level.
665 *
666 * @param[in] the_object The local object acquired by _Objects_Acquire().
667 * @param[in] lock_context The lock context initialized by _Objects_Acquire().
668 *
669 * @return The current processor.
670 */
671RTEMS_INLINE_ROUTINE Per_CPU_Control *
672_Objects_Release_and_thread_dispatch_disable(
673  Objects_Control  *the_object,
674  ISR_lock_Context *lock_context
675)
676{
677  Per_CPU_Control *cpu_self = _Per_CPU_Get();
678
679  _Thread_Dispatch_disable_critical( cpu_self );
680  _Objects_Release_and_ISR_enable( the_object, lock_context );
681
682  return cpu_self;
683}
684
685/**
686 *  Like @ref _Objects_Get, but is used to find "next" open object.
687 *
688 *  @param[in] information points to an object class information block.
689 *  @param[in] id is the Id of the object whose name we are locating.
690 *  @param[in] location_p will contain an indication of success or failure.
691 *  @param[in] next_id_p is the Id of the next object we will look at.
692 *
693 *  @retval This method returns the pointer to the object located or
694 *          NULL on error.
695 */
696Objects_Control *_Objects_Get_next(
697    Objects_Information *information,
698    Objects_Id           id,
699    Objects_Locations   *location_p,
700    Objects_Id          *next_id_p
701);
702
703/**
704 *  @brief Get object information.
705 *
706 *  This function return the information structure given
707 *  an the API and Class.  This can be done independent of
708 *  the existence of any objects created by the API.
709 *
710 *  @param[in] the_api indicates the API for the information we want
711 *  @param[in] the_class indicates the Class for the information we want
712 *
713 *  @retval This method returns a pointer to the Object Information Table
714 *          for the class of objects which corresponds to this object ID.
715 */
716Objects_Information *_Objects_Get_information(
717  Objects_APIs   the_api,
718  uint16_t       the_class
719);
720
721/**
722 *  @brief Get information of an object from an ID.
723 *
724 *  This function return the information structure given
725 *  an @a id of an object.
726 *
727 *  @param[in] id is the object ID to get the information from
728 *
729 *  @retval This method returns a pointer to the Object Information Table
730 *          for the class of objects which corresponds to this object ID.
731 */
732Objects_Information *_Objects_Get_information_id(
733  Objects_Id  id
734);
735
736/**
737 *  @brief Gets object name in the form of a C string.
738 *
739 *  This method objects the name of an object and returns its name
740 *  in the form of a C string.  It attempts to be careful about
741 *  overflowing the user's string and about returning unprintable characters.
742 *
743 *  @param[in] id is the object to obtain the name of
744 *  @param[in] length indicates the length of the caller's buffer
745 *  @param[in] name points a string which will be filled in.
746 *
747 *  @retval This method returns @a name or NULL on error. @a *name will
748 *          contain the name if successful.
749 */
750char *_Objects_Get_name_as_string(
751  Objects_Id   id,
752  size_t       length,
753  char        *name
754);
755
756/**
757 *  @brief Set objects name.
758 *
759 *  This method sets the object name to either a copy of a string
760 *  or up to the first four characters of the string based upon
761 *  whether this object class uses strings for names.
762 *
763 *  @param[in] information points to the object information structure
764 *  @param[in] the_object is the object to operate upon
765 *  @param[in] name is a pointer to the name to use
766 *
767 *  @retval If successful, true is returned.  Otherwise false is returned.
768 */
769bool _Objects_Set_name(
770  Objects_Information *information,
771  Objects_Control     *the_object,
772  const char          *name
773);
774
775/**
776 *  @brief Removes object from namespace.
777 *
778 *  This function removes @a the_object from the namespace.
779 *
780 *  @param[in] information points to an Object Information Table.
781 *  @param[in] the_object is a pointer to an object.
782 */
783void _Objects_Namespace_remove(
784  Objects_Information  *information,
785  Objects_Control      *the_object
786);
787
788/**
789 *  @brief Close object.
790 *
791 *  This function removes the_object control pointer and object name
792 *  in the Local Pointer and Local Name Tables.
793 *
794 *  @param[in] information points to an Object Information Table
795 *  @param[in] the_object is a pointer to an object
796 */
797void _Objects_Close(
798  Objects_Information  *information,
799  Objects_Control      *the_object
800);
801
802/**
803 * @brief Returns the count of active objects.
804 *
805 * @param[in] information The object information table.
806 *
807 * @retval The count of active objects.
808 */
809Objects_Maximum _Objects_Active_count(
810  const Objects_Information *information
811);
812
813/**
814 * This function returns true if the api is valid.
815 *
816 * @param[in] the_api is the api portion of an object ID.
817 *
818 * @return This method returns true if the specified api value is valid
819 *         and false otherwise.
820 */
821RTEMS_INLINE_ROUTINE bool _Objects_Is_api_valid(
822  uint32_t   the_api
823)
824{
825  if ( !the_api || the_api > OBJECTS_APIS_LAST )
826   return false;
827  return true;
828}
829
830/**
831 * This function returns true if the node is of the local object, and
832 * false otherwise.
833 *
834 * @param[in] node is the node number and corresponds to the node number
835 *        portion of an object ID.
836 *
837 * @return This method returns true if the specified node is the local node
838 *         and false otherwise.
839 */
840RTEMS_INLINE_ROUTINE bool _Objects_Is_local_node(
841  uint32_t   node
842)
843{
844  return ( node == _Objects_Local_node );
845}
846
847/**
848 * This function returns true if the id is of a local object, and
849 * false otherwise.
850 *
851 * @param[in] id is an object ID
852 *
853 * @return This method returns true if the specified object Id is local
854 *         and false otherwise.
855 *
856 * @note On a single processor configuration, this always returns true.
857 */
858RTEMS_INLINE_ROUTINE bool _Objects_Is_local_id(
859#if defined(RTEMS_MULTIPROCESSING)
860  Objects_Id id
861#else
862  Objects_Id id __attribute__((unused))
863#endif
864)
865{
866#if defined(RTEMS_MULTIPROCESSING)
867  return _Objects_Is_local_node( _Objects_Get_node(id) );
868#else
869  return true;
870#endif
871}
872
873/**
874 * This function returns true if left and right are equal,
875 * and false otherwise.
876 *
877 * @param[in] left is the Id on the left hand side of the comparison
878 * @param[in] right is the Id on the right hand side of the comparison
879 *
880 * @return This method returns true if the specified object IDs are equal
881 *         and false otherwise.
882 */
883RTEMS_INLINE_ROUTINE bool _Objects_Are_ids_equal(
884  Objects_Id left,
885  Objects_Id right
886)
887{
888  return ( left == right );
889}
890
891/**
892 * This function returns a pointer to the local_table object
893 * referenced by the index.
894 *
895 * @param[in] information points to an Object Information Table
896 * @param[in] index is the index of the object the caller wants to access
897 *
898 * @return This method returns a pointer to a local object or NULL if the
899 *         index is invalid and RTEMS_DEBUG is enabled.
900 */
901RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object(
902  Objects_Information *information,
903  uint16_t             index
904)
905{
906  /*
907   * This routine is ONLY to be called from places in the code
908   * where the Id is known to be good.  Therefore, this should NOT
909   * occur in normal situations.
910   */
911  #if defined(RTEMS_DEBUG)
912    if ( index > information->maximum )
913      return NULL;
914  #endif
915  return information->local_table[ index ];
916}
917
918/**
919 * This function sets the pointer to the local_table object
920 * referenced by the index.
921 *
922 * @param[in] information points to an Object Information Table
923 * @param[in] index is the index of the object the caller wants to access
924 * @param[in] the_object is the local object pointer
925 *
926 * @note This routine is ONLY to be called in places where the
927 *       index portion of the Id is known to be good.  This is
928 *       OK since it is normally called from object create/init
929 *       or delete/destroy operations.
930 */
931
932RTEMS_INLINE_ROUTINE void _Objects_Set_local_object(
933  Objects_Information *information,
934  uint32_t             index,
935  Objects_Control     *the_object
936)
937{
938  /*
939   *  This routine is ONLY to be called from places in the code
940   *  where the Id is known to be good.  Therefore, this should NOT
941   *  occur in normal situations.
942   */
943  #if defined(RTEMS_DEBUG)
944    if ( index > information->maximum )
945      return;
946  #endif
947
948  information->local_table[ index ] = the_object;
949}
950
951/**
952 * This function sets the pointer to the local_table object
953 * referenced by the index to a NULL so the object Id is invalid
954 * after this call.
955 *
956 * @param[in] information points to an Object Information Table
957 * @param[in] the_object is the local object pointer
958 *
959 * @note This routine is ONLY to be called in places where the
960 *       index portion of the Id is known to be good.  This is
961 *       OK since it is normally called from object create/init
962 *       or delete/destroy operations.
963 */
964
965RTEMS_INLINE_ROUTINE void _Objects_Invalidate_Id(
966  Objects_Information  *information,
967  Objects_Control      *the_object
968)
969{
970  _Assert( information != NULL );
971  _Assert( the_object != NULL );
972
973  _Objects_Set_local_object(
974    information,
975    _Objects_Get_index( the_object->id ),
976    NULL
977  );
978}
979
980/**
981 * This function places the_object control pointer and object name
982 * in the Local Pointer and Local Name Tables, respectively.
983 *
984 * @param[in] information points to an Object Information Table
985 * @param[in] the_object is a pointer to an object
986 * @param[in] name is the name of the object to make accessible
987 */
988RTEMS_INLINE_ROUTINE void _Objects_Open(
989  Objects_Information *information,
990  Objects_Control     *the_object,
991  Objects_Name         name
992)
993{
994  _Assert( information != NULL );
995  _Assert( the_object != NULL );
996
997  the_object->name = name;
998  _ISR_lock_Initialize( &the_object->Lock, "Object" );
999
1000  _Objects_Set_local_object(
1001    information,
1002    _Objects_Get_index( the_object->id ),
1003    the_object
1004  );
1005}
1006
1007/**
1008 * This function places the_object control pointer and object name
1009 * in the Local Pointer and Local Name Tables, respectively.
1010 *
1011 * @param[in] information points to an Object Information Table
1012 * @param[in] the_object is a pointer to an object
1013 * @param[in] name is the name of the object to make accessible
1014 */
1015RTEMS_INLINE_ROUTINE void _Objects_Open_u32(
1016  Objects_Information *information,
1017  Objects_Control     *the_object,
1018  uint32_t             name
1019)
1020{
1021  /* ASSERT: information->is_string == false */
1022  the_object->name.name_u32 = name;
1023  _ISR_lock_Initialize( &the_object->Lock, "Object" );
1024
1025  _Objects_Set_local_object(
1026    information,
1027    _Objects_Get_index( the_object->id ),
1028    the_object
1029  );
1030}
1031
1032/**
1033 * This function places the_object control pointer and object name
1034 * in the Local Pointer and Local Name Tables, respectively.
1035 *
1036 * @param[in] information points to an Object Information Table
1037 * @param[in] the_object is a pointer to an object
1038 * @param[in] name is the name of the object to make accessible
1039 */
1040RTEMS_INLINE_ROUTINE void _Objects_Open_string(
1041  Objects_Information *information,
1042  Objects_Control     *the_object,
1043  const char          *name
1044)
1045{
1046  #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES)
1047    /* ASSERT: information->is_string */
1048    the_object->name.name_p = name;
1049  #endif
1050  _ISR_lock_Initialize( &the_object->Lock, "Object" );
1051
1052  _Objects_Set_local_object(
1053    information,
1054    _Objects_Get_index( the_object->id ),
1055    the_object
1056  );
1057}
1058
1059/**
1060 * @brief Puts back an object obtained with _Objects_Get().
1061 *
1062 * This function decrements the thread dispatch disable level.  The
1063 * _Thread_Dispatch() is called if the level reaches zero.
1064 */
1065RTEMS_INLINE_ROUTINE void _Objects_Put(
1066  Objects_Control *the_object
1067)
1068{
1069  (void) the_object;
1070  _Thread_Enable_dispatch();
1071}
1072
1073/**
1074 * @brief Puts back an object obtained with _Objects_Get().
1075 *
1076 * This function decrements the thread dispatch disable level.  The
1077 * _Thread_Dispatch() is not called if the level reaches zero, thus a thread
1078 * dispatch will not take place immediately on the current processor.
1079 */
1080RTEMS_INLINE_ROUTINE void _Objects_Put_without_thread_dispatch(
1081  Objects_Control *the_object
1082)
1083{
1084  (void) the_object;
1085  _Thread_Unnest_dispatch();
1086}
1087
1088/**
1089 * @brief Puts back an object obtained with _Objects_Get_isr_disable().
1090 */
1091RTEMS_INLINE_ROUTINE void _Objects_Put_for_get_isr_disable(
1092  Objects_Control *the_object
1093)
1094{
1095  (void) the_object;
1096#if defined(RTEMS_SMP)
1097  _Thread_Enable_dispatch();
1098#endif
1099}
1100
1101/**
1102 * @brief Locks the object allocator mutex.
1103 *
1104 * While holding the allocator mutex the executing thread is protected from
1105 * asynchronous thread restart and deletion.
1106 *
1107 * The usage of the object allocator mutex with the thread life protection
1108 * makes it possible to allocate and free objects without thread dispatching
1109 * disabled.  The usage of a unified workspace and unlimited objects may lead
1110 * to heap fragmentation.  Thus the execution time of the _Objects_Allocate()
1111 * function may increase during system run-time.
1112 *
1113 * @see _Objects_Allocator_unlock() and _Objects_Allocate().
1114 */
1115RTEMS_INLINE_ROUTINE void _Objects_Allocator_lock( void )
1116{
1117  _RTEMS_Lock_allocator();
1118}
1119
1120/**
1121 * @brief Unlocks the object allocator mutex.
1122 *
1123 * In case the mutex is fully unlocked, then this function restores the
1124 * previous thread life protection state and thus may not return if the
1125 * executing thread was restarted or deleted in the mean-time.
1126 */
1127RTEMS_INLINE_ROUTINE void _Objects_Allocator_unlock( void )
1128{
1129  _RTEMS_Unlock_allocator();
1130}
1131
1132/** @} */
1133
1134#ifdef __cplusplus
1135}
1136#endif
1137
1138#if defined(RTEMS_MULTIPROCESSING)
1139#include <rtems/score/objectmp.h>
1140#endif
1141
1142
1143#endif
1144/* end of include file */
Note: See TracBrowser for help on using the repository browser.