[rtems-central commit] spec: Add build label and target hash directives

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    2fb83c78ed38e2499b15a17baf058f8df3c30dfa
Changeset: http://git.rtems.org/rtems-central/commit/?id=2fb83c78ed38e2499b15a17baf058f8df3c30dfa

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Feb 23 12:00:10 2021 +0100

spec: Add build label and target hash directives

---

 spec/rtems/config/if/get-build-label.yml | 40 +++++++++++++++++++++++++++++++
 spec/rtems/config/if/get-target-hash.yml | 41 ++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)

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 0000000..a904c5e
--- /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 0000000..d987a07
--- /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