spec: Add build label and target hash directives

2 files changed, 81 insertions, 0 deletions

diff --git a/spec/rtems/config/if/get-build-label.yml b/spec/rtems/config/if/get-build-label.yml
new file mode 100644
index 00000000..a904c5eb
--- /dev/null
+++ b/spec/rtems/config/if/get-build-label.yml
@@ -0,0 +1,40 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Gets the RTEMS build label.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: const char *
+  variants: []
+description: |
+  The build label is a user-provided string defined by the build configuration.
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: rtems_get_build_label
+notes: |
+  The build label can be used to distinguish test suite results obtained from
+  different build configurations.  A use case is to record test results with
+  performance data to track performance regressions.  For this a database of
+  performance limits is required.  The build label and the target hash obtained
+  from ${get-target-hash:/name} can be used as a key to obtain performance
+  limits.
+params: []
+return:
+  return: |
+    Returns the pointer to the RTEMS build label.
+  return-values: []
+type: interface
diff --git a/spec/rtems/config/if/get-target-hash.yml b/spec/rtems/config/if/get-target-hash.yml
new file mode 100644
index 00000000..d987a077
--- /dev/null
+++ b/spec/rtems/config/if/get-target-hash.yml
@@ -0,0 +1,41 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Gets the RTEMS target hash.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: const char *
+  variants: []
+description: |
+  The target hash is calculated from BSP-specific values which characterize a
+  target system.
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: rtems_get_target_hash
+notes: |
+  For example, the device tree, settings of the memory controller, processor
+  and bus frequencies, a serial number of a chip may be used to calculate the
+  target hash.
+
+  The target hash can be used to distinguish test suite results obtained from
+  different target systems.
+params: []
+return:
+  return: |
+    Returns the pointer to the RTEMS target hash.
+  return-values: []
+type: interface