[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