[PATCH v2] rtems: Rework object services API
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Feb 2 13:56:40 UTC 2021
Add a "Constraints" paragraph to the documentation.
Provide prototypes for programming language bindings. Use the macro
implementation to implement the corresponding functions.
Update #3993.
---
v2: Add some more constraints.
cpukit/include/rtems/rtems/object.h | 215 +++++++++++++++------
cpukit/rtems/src/rtemsbuildid.c | 19 +-
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 -
9 files changed, 223 insertions(+), 137 deletions(-)
diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h
index b6aabe7c1e..4b84c5cdf6 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,34 @@ 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.
+ * @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 +262,32 @@ 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.
+ * @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 +317,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,
@@ -389,19 +424,25 @@ 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
- * @parblock
- * This directive is strictly local and does not impact task scheduling.
+ * This directive does not validate the object identifier provided in ``id``.
*
- * This directive does not validate the object identifier provided in ``_id``.
+ * @par Constraints
+ * @parblock
+ * 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.
* @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 +452,25 @@ 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
- * @parblock
- * This directive is strictly local and does not impact task scheduling.
+ * This directive does not validate the object identifier provided in ``id``.
*
- * This directive does not validate the object identifier provided in ``_id``.
+ * @par Constraints
+ * @parblock
+ * 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.
* @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 +480,25 @@ 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
- * @parblock
- * This directive is strictly local and does not impact task scheduling.
+ * This directive does not validate the object identifier provided in ``id``.
*
- * This directive does not validate the object identifier provided in ``_id``.
+ * @par Constraints
+ * @parblock
+ * 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.
* @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 +508,25 @@ 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
- * @parblock
- * This directive is strictly local and does not impact task scheduling.
+ * This directive does not validate the object identifier provided in ``id``.
*
- * This directive does not validate the object identifier provided in ``_id``.
+ * @par Constraints
+ * @parblock
+ * 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.
* @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 +540,18 @@ 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:
*
- * 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.
* @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 +565,18 @@ 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.
* @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 +592,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 +616,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 +641,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 +673,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 +709,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 +733,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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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/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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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 <rtems/score/objectimpl.h>
+#include <rtems/rtems/object.h>
-/*
- * 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,
--
2.26.2
More information about the devel
mailing list