RTEMS provides a collection of services to assist in the management and usage of the objects created and utilized via other managers. These services assist in the manipulation of RTEMS objects independent of the API used to create them. More...

Data Structures
struct	rtems_object_api_class_information
	This structure is used to return information to the application about the objects configured for a specific API/Class combination. More...

Macros
#define	rtems_object_id_api_minimum(void) OBJECTS_INTERNAL_API
	Gets the lowest valid value for the API component of an object identifier. More...

#define	rtems_object_id_api_maximum(void) OBJECTS_APIS_LAST
	Gets the highest valid value for the API component of an object identifier. More...

#define	RTEMS_OBJECT_ID_FINAL OBJECTS_ID_FINAL
	This constant represents the highest object identifier value.

#define	RTEMS_OBJECT_ID_FINAL_INDEX OBJECTS_ID_FINAL_INDEX
	This constant represents the highest value for the index component of an object identifier.

#define	RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) OBJECTS_ID_INITIAL( _api, _class, _node )
	Builds the object identifier with the lowest index from the API, class, and MPCI node components. More...

#define	RTEMS_OBJECT_ID_INITIAL_INDEX OBJECTS_ID_INITIAL_INDEX
	This constant represents the lowest value for the index component of an object identifier.

#define	RTEMS_SEARCH_ALL_NODES OBJECTS_SEARCH_ALL_NODES
	This constant indicates that an object name to identifier search should search through all MPCI nodes of the system.

#define	RTEMS_SEARCH_LOCAL_NODE OBJECTS_SEARCH_LOCAL_NODE
	This constant indicates that an object name to identifier search should search only the local MPCI node of the system.

#define	RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES
	This constant indicates that an object name to identifier search should search through all MPCI nodes of the system except the local node.

#define	RTEMS_WHO_AM_I OBJECTS_WHO_AM_I
	This constant indicates that an object name to identifier search is being asked for the identifier of the currently executing task.

Functions
rtems_id	rtems_build_id (uint32_t api, uint32_t the_class, uint32_t node, uint32_t index)
	Builds the object identifier from the API, class, MPCI node, and index components. More...

rtems_name	rtems_build_name (char c1, char c2, char c3, char c4)
	Builds the object name composed of the four characters. More...

rtems_status_code	rtems_object_get_classic_name (rtems_id id, rtems_name *name)
	Gets the object name associated with the object identifier. More...

char *	rtems_object_get_name (rtems_id id, size_t length, char *name)
	Gets the object name associated with the object identifier as a string. More...

rtems_status_code	rtems_object_set_name (rtems_id id, const char *name)
	Sets the object name of the object associated with the object identifier. More...

int	rtems_object_id_get_api (rtems_id id)
	Gets the API component of the object identifier. More...

int	rtems_object_id_get_class (rtems_id id)
	Gets the class component of the object identifier. More...

int	rtems_object_id_get_node (rtems_id id)
	Gets the MPCI node component of the object identifier. More...

int	rtems_object_id_get_index (rtems_id id)
	Gets the index component of the object identifier. More...

int	rtems_object_api_minimum_class (int api)
	Gets the lowest valid class value of the object API. More...

int	rtems_object_api_maximum_class (int api)
	Gets the highest valid class value of the object API. More...

const char *	rtems_object_get_api_name (int api)
	Gets a descriptive name of the object API. More...

const char *	rtems_object_get_api_class_name (int the_api, int the_class)
	Gets a descriptive name of the object class of the object API. More...

rtems_status_code	rtems_object_get_class_information (int the_api, int the_class, rtems_object_api_class_information *info)
	Gets the object class information of the object class of the object API. More...

Detailed Description

RTEMS provides a collection of services to assist in the management and usage of the objects created and utilized via other managers. These services assist in the manipulation of RTEMS objects independent of the API used to create them.

Macro Definition Documentation

◆ rtems_object_id_api_maximum

int rtems_object_id_api_maximum ( void ) OBJECTS_APIS_LAST

Gets the highest valid value for the API component of an object identifier.

Returns: Returns the highest valid value for the API component of an object identifier.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_id_api_minimum

int rtems_object_id_api_minimum ( void ) OBJECTS_INTERNAL_API

Gets the lowest valid value for the API component of an object identifier.

Returns: Returns the lowest valid value for the API component of an object identifier.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ RTEMS_OBJECT_ID_INITIAL

#define RTEMS_OBJECT_ID_INITIAL	(	_api,
		_class,
		_node
	)	OBJECTS_ID_INITIAL( _api, _class, _node )

Builds the object identifier with the lowest index from the API, class, and MPCI node components.

Parameters

_api	is the API of the object identifier to build.
_class	is the class of the object identifier to build.
_node	is the MPCI node of the object identifier to build.

Returns: Returns the object identifier with the lowest index built from the API, class, and MPCI node components.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

Function Documentation

◆ rtems_build_id()

rtems_id rtems_build_id	(	uint32_t	api,
		uint32_t	the_class,
		uint32_t	node,
		uint32_t	index
	)

Builds the object identifier from the API, class, MPCI node, and index components.

Parameters

api	is the API of the object identifier to build.
the_class	is the class of the object identifier to build.
node	is the MPCI node of the object identifier to build.
index	is the index of the object identifier to build.

Returns: Returns the object identifier built from the API, class, MPCI node, and index components.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_build_name()

rtems_name rtems_build_name	(	char	c1,
		char	c2,
		char	c3,
		char	c4
	)

Builds the object name composed of the four characters.

Parameters

c1	is the first character of the name.
c2	is the second character of the name.
c3	is the third character of the name.
c4	is the fourth character of the name.

This directive takes the four characters provided as arguments and composes a 32-bit object name with c1 in the most significant 8-bits and c4 in the least significant 8-bits.

Returns: Returns the object name composed of the four characters.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_api_maximum_class()

int rtems_object_api_maximum_class ( int api )

Gets the highest valid class value of the object API.

Parameters

api	is the object API to get the highest valid class value.

Return values

0	The object API was invalid.

Returns: Returns the highest valid class value of the object API.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_api_minimum_class()

int rtems_object_api_minimum_class ( int api )

Gets the lowest valid class value of the object API.

Parameters

api	is the object API to get the lowest valid class value.

Return values

-1	The object API was invalid.

Returns: Returns the lowest valid class value of the object API.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_get_api_class_name()

const char * rtems_object_get_api_class_name	(	int	the_api,
		int	the_class
	)

Gets a descriptive name of the object class of the object API.

Parameters

the_api	is the object API of the object class.
the_class	is the object class of the object API to get the name.

Return values

BAD API	The API was invalid.
BAD CLASS	The class of the API was invalid.

Returns: Returns a descriptive name of the class of the API, if the class of the API and the API were valid.

Notes: The string returned is from constant space. Do not modify or free it.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_get_api_name()

const char * rtems_object_get_api_name ( int api )

Gets a descriptive name of the object API.

Parameters

api	is the object API to get the name.

Return values

BAD API The API was invalid.

Returns: Returns a descriptive name of the API, if the API was valid.

Notes: The string returned is from constant space. Do not modify or free it.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_get_class_information()

rtems_status_code rtems_object_get_class_information	(	int	the_api,
		int	the_class,
		rtems_object_api_class_information *	info
	)

Gets the object class information of the object class of the object API.

Parameters

	the_api	is the object API of the object class.
	the_class	is the object class of the object API to get the class information.
[out]	info	is the pointer to an rtems_object_api_class_information object. When the directive call is successful, the object class information of the class of the API will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `info` parameter was NULL.
RTEMS_INVALID_NUMBER	The class of the API or the API was invalid.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_get_classic_name()

rtems_status_code rtems_object_get_classic_name	(	rtems_id	id,
		rtems_name *	name
	)

Gets the object name associated with the object identifier.

Parameters

	id	is the object identifier to get the name.
[out]	name	is the pointer to an rtems_name object. When the directive call is successful, the object name associated with the object identifier will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `name` parameter was NULL.
RTEMS_INVALID_ID	There was no object information available for the object identifier.
RTEMS_INVALID_ID	The object name associated with the object identifier was a string.
RTEMS_INVALID_ID	There was no object associated with the object identifier.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_get_name()

char * rtems_object_get_name	(	rtems_id	id,
		size_t	length,
		char *	name
	)

Gets the object name associated with the object identifier as a string.

Parameters

	id	is the object identifier to get the name.
	length	is the buffer length in bytes.
[out]	name	is the pointer to a buffer of the specified length.

The object name is stored in the name buffer. If the name buffer length is greater than zero, then the stored object name will be NUL terminated. The stored object name may be truncated to fit the length. There is no indication if a truncation occurred. Every attempt is made to return name as a printable string even if the object has the Classic API 32-bit integer style name.

Return values

NULL	The `length` parameter was 0.
NULL	The `name` parameter was NULL.
NULL	There was no object information available for the object identifier.
NULL	There was no object associated with the object identifier.

Returns: Returns the name parameter value, if there is an object name associated with the object identifier.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_object_id_get_api()

int rtems_object_id_get_api ( rtems_id id )

Gets the API component of the object identifier.

Parameters

id	is the object identifier with the API component to get.

Returns: Returns the API component of the object identifier.

Notes: This directive does not validate the object identifier provided in id.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_id_get_class()

int rtems_object_id_get_class ( rtems_id id )

Gets the class component of the object identifier.

Parameters

id	is the object identifier with the class component to get.

Returns: Returns the class component of the object identifier.

Notes: This directive does not validate the object identifier provided in id.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_id_get_index()

int rtems_object_id_get_index ( rtems_id id )

Gets the index component of the object identifier.

Parameters

id	is the object identifier with the index component to get.

Returns: Returns the index component of the object identifier.

Notes: This directive does not validate the object identifier provided in id.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_id_get_node()

int rtems_object_id_get_node ( rtems_id id )

Gets the MPCI node component of the object identifier.

Parameters

id	is the object identifier with the MPCI node component to get.

Returns: Returns the MPCI node component of the object identifier.

Notes: This directive does not validate the object identifier provided in id.

Constraints

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

◆ rtems_object_set_name()

rtems_status_code rtems_object_set_name	(	rtems_id	id,
		const char *	name
	)

Sets the object name of the object associated with the object identifier.

Parameters

id	is the object identifier of the object to set the name.
name	is the object name to set.

This directive will set the object name based upon the user string.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `name` parameter was NULL.
RTEMS_INVALID_ID	There was no object information available for the object identifier.
RTEMS_INVALID_ID	There was no object associated with the object identifier.
RTEMS_NO_MEMORY	There was no memory available to duplicate the name.

Notes

This directive can be used to set the name of objects which do not have a naming scheme per their API.

If the object specified by id is of a class that has a string name, this directive will free the existing name to the RTEMS Workspace and allocate enough memory from the RTEMS Workspace to make a copy of the string located at name.

If the object specified by id is of a class that has a 32-bit integer style name, then the first four characters in name will be used to construct the name.

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ rtems_object_id_api_maximum

◆ rtems_object_id_api_minimum

◆ RTEMS_OBJECT_ID_INITIAL

Function Documentation

◆ rtems_build_id()

◆ rtems_build_name()

◆ rtems_object_api_maximum_class()

◆ rtems_object_api_minimum_class()

◆ rtems_object_get_api_class_name()

◆ rtems_object_get_api_name()

◆ rtems_object_get_class_information()

◆ rtems_object_get_classic_name()

◆ rtems_object_get_name()

◆ rtems_object_id_get_api()

◆ rtems_object_id_get_class()

◆ rtems_object_id_get_index()

◆ rtems_object_id_get_node()

◆ rtems_object_set_name()