Specification of application configuration options

[Sebastian Huber]

Hello,

I added specification items for most application configuration options 
(all the ones in the RTEMS Classic API Guide). For example:

https://git.rtems.org/sebh/rtems-qual.git/tree/spec/acfg/opt/RTEMS-ACFG-OPT-MAXBARRIERS.yml

SPDX-License-Identifier: CC-BY-SA-4.0
active: true
appl-config-option-type: integer
appl-config-option-default-value: 0
appl-config-option-description: |
   The value of this configuration option defines the maximum number of 
Classic
   API Barriers that can be concurrently active.
appl-config-option-index: []
appl-config-option-name: CONFIGURE_MAXIMUM_BARRIERS
appl-config-option-notes: |
   This object class can be configured in unlimited allocation mode, see
   :ref:`ConfigUnlimitedObjects`.
appl-config-option-constraint:
   min: 0
   max: 65535
   links:
   - RTEMS-ACFG-OPT-CONSTRAINTUNLIMITED
   - RTEMS-ACFG-OPT-CONSTRAINTMEMSZ
copyrights:
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
derived: false
enabled-by: []
header: ''
interface-type: appl-config-option
level: 1.14
links:
- RTEMS-ACFG-CLASSIC: xIlmS8RsfhmUc14dTO2H9l5xcMKe5d555tGIZ3hz_SM=
normative: true
ref: ''
reviewed: DXQ7n4VFdgQXHBbJOlUe7oLa-mccRpU-Sl5TzVd9RFk=
text: ''
type: interface

This specification item is used to generate the documentation (RTEMS 
Classic API Guide) with the following Python module (less than 200 lines 
of code):

https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py

The value constraints are defined in a formalized format.

I have now three open issues.

1.

I need a requirement for this configuration option. The description

"The value of this configuration option defines the maximum number of 
Classic
   API Barriers that can be concurrently active."

is close to a requirement formulation. Should we use the descriptions as 
is as a requirement? Should we add some text like this for each option:

"The system shall provide an application configuration option which 
defines the maximum number of Classic
   API Barriers that can be concurrently active."

2.

I need traceability to the source code, e.g. I need a link to

https://git.rtems.org/rtems/tree/cpukit/include/rtems/confdefs/objectsclassic.h#n86

and

https://git.rtems.org/rtems/tree/cpukit/rtems/src/barrier.c

I opened a separate thread for this:

https://lists.rtems.org/pipermail/devel/2020-March/058744.html

3.

The specification items may contain more than one requirement, e.g. the 
"appl-config-option-default-value" is the short form of a requirement 
like this:

"The application configuration option CONFIGURE_MAXIMUM_BARRIERS shall 
have a default value of 0."

How should we reference requirements like this. For example:

RTEMS-ACFG-OPT-MAXBARRIERS:appl-config-option-default-value

RTEMS-ACFG-OPT-MAXBARRIERS/appl-config-option-default-value

?

This is no longer in line with the Doorstop tool. Here we would have to 
add a new file for this which is linked to RTEMS-ACFG-OPT-MAXBARRIERS, 
e.g. RTEMS-ACFG-OPT-MAXBARRIERS-DEFAULTVALUE.

We should think about dropping the use of Doorstop and instead use our 
own tool. I really like the ideas of Doorstop, but I think it could be a 
bit too inflexible for our purpose. Not using Doorstop would enable us 
to shorten the paths. We could use a scheme like this to identify 
requirements: dir/dir2/dir3/item:attr:subattr which maps to a file 
dir/dir2/dir3/item.yaml. With Doorstop this would be 
dir/dir2/dir3/dir-dir2-dir3-item.yml. We don't have to decide this now, 
it is just something to think about. Ideally before the new build system 
is integrated.