RTEMS 6.1-rc6
Loading...
Searching...
No Matches
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Object Handler

This group contains the Object Handler implementation. More...

Modules

 Object Handler Multiprocessing (MP) Support
 This group contains the implementation to support the Object Handler in multiprocessing (MP) configurations.
 

Files

file  object.h
 This header file provides interfaces of the Object Handler which are used by the implementation and the Application Configuration.
 
file  objectdata.h
 This header file provides data structures used by the implementation and the Application Configuration to define instances of Objects_Information, _Objects_MP_Controls, and ultimately Thread_Configured_control.
 
file  objectimpl.h
 This header file provides interfaces of the Object Handler which are only used by the implementation.
 
file  objectactivecount.c
 This source file contains the implementation of _Objects_Active_count().
 
file  objectallocate.c
 This source file contains the implementation of _Objects_Allocate().
 
file  objectallocatenone.c
 This source file contains the implementation of _Objects_Allocate_none().
 
file  objectallocatestatic.c
 This source file contains the implementation of _Objects_Allocate_static().
 
file  objectallocateunlimited.c
 This source file contains the implementation of _Objects_Allocate_unlimited().
 
file  objectapimaximumclass.c
 This source file contains the implementation of _Objects_API_maximum_class().
 
file  objectclose.c
 This source file contains the implementation of _Objects_Close().
 
file  objectextendinformation.c
 This source file contains the implementation of _Objects_Extend_information().
 
file  objectfree.c
 This source file contains the implementation of _Objects_Free_unlimited().
 
file  objectfreenothing.c
 This source file contains the implementation of _Objects_Free_nothing().
 
file  objectfreestatic.c
 This source file contains the implementation of _Objects_Free_static().
 
file  objectgetinfo.c
 This source file contains the implementation of _Objects_Get_information().
 
file  objectgetinfoid.c
 This source file contains the implementation of _Objects_Get_information_id().
 
file  objectgetlocal.c
 This source file contains the implementation of _Objects_Get().
 
file  objectgetnameasstring.c
 This source file contains the implementation of _Objects_Name_to_string() and _Objects_Get_name_as_string().
 
file  objectgetnext.c
 This source file contains the implementation of _Objects_Get_next().
 
file  objectgetnoprotection.c
 This source file contains the implementation of _Objects_Get_no_protection().
 
file  objectidtoname.c
 This source file contains the implementation of _Objects_Id_to_name().
 
file  objectinitializeinformation.c
 This source file contains the implementation of _Objects_Initialize_information().
 
file  objectnamespaceremove.c
 This source file contains the implementation of _Objects_Namespace_remove_string().
 
file  objectnametoid.c
 This source file contains the implementation of _Objects_Name_to_id_u32().
 
file  objectnametoidstring.c
 This source file contains the implementation of _Objects_Get_by_name().
 
file  objectsetname.c
 This source file contains the implementation of _Objects_Set_name().
 
file  objectshrinkinformation.c
 This source file contains the implementation of _Objects_Free_objects_block() and _Objects_Shrink_information().
 

Data Structures

union  Objects_Name
 
struct  Objects_Control
 
struct  Objects_Information
 The information structure used to manage each API class of objects. More...
 

Macros

#define OBJECTS_INDEX_START_BIT   0U
 
#define OBJECTS_NODE_START_BIT   16U
 
#define OBJECTS_API_START_BIT   24U
 
#define OBJECTS_CLASS_START_BIT   27U
 
#define OBJECTS_INDEX_MASK   (Objects_Id)0x0000ffffU
 
#define OBJECTS_NODE_MASK   (Objects_Id)0x00ff0000U
 
#define OBJECTS_API_MASK   (Objects_Id)0x07000000U
 
#define OBJECTS_CLASS_MASK   (Objects_Id)0xf8000000U
 
#define OBJECTS_INDEX_VALID_BITS   (Objects_Id)0x0000ffffU
 
#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ffU
 
#define OBJECTS_API_VALID_BITS   (Objects_Id)0x00000007U
 
#define OBJECTS_CLASS_VALID_BITS   (Objects_Id)0x0000001fU
 
#define OBJECTS_UNLIMITED_OBJECTS   0x80000000U
 
#define OBJECTS_ID_INITIAL_INDEX   (0)
 
#define OBJECTS_ID_FINAL_INDEX   (0xffffU)
 
#define OBJECTS_APIS_LAST   OBJECTS_POSIX_API
 
#define OBJECTS_ID_NONE   0
 
#define OBJECTS_ID_OF_SELF   ((Objects_Id) 0)
 
#define OBJECTS_SEARCH_ALL_NODES   0
 
#define OBJECTS_SEARCH_OTHER_NODES   0x7FFFFFFE
 
#define OBJECTS_SEARCH_LOCAL_NODE   0x7FFFFFFF
 
#define OBJECTS_WHO_AM_I   0
 
#define OBJECTS_ID_INITIAL(_api, _class, _node)    _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )
 
#define OBJECTS_ID_FINAL   ((Objects_Id)~0)
 
#define _Objects_Build_name(_C1, _C2, _C3, _C4)
 
#define _Objects_Build_id(the_api, the_class, node, index)
 Builds an object ID from its components.
 
#define _Objects_Is_unlimited(maximum)    ( ( ( maximum ) & OBJECTS_UNLIMITED_OBJECTS ) != 0 )
 
#define _Objects_Maximum_per_allocation(maximum)    ((Objects_Maximum) ((maximum) & ~OBJECTS_UNLIMITED_OBJECTS))
 
#define _Objects_Local_node   ((uint16_t) 1)
 The local MPCI node number.
 
#define OBJECTS_NO_STRING_NAME   0
 Constant for the object information string name length to indicate that this object class has no string names.
 
#define OBJECTS_INFORMATION_MP(name, extract)
 
#define OBJECTS_INFORMATION_DEFINE_ZERO(name, api, cls, nl)
 Statically initializes an objects information.
 
#define OBJECTS_INFORMATION_DEFINE(name, api, cls, type, max, nl, ex)
 Statically initializes an objects information.
 
#define OBJECTS_INTERNAL_CLASSES_LAST   OBJECTS_INTERNAL_THREADS
 
#define OBJECTS_RTEMS_CLASSES_LAST   OBJECTS_RTEMS_BARRIERS
 
#define OBJECTS_POSIX_CLASSES_LAST   OBJECTS_POSIX_SHMS
 
#define _Objects_Maximum_nodes   1
 
#define OBJECTS_INDEX_MINIMUM   1U
 

Typedefs

typedef uint32_t Objects_Id
 
typedef uint16_t Objects_Maximum
 
typedef struct Objects_Information Objects_Information
 
typedef bool(* Objects_Name_comparators) (void *, void *, uint16_t)
 

Enumerations

enum  Objects_APIs {
  OBJECTS_NO_API = 0 , OBJECTS_INTERNAL_API = 1 , OBJECTS_CLASSIC_API = 2 , OBJECTS_POSIX_API = 3 ,
  OBJECTS_FAKE_OBJECTS_API = 7
}
 
enum  Objects_Internal_API { OBJECTS_INTERNAL_NO_CLASS = 0 , OBJECTS_INTERNAL_THREADS = 1 }
 
enum  Objects_Classic_API {
  OBJECTS_CLASSIC_NO_CLASS = 0 , OBJECTS_RTEMS_TASKS = 1 , OBJECTS_RTEMS_TIMERS , OBJECTS_RTEMS_SEMAPHORES ,
  OBJECTS_RTEMS_MESSAGE_QUEUES , OBJECTS_RTEMS_PARTITIONS , OBJECTS_RTEMS_REGIONS , OBJECTS_RTEMS_PORTS ,
  OBJECTS_RTEMS_PERIODS , OBJECTS_RTEMS_EXTENSIONS , OBJECTS_RTEMS_BARRIERS
}
 
enum  Objects_POSIX_API {
  OBJECTS_POSIX_NO_CLASS = 0 , OBJECTS_POSIX_THREADS = 1 , OBJECTS_POSIX_KEYS , OBJECTS_POSIX_MESSAGE_QUEUES ,
  OBJECTS_POSIX_SEMAPHORES , OBJECTS_POSIX_TIMERS , OBJECTS_POSIX_SHMS
}
 
enum  Objects_Fake_objects_API { OBJECTS_FAKE_OBJECTS_NO_CLASS = 0 , OBJECTS_FAKE_OBJECTS_SCHEDULERS = 1 }
 
enum  Objects_Get_by_name_error { OBJECTS_GET_BY_NAME_INVALID_NAME , OBJECTS_GET_BY_NAME_NAME_TOO_LONG , OBJECTS_GET_BY_NAME_NO_OBJECT }
 

Functions

Objects_Control_Objects_Allocate_none (Objects_Information *information)
 Always return NULL.
 
Objects_Control_Objects_Allocate_static (Objects_Information *information)
 Return an inactive object or NULL.
 
Objects_Control_Objects_Allocate_unlimited (Objects_Information *information)
 Return an inactive object or NULL.
 
void _Objects_Free_static (Objects_Information *information, Objects_Control *the_object)
 Free the object.
 
void _Objects_Free_unlimited (Objects_Information *information, Objects_Control *the_object)
 Free the object.
 
Objects_Maximum _Objects_Extend_information (Objects_Information *information)
 Extends an object class information record.
 
void _Objects_Free_objects_block (Objects_Information *information, Objects_Maximum block)
 Free the objects block with the specified index.
 
void _Objects_Shrink_information (Objects_Information *information)
 Shrinks an object class information record.
 
void _Objects_Initialize_information (Objects_Information *information)
 Initializes the specified objects information.
 
unsigned int _Objects_API_maximum_class (uint32_t api)
 Returns highest numeric value of a valid API for the specified API.
 
Objects_Control_Objects_Allocate (Objects_Information *information)
 Allocates an object.
 
Status_Control _Objects_Name_to_id_u32 (uint32_t name, uint32_t node, Objects_Id *id, const Objects_Information *information)
 Searches an object of the specified class with the specified name on the specified set of nodes.
 
Objects_Control_Objects_Get_by_name (const Objects_Information *information, const char *name, size_t *name_length_p, Objects_Get_by_name_error *error)
 Gets an object control block identified by its name.
 
Status_Control _Objects_Id_to_name (Objects_Id id, Objects_Name *name)
 Returns the name associated with object id.
 
Objects_Control_Objects_Get (Objects_Id id, ISR_lock_Context *lock_context, const Objects_Information *information)
 Maps the specified object identifier to the associated local object control block.
 
Objects_Control_Objects_Get_no_protection (Objects_Id id, const Objects_Information *information)
 Maps object ids to object control blocks.
 
Objects_Control_Objects_Get_next (Objects_Id id, const Objects_Information *information, Objects_Id *next_id_p)
 Gets the next open object after the specified object identifier.
 
Objects_Information_Objects_Get_information (Objects_APIs the_api, uint16_t the_class)
 Gets object information.
 
Objects_Information_Objects_Get_information_id (Objects_Id id)
 Gets information of an object from an ID.
 
char * _Objects_Get_name_as_string (Objects_Id id, size_t length, char *name)
 Gets object name in the form of a C string.
 
size_t _Objects_Name_to_string (Objects_Name name, bool is_string, char *buffer, size_t buffer_size)
 Converts the specified object name to a text representation.
 
Status_Control _Objects_Set_name (const Objects_Information *information, Objects_Control *the_object, const char *name)
 Sets objects name.
 
void _Objects_Namespace_remove_string (const Objects_Information *information, Objects_Control *the_object)
 Removes object with a string name from its namespace.
 
void _Objects_Close (const Objects_Information *information, Objects_Control *the_object)
 Closes object.
 
Objects_Maximum _Objects_Active_count (const Objects_Information *information)
 Returns the count of active objects.
 
void _Objects_Free_nothing (void *ptr)
 This function does nothing.
 

Variables

Objects_Information **const _Objects_Information_table [OBJECTS_APIS_LAST+1]
 

Detailed Description

This group contains the Object Handler implementation.

This handler provides mechanisms which can be used to initialize and manipulate all objects which have identifiers.

Macro Definition Documentation

◆ _Objects_Build_id

#define _Objects_Build_id (   the_api,
  the_class,
  node,
  index 
)
Value:
( (Objects_Id) ( (Objects_Id) the_api << OBJECTS_API_START_BIT ) | \
( (Objects_Id) the_class << OBJECTS_CLASS_START_BIT ) | \
#define OBJECTS_NODE_START_BIT
Definition: object.h:118
uint32_t Objects_Id
Definition: object.h:101
#define OBJECTS_INDEX_START_BIT
Definition: object.h:113
#define OBJECTS_API_START_BIT
Definition: object.h:124
#define OBJECTS_CLASS_START_BIT
Definition: object.h:130

Builds an object ID from its components.

Parameters
the_apiThe object API.
the_classThe object API class.
nodeThe object node.
indexThe object index.
Returns
Returns the object ID constructed from the arguments.

◆ _Objects_Build_name

#define _Objects_Build_name (   _C1,
  _C2,
  _C3,
  _C4 
)
Value:
( (uint32_t) (uint8_t) (_C1) << 24 | \
(uint32_t) (uint8_t) (_C2) << 16 | \
(uint32_t) (uint8_t) (_C3) << 8 | \
(uint8_t) (_C4) )

This macro is used to build a thirty-two bit style name from four characters. The most significant byte will be the character _C1.

Parameters
[in]_C1is the first character of the name
[in]_C2is the second character of the name
[in]_C3is the third character of the name
[in]_C4is the fourth character of the name

◆ _Objects_Is_unlimited

#define _Objects_Is_unlimited (   maximum)     ( ( ( maximum ) & OBJECTS_UNLIMITED_OBJECTS ) != 0 )

Returns if the object maximum specifies unlimited objects.

Parameters
[in]maximumThe object maximum specification.
Return values
trueUnlimited objects are available.
falseThe object count is fixed.

◆ _Objects_Maximum_nodes

#define _Objects_Maximum_nodes   1

The following is referenced to the number of nodes in the system.

◆ OBJECTS_API_MASK

#define OBJECTS_API_MASK   (Objects_Id)0x07000000U

This mask is used to extract the API portion of an object Id.

◆ OBJECTS_API_START_BIT

#define OBJECTS_API_START_BIT   24U

This is the bit position of the starting bit of the API portion of the object Id.

◆ OBJECTS_API_VALID_BITS

#define OBJECTS_API_VALID_BITS   (Objects_Id)0x00000007U

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.

◆ OBJECTS_APIS_LAST

#define OBJECTS_APIS_LAST   OBJECTS_POSIX_API

This macro is used to generically specify the last API index.

◆ OBJECTS_CLASS_MASK

#define OBJECTS_CLASS_MASK   (Objects_Id)0xf8000000U

This mask is used to extract the class portion of an object Id.

◆ OBJECTS_CLASS_START_BIT

#define OBJECTS_CLASS_START_BIT   27U

This is the bit position of the starting bit of the class portion of the object Id.

◆ OBJECTS_CLASS_VALID_BITS

#define OBJECTS_CLASS_VALID_BITS   (Objects_Id)0x0000001fU

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.

◆ OBJECTS_ID_FINAL

#define OBJECTS_ID_FINAL   ((Objects_Id)~0)

This macro specifies the highest object ID value

◆ OBJECTS_ID_FINAL_INDEX

#define OBJECTS_ID_FINAL_INDEX   (0xffffU)

This is the highest value for the index portion of an object Id.

◆ OBJECTS_ID_INITIAL

#define OBJECTS_ID_INITIAL (   _api,
  _class,
  _node 
)     _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX )

This macros calculates the lowest ID for the specified api, class, and node.

◆ OBJECTS_ID_INITIAL_INDEX

#define OBJECTS_ID_INITIAL_INDEX   (0)

This is the lowest value for the index portion of an object Id.

◆ OBJECTS_ID_NONE

#define OBJECTS_ID_NONE   0

No object can have this ID.

◆ OBJECTS_ID_OF_SELF

#define OBJECTS_ID_OF_SELF   ((Objects_Id) 0)

The following defines the constant which may be used to manipulate the calling task.

◆ OBJECTS_INDEX_MASK

#define OBJECTS_INDEX_MASK   (Objects_Id)0x0000ffffU

This mask is used to extract the index portion of an object Id.

◆ OBJECTS_INDEX_MINIMUM

#define OBJECTS_INDEX_MINIMUM   1U

This is the minimum object ID index associated with an object.

◆ OBJECTS_INDEX_START_BIT

#define OBJECTS_INDEX_START_BIT   0U

This is the bit position of the starting bit of the index portion of the object Id.

◆ OBJECTS_INDEX_VALID_BITS

#define OBJECTS_INDEX_VALID_BITS   (Objects_Id)0x0000ffffU

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.

◆ OBJECTS_INFORMATION_DEFINE

#define OBJECTS_INFORMATION_DEFINE (   name,
  api,
  cls,
  type,
  max,
  nl,
  ex 
)
Value:
static Objects_Control * \
name##_Local_table[ _Objects_Maximum_per_allocation( max ) ]; \
static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
type \
name##_Objects[ _Objects_Maximum_per_allocation( max ) ]; \
Objects_Information name##_Information = { \
_Objects_Build_id( api, cls, 1, _Objects_Maximum_per_allocation( max ) ), \
name##_Local_table, \
_Objects_Is_unlimited( max ) ? \
_Objects_Is_unlimited( max ) ? \
0, \
_Objects_Is_unlimited( max ) ? _Objects_Maximum_per_allocation( max ) : 0, \
sizeof( type ), \
nl, \
CHAIN_INITIALIZER_EMPTY( name##_Information.Inactive ), \
NULL, \
NULL, \
&name##_Objects[ 0 ].Object \
OBJECTS_INFORMATION_MP( name##_Information, ex ) \
}
#define RTEMS_SECTION(_section)
Instructs the compiler to place the variable or function in the section.
Definition: basedefs.h:411
#define CHAIN_INITIALIZER_EMPTY(name)
Chain initializer for an empty chain with designator name.
Definition: chainimpl.h:59
void _Objects_Free_static(Objects_Information *information, Objects_Control *the_object)
Free the object.
Definition: objectfreestatic.c:44
Objects_Control * _Objects_Allocate_static(Objects_Information *information)
Return an inactive object or NULL.
Definition: objectallocatestatic.c:44
Objects_Control * _Objects_Allocate_unlimited(Objects_Information *information)
Return an inactive object or NULL.
Definition: objectallocateunlimited.c:49
void _Objects_Free_unlimited(Objects_Information *information, Objects_Control *the_object)
Free the object.
Definition: objectfree.c:45
Definition: objectdata.h:61
The information structure used to manage each API class of objects.
Definition: objectdata.h:198

Statically initializes an objects information.

The initialized objects information references a table with statically allocated objects as specified by the object maximum parameter. These objects must be registered via a call to _Objects_Information().

Parameters
nameThe object class C designator namespace prefix, e.g. _Semaphore.
apiThe object API number, e.g. OBJECTS_CLASSIC_API.
clsThe object class number, e.g. OBJECTS_RTEMS_SEMAPHORES.
typeThe object class type.
maxThe configured object maximum (the OBJECTS_UNLIMITED_OBJECTS flag may be set).
nlThe object name string length, use OBJECTS_NO_STRING_NAME for objects without a string name.
exThe optional object extraction method. Used only if multiprocessing (RTEMS_MULTIPROCESSING) is enabled.

◆ OBJECTS_INFORMATION_DEFINE_ZERO

#define OBJECTS_INFORMATION_DEFINE_ZERO (   name,
  api,
  cls,
  nl 
)
Value:
Objects_Information name##_Information = { \
_Objects_Build_id( api, cls, 1, 0 ), \
NULL, \
NULL, \
0, \
0, \
0, \
nl, \
CHAIN_INITIALIZER_EMPTY( name##_Information.Inactive ), \
NULL, \
NULL, \
NULL \
OBJECTS_INFORMATION_MP( name##_Information, NULL ) \
}
Objects_Control * _Objects_Allocate_none(Objects_Information *information)
Always return NULL.
Definition: objectallocatenone.c:43

Statically initializes an objects information.

The initialized objects information contains no objects.

Parameters
nameThe object class C designator namespace prefix, e.g. _Semaphore.
apiThe object API number, e.g. OBJECTS_CLASSIC_API.
clsThe object class number, e.g. OBJECTS_RTEMS_SEMAPHORES.
nlThe object name string length, use OBJECTS_NO_STRING_NAME for objects without a string name.

◆ OBJECTS_INTERNAL_CLASSES_LAST

#define OBJECTS_INTERNAL_CLASSES_LAST   OBJECTS_INTERNAL_THREADS

This macro is used to generically specify the last API index.

◆ OBJECTS_NODE_MASK

#define OBJECTS_NODE_MASK   (Objects_Id)0x00ff0000U

This mask is used to extract the node portion of an object Id.

◆ OBJECTS_NODE_START_BIT

#define OBJECTS_NODE_START_BIT   16U

This is the bit position of the starting bit of the node portion of the object Id.

◆ OBJECTS_NODE_VALID_BITS

#define OBJECTS_NODE_VALID_BITS   (Objects_Id)0x000000ffU

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.

◆ OBJECTS_POSIX_CLASSES_LAST

#define OBJECTS_POSIX_CLASSES_LAST   OBJECTS_POSIX_SHMS

This macro is used to generically specify the last API index.

◆ OBJECTS_RTEMS_CLASSES_LAST

#define OBJECTS_RTEMS_CLASSES_LAST   OBJECTS_RTEMS_BARRIERS

This macro is used to generically specify the last API index.

◆ OBJECTS_SEARCH_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.

◆ OBJECTS_SEARCH_LOCAL_NODE

#define OBJECTS_SEARCH_LOCAL_NODE   0x7FFFFFFF

The following constant is used to specify that a name to ID search should search only on this node.

◆ OBJECTS_SEARCH_OTHER_NODES

#define OBJECTS_SEARCH_OTHER_NODES   0x7FFFFFFE

The following constant is used to specify that a name to ID search should search through all nodes except the current node.

◆ OBJECTS_UNLIMITED_OBJECTS

#define OBJECTS_UNLIMITED_OBJECTS   0x80000000U

Mask to enable unlimited objects. This is used in the configuration table when specifying the number of configured objects.

◆ OBJECTS_WHO_AM_I

#define OBJECTS_WHO_AM_I   0

The following constant is used to specify that a name to ID search is being asked for the ID of the currently executing task.

Typedef Documentation

◆ Objects_Id

typedef uint32_t Objects_Id

The following type defines the control block used to manage object IDs. The format is as follows (0=LSB):

Bits 0 .. 15 = index (up to 65535 objects of a type) Bits 16 .. 23 = node (up to 255 nodes) Bits 24 .. 26 = API (up to 7 API classes) Bits 27 .. 31 = class (up to 31 object types per API)

◆ Objects_Maximum

typedef uint16_t Objects_Maximum

This type is used to store the maximum number of allowed objects of each type.

◆ Objects_Name_comparators

typedef bool(* Objects_Name_comparators) (void *, void *, uint16_t)

Functions which compare names are prototyped like this.

Enumeration Type Documentation

◆ Objects_APIs

This enumerated type is used in the class field of the object ID.

◆ Objects_Classic_API

This enumerated type is used in the class field of the object ID for the RTEMS Classic API.

◆ Objects_Internal_API

This enumerated type is used in the class field of the object ID for RTEMS internal object classes.

◆ Objects_POSIX_API

This enumerated type is used in the class field of the object ID for the POSIX API.

Function Documentation

◆ _Objects_Active_count()

Objects_Maximum _Objects_Active_count ( const Objects_Information information)

Returns the count of active objects.

Parameters
informationThe object information table.
Returns
The count of active objects.

◆ _Objects_Allocate()

Objects_Control * _Objects_Allocate ( Objects_Information information)

Allocates an object.

This function locks the object allocator mutex via _Objects_Allocator_lock(). The caller must later unlock the object allocator mutex via _Objects_Allocator_unlock(). The caller must unlock the mutex in any case, even if the allocation failed due to resource shortage.

A typical object allocation code looks like this:

rtems_status_code some_create( rtems_id *id )
{
Some_Control *some;
// The object allocator mutex protects the executing thread from
// asynchronous thread restart and deletion.
some = (Some_Control *) _Objects_Allocate( &_Some_Information );
if ( some != NULL ) {
_Some_Initialize( some );
} else {
}
_Objects_Allocator_unlock();
return sc;
}
rtems_status_code
This enumeration provides status codes for directives of the Classic API.
Definition: status.h:85
@ RTEMS_SUCCESSFUL
This status code indicates successful completion of a requested operation.
Definition: status.h:90
@ RTEMS_TOO_MANY
This status code indicates you have attempted to create too many instances of a particular object cla...
Definition: status.h:116
Objects_Id rtems_id
This type represents RTEMS object identifiers.
Definition: types.h:94
Objects_Control * _Objects_Allocate(Objects_Information *information)
Allocates an object.
Definition: objectallocate.c:43
Parameters
[in,out]informationThe object information block.
Return values
objectThe allocated object.
NULLNo object available.
See also
_Objects_Free().

◆ _Objects_Allocate_none()

Objects_Control * _Objects_Allocate_none ( Objects_Information information)

Always return NULL.

Parameters
informationThe objects information.
Return values
NULLAlways.

◆ _Objects_Allocate_static()

Objects_Control * _Objects_Allocate_static ( Objects_Information information)

Return an inactive object or NULL.

Parameters
informationThe objects information.
Return values
NULLNo inactive object is available.
objectAn inactive object.

◆ _Objects_Allocate_unlimited()

Objects_Control * _Objects_Allocate_unlimited ( Objects_Information information)

Return an inactive object or NULL.

Try to extend the objects information if necessary.

Parameters
informationThe objects information.
Return values
NULLNo inactive object is available.
objectAn inactive object.

◆ _Objects_API_maximum_class()

unsigned int _Objects_API_maximum_class ( uint32_t  api)

Returns highest numeric value of a valid API for the specified API.

This function returns the highest numeric value of a valid API for the specified api.

Parameters
apiThe API of interest.
Return values
some_valuePositive integer on success.
0The method failed.

◆ _Objects_Close()

void _Objects_Close ( const Objects_Information information,
Objects_Control the_object 
)

Closes object.

This function removes the_object control pointer and object name in the Local Pointer and Local Name Tables.

Parameters
informationPoints to an Object Information Table.
[out]the_objectA pointer to an object.

◆ _Objects_Extend_information()

Objects_Maximum _Objects_Extend_information ( Objects_Information information)

Extends an object class information record.

Parameters
informationPoints to an object class information block.
Return values
0The extend operation failed.
blockThe block index of the new objects block.

◆ _Objects_Free_nothing()

void _Objects_Free_nothing ( void *  ptr)

This function does nothing.

Parameters
ptris not used.

◆ _Objects_Free_objects_block()

void _Objects_Free_objects_block ( Objects_Information information,
Objects_Maximum  block 
)

Free the objects block with the specified index.

Parameters
informationThe objects information.
blockThe block index.

◆ _Objects_Free_static()

void _Objects_Free_static ( Objects_Information information,
Objects_Control the_object 
)

Free the object.

Append the object to the inactive chain of the objects information.

Parameters
informationThe objects information.
the_objectThe object to free.

◆ _Objects_Free_unlimited()

void _Objects_Free_unlimited ( Objects_Information information,
Objects_Control the_object 
)

Free the object.

Append the object to the inactive chain of the objects information and shrink the objects information if necessary.

Parameters
informationThe objects information.
the_objectThe object to free.

◆ _Objects_Get()

Objects_Control * _Objects_Get ( Objects_Id  id,
ISR_lock_Context lock_context,
const Objects_Information information 
)

Maps the specified object identifier to the associated local object control block.

In this function interrupts are disabled during the object lookup. In case an associated object exists, then interrupts remain disabled, otherwise the previous interrupt state is restored.

Parameters
idThe object identifier. This is the first parameter since usual callers get the object identifier as the first parameter themself.
lock_contextThe interrupt lock context. This is the second parameter since usual callers get the interrupt lock context as the second parameter themself.
informationThe object class information block.
Return values
pointerThe pointer to the associated object control block. Interrupts are now disabled and must be restored using the specified lock context via _ISR_lock_ISR_enable() or _ISR_lock_Release_and_ISR_enable().
NULLNo associated object exists.

◆ _Objects_Get_by_name()

Objects_Control * _Objects_Get_by_name ( const Objects_Information information,
const char *  name,
size_t *  name_length_p,
Objects_Get_by_name_error *  error 
)

Gets an object control block identified by its name.

The object information must use string names.

Parameters
informationThe object information. Must not be NULL.
nameThe object name.
[out]name_length_pOptional parameter to return the name length.
[out]errorThe error indication in case of failure. Must not be NULL.
Return values
pointerThe first object according to object index associated with this name.
NULLNo object exists for this name or invalid parameters.

◆ _Objects_Get_information()

Objects_Information * _Objects_Get_information ( Objects_APIs  the_api,
uint16_t  the_class 
)

Gets object information.

This function returns the information structure given an API and Class. This can be done independent of the existence of any objects created by the API.

Parameters
the_apiIndicates the API for the information we want
the_classIndicates the Class for the information we want
Return values
pointerPointer to the Object Information Table for the class of objects which corresponds to this object ID.
NULLAn error occurred.

◆ _Objects_Get_information_id()

Objects_Information * _Objects_Get_information_id ( Objects_Id  id)

Gets information of an object from an ID.

This function returns the information structure given an id of an object.

Parameters
idThe object ID to get the information from.
Return values
pointerPointer to the Object Information Table for the class of objects which corresponds to this object ID.
NULLAn error occurred.

◆ _Objects_Get_name_as_string()

char * _Objects_Get_name_as_string ( Objects_Id  id,
size_t  length,
char *  name 
)

Gets object name in the form of a C string.

This method gets the name of an object and returns its name in the form of a C string. It attempts to be careful about overflowing the user's string and about returning unprintable characters.

Parameters
idThe object to obtain the name of.
lengthIndicates the length of the caller's buffer.
[out]nameA string which will be filled in.
Return values

a name The operation was succeeded and the string was correctly filled in.

Return values
NULLAn error occurred.

◆ _Objects_Get_next()

Objects_Control * _Objects_Get_next ( Objects_Id  id,
const Objects_Information information,
Objects_Id next_id_p 
)

Gets the next open object after the specified object identifier.

Locks the object allocator mutex in case a next object exists.

Parameters
idThe Id of the object whose name we are locating. This is the first parameter since usual callers get the object identifier as the first parameter themself.
informationPoints to an object class information block.
[in,out]next_id_pThe Id of the next object we will look at.
Return values
pointerPointer to the located object.
NULLAn error occurred.

◆ _Objects_Get_no_protection()

Objects_Control * _Objects_Get_no_protection ( Objects_Id  id,
const Objects_Information information 
)

Maps object ids to object control blocks.

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.

Parameters
idThe Id of the object whose name we are locating. This is the first parameter since usual callers get the object identifier as the first parameter themself.
informationPoints to an object class information block.
Return values
pointerThe local object corresponding to the given id.
NULLThe object to the given id was not found locally.

◆ _Objects_Id_to_name()

Status_Control _Objects_Id_to_name ( Objects_Id  id,
Objects_Name name 
)

Returns the name associated with object id.

This function implements the common portion of the object Id to name directives. This function returns the name associated with object id.

Parameters
idis the Id of the object whose name we are locating.
[out]namewill contain the name of the object, if found.
Return values
STATUS_SUCCESSFULThe operation succeeded. name contains the name of the object.
STATUS_INVALID_IDThe id is invalid, the operation failed.
Note
This function currently does not support string names.

◆ _Objects_Initialize_information()

void _Objects_Initialize_information ( Objects_Information information)

Initializes the specified objects information.

The objects information must be statically pre-initialized with the OBJECTS_INFORMATION_DEFINE() macro before this function is called.

Parameters
informationThe object information to be initialized.

◆ _Objects_Name_to_id_u32()

Status_Control _Objects_Name_to_id_u32 ( uint32_t  name,
uint32_t  node,
Objects_Id id,
const Objects_Information information 
)

Searches an object of the specified class with the specified name on the specified set of nodes.

This method converts an object name to an identifier. It performs a look up using the object information block for this object class.

Parameters
nameis the name of the object to find.
nodeis the set of nodes to search.
[out]idis the pointer to an object identifier variable or NULL. The object identifier will be stored in the referenced variable, if the operation was successful.
informationis the pointer to an object class information block.
Return values
STATUS_SUCCESSFULThe operations was successful.
STATUS_INVALID_ADDRESSThe id parameter was NULL.
STATUS_INVALID_NAMENo object exists with the specified name on the specified node set.

◆ _Objects_Name_to_string()

size_t _Objects_Name_to_string ( Objects_Name  name,
bool  is_string,
char *  buffer,
size_t  buffer_size 
)

Converts the specified object name to a text representation.

Non-printable characters according to isprint() are converted to '*'.

Parameters
nameThe object name.
is_stringIndicates if the object name is a string or a four character array (32-bit unsigned integer).
[out]bufferThe string buffer for the text representation.
buffer_sizeThe buffer size in characters.
Returns
The length of the text representation. May be greater than or equal to the buffer size if truncation occurred.

◆ _Objects_Namespace_remove_string()

void _Objects_Namespace_remove_string ( const Objects_Information information,
Objects_Control the_object 
)

Removes object with a string name from its namespace.

Parameters
informationThe corresponding object information table.
[out]the_objectThe object the object to operate upon.

◆ _Objects_Set_name()

Status_Control _Objects_Set_name ( const Objects_Information information,
Objects_Control the_object,
const char *  name 
)

Sets objects name.

This method sets the object name to either a copy of a string or up to the first four characters of the string based upon whether this object class uses strings for names.

Parameters
informationpoints to the object information.
[out]the_objectis the object to operate upon.
nameis a pointer to the name to use.
Return values
STATUS_SUCCESSFULThe operation succeeded.
STATUS_NO_MEMORYThere was no memory available to duplicate the name.

◆ _Objects_Shrink_information()

void _Objects_Shrink_information ( Objects_Information information)

Shrinks an object class information record.

This function shrinks an object class information record. The object's name and object space are released. The local_table etc block does not shrink. The InActive list needs to be scanned to find the objects are remove them.

Parameters
informationPoints to an object class information block.

Variable Documentation

◆ _Objects_Information_table

Objects_Information** const _Objects_Information_table[OBJECTS_APIS_LAST+1]
extern

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.