spec: Fix RTEMS_SYMBOL_NAME() specification

10 files changed, 48 insertions, 214 deletions

diff --git a/spec/rtems/basedefs/req/symbol-name-0.yml b/spec/rtems/basedefs/req/symbol-name-0.yml
deleted file mode 100644
index 766f94cf..00000000
--- a/spec/rtems/basedefs/req/symbol-name-0.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: null
-references: []
-requirement-type: non-functional
-text: |
-  When argument ${../if/symbol-name:/params[0]/name} after undergoing
-  C pre-processor substitutions results in a valid C identifier name,
-  while the symbol ``__USER_LABEL_PREFIX__`` is *not* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} macro shall
-  apply all possible C pre-processor substitutions to its argument value
-  before it evaluates to the identifier name resulting
-  from the argument value.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-1.yml b/spec/rtems/basedefs/req/symbol-name-1.yml
deleted file mode 100644
index 014a9733..00000000
--- a/spec/rtems/basedefs/req/symbol-name-1.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: null
-references: []
-requirement-type: non-functional
-text: |
-  When argument ${../if/symbol-name:/params[0]/name} after undergoing
-  C pre-processor substitutions results in a valid C identifier name,
-  while the symbol ``__USER_LABEL_PREFIX__`` *is* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} macro shall
-  apply all possible C pre-processor substitutions to its argument value
-  and the value of ``__USER_LABEL_PREFIX__`` before it evaluates to the
-  concatenation of the value resulting from substituting
-  the symbol ``__USER_LABEL_PREFIX__`` and the identifier name resulting
-  from the argument value.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-2.yml b/spec/rtems/basedefs/req/symbol-name-2.yml
deleted file mode 100644
index 09890535..00000000
--- a/spec/rtems/basedefs/req/symbol-name-2.yml
+++ /dev/null
@@ -1,19 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: null
-references: []
-requirement-type: non-functional
-text: |
-  While the symbol ``__USER_LABEL_PREFIX__`` *is* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} macro shall result
-  in the substituted values textually concatenated
-  in the order ``__USER_LABEL_PREFIX__`` left and
-  ${../if/symbol-name:/params[0]/name} right.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-3.yml b/spec/rtems/basedefs/req/symbol-name-3.yml
deleted file mode 100644
index ab11cbfa..00000000
--- a/spec/rtems/basedefs/req/symbol-name-3.yml
+++ /dev/null
@@ -1,20 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: |
-  There should be no additional character before, between or after the
-  arguments in the result.
-references: []
-requirement-type: non-functional
-text: |
-  While the symbol ``__USER_LABEL_PREFIX__`` is *not* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} shall result in only those
-  characters which also appear in its argument value
-  after applying all possible C pre-processor substitutions to it.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-4.yml b/spec/rtems/basedefs/req/symbol-name-4.yml
deleted file mode 100644
index c224de10..00000000
--- a/spec/rtems/basedefs/req/symbol-name-4.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: |
-  There should be no additional character before, between or after the
-  arguments in the result.
-references: []
-requirement-type: non-functional
-text: |
-  While the symbol ``__USER_LABEL_PREFIX__`` *is* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} shall result in only those
-  characters which also appear in the value of ``__USER_LABEL_PREFIX__``
-  and its argument value
-  after applying all possible C pre-processor substitutions to them.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-5.yml b/spec/rtems/basedefs/req/symbol-name-5.yml
deleted file mode 100644
index b49aa5ba..00000000
--- a/spec/rtems/basedefs/req/symbol-name-5.yml
+++ /dev/null
@@ -1,15 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: null
-references: []
-requirement-type: non-functional
-text: |
-  The macro ${../if/symbol-name:/name} shall make its result
-  subject to C pre-processor substitutions.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-6.yml b/spec/rtems/basedefs/req/symbol-name-6.yml
deleted file mode 100644
index 15825973..00000000
--- a/spec/rtems/basedefs/req/symbol-name-6.yml
+++ /dev/null
@@ -1,22 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-enabled-by: true
-links:
-- role: interface-function
-  uid: ../if/symbol-name
-non-functional-type: interface
-rationale: |
-  First, if the ``__USER_LABEL_PREFIX__`` is defined when the macro is
-  defined, it must also be defined at all places where the macro is used.
-  Second, value of the ``__USER_LABEL_PREFIX__`` is not stored in the
-  macro but can be different each time the macro is called.
-references: []
-requirement-type: non-functional
-text: |
-  While the symbol ``__USER_LABEL_PREFIX__`` *is* defined
-  during pre-processing of the ``basedefs.h`` file,
-  the ${../if/symbol-name:/name} macro shall
-  use the value which the ``__USER_LABEL_PREFIX__`` has at the place
-  the macro call is processed.
-type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name-expand.yml b/spec/rtems/basedefs/req/symbol-name-expand.yml
new file mode 100644
index 00000000..0e03c773
--- /dev/null
+++ b/spec/rtems/basedefs/req/symbol-name-expand.yml
@@ -0,0 +1,15 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/symbol-name
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/symbol-name:/params[0]/name} parameter value shall be expanded by
+  the C preprocessor.
+type: requirement
diff --git a/spec/rtems/basedefs/req/symbol-name.yml b/spec/rtems/basedefs/req/symbol-name.yml
new file mode 100644
index 00000000..9493f3ab
--- /dev/null
+++ b/spec/rtems/basedefs/req/symbol-name.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/symbol-name
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/symbol-name:/name} macro shall expand to the
+  ${/glossary/elf:/term} symbol name associated with the C language identifier
+  specified by the ${../if/symbol-name:/params[0]/name} parameter.
+type: requirement
diff --git a/spec/rtems/basedefs/val/basedefs.yml b/spec/rtems/basedefs/val/basedefs.yml
index 617920ea..d0c8baf2 100644
--- a/spec/rtems/basedefs/val/basedefs.yml
+++ b/spec/rtems/basedefs/val/basedefs.yml
@@ -1030,82 +1030,20 @@ test-actions:
       uid: ../req/string-0
   links: []
 - action-brief: |
-    Use the ${../if/symbol-name:/name} macro on examples.
+    Use the ${../if/symbol-name:/name} macro with an example object.
   action-code: |
-    const int symbol_name = 321;
-    int symbol_name_0_var;
-    int symbol_name_1_var;
-    int prefixed_symbol_name_var;
-    int prefixed_symbol_id_var;
-    int prefixed_upper_symbol_name_var;
-    symbol_name_0_var = RTEMS_SYMBOL_NAME( symbol_name );
-    symbol_name_1_var = RTEMS_SYMBOL_NAME( SYMBOL_NAME );
-    prefixed_symbol_name_var = basedefs_use_prefixed_symbol_name();
-    prefixed_symbol_id_var = basedefs_use_prefixed_symbol_id();
-    prefixed_upper_symbol_name_var = basedefs_use_prefixed_upper_symbol_name();
+    /* Nothing to do */
   checks:
   - brief: |
-      Case ``__USER_LABEL_PREFIX__`` undefined.
-      Check that the ${../if/symbol-name:/name} macro
-      without any pre-processor substitutions applicable results
-      in its literal argument.
+      Check that the ${../if/symbol-name:/name} macro expands to the expected
+      symbol name.
     code: |
-      T_step_eq_int( ${step}, symbol_name_0_var, 321 );
+      T_step_eq_ptr( ${step}, &global_object, &address_of_global_object );
     links:
     - role: validation
-      uid: ../req/symbol-name-3
-  - brief: |
-      Case ``__USER_LABEL_PREFIX__`` undefined.
-      Check that the ${../if/symbol-name:/name} macro
-      applies pre-processor substitutions to its argument
-      and its result.
-    code: |
-      T_step_eq_int( ${step}, symbol_name_1_var, 321 );
-    links:
-    - role: validation
-      uid: ../req/symbol-name-0
+      uid: ../req/symbol-name
     - role: validation
-      uid: ../req/symbol-name-3
-    - role: validation
-      uid: ../req/symbol-name-5
-  - brief: |
-      Case ``__USER_LABEL_PREFIX__`` defined.
-      Check that the ${../if/symbol-name:/name} macro
-      without any pre-processor substitutions applicable results
-      in the literal prefix and argument.
-    code: |
-      T_step_eq_int( ${step}, prefixed_symbol_name_var, 124 );
-    links:
-    - role: validation
-      uid: ../req/symbol-name-1
-    - role: validation
-      uid: ../req/symbol-name-2
-  - brief: |
-      Case ``__USER_LABEL_PREFIX__`` defined.
-      Check that the ${../if/symbol-name:/name} macro
-      applies pre-processor substitutions to its argument.
-    code: |
-      T_step_eq_int( ${step}, prefixed_upper_symbol_name_var, 125 );
-    links:
-    - role: validation
-      uid: ../req/symbol-name-1
-    - role: validation
-      uid: ../req/symbol-name-2
-    - role: validation
-      uid: ../req/symbol-name-6
-  - brief: |
-      Case ``__USER_LABEL_PREFIX__`` defined.
-      Check that the ${../if/symbol-name:/name} macro
-      applies pre-processor substitutions to its result.
-    code: |
-      T_step_eq_int( ${step}, prefixed_symbol_id_var, 126 );
-    links:
-    - role: validation
-      uid: ../req/symbol-name-4
-    - role: validation
-      uid: ../req/symbol-name-5
-    - role: validation
-      uid: ../req/symbol-name-6
+      uid: ../req/symbol-name-expand
   links: []
 - action-brief: |
     Invoke the  ${../if/true:/name} macro on an example.
@@ -1441,8 +1379,6 @@ test-context-support: null
 test-description: null
 test-header: null
 test-includes:
-- stddef.h
-- stdarg.h
 - rtems.h
 test-local-includes:
 - tc-basedefs-pendant.h
@@ -1461,11 +1397,19 @@ test-support: |
   #define SECTION_NAME ".rtemsroset.test"
   #define STATIC_ASSERT_COND 0 +
   #define STRING_PREFIX str
-  #define SYMBOL_NAME SYMBOL_name
-  #define SYMBOL_name symbol_name
+  #define SYMBOL_NAME global_object
   #define _TO_STR2( _text ) #_text
   #define _TO_STR( _text ) _TO_STR2( _text )
 
+  int global_object;
+
+  extern int address_of_global_object;
+
+  __asm__(
+    "\n\t.set " RTEMS_XSTRING( RTEMS_SYMBOL_NAME( address_of_global_object ) )
+    ", " RTEMS_XSTRING( RTEMS_SYMBOL_NAME( SYMBOL_NAME ) ) "\n"
+  );
+
   /*
    * For some reasons - which I fail to fully understand - _TO_STR()
    * seems to remove spaces around `()` at times and at other times