From 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 16 Jan 2006 15:13:58 +0000 Subject: 2006-01-16 Joel Sherrill Large patch to improve Doxygen output. As a side-effect, grammar and spelling errors were corrected, spacing errors were address, and some variable names were improved. * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. * score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output. * score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes. --- cpukit/score/include/rtems/score/object.h | 527 +++++++++++++++++++++--------- 1 file changed, 364 insertions(+), 163 deletions(-) (limited to 'cpukit/score/include/rtems/score/object.h') diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 145b003147..661f53eb11 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -8,7 +8,7 @@ * can be used to initialize and manipulate all objects which have * ids. * - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,25 +28,22 @@ extern "C" { #include #include -/* +/** * The following type defines the control block used to manage * object names. */ - typedef void * Objects_Name; -/* +/** * Space for object names is allocated in multiples of this. * * NOTE: Must be a power of 2. Matches the name manipulation routines. */ - #define OBJECTS_NAME_ALIGNMENT sizeof( uint32_t ) -/* +/** * Functions which compare names are prototyped like this. */ - typedef boolean (*Objects_Name_comparators)( void * /* name_1 */, void * /* name_2 */, @@ -54,7 +51,7 @@ typedef boolean (*Objects_Name_comparators)( ); #if defined(RTEMS_USE_16_BIT_OBJECT) -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -62,8 +59,12 @@ typedef boolean (*Objects_Name_comparators)( * Bits 8 .. 10 = API (up to 7 API classes) * Bits 11 .. 15 = class (up to 31 object types per API) */ - typedef uint16_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint8_t Objects_Maximum; #define OBJECTS_INDEX_START_BIT 0 @@ -81,8 +82,11 @@ typedef uint8_t Objects_Maximum; #define OBJECTS_UNLIMITED_OBJECTS 0x8000 +#define OBJECTS_ID_INITIAL_INDEX (0) +#define OBJECTS_ID_FINAL_INDEX (0xff) + #else -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -91,39 +95,103 @@ typedef uint8_t Objects_Maximum; * Bits 24 .. 26 = API (up to 7 API classes) * Bits 27 .. 31 = class (up to 31 object types per API) */ - typedef uint32_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint16_t Objects_Maximum; +/** + * This is the bit position of the starting bit of the index portion of + * the object Id. + */ #define OBJECTS_INDEX_START_BIT 0 + + +/** + * This is the bit position of the starting bit of the node portion of + * the object Id. + */ #define OBJECTS_NODE_START_BIT 16 + +/** + * This is the bit position of the starting bit of the API portion of + * the object Id. + */ #define OBJECTS_API_START_BIT 24 + +/** + * This is the bit position of the starting bit of the class portion of + * the object Id. + */ #define OBJECTS_CLASS_START_BIT 27 +/** + * This mask is used to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_MASK (Objects_Id)0x0000ffff + +/** + * This mask is used to extract the node portion of an object Id. + */ #define OBJECTS_NODE_MASK (Objects_Id)0x00ff0000 + +/** + * This mask is used to extract the API portion of an object Id. + */ #define OBJECTS_API_MASK (Objects_Id)0x07000000 + +/** + * This mask is used to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_MASK (Objects_Id)0xf8000000 +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_VALID_BITS (Objects_Id)0x0000ffff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the node portion of an object Id. + */ #define OBJECTS_NODE_VALID_BITS (Objects_Id)0x000000ff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the API portion of an object Id. + */ #define OBJECTS_API_VALID_BITS (Objects_Id)0x00000007 + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_VALID_BITS (Objects_Id)0x0000001f -/* +/** * Mask to enable unlimited objects. This is used in the configuration * table when specifying the number of configured objects. */ #define OBJECTS_UNLIMITED_OBJECTS 0x80000000 +/** + * This is the lowest value for the index portion of an object Id. + */ +#define OBJECTS_ID_INITIAL_INDEX (0) + +/** + * This is the highest value for the index portion of an object Id. + */ +#define OBJECTS_ID_FINAL_INDEX (0xff) #endif -/* +/** * This enumerated type is used in the class field of the object ID. */ - -#define OBJECTS_NO_CLASS 0 - typedef enum { OBJECTS_NO_API = 0, OBJECTS_INTERNAL_API = 1, @@ -132,16 +200,26 @@ typedef enum { OBJECTS_ITRON_API = 4 } Objects_APIs; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_APIS_LAST OBJECTS_ITRON_API +/** + * This enumerated type is used in the class field of the object ID + * for RTEMS internal object classes. + */ typedef enum { OBJECTS_INTERNAL_NO_CLASS = 0, OBJECTS_INTERNAL_THREADS = 1, OBJECTS_INTERNAL_MUTEXES = 2 } Objects_Internal_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES +/** + * This enumerated type is used in the class field of the object ID + * for the RTEMS Classic API. + */ typedef enum { OBJECTS_CLASSIC_NO_CLASS = 0, OBJECTS_RTEMS_TASKS = 1, @@ -155,8 +233,13 @@ typedef enum { OBJECTS_RTEMS_EXTENSIONS = 9 } Objects_Classic_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_EXTENSIONS +/** + * This enumerated type is used in the class field of the object ID + * for the POSIX API. + */ typedef enum { OBJECTS_POSIX_NO_CLASS = 0, OBJECTS_POSIX_THREADS = 1, @@ -169,8 +252,13 @@ typedef enum { OBJECTS_POSIX_CONDITION_VARIABLES = 8 } Objects_POSIX_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_CONDITION_VARIABLES +/** + * This enumerated type is used in the class field of the object ID + * for the ITRON API. + */ typedef enum { OBJECTS_ITRON_NO_CLASS = 0, OBJECTS_ITRON_TASKS = 1, @@ -183,161 +271,186 @@ typedef enum { OBJECTS_ITRON_FIXED_MEMORY_POOLS = 8 } Objects_ITRON_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS -/* +/** * This enumerated type lists the locations which may be returned * by _Objects_Get. These codes indicate the success of locating * an object with the specified ID. */ - typedef enum { OBJECTS_LOCAL = 0, /* object is local */ OBJECTS_REMOTE = 1, /* object is remote */ OBJECTS_ERROR = 2 /* id was invalid */ } Objects_Locations; -/* +/** * The following type defines the callout used when a local task * is extracted from a remote thread queue (i.e. it's proxy must * extracted from the remote queue). */ - typedef void ( *Objects_Thread_queue_Extract_callout )( void * ); -/* +/** * The following defines the Object Control Block used to manage * each object local to this node. */ - typedef struct { + /** This is the chain node portion of an object. */ Chain_Node Node; + /** This is the object's ID. */ Objects_Id id; + /** This is the object's name. */ Objects_Name name; } Objects_Control; -/* +/** * The following defines the structure for the information used to * manage each class of objects. */ - typedef struct { - Objects_APIs the_api; /* API of this object */ - uint16_t the_class; /* class of this object */ - Objects_Id minimum_id; /* minimum valid id of this type */ - Objects_Id maximum_id; /* maximum valid id of this type */ - Objects_Maximum maximum; /* maximum number of objects */ - boolean auto_extend; /* TRUE if unlimited objects */ - uint32_t allocation_size; /* number of objects in a block */ - uint32_t size; /* size of the objects */ + /** This field indicates the API of this object class. */ + Objects_APIs the_api; + /** This is the class of this object set. */ + uint16_t the_class; + /** This is the minimum valid id of this object class. */ + Objects_Id minimum_id; + /** This is the maximum valid id of this object class. */ + Objects_Id maximum_id; + /** This is the maximum number of objects in this class. */ + Objects_Maximum maximum; + /** This is the TRUE if unlimited objects in this class. */ + boolean auto_extend; + /** This is the number of objects in a block. */ + uint32_t allocation_size; + /** This is the size in bytes of each object instance. */ + uint32_t size; + /** This points to the table of local objects. */ Objects_Control **local_table; + /** This points to the table of local object names. */ Objects_Name *name_table; - Chain_Control Inactive; /* chain of inactive ctl blocks */ - Objects_Maximum inactive; /* number of objects on the InActive list */ - uint32_t *inactive_per_block; /* used to release a block */ - void **object_blocks; /* the object memory to remove */ - boolean is_string; /* TRUE if names are strings */ - uint16_t name_length; /* maximum length of names */ + /** This is the chain of inactive control blocks. */ + Chain_Control Inactive; + /** This is the number of objects on the Inactive list. */ + Objects_Maximum inactive; + /** This is the number of inactive objects per block. */ + uint32_t *inactive_per_block; + /** This is a table to the chain of inactive object memory blocks. */ + void **object_blocks; + /** This is the TRUE if names are strings. */ + boolean is_string; + /** This is the maximum length of names. */ + uint16_t name_length; + /** This is this object class' method called when extracting a thread. */ Objects_Thread_queue_Extract_callout extract; #if defined(RTEMS_MULTIPROCESSING) - Chain_Control *global_table; /* pointer to global table */ + /** This is this object class' pointer to the global name table */ + Chain_Control *global_table; #endif } Objects_Information; -/* - * The following defines the data storage which contains the - * node number of the local node. +/** + * The following is referenced to the node number of the local node. */ - #if defined(RTEMS_MULTIPROCESSING) SCORE_EXTERN uint16_t _Objects_Local_node; -SCORE_EXTERN uint16_t _Objects_Maximum_nodes; #else #define _Objects_Local_node 1 +#endif + +/** + * The following is referenced to the number of nodes in the system. + */ +#if defined(RTEMS_MULTIPROCESSING) +SCORE_EXTERN uint16_t _Objects_Maximum_nodes; +#else #define _Objects_Maximum_nodes 1 #endif -/* +/** * The following is the list of information blocks per API for each object * class. From the ID, we can go to one of these information blocks, * and obtain a pointer to the appropriate object control block. */ - SCORE_EXTERN Objects_Information **_Objects_Information_table[OBJECTS_APIS_LAST + 1]; -/* +/** * The following defines the constant which may be used * with _Objects_Get to manipulate the calling task. - * */ - #define OBJECTS_ID_OF_SELF ((Objects_Id) 0) -/* - * The following define the constants which may be used in name searches. +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes. */ - #define OBJECTS_SEARCH_ALL_NODES 0 + +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes except the current node. + */ #define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE -#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_WHO_AM_I 0 -/* - * Parameters and return id's for _Objects_Get_next +/** + * The following constant is used to specify that a name to ID search + * should search only on this node. */ +#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_ID_INITIAL_INDEX (0) -#define OBJECTS_ID_FINAL_INDEX (0xffff) +/** + * The following constant is used to specify that a name to ID search + * is being asked for the ID of the currently executing task. + */ +#define OBJECTS_WHO_AM_I 0 +/** + * This macros calculates the lowest ID for the specified api, class, + * and node. + */ #define OBJECTS_ID_INITIAL(_api, _class, _node) \ _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX ) + +/** + * This macro specifies the highest object ID value + */ #define OBJECTS_ID_FINAL ((Objects_Id)~0) -/* - * _Objects_Handler_initialization - * - * DESCRIPTION: - * +/** * This function performs the initialization necessary for this handler. * + * @param[in] node indicates the identifying number of this node. + * @param[in] maximum_nodes is the maximum number of nodes in this system. + * @param[in] maximum_global_objects is maximum number of global objects + * concurrently offered in the system. */ - void _Objects_Handler_initialization( uint32_t node, uint32_t maximum_nodes, uint32_t maximum_global_objects ); -/* - * _Objects_Extend_information - * - * DESCRIPTION: - * +/** * This function extends an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Extend_information( Objects_Information *information ); -/* - * _Objects_Shrink_information - * - * DESCRIPTION: - * +/** * This function shrink an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Shrink_information( Objects_Information *information ); -/* - * _Objects_Initialize_information - * - * DESCRIPTION: - * +/** * This function initializes an object class information record. * SUPPORTS_GLOBAL is TRUE if the object class supports global * objects, and FALSE otherwise. Maximum indicates the number @@ -345,8 +458,17 @@ void _Objects_Shrink_information( * in bytes of each control block for this object class. The * name length and string designator are also set. In addition, * the class may be a task, therefore this information is also included. + * + * @param[in] information points to an object class information block. + * @param[in] the_api indicates the API associated with this information block. + * @param[in] the_class indicates the class of object being managed + * by this information block. It is specific to @a the_api. + * @param[in] maximum is the maximum number of instances of this object + * class which may be concurrently active. + * @param[in] size is the size of the data structure for this class. + * @param[in] is_string is TRUE if this object uses string style names. + * @param[in] maximum_name_length is the maximum length of object names. */ - void _Objects_Initialize_information ( Objects_Information *information, Objects_APIs the_api, @@ -362,125 +484,108 @@ void _Objects_Initialize_information ( #endif ); -/*PAGE - * - * _Objects_Allocate - * - * DESCRIPTION: - * +/** * This function allocates a object control block from * the inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. */ - Objects_Control *_Objects_Allocate( Objects_Information *information ); -/* - * _Objects_Allocate_by_index - * - * DESCRIPTION: - * +/** * This function allocates the object control block * specified by the index from the inactive chain of * free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] index is the index of the object to allocate. + * @param[in] sizeof_control is the size of the object control block. */ - Objects_Control *_Objects_Allocate_by_index( Objects_Information *information, uint16_t index, uint16_t sizeof_control ); -/*PAGE - * - * _Objects_Free - * - * DESCRIPTION: +/** * * This function frees a object control block to the * inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] the_object points to the object to deallocate. */ - void _Objects_Free( Objects_Information *information, Objects_Control *the_object ); -/* - * _Objects_Clear_name - * - * DESCRIPTION: - * +/** * This method zeroes out the name. + * + * @param[in] name points to the name to be zeroed out. + * @param[in] length is the length of the object name field. */ - void _Objects_Clear_name( void *name, uint16_t length ); -/* - * _Objects_Copy_name_string - * - * DESCRIPTION: - * +/** * This method copies a string style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_string( void *source, void *destination, uint16_t length ); -/* - * _Objects_Copy_name_raw - * - * DESCRIPTION: - * +/** * This method copies a raw style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_raw( void *source, void *destination, uint16_t length ); -/* - * _Objects_Compare_name_string - * - * DESCRIPTION: - * +/** * This method compares two string style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_string( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Compare_name_raw - * - * DESCRIPTION: - * +/** * This method compares two raw style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_raw( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Name_to_id - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object * identification directives. This directive returns the object * id associated with name. If more than one object of this class @@ -489,9 +594,7 @@ boolean _Objects_Compare_name_raw( * id of the object named name. If the object class supports global * objects, then the search can be limited to a particular node * or allowed to encompass all nodes. - * */ - typedef enum { OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL, OBJECTS_INVALID_NAME, @@ -500,9 +603,30 @@ typedef enum { OBJECTS_INVALID_NODE } Objects_Name_or_id_lookup_errors; +/** This macro defines the first entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL + +/** This macro defines the last entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE +/** + * This method converts an object name to an Id. It performs a look up + * using the object information block for this object class. + * + * @param[in] information points to an object class information block. + * @param[in] name is the name of the object to find. + * @param[in] node is the set of nodes to search. + * @param[in] id will contain the Id if the search is successful. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + */ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Information *information, Objects_Name name, @@ -510,30 +634,27 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Id *id ); -/* - * _Objects_Id_to_Name - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object Id * to name directives. This function returns the name * associated with object id. * - * NOTE: + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] name will contain the name of the object, if found. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a name will contain the name of + * the requested object. * - * This function currently does not support string names. + * @note This function currently does not support string names. */ - Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( Objects_Id id, Objects_Name *name ); -/* - * _Objects_Get - * - * DESCRIPTION: - * +/** * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location @@ -543,19 +664,51 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( * is undefined. Otherwise, location is set to OBJECTS_ERROR * and the_object is undefined. * - * NOTE: _Objects_Get returns with dispatching disabled for - * local and remote objects. - * _Objects_Get_isr_disable returns with dispatching - * disabled for remote objects and interrupts for local - * objects. + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. */ - Objects_Control *_Objects_Get ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * This function maps object ids to object control blocks. + * If id corresponds to a local object, then it returns + * the_object control pointer which maps to id and location + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * @param[in] level is the interrupt level being turned. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a name will contain the name of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_isr_disable( Objects_Information *information, Objects_Id id, @@ -563,27 +716,75 @@ Objects_Control *_Objects_Get_isr_disable( ISR_Level *level ); +/** + * This function maps object index to object control blocks which must. + * be local. The parameter the_object control pointer which maps to id + * and location is set to OBJECTS_LOCAL. Otherwise, location is set to + OBJECTS_ERROR and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns a pointer to the object associated with ID. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_by_index ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * This function maps object ids to object control blocks. + * If id corresponds to a local object, then it returns + * the_object control pointer which maps to id and location + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_no_protection( Objects_Information *information, Objects_Id id, Objects_Locations *location ); -/* - * _Objects_Get_next - * - * DESCRIPTION: +/** + * Like @ref _Objects_Get, but is used to find "next" open object. * - * Like _Objects_Get, but is used to find "next" open object. + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location_p will contain an indication of success or failure. + * @param[in] next_id_p is the Id of the next object we will look at. * + * @return This method returns the pointer to the object located or + * NULL on error. */ - Objects_Control *_Objects_Get_next( Objects_Information *information, Objects_Id id, -- cgit v1.2.3