From e3524c54848d04ccfb0e5e0a5aed76824b04e922 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 9 Nov 2020 14:40:10 +0100 Subject: spec: Review basic definitions API --- spec/rtems/basedefs/if/alias.yml | 2 +- spec/rtems/basedefs/if/align-down.yml | 4 ++-- spec/rtems/basedefs/if/align-up.yml | 4 ++-- spec/rtems/basedefs/if/aligned.yml | 2 +- spec/rtems/basedefs/if/array-size.yml | 9 +++++---- spec/rtems/basedefs/if/concat.yml | 2 +- spec/rtems/basedefs/if/container-of.yml | 4 ++-- spec/rtems/basedefs/if/declare-global-symbol.yml | 2 +- spec/rtems/basedefs/if/deconst.yml | 2 +- spec/rtems/basedefs/if/define-global-symbol.yml | 2 +- spec/rtems/basedefs/if/dequalify-depthx.yml | 2 +- spec/rtems/basedefs/if/dequalify.yml | 2 +- spec/rtems/basedefs/if/devolatile.yml | 2 +- spec/rtems/basedefs/if/expand.yml | 2 +- spec/rtems/basedefs/if/false.yml | 3 ++- spec/rtems/basedefs/if/have-member-same-type.yml | 7 ++++--- spec/rtems/basedefs/if/predict-false.yml | 10 ++++++---- spec/rtems/basedefs/if/predict-true.yml | 12 +++++++----- spec/rtems/basedefs/if/return-address.yml | 5 +++-- spec/rtems/basedefs/if/section.yml | 3 +-- spec/rtems/basedefs/if/static-assert.yml | 2 +- spec/rtems/basedefs/if/string.yml | 2 +- spec/rtems/basedefs/if/symbol-name.yml | 5 +++-- spec/rtems/basedefs/if/true.yml | 3 ++- spec/rtems/basedefs/if/typeof-refx.yml | 7 ++++--- spec/rtems/basedefs/if/unused.yml | 3 +-- spec/rtems/basedefs/if/used.yml | 2 +- spec/rtems/basedefs/if/weak-alias.yml | 3 +-- spec/rtems/basedefs/if/xconcat.yml | 2 +- spec/rtems/basedefs/if/xstring.yml | 2 +- spec/rtems/basedefs/if/zero-length-array.yml | 2 +- 31 files changed, 61 insertions(+), 53 deletions(-) diff --git a/spec/rtems/basedefs/if/alias.yml b/spec/rtems/basedefs/if/alias.yml index ef65f1bc..656c2a8e 100644 --- a/spec/rtems/basedefs/if/alias.yml +++ b/spec/rtems/basedefs/if/alias.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Instructs the compiler to generate an alias to the specified target function. + Instructs the compiler to generate an alias to the target function. copyrights: - Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/align-down.yml b/spec/rtems/basedefs/if/align-down.yml index d38b4d20..a8efbdad 100644 --- a/spec/rtems/basedefs/if/align-down.yml +++ b/spec/rtems/basedefs/if/align-down.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the specified value aligned down to the specified alignment. + Aligns down the value to the alignment. copyrights: - Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -31,6 +31,6 @@ params: name: _alignment return: return: | - The specified value aligned down to the specified alignment is returned. + Returns the value aligned down to the alignment. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/align-up.yml b/spec/rtems/basedefs/if/align-up.yml index 597667aa..e494b74b 100644 --- a/spec/rtems/basedefs/if/align-up.yml +++ b/spec/rtems/basedefs/if/align-up.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the specified value aligned up to the specified alignment. + Aligns up the value to the alignment. copyrights: - Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -31,6 +31,6 @@ params: name: _alignment return: return: | - The specified value aligned up to the specified alignment is returned. + Returns the value aligned up to the alignment. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/aligned.yml b/spec/rtems/basedefs/if/aligned.yml index 65761ac2..44f3e12e 100644 --- a/spec/rtems/basedefs/if/aligned.yml +++ b/spec/rtems/basedefs/if/aligned.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Instructs the compiler in a declaration or definition to enforce the - specified alignment. + alignment. copyrights: - Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/array-size.yml b/spec/rtems/basedefs/if/array-size.yml index f9a1e898..991dfc20 100644 --- a/spec/rtems/basedefs/if/array-size.yml +++ b/spec/rtems/basedefs/if/array-size.yml @@ -1,11 +1,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the element count of the specified array. + Gets the element count of the array. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: default: | - (sizeof(_array) / sizeof((_array)[0])) + ( sizeof( _array ) / sizeof( ( _array )[ 0 ] ) ) variants: [] description: null enabled-by: true @@ -20,10 +20,11 @@ name: RTEMS_ARRAY_SIZE notes: null params: - description: | - is the name of the array. + is the name of the array. This parameter is evaluated twice. dir: null name: _array return: - return: The element count of the specified array. + return: | + Returns the element count of the array. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/concat.yml b/spec/rtems/basedefs/if/concat.yml index 17e3229b..d0f7ebdd 100644 --- a/spec/rtems/basedefs/if/concat.yml +++ b/spec/rtems/basedefs/if/concat.yml @@ -28,6 +28,6 @@ params: name: _y return: return: | - The concatenation of the tokens _x and _y. + Returns the concatenation of the tokens _x and _y. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/container-of.yml b/spec/rtems/basedefs/if/container-of.yml index 40eb28f4..0636d79b 100644 --- a/spec/rtems/basedefs/if/container-of.yml +++ b/spec/rtems/basedefs/if/container-of.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the pointer to the container of a specified member pointer. + Gets the container of a member. copyrights: - Copyright (C) 2014 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -33,6 +33,6 @@ params: name: _member_name return: return: | - Returns the pointer to the container of a specified member pointer. + Returns the pointer to the container of a member pointer. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/declare-global-symbol.yml b/spec/rtems/basedefs/if/declare-global-symbol.yml index 02e319fe..edd39ff4 100644 --- a/spec/rtems/basedefs/if/declare-global-symbol.yml +++ b/spec/rtems/basedefs/if/declare-global-symbol.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Declares a global symbol with the specified name. + Declares a global symbol with the name. copyrights: - Copyright (C) 2018 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/deconst.yml b/spec/rtems/basedefs/if/deconst.yml index 69087d1a..461bb110 100644 --- a/spec/rtems/basedefs/if/deconst.yml +++ b/spec/rtems/basedefs/if/deconst.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Performs a type cast which removes const qualifiers without warnings to the - specified type for the specified pointer variable. + type for the pointer variable. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2014 Paval Pisa diff --git a/spec/rtems/basedefs/if/define-global-symbol.yml b/spec/rtems/basedefs/if/define-global-symbol.yml index 32ba2b76..33b50e9b 100644 --- a/spec/rtems/basedefs/if/define-global-symbol.yml +++ b/spec/rtems/basedefs/if/define-global-symbol.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Defines a global symbol with the specified name and value. + Defines a global symbol with the name and value. copyrights: - Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/dequalify-depthx.yml b/spec/rtems/basedefs/if/dequalify-depthx.yml index 8d681178..43209566 100644 --- a/spec/rtems/basedefs/if/dequalify-depthx.yml +++ b/spec/rtems/basedefs/if/dequalify-depthx.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Performs a type cast which removes qualifiers without warnings to the - specified type for the specified variable. + type for the variable. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2014 Paval Pisa diff --git a/spec/rtems/basedefs/if/dequalify.yml b/spec/rtems/basedefs/if/dequalify.yml index 70b78b21..3a9da4dc 100644 --- a/spec/rtems/basedefs/if/dequalify.yml +++ b/spec/rtems/basedefs/if/dequalify.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Performs a type cast which removes all qualifiers without warnings to the - specified type for the specified pointer variable. + type for the pointer variable. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2014 Paval Pisa diff --git a/spec/rtems/basedefs/if/devolatile.yml b/spec/rtems/basedefs/if/devolatile.yml index 06eb7f4c..8431a4e5 100644 --- a/spec/rtems/basedefs/if/devolatile.yml +++ b/spec/rtems/basedefs/if/devolatile.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | Performs a type cast which removes volatile qualifiers without warnings to - the specified type for the specified pointer variable. + the type for the pointer variable. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2014 Paval Pisa diff --git a/spec/rtems/basedefs/if/expand.yml b/spec/rtems/basedefs/if/expand.yml index 70c19372..5172e481 100644 --- a/spec/rtems/basedefs/if/expand.yml +++ b/spec/rtems/basedefs/if/expand.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Helper macro to perform a macro expansion on the specified token. + Helper macro to perform a macro expansion on the token. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/false.yml b/spec/rtems/basedefs/if/false.yml index 88bad480..5036cc98 100644 --- a/spec/rtems/basedefs/if/false.yml +++ b/spec/rtems/basedefs/if/false.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: If FALSE is undefined, then FALSE is defined to 0. +brief: | + If FALSE is undefined, then FALSE is defined to 0. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/have-member-same-type.yml b/spec/rtems/basedefs/if/have-member-same-type.yml index cc0ed3f5..24fcdc7d 100644 --- a/spec/rtems/basedefs/if/have-member-same-type.yml +++ b/spec/rtems/basedefs/if/have-member-same-type.yml @@ -1,7 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Evaluates to true if the specified members of two types have compatible - types, otherwise to false. + Checks if members of two types have compatible types. copyrights: - Copyright (C) 2017 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -44,6 +43,8 @@ params: dir: null name: _m_rhs return: - return: null + return: | + Returns to true, if the members of two types have compatible types, + otherwise false. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/predict-false.yml b/spec/rtems/basedefs/if/predict-false.yml index 22b6dd78..44af5da4 100644 --- a/spec/rtems/basedefs/if/predict-false.yml +++ b/spec/rtems/basedefs/if/predict-false.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the value of the specified integral expression and tells the compiler - that the predicted value is false (1). + Evaluates the integral expression and tells the compiler that the predicted + value is false (0). copyrights: - Copyright (C) 2018 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -25,10 +25,12 @@ name: RTEMS_PREDICT_FALSE notes: null params: - description: | - is the expression. + is the integral expression. dir: null name: _exp return: - return: The value of the expression. + return: | + Returns the value of the integral expression and tells the compiler that + the predicted value is false (0). return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/predict-true.yml b/spec/rtems/basedefs/if/predict-true.yml index 83afbb07..74151329 100644 --- a/spec/rtems/basedefs/if/predict-true.yml +++ b/spec/rtems/basedefs/if/predict-true.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the value of the specified integral expression and tells the compiler - that the predicted value is true (1). + Evaluates the integral expression and tells the compiler that the predicted + value is true (1). copyrights: - Copyright (C) 2018 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -9,7 +9,7 @@ definition: ( _exp ) variants: - definition: | - ${/compiler/if/builtin-expect:/name}( ( _exp ), 1 ) + ${/compiler/if/builtin-expect:/name}( ( _exp ), 0 ) enabled-by: - defined(${/compiler/if/gnuc:/name}) description: null @@ -25,10 +25,12 @@ name: RTEMS_PREDICT_TRUE notes: null params: - description: | - is the expression. + is the integral expression. dir: null name: _exp return: - return: The value of the expression. + return: | + Returns the value of the integral expression and tells the compiler that + the predicted value is true (1). return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/return-address.yml b/spec/rtems/basedefs/if/return-address.yml index f2fb271a..4a5994c2 100644 --- a/spec/rtems/basedefs/if/return-address.yml +++ b/spec/rtems/basedefs/if/return-address.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the return address of the current function. + Gets the return address of the current function. copyrights: - Copyright (C) 2019 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -23,6 +23,7 @@ name: RTEMS_RETURN_ADDRESS notes: null params: [] return: - return: The return address of the current function. + return: | + Returns the return address of the current function. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/section.yml b/spec/rtems/basedefs/if/section.yml index 1777393b..cfe39de7 100644 --- a/spec/rtems/basedefs/if/section.yml +++ b/spec/rtems/basedefs/if/section.yml @@ -1,7 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Instructs the compiler to place a specific variable or function in the - specified section. + Instructs the compiler to place the variable or function in the section. copyrights: - Copyright (C) 2015 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/static-assert.yml b/spec/rtems/basedefs/if/static-assert.yml index 1ada0b73..a66edb71 100644 --- a/spec/rtems/basedefs/if/static-assert.yml +++ b/spec/rtems/basedefs/if/static-assert.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Asserts at compile time that the specified condition is satisfied. + Asserts at compile time that the condition is satisfied. copyrights: - Copyright (C) 2011, 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/string.yml b/spec/rtems/basedefs/if/string.yml index c6c4746a..e8f2839b 100644 --- a/spec/rtems/basedefs/if/string.yml +++ b/spec/rtems/basedefs/if/string.yml @@ -24,6 +24,6 @@ params: name: _x return: return: | - The stringification of the token _x. + Returns the stringification of the token _x. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/symbol-name.yml b/spec/rtems/basedefs/if/symbol-name.yml index 6bd5c607..198818ba 100644 --- a/spec/rtems/basedefs/if/symbol-name.yml +++ b/spec/rtems/basedefs/if/symbol-name.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Constructs a symbol name. + Maps the name to the associated symbol name. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -29,6 +29,7 @@ params: dir: null name: _name return: - return: null + return: | + Returns the symbol name associated with the name. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/true.yml b/spec/rtems/basedefs/if/true.yml index 95cecf0f..f034ab6e 100644 --- a/spec/rtems/basedefs/if/true.yml +++ b/spec/rtems/basedefs/if/true.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: If TRUE is undefined, then TRUE is defined to 1. +brief: | + If TRUE is undefined, then TRUE is defined to 1. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/typeof-refx.yml b/spec/rtems/basedefs/if/typeof-refx.yml index b05a8809..36adaf79 100644 --- a/spec/rtems/basedefs/if/typeof-refx.yml +++ b/spec/rtems/basedefs/if/typeof-refx.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the type of a pointer reference of the specified level to the specified type. + Gets the pointer reference type. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 2014 Paval Pisa @@ -8,7 +8,7 @@ definition: default: '' variants: - definition: | - ${/compiler/if/typeof:/name}(_level(union { int z; ${/compiler/if/typeof:/name}(_target) x; }){0}.x) + ${/compiler/if/typeof:/name}( _level( union { int z; ${/compiler/if/typeof:/name}( _target ) x; } ){ 0 }.x ) enabled-by: - defined(${/compiler/if/gnuc:/name}) description: | @@ -33,6 +33,7 @@ params: dir: null name: _target return: - return: null + return: | + Returns the type of a pointer reference of the specified level to the specified type. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/unused.yml b/spec/rtems/basedefs/if/unused.yml index e3998f70..935eaaff 100644 --- a/spec/rtems/basedefs/if/unused.yml +++ b/spec/rtems/basedefs/if/unused.yml @@ -1,7 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Tells the compiler that a specific variable or function is deliberately - unused. + Tells the compiler that the variable or function is deliberately unused. copyrights: - Copyright (C) 2013 On-Line Applications Research Corporation (OAR) definition: diff --git a/spec/rtems/basedefs/if/used.yml b/spec/rtems/basedefs/if/used.yml index 0d2fd7dc..41688717 100644 --- a/spec/rtems/basedefs/if/used.yml +++ b/spec/rtems/basedefs/if/used.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Tells the compiler that a specific variable or function is used. + Tells the compiler that the variable or function is used. copyrights: - Copyright (C) 2009 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/weak-alias.yml b/spec/rtems/basedefs/if/weak-alias.yml index dc71c778..289bbf63 100644 --- a/spec/rtems/basedefs/if/weak-alias.yml +++ b/spec/rtems/basedefs/if/weak-alias.yml @@ -1,7 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Instructs the compiler to generate a weak alias to the specified target - function. + Instructs the compiler to generate a weak alias to the target function. copyrights: - Copyright (C) 2017 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/basedefs/if/xconcat.yml b/spec/rtems/basedefs/if/xconcat.yml index d12df956..2b753b0e 100644 --- a/spec/rtems/basedefs/if/xconcat.yml +++ b/spec/rtems/basedefs/if/xconcat.yml @@ -30,6 +30,6 @@ params: name: _y return: return: | - The concatenation of the expansions of tokens _x and _y. + Returns the concatenation of the expansions of tokens _x and _y. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/xstring.yml b/spec/rtems/basedefs/if/xstring.yml index 67c71605..6a335c32 100644 --- a/spec/rtems/basedefs/if/xstring.yml +++ b/spec/rtems/basedefs/if/xstring.yml @@ -24,6 +24,6 @@ params: name: _x return: return: | - The stringification of the expansion of token _x. + Returns the stringification of the expansion of token _x. return-values: [] type: interface diff --git a/spec/rtems/basedefs/if/zero-length-array.yml b/spec/rtems/basedefs/if/zero-length-array.yml index cef505c6..b82a2c5f 100644 --- a/spec/rtems/basedefs/if/zero-length-array.yml +++ b/spec/rtems/basedefs/if/zero-length-array.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - This is a constant to declare zero-length arrays. + This constant represents the element count of a zero-length array. copyrights: - Copyright (C) 2014 embedded brains GmbH (http://www.embedded-brains.de) definition: -- cgit v1.2.3