From 8a95e6f820f066451e1325592c9c0f18fa205c17 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 2 Feb 2021 14:23:52 +0100 Subject: 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. --- cpukit/include/rtems/rtems/object.h | 250 ++++++++++++++++++++++------- cpukit/rtems/src/rtemsbuildid.c | 19 +-- cpukit/rtems/src/rtemsbuildname.c | 33 +--- cpukit/rtems/src/rtemsobjectidapimaximum.c | 17 +- cpukit/rtems/src/rtemsobjectidapiminimum.c | 17 +- cpukit/rtems/src/rtemsobjectidgetapi.c | 21 ++- cpukit/rtems/src/rtemsobjectidgetclass.c | 21 ++- cpukit/rtems/src/rtemsobjectidgetindex.c | 21 ++- cpukit/rtems/src/rtemsobjectidgetnode.c | 21 ++- testsuites/sptests/sp43/init.c | 8 - 10 files changed, 264 insertions(+), 164 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 ) { diff --git a/cpukit/rtems/src/rtemsbuildid.c b/cpukit/rtems/src/rtemsbuildid.c index ec3a715473..069812a3d5 100644 --- a/cpukit/rtems/src/rtemsbuildid.c +++ b/cpukit/rtems/src/rtemsbuildid.c @@ -20,25 +20,26 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -Objects_Id rtems_build_id( +static rtems_id _RTEMS_Build_id( uint32_t api, uint32_t class, uint32_t node, uint32_t index -); +) +{ + return rtems_build_id( api, class, node, index ); +} + +#undef rtems_build_id -Objects_Id rtems_build_id( +rtems_id rtems_build_id( uint32_t api, uint32_t class, uint32_t node, uint32_t index ) { - return _Objects_Build_id( api, class, node, index ); + return _RTEMS_Build_id( api, class, node, index ); } diff --git a/cpukit/rtems/src/rtemsbuildname.c b/cpukit/rtems/src/rtemsbuildname.c index 42c8c46fd3..300c3638f9 100644 --- a/cpukit/rtems/src/rtemsbuildname.c +++ b/cpukit/rtems/src/rtemsbuildname.c @@ -20,33 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * Undefine since this is normally a macro and we want a real body in - * the library for other language bindings. - */ -#undef rtems_build_name +static rtems_name _RTEMS_Build_name( char c1, char c2, char c3, char c4 ) +{ + return rtems_build_name( c1, c2, c3, c4 ); +} -/* - * Prototype it to avoid warnings - */ -rtems_name rtems_build_name( - char C1, - char C2, - char C3, - char C4 -); +#undef rtems_build_name -/* - * Now define a real body - */ -rtems_name rtems_build_name( - char C1, - char C2, - char C3, - char C4 -) +rtems_id rtems_build_name( char c1, char c2, char c3, char c4 ) { - return _Objects_Build_name( C1, C2, C3, C4 ); + return _RTEMS_Build_name( c1, c2, c3, c4 ); } diff --git a/cpukit/rtems/src/rtemsobjectidapimaximum.c b/cpukit/rtems/src/rtemsobjectidapimaximum.c index 3d624b0b5a..d432647bd3 100644 --- a/cpukit/rtems/src/rtemsobjectidapimaximum.c +++ b/cpukit/rtems/src/rtemsobjectidapimaximum.c @@ -20,15 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_api_maximum(void); +static int _RTEMS_Object_id_api_maximum( void ) +{ + return rtems_object_id_api_maximum(); +} + +#undef rtems_object_id_api_maximum -int rtems_object_id_api_maximum(void) +int rtems_object_id_api_maximum( void ) { - return OBJECTS_APIS_LAST; + return _RTEMS_Object_id_api_maximum(); } diff --git a/cpukit/rtems/src/rtemsobjectidapiminimum.c b/cpukit/rtems/src/rtemsobjectidapiminimum.c index f9af3914a6..55bb014136 100644 --- a/cpukit/rtems/src/rtemsobjectidapiminimum.c +++ b/cpukit/rtems/src/rtemsobjectidapiminimum.c @@ -20,15 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_api_minimum(void); +static int _RTEMS_Object_id_api_minimum( void ) +{ + return rtems_object_id_api_minimum(); +} + +#undef rtems_object_id_api_minimum -int rtems_object_id_api_minimum(void) +int rtems_object_id_api_minimum( void ) { - return OBJECTS_INTERNAL_API; + return _RTEMS_Object_id_api_minimum(); } diff --git a/cpukit/rtems/src/rtemsobjectidgetapi.c b/cpukit/rtems/src/rtemsobjectidgetapi.c index 087402a911..a5efeb3290 100644 --- a/cpukit/rtems/src/rtemsobjectidgetapi.c +++ b/cpukit/rtems/src/rtemsobjectidgetapi.c @@ -20,19 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_get_api( - Objects_Id id -); +static int _RTEMS_Object_id_get_api( rtems_id id ) +{ + return rtems_object_id_get_api( id ); +} + +#undef rtems_object_id_get_api -int rtems_object_id_get_api( - Objects_Id id -) +int rtems_object_id_get_api( rtems_id id ) { - return _Objects_Get_API( id ); + return _RTEMS_Object_id_get_api( id ); } diff --git a/cpukit/rtems/src/rtemsobjectidgetclass.c b/cpukit/rtems/src/rtemsobjectidgetclass.c index bc2d11a5ea..6b817e55fe 100644 --- a/cpukit/rtems/src/rtemsobjectidgetclass.c +++ b/cpukit/rtems/src/rtemsobjectidgetclass.c @@ -20,19 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_get_class( - Objects_Id id -); +static int _RTEMS_Object_id_get_class( rtems_id id ) +{ + return rtems_object_id_get_class( id ); +} + +#undef rtems_object_id_get_class -int rtems_object_id_get_class( - Objects_Id id -) +int rtems_object_id_get_class( rtems_id id ) { - return _Objects_Get_class( id ); + return _RTEMS_Object_id_get_class( id ); } diff --git a/cpukit/rtems/src/rtemsobjectidgetindex.c b/cpukit/rtems/src/rtemsobjectidgetindex.c index cdcbd2f609..48e2f5ad95 100644 --- a/cpukit/rtems/src/rtemsobjectidgetindex.c +++ b/cpukit/rtems/src/rtemsobjectidgetindex.c @@ -20,19 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_get_index( - Objects_Id id -); +static int _RTEMS_Object_id_get_index( rtems_id id ) +{ + return rtems_object_id_get_index( id ); +} + +#undef rtems_object_id_get_index -int rtems_object_id_get_index( - Objects_Id id -) +int rtems_object_id_get_index( rtems_id id ) { - return _Objects_Get_index( id ); + return _RTEMS_Object_id_get_index( id ); } diff --git a/cpukit/rtems/src/rtemsobjectidgetnode.c b/cpukit/rtems/src/rtemsobjectidgetnode.c index 4d8a4288d1..6d26f4caea 100644 --- a/cpukit/rtems/src/rtemsobjectidgetnode.c +++ b/cpukit/rtems/src/rtemsobjectidgetnode.c @@ -20,19 +20,16 @@ #include "config.h" #endif -#include +#include -/* - * This is implemented as a macro. This body is provided to support - * bindings from non-C based languages. - */ -int rtems_object_id_get_node( - Objects_Id id -); +static int _RTEMS_Object_id_get_node( rtems_id id ) +{ + return rtems_object_id_get_node( id ); +} + +#undef rtems_object_id_get_node -int rtems_object_id_get_node( - Objects_Id id -) +int rtems_object_id_get_node( rtems_id id ) { - return _Objects_Get_node( id ); + return _RTEMS_Object_id_get_node( id ); } diff --git a/testsuites/sptests/sp43/init.c b/testsuites/sptests/sp43/init.c index 57f883daf0..09c60cdb0d 100644 --- a/testsuites/sptests/sp43/init.c +++ b/testsuites/sptests/sp43/init.c @@ -22,21 +22,13 @@ const char rtems_test_name[] = "SP 43"; /* These functions have both macro and function incarnations */ #undef rtems_build_id -extern rtems_id rtems_build_id(int api,int class,int node,int index); #undef rtems_build_name -extern rtems_name rtems_build_name(char C1,char C2,char C3,char C4); #undef rtems_object_id_api_maximum -extern int rtems_object_id_api_maximum(void); #undef rtems_object_id_api_minimum -extern int rtems_object_id_api_minimum(void); #undef rtems_object_id_get_api -extern int rtems_object_id_get_api(rtems_id id); #undef rtems_object_id_get_class -extern int rtems_object_id_get_class(rtems_id id); #undef rtems_object_id_get_index -extern int rtems_object_id_get_index(rtems_id id); #undef rtems_object_id_get_node -extern int rtems_object_id_get_node(rtems_id id); void print_class_info( int api, -- cgit v1.2.3