From 6856765a1d447ef914887a8279b3e12ac8775dee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Frank=20K=C3=BChndel?= Date: Wed, 2 Dec 2020 11:17:34 +0100 Subject: spec: Requirements and validation for basedefs.h --- config.yml | 1 + spec/rtems/basedefs/req/alias-0.yml | 25 + spec/rtems/basedefs/req/align-down-0.yml | 21 + spec/rtems/basedefs/req/align-up-0.yml | 21 + spec/rtems/basedefs/req/aligned-0.yml | 24 + spec/rtems/basedefs/req/alloc-align-0.yml | 26 + spec/rtems/basedefs/req/alloc-size-0.yml | 23 + spec/rtems/basedefs/req/alloc-size-2-0.yml | 26 + spec/rtems/basedefs/req/array-size-0.yml | 18 + .../req/compiler-deprecated-attribute-0.yml | 15 + .../basedefs/req/compiler-memory-barrier-0.yml | 22 + .../req/compiler-no-return-attribute-0.yml | 15 + .../basedefs/req/compiler-packed-attribute-0.yml | 15 + .../basedefs/req/compiler-pure-attribute-0.yml | 15 + .../basedefs/req/compiler-unused-attribute-0.yml | 15 + spec/rtems/basedefs/req/concat-0.yml | 18 + spec/rtems/basedefs/req/concat-1.yml | 17 + spec/rtems/basedefs/req/concat-2.yml | 15 + spec/rtems/basedefs/req/const-0.yml | 22 + spec/rtems/basedefs/req/container-of-0.yml | 21 + .../rtems/basedefs/req/declare-global-symbol-0.yml | 22 + spec/rtems/basedefs/req/deconst-0.yml | 20 + spec/rtems/basedefs/req/define-global-symbol-0.yml | 25 + spec/rtems/basedefs/req/define-global-symbol-1.yml | 15 + spec/rtems/basedefs/req/deprecated-0.yml | 19 + spec/rtems/basedefs/req/dequalify-0.yml | 22 + spec/rtems/basedefs/req/dequalify-depthx-0.yml | 29 + spec/rtems/basedefs/req/devolatile-0.yml | 21 + spec/rtems/basedefs/req/expand-0.yml | 16 + spec/rtems/basedefs/req/false-0.yml | 14 + .../rtems/basedefs/req/have-member-same-type-0.yml | 34 + spec/rtems/basedefs/req/inline-routine-0.yml | 25 + spec/rtems/basedefs/req/malloclike-0.yml | 27 + spec/rtems/basedefs/req/no-inline-0.yml | 20 + spec/rtems/basedefs/req/no-return-0.yml | 24 + spec/rtems/basedefs/req/obfuscate-variable-0.yml | 20 + spec/rtems/basedefs/req/packed-0.yml | 22 + spec/rtems/basedefs/req/packed-1.yml | 25 + spec/rtems/basedefs/req/packed-2.yml | 18 + spec/rtems/basedefs/req/predict-false-0.yml | 24 + spec/rtems/basedefs/req/predict-true-0.yml | 27 + spec/rtems/basedefs/req/printflike-0.yml | 32 + spec/rtems/basedefs/req/printflike-1.yml | 30 + spec/rtems/basedefs/req/pure-0.yml | 23 + spec/rtems/basedefs/req/return-address-0.yml | 29 + spec/rtems/basedefs/req/section-0.yml | 23 + spec/rtems/basedefs/req/static-assert-0.yml | 23 + spec/rtems/basedefs/req/string-0.yml | 17 + spec/rtems/basedefs/req/symbol-name-0.yml | 21 + spec/rtems/basedefs/req/symbol-name-1.yml | 23 + spec/rtems/basedefs/req/symbol-name-2.yml | 19 + spec/rtems/basedefs/req/symbol-name-3.yml | 20 + spec/rtems/basedefs/req/symbol-name-4.yml | 21 + spec/rtems/basedefs/req/symbol-name-5.yml | 15 + spec/rtems/basedefs/req/symbol-name-6.yml | 22 + spec/rtems/basedefs/req/true-0.yml | 14 + spec/rtems/basedefs/req/typeof-refx-0.yml | 28 + spec/rtems/basedefs/req/unreachable-0.yml | 20 + spec/rtems/basedefs/req/unused-0.yml | 17 + spec/rtems/basedefs/req/unused-1.yml | 18 + spec/rtems/basedefs/req/unused-2.yml | 18 + spec/rtems/basedefs/req/unused-3.yml | 17 + spec/rtems/basedefs/req/used-0.yml | 19 + spec/rtems/basedefs/req/warn-unused-result-0.yml | 19 + spec/rtems/basedefs/req/weak-0.yml | 20 + spec/rtems/basedefs/req/weak-1.yml | 29 + spec/rtems/basedefs/req/weak-alias-0.yml | 28 + spec/rtems/basedefs/req/weak-alias-1.yml | 34 + spec/rtems/basedefs/req/xconcat-0.yml | 19 + spec/rtems/basedefs/req/xconcat-1.yml | 17 + spec/rtems/basedefs/req/xconcat-2.yml | 18 + spec/rtems/basedefs/req/xconcat-3.yml | 15 + spec/rtems/basedefs/req/xstring-0.yml | 20 + spec/rtems/basedefs/req/zero-length-array-0.yml | 44 + spec/rtems/basedefs/val/basedefs.yml | 1688 ++++++++++++++++++++ 75 files changed, 3264 insertions(+) create mode 100644 spec/rtems/basedefs/req/alias-0.yml create mode 100644 spec/rtems/basedefs/req/align-down-0.yml create mode 100644 spec/rtems/basedefs/req/align-up-0.yml create mode 100644 spec/rtems/basedefs/req/aligned-0.yml create mode 100644 spec/rtems/basedefs/req/alloc-align-0.yml create mode 100644 spec/rtems/basedefs/req/alloc-size-0.yml create mode 100644 spec/rtems/basedefs/req/alloc-size-2-0.yml create mode 100644 spec/rtems/basedefs/req/array-size-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-deprecated-attribute-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-memory-barrier-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-no-return-attribute-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-packed-attribute-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-pure-attribute-0.yml create mode 100644 spec/rtems/basedefs/req/compiler-unused-attribute-0.yml create mode 100644 spec/rtems/basedefs/req/concat-0.yml create mode 100644 spec/rtems/basedefs/req/concat-1.yml create mode 100644 spec/rtems/basedefs/req/concat-2.yml create mode 100644 spec/rtems/basedefs/req/const-0.yml create mode 100644 spec/rtems/basedefs/req/container-of-0.yml create mode 100644 spec/rtems/basedefs/req/declare-global-symbol-0.yml create mode 100644 spec/rtems/basedefs/req/deconst-0.yml create mode 100644 spec/rtems/basedefs/req/define-global-symbol-0.yml create mode 100644 spec/rtems/basedefs/req/define-global-symbol-1.yml create mode 100644 spec/rtems/basedefs/req/deprecated-0.yml create mode 100644 spec/rtems/basedefs/req/dequalify-0.yml create mode 100644 spec/rtems/basedefs/req/dequalify-depthx-0.yml create mode 100644 spec/rtems/basedefs/req/devolatile-0.yml create mode 100644 spec/rtems/basedefs/req/expand-0.yml create mode 100644 spec/rtems/basedefs/req/false-0.yml create mode 100644 spec/rtems/basedefs/req/have-member-same-type-0.yml create mode 100644 spec/rtems/basedefs/req/inline-routine-0.yml create mode 100644 spec/rtems/basedefs/req/malloclike-0.yml create mode 100644 spec/rtems/basedefs/req/no-inline-0.yml create mode 100644 spec/rtems/basedefs/req/no-return-0.yml create mode 100644 spec/rtems/basedefs/req/obfuscate-variable-0.yml create mode 100644 spec/rtems/basedefs/req/packed-0.yml create mode 100644 spec/rtems/basedefs/req/packed-1.yml create mode 100644 spec/rtems/basedefs/req/packed-2.yml create mode 100644 spec/rtems/basedefs/req/predict-false-0.yml create mode 100644 spec/rtems/basedefs/req/predict-true-0.yml create mode 100644 spec/rtems/basedefs/req/printflike-0.yml create mode 100644 spec/rtems/basedefs/req/printflike-1.yml create mode 100644 spec/rtems/basedefs/req/pure-0.yml create mode 100644 spec/rtems/basedefs/req/return-address-0.yml create mode 100644 spec/rtems/basedefs/req/section-0.yml create mode 100644 spec/rtems/basedefs/req/static-assert-0.yml create mode 100644 spec/rtems/basedefs/req/string-0.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-0.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-1.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-2.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-3.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-4.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-5.yml create mode 100644 spec/rtems/basedefs/req/symbol-name-6.yml create mode 100644 spec/rtems/basedefs/req/true-0.yml create mode 100644 spec/rtems/basedefs/req/typeof-refx-0.yml create mode 100644 spec/rtems/basedefs/req/unreachable-0.yml create mode 100644 spec/rtems/basedefs/req/unused-0.yml create mode 100644 spec/rtems/basedefs/req/unused-1.yml create mode 100644 spec/rtems/basedefs/req/unused-2.yml create mode 100644 spec/rtems/basedefs/req/unused-3.yml create mode 100644 spec/rtems/basedefs/req/used-0.yml create mode 100644 spec/rtems/basedefs/req/warn-unused-result-0.yml create mode 100644 spec/rtems/basedefs/req/weak-0.yml create mode 100644 spec/rtems/basedefs/req/weak-1.yml create mode 100644 spec/rtems/basedefs/req/weak-alias-0.yml create mode 100644 spec/rtems/basedefs/req/weak-alias-1.yml create mode 100644 spec/rtems/basedefs/req/xconcat-0.yml create mode 100644 spec/rtems/basedefs/req/xconcat-1.yml create mode 100644 spec/rtems/basedefs/req/xconcat-2.yml create mode 100644 spec/rtems/basedefs/req/xconcat-3.yml create mode 100644 spec/rtems/basedefs/req/xstring-0.yml create mode 100644 spec/rtems/basedefs/req/zero-length-array-0.yml create mode 100644 spec/rtems/basedefs/val/basedefs.yml diff --git a/config.yml b/config.yml index 4e7cb5e8..280f9b5d 100644 --- a/config.yml +++ b/config.yml @@ -30,6 +30,7 @@ build: - cpukit/score/src/opt_ntp.h - gccdeps.py - long_gcc.py + - testsuites/validation/tc-basedefs-pendant.h - testsuites/validation/tr-event-constant.h - testsuites/validation/tr-event-send-receive.h - testsuites/validation/tr-object-ident.h diff --git a/spec/rtems/basedefs/req/alias-0.yml b/spec/rtems/basedefs/req/alias-0.yml new file mode 100644 index 00000000..3a788e89 --- /dev/null +++ b/spec/rtems/basedefs/req/alias-0.yml @@ -0,0 +1,25 @@ +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: requirement-refinement + uid: ../if/alias +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When argument ${../if/alias:/params[0]/name} is a name of a function, + and the macro ${../if/alias:/name} call is in the same compilation unit + as the function, + and the macro is not used in block scope, + and the macro is used in this form: + `` newname([argument-type-list]) ${../if/alias:/name}(oldname)``;, + and the ```` and ``argument-type-list`` match the + signature of the function ``oldname``, + and the code is compiled with the GNU C compiler, + the ${../if/alias:/name} macro shall cause the compiler to create + an additional name (``newname`` in the syntax) for the function + given as argument ${../if/alias:/params[0]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/align-down-0.yml b/spec/rtems/basedefs/req/align-down-0.yml new file mode 100644 index 00000000..b0c824db --- /dev/null +++ b/spec/rtems/basedefs/req/align-down-0.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + uid: ../if/align-down +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the argument ${../if/align-down:/params[1]/name} is a + positive power of two integer, + and argument ${../if/align-down:/params[0]/name} is a positive or 0 + integer, + the macro ${../if/align-down:/name} shall result in a side-effect free formula + calculating an integer which is the *greatest* whole-number *multiple* of + ${../if/align-down:/params[1]/name} which is smaller or equal + ${../if/align-down:/params[0]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/align-up-0.yml b/spec/rtems/basedefs/req/align-up-0.yml new file mode 100644 index 00000000..823c22c7 --- /dev/null +++ b/spec/rtems/basedefs/req/align-up-0.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + uid: ../if/align-up +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the argument ${../if/align-up:/params[1]/name} is a + positive power of two integer, + and argument ${../if/align-up:/params[0]/name} is a positive or 0 + integer, + the macro ${../if/align-up:/name} shall result in a side-effect free formula + calculating an integer which is the *smallest* whole-number *multiple* of + ${../if/align-up:/params[1]/name} which is greater or equal + ${../if/align-up:/params[0]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/aligned-0.yml b/spec/rtems/basedefs/req/aligned-0.yml new file mode 100644 index 00000000..3a4a57aa --- /dev/null +++ b/spec/rtems/basedefs/req/aligned-0.yml @@ -0,0 +1,24 @@ +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: requirement-refinement + uid: ../if/aligned +non-functional-type: interface +rationale: | + Note that the ${../if/aligned:/name} macro can often only increases the + alignment but under some circumstances, it can also decrease the alignment. +references: [] +requirement-type: non-functional +text: | + When the argument ${../if/aligned:/params[0]/name} is a + positive power of two integer, + and the macro ${../if/aligned:/name} is used on a none-``static`` + variable or structure field, + and the used linker supports alignments of the size given by the + ${../if/aligned:/params[0]/name} argument, + and the code is compiled with the GNU C compiler, + the macro shall specify a minimum alignment for the variable or + structure field, measured in bytes. +type: requirement diff --git a/spec/rtems/basedefs/req/alloc-align-0.yml b/spec/rtems/basedefs/req/alloc-align-0.yml new file mode 100644 index 00000000..c58050a5 --- /dev/null +++ b/spec/rtems/basedefs/req/alloc-align-0.yml @@ -0,0 +1,26 @@ +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: requirement-refinement + uid: ../if/alloc-align +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/alloc-align:/name} macro is used as last part of a + function declaration, + and ${../if/alloc-align:/params[0]/name} is a constant number + referring to an argument of that function + (counting of arguments starts at 1 from the left), + and the argument with that number is an integral value of a power of two, + and the declared function + returns a pointer to memory which starts at an integral *multiple* + of the value provided by the function argument number + ${../if/alloc-align:/params[0]/name}, + the macro shall cause the compiler to use the information of the alignment + of the returned memory in its pointer analysis. +type: requirement diff --git a/spec/rtems/basedefs/req/alloc-size-0.yml b/spec/rtems/basedefs/req/alloc-size-0.yml new file mode 100644 index 00000000..089388ee --- /dev/null +++ b/spec/rtems/basedefs/req/alloc-size-0.yml @@ -0,0 +1,23 @@ +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: requirement-refinement + uid: ../if/alloc-size +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/alloc-size:/name} macro is used as last part of a + function declaration, + and ${../if/alloc-size:/params[0]/name} is a constant number + referring to an argument of that function + (counting of arguments starts at 1 from the left), + and the declared function returns a pointer to memory with the size in bytes + provided by the function argument number ${../if/alloc-size:/params[0]/name}, + the macro shall cause the compiler to improve the correctness of + ``__builtin_object_sizepointer`` analysis. +type: requirement diff --git a/spec/rtems/basedefs/req/alloc-size-2-0.yml b/spec/rtems/basedefs/req/alloc-size-2-0.yml new file mode 100644 index 00000000..6e2e26e3 --- /dev/null +++ b/spec/rtems/basedefs/req/alloc-size-2-0.yml @@ -0,0 +1,26 @@ +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: requirement-refinement + uid: ../if/alloc-size-2 +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/alloc-size-2:/name} macro is used as last part of a + function declaration, + and ${../if/alloc-size-2:/params[0]/name} as well as + ${../if/alloc-size-2:/params[1]/name} are constant numbers + referring to two different arguments of that function + (counting of arguments starts at 1 from the left), + and the declared function returns a pointer to memory with the size in bytes + provided by the multiplication of the function arguments + number ${../if/alloc-size-2:/params[0]/name} and + ${../if/alloc-size-2:/params[1]/name}, + the macro shall cause the compiler to improve the correctness of + ``__builtin_object_sizepointer`` analysis. +type: requirement diff --git a/spec/rtems/basedefs/req/array-size-0.yml b/spec/rtems/basedefs/req/array-size-0.yml new file mode 100644 index 00000000..d00ee249 --- /dev/null +++ b/spec/rtems/basedefs/req/array-size-0.yml @@ -0,0 +1,18 @@ +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: requirement-refinement + uid: ../if/array-size +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the argument ${../if/alloc-size:/params[0]/name} evaluates to an + value of a C one-dimensional array type, + and the evaluation of that argument has no side effects, + the macro ${../if/array-size:/name} shall result in the number of elements + with which that array has been defined. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-deprecated-attribute-0.yml b/spec/rtems/basedefs/req/compiler-deprecated-attribute-0.yml new file mode 100644 index 00000000..31e45fa2 --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-deprecated-attribute-0.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/compiler-deprecated-attribute +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/compiler-deprecated-attribute:/name} shall + have exactly the same effect as the macro ${../if/deprecated:/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-memory-barrier-0.yml b/spec/rtems/basedefs/req/compiler-memory-barrier-0.yml new file mode 100644 index 00000000..e3101e55 --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-memory-barrier-0.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + uid: ../if/compiler-memory-barrier +non-functional-type: interface +rationale: | + A Full Software Memory Barrier prevents the compiler to move loads and + stores (in any direction) beyond the point where the barrier is in the + code. Otherwise this may occur as part of compiler optimizations. + This is a compile time only barrier. The CPU optimizations can still + move instructions over the barrier at run-time. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + the ${../if/compiler-memory-barrier:/name} macro shall + realize a Full Software Memory Barrier at the place in the code where + it occurs. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-no-return-attribute-0.yml b/spec/rtems/basedefs/req/compiler-no-return-attribute-0.yml new file mode 100644 index 00000000..3413e9b4 --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-no-return-attribute-0.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/compiler-no-return-attribute +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/compiler-no-return-attribute:/name} shall + have exactly the same effect as the macro ${../if/no-return:/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-packed-attribute-0.yml b/spec/rtems/basedefs/req/compiler-packed-attribute-0.yml new file mode 100644 index 00000000..1dc6a698 --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-packed-attribute-0.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/compiler-packed-attribute +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/compiler-packed-attribute:/name} shall + have exactly the same effect as the macro ${../if/packed:/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-pure-attribute-0.yml b/spec/rtems/basedefs/req/compiler-pure-attribute-0.yml new file mode 100644 index 00000000..465d76bc --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-pure-attribute-0.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/compiler-pure-attribute +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/compiler-pure-attribute:/name} shall + have exactly the same effect as the macro ${../if/pure:/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/compiler-unused-attribute-0.yml b/spec/rtems/basedefs/req/compiler-unused-attribute-0.yml new file mode 100644 index 00000000..57ef81aa --- /dev/null +++ b/spec/rtems/basedefs/req/compiler-unused-attribute-0.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/compiler-unused-attribute +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/compiler-unused-attribute:/name} shall + have exactly the same effect as the macro ${../if/unused:/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/concat-0.yml b/spec/rtems/basedefs/req/concat-0.yml new file mode 100644 index 00000000..e6e46d6c --- /dev/null +++ b/spec/rtems/basedefs/req/concat-0.yml @@ -0,0 +1,18 @@ +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: requirement-refinement + uid: ../if/concat +non-functional-type: interface +rationale: | + The rules for nested use of the ## operator are arcane. The result of such + nested macro calls is undefined. +references: [] +requirement-type: non-functional +text: | + When neither argument is a call of the macro ${../if/concat:/name} itself, + the macro shall result in both argument values + concatenated textually unaltered in the order they are provided. +type: requirement diff --git a/spec/rtems/basedefs/req/concat-1.yml b/spec/rtems/basedefs/req/concat-1.yml new file mode 100644 index 00000000..f21e592e --- /dev/null +++ b/spec/rtems/basedefs/req/concat-1.yml @@ -0,0 +1,17 @@ +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: requirement-refinement + uid: ../if/concat +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: | + The macro ${../if/concat:/name} shall result in only those + characters which also appear in its argument values. +type: requirement diff --git a/spec/rtems/basedefs/req/concat-2.yml b/spec/rtems/basedefs/req/concat-2.yml new file mode 100644 index 00000000..751836f6 --- /dev/null +++ b/spec/rtems/basedefs/req/concat-2.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/concat +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/concat:/name} shall make its result + subject to C pre-processor operations. +type: requirement diff --git a/spec/rtems/basedefs/req/const-0.yml b/spec/rtems/basedefs/req/const-0.yml new file mode 100644 index 00000000..47601ca3 --- /dev/null +++ b/spec/rtems/basedefs/req/const-0.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + uid: ../if/const +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/const:/name} macro is attached to a + function declaration or definition, + and the return value of that function is not affected by changes + to the observable state of the program and that function has + no observable effects on such state other than to return a value, + the ${../if/const:/name} macro shall permit the compiler to replace + subsequent calls to the function with the same argument values by the + result of the first call. +type: requirement diff --git a/spec/rtems/basedefs/req/container-of-0.yml b/spec/rtems/basedefs/req/container-of-0.yml new file mode 100644 index 00000000..8bb2aa9a --- /dev/null +++ b/spec/rtems/basedefs/req/container-of-0.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + uid: ../if/container-of +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When argument ${../if/container-of/params[0]/name} points to a + member field of a structure or union or C++ class, + and argument ${../if/container-of/params[1]/name} is the C type of this + structure or union or C++ class, + and argument ${../if/container-of/params[2]/name} is the name of + this member field, + the ${../if/container-of:/name} macro shall result in a pointer + to the start address of the structure or union or C++ class. +type: requirement diff --git a/spec/rtems/basedefs/req/declare-global-symbol-0.yml b/spec/rtems/basedefs/req/declare-global-symbol-0.yml new file mode 100644 index 00000000..402925d7 --- /dev/null +++ b/spec/rtems/basedefs/req/declare-global-symbol-0.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + uid: ../if/declare-global-symbol +non-functional-type: interface +rationale: | + See also ${../if/define-global-symbol:/name}. +references: [] +requirement-type: non-functional +text: | + When the macro ${../if/declare-global-symbol:/name} appears at file scope, + and argument ${../if/declare-global-symbol:/params[0]/name} after undergoing + C pre-processor substitutions results in a valid C identifier name, + and this identifier name is not yet defined at file scope, + the macro ${../if/declare-global-symbol:/name} shall apply all possible C + pre-processor substitutions to its argument value + before it results in code which declares a global symbol + with the respective name. +type: requirement diff --git a/spec/rtems/basedefs/req/deconst-0.yml b/spec/rtems/basedefs/req/deconst-0.yml new file mode 100644 index 00000000..c3b1aff0 --- /dev/null +++ b/spec/rtems/basedefs/req/deconst-0.yml @@ -0,0 +1,20 @@ +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: requirement-refinement + uid: ../if/deconst +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When ${../if/deconst:/params[0]/name} is a non-const pointer type, + and ${../if/deconst:/params[1]/name} is a pointer to a value of const type, + and the types of ${../if/deconst:/params[0]/name} and + ${../if/deconst:/params[1]/name} are compatible in the sense of C, + the macro ${../if/deconst:/name} shall result in an expression + which returns a pointer of type ${../if/deconst:/params[0]/name} pointing + to the same address as ${../if/deconst:/params[1]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/define-global-symbol-0.yml b/spec/rtems/basedefs/req/define-global-symbol-0.yml new file mode 100644 index 00000000..f59ae9dc --- /dev/null +++ b/spec/rtems/basedefs/req/define-global-symbol-0.yml @@ -0,0 +1,25 @@ +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: requirement-refinement + uid: ../if/define-global-symbol +non-functional-type: interface +rationale: | + See also ${../if/declare-global-symbol:/name}. + *File scope* excludes for example a placement in a function body. +references: [] +requirement-type: non-functional +text: | + When the macro ${../if/define-global-symbol:/name} appears at file scope, + and argument ${../if/define-global-symbol:/params[0]/name} after undergoing + C pre-processor substitutions results in a valid C identifier name, + and this identifier name is not yet defined at file scope, + and argument ${../if/define-global-symbol:/params[1]/name} after undergoing + C pre-processor substitutions results in a valid assembler integer value, + the macro ${../if/define-global-symbol:/name} shall apply all possible C + pre-processor substitutions to its argument values + before it results in assembler code which defines a global symbol + with the respective name and value. +type: requirement diff --git a/spec/rtems/basedefs/req/define-global-symbol-1.yml b/spec/rtems/basedefs/req/define-global-symbol-1.yml new file mode 100644 index 00000000..f66e543b --- /dev/null +++ b/spec/rtems/basedefs/req/define-global-symbol-1.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + uid: ../if/define-global-symbol +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/define-global-symbol:/name} shall define + a global symbol of ``void`` pointer type with the value being an address. +type: requirement diff --git a/spec/rtems/basedefs/req/deprecated-0.yml b/spec/rtems/basedefs/req/deprecated-0.yml new file mode 100644 index 00000000..a477f69e --- /dev/null +++ b/spec/rtems/basedefs/req/deprecated-0.yml @@ -0,0 +1,19 @@ +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: requirement-refinement + uid: ../if/deprecated +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/deprecated:/name} macro is used as last part of a + function declaration or type declaration or variable declaration or + variable definition, + the macro shall cause the compiler to issue a warning message when it + encounters a use of the function, type or variable. +type: requirement diff --git a/spec/rtems/basedefs/req/dequalify-0.yml b/spec/rtems/basedefs/req/dequalify-0.yml new file mode 100644 index 00000000..a94453b1 --- /dev/null +++ b/spec/rtems/basedefs/req/dequalify-0.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + uid: ../if/dequalify +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When ${../if/dequalify:/params[0]/name} is a non-const non-volatile + pointer type, + and ${../if/dequalify:/params[1]/name} is a pointer to a value of + const volatile type, + and the types of ${../if/dequalify:/params[0]/name} and + ${../if/dequalify:/params[1]/name} are compatible in the sense of C, + the macro ${../if/dequalify:/name} shall result in an expression + which returns a pointer of type ${../if/dequalify:/params[0]/name} pointing + to the same address as ${../if/dequalify:/params[1]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/dequalify-depthx-0.yml b/spec/rtems/basedefs/req/dequalify-depthx-0.yml new file mode 100644 index 00000000..7f86363c --- /dev/null +++ b/spec/rtems/basedefs/req/dequalify-depthx-0.yml @@ -0,0 +1,29 @@ +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: requirement-refinement + uid: ../if/dequalify-depthx +non-functional-type: interface +rationale: | + ${../if/dequalify-depthx:/name} checks for incompatible pointer types. +references: [] +requirement-type: non-functional +text: | + When the argument value of ${../if/dequalify-depthx:/params[0]/name} consists + of a sequence of *i* ``*`` and the types of both other arguments both + have *i* nested pointers (for example ``*`` for a pointer to ``int``, + ``**`` for a pointer to a pointer of ``int``, ``***`` for a pointer to + a pointer to a pointer to ``int``), + and ${../if/dequalify-depthx:/params[1]/name} is a pointer type with + different (compared to the type of + ${../if/dequalify-depthx:/params[2]/name}) qualifiers + (such as ``const`` or ``volatile``) or the same qualifiers or + without any qualifiers, + and the types of ${../if/dequalify-depthx:/params[1]/name} and + ${../if/dequalify-depthx:/params[2]/name} are compatible in the sense of C, + the macro ${../if/dequalify-depthx:/name} shall result in an expression + which returns a pointer of type ${../if/dequalify-depthx:/params[1]/name} + pointing to the same address as ${../if/dequalify-depthx:/params[2]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/devolatile-0.yml b/spec/rtems/basedefs/req/devolatile-0.yml new file mode 100644 index 00000000..5125aa86 --- /dev/null +++ b/spec/rtems/basedefs/req/devolatile-0.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + uid: ../if/devolatile +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When ${../if/devolatile:/params[0]/name} is a non-volatile pointer type, + and ${../if/devolatile:/params[1]/name} is a pointer to a value of + volatile type, + and the types of ${../if/devolatile:/params[0]/name} and + ${../if/devolatile:/params[1]/name} are compatible in the sense of C, + the macro ${../if/devolatile:/name} shall result in an expression + which returns a pointer of type ${../if/devolatile:/params[0]/name} pointing + to the same address as ${../if/devolatile:/params[1]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/expand-0.yml b/spec/rtems/basedefs/req/expand-0.yml new file mode 100644 index 00000000..db8a4a4f --- /dev/null +++ b/spec/rtems/basedefs/req/expand-0.yml @@ -0,0 +1,16 @@ +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: requirement-refinement + uid: ../if/expand +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/expand:/name} shall apply all possible C + pre-processor substitutions to its argument value + before it results in the substituted value. +type: requirement diff --git a/spec/rtems/basedefs/req/false-0.yml b/spec/rtems/basedefs/req/false-0.yml new file mode 100644 index 00000000..11f4c13e --- /dev/null +++ b/spec/rtems/basedefs/req/false-0.yml @@ -0,0 +1,14 @@ +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: requirement-refinement + uid: ../if/false +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/false:/name} shall result in the text 0. +type: requirement diff --git a/spec/rtems/basedefs/req/have-member-same-type-0.yml b/spec/rtems/basedefs/req/have-member-same-type-0.yml new file mode 100644 index 00000000..9a72691a --- /dev/null +++ b/spec/rtems/basedefs/req/have-member-same-type-0.yml @@ -0,0 +1,34 @@ +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: requirement-refinement + uid: ../if/have-member-same-type +non-functional-type: interface +rationale: | + The ${../if/have-member-same-type:/name} does only work in C. + Type qualifiers do not matter (``const int`` is + compatible to ``int``); arrays with undefined length are compatible + with arrays of defined length (``int[]`` is compatible + to ``int[5]``); enums are always incompatible; the number of pointer + indirection matters (``**int`` is not compatible with ``*int``). + See https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005ftypes_005fcompatible_005fp +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and argument ${../if/have-member-same-type:/params[0]/name} is a union or + structure, + and ${../if/have-member-same-type:/params[1]/name} is a member of + ${../if/have-member-same-type:/params[0]/name}, + and argument ${../if/have-member-same-type:/params[2]/name} is a union or + structure, + and ${../if/have-member-same-type:/params[3]/name} is a member of + ${../if/have-member-same-type:/params[2]/name}, + the ${../if/have-member-same-type:/name} macro shall + evaluate to the integer values 1 or 0 depending on whether + the types of the members {../if/have-member-same-type:/params[1]/name} + and ${../if/have-member-same-type:/params[3]/name} are compatible in + the sense of C. +type: requirement diff --git a/spec/rtems/basedefs/req/inline-routine-0.yml b/spec/rtems/basedefs/req/inline-routine-0.yml new file mode 100644 index 00000000..3d74a129 --- /dev/null +++ b/spec/rtems/basedefs/req/inline-routine-0.yml @@ -0,0 +1,25 @@ +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: requirement-refinement + uid: ../if/inline-routine +non-functional-type: interface +rationale: | + ``inline`` and ``__inline__`` have the same effect at least for the + GNU C compiler. ``__inline__`` works even if the GNU C compiler + is invoked with the ``-ansi``, or ``-std`` flags. + + The compiler may still emit code for a function defined or declared + with ``static inline`` or ``static __inline__``. Therefore, + if you want to put an inline function definition into a header + file, consider ``extern inline`` instead (see the compiler + documentation). +references: [] +requirement-type: non-functional +text: | + The ${../if/inline-routine:/name} macro shall evaluate + to the keywords ``static inline`` or ``static __inline__`` + which ever variant is available to the used compiler. +type: requirement diff --git a/spec/rtems/basedefs/req/malloclike-0.yml b/spec/rtems/basedefs/req/malloclike-0.yml new file mode 100644 index 00000000..6bb7cc28 --- /dev/null +++ b/spec/rtems/basedefs/req/malloclike-0.yml @@ -0,0 +1,27 @@ +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: requirement-refinement + uid: ../if/malloclike +non-functional-type: interface +rationale: | + Functions like malloc() and calloc() have this property but functions + like realloc() do not have this property because the memory it returns + may pointer to valid objects. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/malloclike:/name} macro is used as last part of a + function declaration or is attached to a function definition, + and the function returns a pointer to memory, + and this pointer cannot be an alias of any other pointer valid when + the function returns, + and no pointers to valid objects occur in any storage addressed by + that pointer, + and the function returns non-NULL in more than 50% of the cases, + the macro shall cause the compiler to use this information for + optimization. +type: requirement diff --git a/spec/rtems/basedefs/req/no-inline-0.yml b/spec/rtems/basedefs/req/no-inline-0.yml new file mode 100644 index 00000000..9dde8a68 --- /dev/null +++ b/spec/rtems/basedefs/req/no-inline-0.yml @@ -0,0 +1,20 @@ +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: requirement-refinement + uid: ../if/no-inline +non-functional-type: interface +rationale: | + If the function has no side effects, it may still be subject to inlining. + To avoid this, produce an artificial side effect with ``asm ("");``. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/no-inline:/name} macro is used as last part of a + function declaration or is attached to a function definition, + and the function has side-effects, + the macro shall prevent the compiler from inlining this function. +type: requirement diff --git a/spec/rtems/basedefs/req/no-return-0.yml b/spec/rtems/basedefs/req/no-return-0.yml new file mode 100644 index 00000000..7643ef51 --- /dev/null +++ b/spec/rtems/basedefs/req/no-return-0.yml @@ -0,0 +1,24 @@ +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: requirement-refinement + uid: ../if/no-return +non-functional-type: interface +rationale: | + The GNU C compiler can optimize such a function without regard to what would + happen if it ever did return. Declaring a function ${../if/no-return:/name} + also avoids spurious warnings of uninitialized variables. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler starting at version 2.5 + or the ``__cplusplus`` symbol is defined with version ``201103L`` or higher + or the ``__STDC_VERSION__`` symbol is defined with version ``201112L`` + or higher, + and the ${../if/no-return:/name} macro is used as first part of a + function declaration or definition, + the ${../if/no-return:/name} macro shall + inform the compiler that this function does not return when called. +type: requirement diff --git a/spec/rtems/basedefs/req/obfuscate-variable-0.yml b/spec/rtems/basedefs/req/obfuscate-variable-0.yml new file mode 100644 index 00000000..11a132d9 --- /dev/null +++ b/spec/rtems/basedefs/req/obfuscate-variable-0.yml @@ -0,0 +1,20 @@ +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: requirement-refinement + uid: ../if/obfuscate-variable +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and argument ${../if/obfuscate-variable:/params[0]/name} + is an automatic variable or function argument, + and the value of that variable or function argument is of a type + which fits into a register, + the ${../if/obfuscate-variable:/name} macro shall prevent the compiler + from performing optimizations based on the variable value. +type: requirement diff --git a/spec/rtems/basedefs/req/packed-0.yml b/spec/rtems/basedefs/req/packed-0.yml new file mode 100644 index 00000000..2a6085be --- /dev/null +++ b/spec/rtems/basedefs/req/packed-0.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + uid: ../if/packed +non-functional-type: interface +rationale: | + Note: The 4.1, 4.2 and 4.3 series of GCC ignore the packed attribute + on bit-fields of type char. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/packed:/name} macro is used as last part of a + structure member declaration, + and the ``aligned`` attribute or ${../if/aligned:/name} macro + is not used on this structure member, + the ${../if/packed:/name} macro shall cause the structure member + to be aligned at one bit for a bit-field member and one byte otherwise. +type: requirement diff --git a/spec/rtems/basedefs/req/packed-1.yml b/spec/rtems/basedefs/req/packed-1.yml new file mode 100644 index 00000000..9f100baf --- /dev/null +++ b/spec/rtems/basedefs/req/packed-1.yml @@ -0,0 +1,25 @@ +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: requirement-refinement + uid: ../if/packed +non-functional-type: interface +rationale: | + The effect of the ${../if/packed:/name} macro is not propagated into any + structure, union or C++ class which is member of the structure, union or + C++ class declaration to which the macro is attached. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/packed:/name} macro is attached to a + struct, union, or C++ class type definition, + and the ``aligned`` attribute or ${../if/aligned:/name} macro + is not used on the struct, union, or C++ class type definition or + any member thereof, + the ${../if/packed:/name} macro shall cause all structure, union, or class + members to be aligned at one bit for a bit-field member and + one byte otherwise. +type: requirement diff --git a/spec/rtems/basedefs/req/packed-2.yml b/spec/rtems/basedefs/req/packed-2.yml new file mode 100644 index 00000000..77240d51 --- /dev/null +++ b/spec/rtems/basedefs/req/packed-2.yml @@ -0,0 +1,18 @@ +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: requirement-refinement + uid: ../if/packed +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/packed:/name} macro is attached to a + enum type definition, + the ${../if/packed:/name} macro shall cause the use of the smallest integral + type to represent the values of the enum. +type: requirement diff --git a/spec/rtems/basedefs/req/predict-false-0.yml b/spec/rtems/basedefs/req/predict-false-0.yml new file mode 100644 index 00000000..4d05c771 --- /dev/null +++ b/spec/rtems/basedefs/req/predict-false-0.yml @@ -0,0 +1,24 @@ +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: requirement-refinement + uid: ../if/predict-false +non-functional-type: interface +rationale: | + Example: ``if ( ${../if/predict-false:/name}( -1 == i ) ) { ... }``. + The GNU C compiler uses this information for branch optimization. + ``builtin-expect-probability`` defaults to 90%. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/predict-false:/name} macro is used as a conditional + in ``if``-expressions and loop expressions, + and ${../if/predict-false:/params[0]/name} after undergoing all possible C + pre-processor substitutions is an integral expression, + the macro shall cause the compiler to assume that by the percentage of + cases defined by ``builtin-expect-probability`` the expression evaluates + to 0. +type: requirement diff --git a/spec/rtems/basedefs/req/predict-true-0.yml b/spec/rtems/basedefs/req/predict-true-0.yml new file mode 100644 index 00000000..9c75707d --- /dev/null +++ b/spec/rtems/basedefs/req/predict-true-0.yml @@ -0,0 +1,27 @@ +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: requirement-refinement + uid: ../if/predict-true +non-functional-type: interface +rationale: | + Example: ``if ( ${../if/predict-true:/name}( 99 > i ) ) { ... }``. + The GNU C compiler uses this information for branch optimization. + ``builtin-expect-probability`` defaults to 90%. + Note the misleading name: The macro tells the compiler to assume + "the result is 1" not "the result is not 0" as one would expect for + ``true``. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/predict-true:/name} macro is used as a conditional + in ``if``-expressions and loop expressions, + and ${../if/predict-true:/params[0]/name} after undergoing all possible C + pre-processor substitutions is an integral expression, + the macro shall cause the compiler to assume that by the percentage of + cases defined by ``builtin-expect-probability`` the expression evaluates + to 1. +type: requirement diff --git a/spec/rtems/basedefs/req/printflike-0.yml b/spec/rtems/basedefs/req/printflike-0.yml new file mode 100644 index 00000000..39c923dc --- /dev/null +++ b/spec/rtems/basedefs/req/printflike-0.yml @@ -0,0 +1,32 @@ +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: requirement-refinement + uid: ../if/printflike +non-functional-type: interface +rationale: | + Counting of arguments starts at 1 from the left with the + exception of non-static C++ methods where the counting starts with + 2 due to the implicit ``this`` argument. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/printflike:/name} macro is used as last part of a + function declaration or prefixes a function definition, + and ${../if/printflike:/params[0]/name} as well as + ${../if/printflike:/params[1]/name} are constant numbers + referring to two different arguments of that function, + and the function argument number ${../if/printflike:/params[0]/name} + is a ``printf``-format string, + and the function argument number {../if/printflike:/params[1]/name} + is the first argument to be used in the ``printf``-format string, + and all other arguments used in the ``printf``-format string + are arguments {../if/printflike:/params[1]/name} + 1, + {../if/printflike:/params[1]/name} + 2, + {../if/printflike:/params[1]/name} + 3, and so on, + the macro shall cause the compiler to use this information for + type checking the format string and arguments. +type: requirement diff --git a/spec/rtems/basedefs/req/printflike-1.yml b/spec/rtems/basedefs/req/printflike-1.yml new file mode 100644 index 00000000..48d3f0b9 --- /dev/null +++ b/spec/rtems/basedefs/req/printflike-1.yml @@ -0,0 +1,30 @@ +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: requirement-refinement + uid: ../if/printflike +non-functional-type: interface +rationale: | + This case is for functions where the arguments are not available + to be checked (such as ``vprintf``). The compiler will only check + the format string for consistency. + + Counting of arguments starts at 1 from the left with the + exception of non-static C++ methods where the counting starts with + 2 due to the implicit ``this`` argument. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/printflike:/name} macro is used as last part of a + function declaration or prefixes a function definition, + and ${../if/printflike:/params[0]/name} is a constant number + referring to an argument of that function, + and the function argument number ${../if/printflike:/params[0]/name} + is a ``printf``-format string, + and the function argument {../if/printflike:/params[1]/name} is 0, + the macro shall cause the compiler to use this information for + checking the format string. +type: requirement diff --git a/spec/rtems/basedefs/req/pure-0.yml b/spec/rtems/basedefs/req/pure-0.yml new file mode 100644 index 00000000..450b9804 --- /dev/null +++ b/spec/rtems/basedefs/req/pure-0.yml @@ -0,0 +1,23 @@ +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: requirement-refinement + uid: ../if/pure +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/pure:/name} macro is attached to a + function declaration or definition, + and the function has no observable effects on the state of the program other + than to return a value, + the ${../if/pure:/name} macro shall permit the compiler to replace + subsequent calls to the function with the same argument values by the result + of the first call + provided the state of the program observable by that function + does not change in between two calls. +type: requirement diff --git a/spec/rtems/basedefs/req/return-address-0.yml b/spec/rtems/basedefs/req/return-address-0.yml new file mode 100644 index 00000000..dccc706f --- /dev/null +++ b/spec/rtems/basedefs/req/return-address-0.yml @@ -0,0 +1,29 @@ +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: requirement-refinement + uid: ../if/return-address +non-functional-type: interface +rationale: | + From the GNU C compiler documentation: + + * When inlining the expected behavior is that the function returns + the address of the function that is returned to. + * When the top of the stack has been reached, this function returns + an unspecified value. + * Additional post-processing of the returned value may be needed, see + ``__builtin_extract_return_addr``. + * The stored representation of the return address in memory may be + different from the address returned by ``__builtin_return_address``. + + Under these circumstances it is at least difficult to specify + what the actual result of this macro is. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + the ${../if/return-address:/name} macro shall evaluate to the + code ``__builtin_return_address( 0 )``. +type: requirement diff --git a/spec/rtems/basedefs/req/section-0.yml b/spec/rtems/basedefs/req/section-0.yml new file mode 100644 index 00000000..9274f10e --- /dev/null +++ b/spec/rtems/basedefs/req/section-0.yml @@ -0,0 +1,23 @@ +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: requirement-refinement + uid: ../if/section +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/section:/name} macro is attached to a + function declaration or definition or a global variable definition, + and the argument ${../if/section:/params[0]/name} after applying + all possible C pre-processor substitutions to its value is a + C sting containing valid linker section name, + and the file format used supports arbitary sections, + the macro shall cause the compiler to store the function or + variable is a section named like the result of the pre-processor + substitutions on its argument ${../if/section:/params[0]/name}. +type: requirement diff --git a/spec/rtems/basedefs/req/static-assert-0.yml b/spec/rtems/basedefs/req/static-assert-0.yml new file mode 100644 index 00000000..738c48d0 --- /dev/null +++ b/spec/rtems/basedefs/req/static-assert-0.yml @@ -0,0 +1,23 @@ +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: requirement-refinement + uid: ../if/static-assert +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the argument ${../if/static-assert:/params[0]/name} after + applying all possible C pre-processor substitutions to its + value results in a valid C expression of integral type, + and this expression can be evaluated at compile time, + and the argument ${../if/static-assert:/params[1]/name} which + may or may not undergo C pre-processor substitutions results + into a valid C identifier, + the ${../if/static-assert:/name} macro shall cause the compiler to + produce a compilation error if the expression resulting from + ${../if/static-assert:/params[0]/name} evaluates to 0. +type: requirement diff --git a/spec/rtems/basedefs/req/string-0.yml b/spec/rtems/basedefs/req/string-0.yml new file mode 100644 index 00000000..d16c06dc --- /dev/null +++ b/spec/rtems/basedefs/req/string-0.yml @@ -0,0 +1,17 @@ +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: requirement-refinement + uid: ../if/string +non-functional-type: interface +rationale: | + The exact rules on how this string is build are defined by the C standard + and are too complex to be repeated in this requirement. +references: [] +requirement-type: non-functional +text: | + The ${../if/string:/name} macro shall result in a string formed by + the C pre-processor ``#`` operator placed before the formal parameter. +type: requirement diff --git a/spec/rtems/basedefs/req/symbol-name-0.yml b/spec/rtems/basedefs/req/symbol-name-0.yml new file mode 100644 index 00000000..a27f63fc --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-0.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..45535a23 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-1.yml @@ -0,0 +1,23 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..1141f2b5 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-2.yml @@ -0,0 +1,19 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..18daa006 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-3.yml @@ -0,0 +1,20 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..f2a07989 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-4.yml @@ -0,0 +1,21 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..508ee639 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-5.yml @@ -0,0 +1,15 @@ +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: requirement-refinement + 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 new file mode 100644 index 00000000..e9394553 --- /dev/null +++ b/spec/rtems/basedefs/req/symbol-name-6.yml @@ -0,0 +1,22 @@ +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: requirement-refinement + 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/true-0.yml b/spec/rtems/basedefs/req/true-0.yml new file mode 100644 index 00000000..1de18ee2 --- /dev/null +++ b/spec/rtems/basedefs/req/true-0.yml @@ -0,0 +1,14 @@ +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: requirement-refinement + uid: ../if/true +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + The macro ${../if/true:/name} shall result in the text 1. +type: requirement diff --git a/spec/rtems/basedefs/req/typeof-refx-0.yml b/spec/rtems/basedefs/req/typeof-refx-0.yml new file mode 100644 index 00000000..b6a92273 --- /dev/null +++ b/spec/rtems/basedefs/req/typeof-refx-0.yml @@ -0,0 +1,28 @@ +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: requirement-refinement + uid: ../if/typeof-refx +non-functional-type: interface +rationale: | + From the GNU C compiler documentation: + The operand of ${../if/typeof-refx:/params[1]/name} is evaluated for + its side effects if and only if it is an expression of variably + modified type or the name of such a type. +references: [] +requirement-type: non-functional +text: | + When the argument value of ${../if/typeof-refx:/params[0]/name} consists + of a sequence of *i* ``*`` and the type of the other argument + has *i* or less than *i* nested pointers + (for example ``*`` for a pointer to ``int``, + ``**`` for a pointer to a pointer of ``int``, ``***`` for a pointer to + a pointer to a pointer to ``int``), + and ${../if/typeof-refx:/params[1]/name} is either a pointer type + (possibly with qualifiers) or an expression of such a pointer type, + the macro ${../if/typeof-refx:/name} shall result in a type expression + which is the type of argument ${../if/typeof-refx:/params[1]/name} + with the given number of pointers removed. +type: requirement diff --git a/spec/rtems/basedefs/req/unreachable-0.yml b/spec/rtems/basedefs/req/unreachable-0.yml new file mode 100644 index 00000000..fb30d41c --- /dev/null +++ b/spec/rtems/basedefs/req/unreachable-0.yml @@ -0,0 +1,20 @@ +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: requirement-refinement + uid: ../if/unreachable +non-functional-type: interface +rationale: | + The use of this macro will suppress some compiler warnings + and may permit some compiler optimizations. +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/unreachable:/name} macro is placed in a part of + the code which control flow can under no circumstances ever reach, + the macro shall inform the compiler that this place in code + cannot be reached. +type: requirement diff --git a/spec/rtems/basedefs/req/unused-0.yml b/spec/rtems/basedefs/req/unused-0.yml new file mode 100644 index 00000000..8b79965c --- /dev/null +++ b/spec/rtems/basedefs/req/unused-0.yml @@ -0,0 +1,17 @@ +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: requirement-refinement + uid: ../if/unused +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/unused:/name} macro is attached to a function definition, + the ${../if/unused:/name} macro shall prevent the compiler from emitting + a warning if this function is not used. +type: requirement diff --git a/spec/rtems/basedefs/req/unused-1.yml b/spec/rtems/basedefs/req/unused-1.yml new file mode 100644 index 00000000..5778e3a0 --- /dev/null +++ b/spec/rtems/basedefs/req/unused-1.yml @@ -0,0 +1,18 @@ +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: requirement-refinement + uid: ../if/unused +non-functional-type: interface +rationale: null +references: [] +requirement-type: non-functional +text: | + When the code is compiled with the GNU C compiler, + and the ${../if/unused:/name} macro is appended to a label in this form: + ``