diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-02-02 14:23:52 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-02-03 05:57:06 +0100 |
commit | 8a95e6f820f066451e1325592c9c0f18fa205c17 (patch) | |
tree | ef684ed217a4af5ac6e20eaf7e578b83d6afb50c /cpukit/include | |
parent | score: Define _Assert() for static analysis runs (diff) | |
download | rtems-8a95e6f820f066451e1325592c9c0f18fa205c17.tar.bz2 |
rtems: Rework object services API
Add a "Constraints" paragraph to the documentation.
Provide prototypes for programming language bindings. Use the macro
implementation to implement the corresponding functions.
Update #3993.
Diffstat (limited to 'cpukit/include')
-rw-r--r-- | cpukit/include/rtems/rtems/object.h | 250 |
1 files changed, 192 insertions, 58 deletions
diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h index b6aabe7c1e..f3edabbd3c 100644 --- a/cpukit/include/rtems/rtems/object.h +++ b/cpukit/include/rtems/rtems/object.h @@ -7,7 +7,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) * Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -154,8 +154,14 @@ typedef struct { * @return Returns the object identifier with the lowest index built from the * API, class, and MPCI node components. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define RTEMS_OBJECT_ID_INITIAL( _api, _class, _node ) \ OBJECTS_ID_INITIAL( _api, _class, _node ) @@ -218,20 +224,36 @@ typedef struct { * @brief Builds the object identifier from the API, class, MPCI node, and * index components. * - * @param _api is the API of the object identifier to build. + * @param api is the API of the object identifier to build. * - * @param _class is the class of the object identifier to build. + * @param the_class is the class of the object identifier to build. * - * @param _node is the MPCI node of the object identifier to build. + * @param node is the MPCI node of the object identifier to build. * - * @param _index is the index of the object identifier to build. + * @param index is the index of the object identifier to build. * * @return Returns the object identifier built from the API, class, MPCI node, * and index components. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ +rtems_id rtems_build_id( + uint32_t api, + uint32_t the_class, + uint32_t node, + uint32_t index +); + +/* Generated from spec:/rtems/object/if/build-id-macro */ #define rtems_build_id( _api, _class, _node, _index ) \ _Objects_Build_id( _api, _class, _node, _index ) @@ -242,23 +264,34 @@ typedef struct { * * @brief Builds the object name composed of the four characters. * - * @param _c1 is the first character of the name. + * @param c1 is the first character of the name. * - * @param _c2 is the second character of the name. + * @param c2 is the second character of the name. * - * @param _c3 is the third character of the name. + * @param c3 is the third character of the name. * - * @param _c4 is the fourth character of the name. + * @param 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`` + * a 32-bit object name with ``c1`` in the most significant 8-bits and ``c4`` * in the least significant 8-bits. * * @return Returns the object name composed of the four characters. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ +rtems_name rtems_build_name( char c1, char c2, char c3, char c4 ); + +/* Generated from spec:/rtems/object/if/build-name-macro */ #define rtems_build_name( _c1, _c2, _c3, _c4 ) \ _Objects_Build_name( _c1, _c2, _c3, _c4 ) @@ -288,8 +321,14 @@ typedef struct { * @retval ::RTEMS_INVALID_ID There was no object associated with the object * identifier. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ rtems_status_code rtems_object_get_classic_name( rtems_id id, @@ -329,9 +368,14 @@ rtems_status_code rtems_object_get_classic_name( * @return Returns the ``name`` parameter value, if there is an object name * associated with the object identifier. * - * @par Notes - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. + * @par Constraints + * @parblock + * 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. + * @endparblock */ char *rtems_object_get_name( rtems_id id, size_t length, char *name ); @@ -364,9 +408,6 @@ char *rtems_object_get_name( rtems_id id, size_t length, char *name ); * * @par Notes * @parblock - * This directive may cause the calling task to be preempted due to an obtain - * and release of the object allocator mutex. - * * This directive can be used to set the name of objects which do not have a * naming scheme per their API. * @@ -379,6 +420,19 @@ char *rtems_object_get_name( rtems_id id, size_t length, char *name ); * style name, then the first four characters in ``name`` will be used to * construct the name. * @endparblock + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); @@ -389,19 +443,27 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * * @brief Gets the API component of the object identifier. * - * @param _id is the object identifier with the API component to get. + * @param id is the object identifier with the API component to get. * * @return Returns the API component of the object identifier. * * @par Notes + * This directive does not validate the object identifier provided in ``id``. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * This directive does not validate the object identifier provided in ``_id``. + * * 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. * - * A body is also provided. + * * The directive will not cause the calling task to be preempted. * @endparblock */ +int rtems_object_id_get_api( rtems_id id ); + +/* Generated from spec:/rtems/object/if/id-get-api-macro */ #define rtems_object_id_get_api( _id ) _Objects_Get_API( _id ) /* Generated from spec:/rtems/object/if/id-get-class */ @@ -411,19 +473,27 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * * @brief Gets the class component of the object identifier. * - * @param _id is the object identifier with the class component to get. + * @param id is the object identifier with the class component to get. * * @return Returns the class component of the object identifier. * * @par Notes + * This directive does not validate the object identifier provided in ``id``. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * This directive does not validate the object identifier provided in ``_id``. + * * 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. * - * A body is also provided. + * * The directive will not cause the calling task to be preempted. * @endparblock */ +int rtems_object_id_get_class( rtems_id id ); + +/* Generated from spec:/rtems/object/if/id-get-class-macro */ #define rtems_object_id_get_class( _id ) _Objects_Get_class( _id ) /* Generated from spec:/rtems/object/if/id-get-node */ @@ -433,19 +503,27 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * * @brief Gets the MPCI node component of the object identifier. * - * @param _id is the object identifier with the MPCI node component to get. + * @param id is the object identifier with the MPCI node component to get. * * @return Returns the MPCI node component of the object identifier. * * @par Notes + * This directive does not validate the object identifier provided in ``id``. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * This directive does not validate the object identifier provided in ``_id``. + * * 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. * - * A body is also provided. + * * The directive will not cause the calling task to be preempted. * @endparblock */ +int rtems_object_id_get_node( rtems_id id ); + +/* Generated from spec:/rtems/object/if/id-get-node-macro */ #define rtems_object_id_get_node( _id ) _Objects_Get_node( _id ) /* Generated from spec:/rtems/object/if/id-get-index */ @@ -455,19 +533,27 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * * @brief Gets the index component of the object identifier. * - * @param _id is the object identifier with the index component to get. + * @param id is the object identifier with the index component to get. * * @return Returns the index component of the object identifier. * * @par Notes + * This directive does not validate the object identifier provided in ``id``. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * This directive does not validate the object identifier provided in ``_id``. + * * 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. * - * A body is also provided. + * * The directive will not cause the calling task to be preempted. * @endparblock */ +int rtems_object_id_get_index( rtems_id id ); + +/* Generated from spec:/rtems/object/if/id-get-index-macro */ #define rtems_object_id_get_index( _id ) _Objects_Get_index( _id ) /* Generated from spec:/rtems/object/if/id-api-minimum */ @@ -481,13 +567,20 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * @return Returns the lowest valid value for the API component of an object * identifier. * - * @par Notes + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * 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. * - * A body is also provided. + * * The directive will not cause the calling task to be preempted. * @endparblock */ +int rtems_object_id_api_minimum( void ); + +/* Generated from spec:/rtems/object/if/id-api-minimum-macro */ #define rtems_object_id_api_minimum() OBJECTS_INTERNAL_API /* Generated from spec:/rtems/object/if/id-api-maximum */ @@ -501,13 +594,20 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * @return Returns the highest valid value for the API component of an object * identifier. * - * @par Notes + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * A body is also provided. + * * 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. * @endparblock */ +int rtems_object_id_api_maximum( void ); + +/* Generated from spec:/rtems/object/if/id-api-maximum-macro */ #define rtems_object_id_api_maximum() OBJECTS_APIS_LAST /* Generated from spec:/rtems/object/if/api-minimum-class */ @@ -523,8 +623,14 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); * * @return Returns the lowest valid class value of the object API. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ int rtems_object_api_minimum_class( int api ); @@ -541,8 +647,14 @@ int rtems_object_api_minimum_class( int api ); * * @return Returns the highest valid class value of the object API. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ int rtems_object_api_maximum_class( int api ); @@ -560,10 +672,15 @@ int rtems_object_api_maximum_class( int api ); * @return Returns a descriptive name of the API, if the API was valid. * * @par Notes + * The string returned is from constant space. Do not modify or free it. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * The string returned is from constant space. Do not modify or free it. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. * @endparblock */ const char *rtems_object_get_api_name( int api ); @@ -587,10 +704,15 @@ const char *rtems_object_get_api_name( int api ); * the API and the API were valid. * * @par Notes + * The string returned is from constant space. Do not modify or free it. + * + * @par Constraints * @parblock - * This directive is strictly local and does not impact task scheduling. + * The following constraints apply to this directive: * - * The string returned is from constant space. Do not modify or free it. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. * @endparblock */ const char *rtems_object_get_api_class_name( int the_api, int the_class ); @@ -618,8 +740,14 @@ const char *rtems_object_get_api_class_name( int the_api, int the_class ); * * @retval ::RTEMS_INVALID_NUMBER The class of the API or the API was invalid. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ rtems_status_code rtems_object_get_class_information( int the_api, @@ -636,8 +764,14 @@ rtems_status_code rtems_object_get_class_information( * * @return Returns the local MPCI node number. * - * @par Notes - * This directive is strictly local and does not impact task scheduling. + * @par Constraints + * @parblock + * 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. + * @endparblock */ static inline uint16_t rtems_object_get_local_node( void ) { |