Home
DO-178B
Do178Builder
Tutorial
Samples
DocBook
Birds Project
Traceability Tools
 
Bird Man, a painting by artist Lynn Rothan

Contents


Introduction

Among the various objectives which you must satisfy to achieve compliance with DO-178B is providing traceability.  Several kinds of traceability may need to be addressed:
  1. Traceability from system requirements to software requirements, and vice-versa.  In other words, is every system requirement accounted for in the software requirements, and do all of the software requirements result from system requirements?  Those software requirements that do not result from system requirements—the so-called "derived requirements"—need to be identified so that they can be fed back to the system safety assessment process.
  2. Traceability from software requirements ("high-level" requirements) to design ("low-level" requirements), and possibly vice-versa.
  3. Traceability from software requirements and/or design ("high-level" and/or "low-level" requirements) to source code, and at assurance level C or above, vice-versa.  In other words, are all of the software requirements addressed in the code, and at level C or above, are we assured that there'e no "extra" code that doesn't relate to requirements?  Recall that since software test cases are supposed to be based on the software requirements, code that is not based on the software requirements will not have test cases, and therefore will not be tested.  This is a no-no at level C or higher.
  4. Traceability from software requirements and design to software test cases.  The comment above says it all!
To demonstrate traceability, it is normally necessary to construct cross-reference data interrelating the various items mentioned above.  Construction of these traceability cross-references can be very time-consuming and labor-intensive even if done efficiently, and therefore can cause your development effort to be very inefficient if handled inefficiently.

Do178Builder has native support for automatically generating cross-reference data for traceability types #2 and #3, and partially-automatic partially-manual support for traceability types #1 and #4.  (Support for types #1 and #4 cannot be fully automatic, simply because system requirements are typically not maintained within Do178Builder, and source never is maintained within Do178Builder, so only part of the information needed to generate cross-reference is available unless you enter it manually.)

It is important to recognize that any support provided by Do178Builder or other tools for automatically creating traceability cross-reference data only exposes the interrelationships among the data you've created.  It cannot of itself guarantee that your structuring of the data has created correct interrelationships.  It's always your responsibility to do that.  So our discussion here relates entirely to construction of a sensible representation of the cross-reference data.

(What does this mean?  Well, the action of automatically generating a trace matrix from your Do178Builder project data is like using a compiler to automatically generate executable code from source code:  even if the compilation is successful without errors or warnings, there's no guarantee that the code is correct or will run properly.  The error-free compilation is necessary but not sufficient to guarantee correctness.  Expecting a trace matrix to be correct without checking it is like expecting your program to run properly just because it compiled without errors.  But enough said about that!  It's a problem you'll have regardless of what method you've used.)

In order for the native traceability features in Do178Builder to be used, you need to buy into Do178Builder's world view.  In Do178Builder's world view, requirements and test cases are strictly hierarchical.  In other words, Do178Builder expects that a high-level software requirement may be expressed or augmented by one or more low-level requirements, and that a high-level or low-level software requirement is testable by one or more test cases.  It does not expect, for example, that a low-level requirement is related to multiple high-level requirements.  Furthermore, it expects you to structure that data within your Do178Builder project database in such a way that each high-level or low-level requirement is expressed within a single section of the software requirements document (SRD) or software design data (SDD).  If this is the case, then the high-level and low-level requirements can be uniquely identified by their SRD or SDD section numbers.  When this method words, it works well essentially without effort from the software developers.

Nevertheless, there are three basic weaknesses of Do178Builder's native method:
There is only one real alternative, whether Do178Builder is used to manage requirements, whether they are managed manually, or whether they are managed within a dedicated requirements-management system such as DOORS, and that is to associate each requirement with an explicit label other than the section numbers.  This method also has disadvantages:
I fear that there is no good solution for this problem, unless it was a complete new version of Do178Builder that was designed from the ground up to be integrated with a similarly-newly designed requirements management system.  (I don't think this is going to happen!) 

But some partial help can be given by the introduction of additional tools that can perform post-processing of the Do178Builder project databases to fill in some of the gaps.  In other words, a utility program that is somewhat more flexible than Do178Builder's native traceability functionality.  The utility program I'm referring to is known as Do178Builder-utility (surprise!), and its purpose is to generate traceability cross-references independent of the SRD, SDD, and test cases (SVCP), suitable for creation of stand-alone "traceability-matrix" documents and/or massaging via spreadsheet programs like Microsoft Excel.


Hints on Satisfactorily Meeting Traceability Objectives

(I'll fill this in later.)


Files Produced by the Do178Builder-utility Program

Do178Builder-utility is used to process the Do178Builder your XML project database to produce various kinds of Comma Separated Value (CSV) files containing traceability data.  These files could be brought into a spreadsheet program such as Microsoft Excel (I use OpenOffice.org's Calc spreadsheet program myself).  Having done that, you can sort or otherwise process the data in various ways.

Here are the CSV files which can be produced:

CSV File
Description
Sample
Do178Builder-trace-design.csv This is a simple two-column table in which the first column contains high-level software requirements from the SRD document, and the second column contains low-level software requirements from the SDD document.  Because a given high-level requirement could have multiple low-level requirements associated with it, there could be multiple rows with the same high-level requirement.  Or, a given high-level requirement might have no low-level requirements, in which case the low-level requirement is listed as "(none)".

As output by Do178Builder-utility, the table is ordered according to the sequence in which the various objects were encountered in the XML project database, so a useful thing to do within a spreadsheet program is to sort it either on the high-level requirements column or the low-level requirements column.  In the latter case, you may also want to swap the columns so that the (sorted) low-level requirements column appears to the left of the high-level requirements column.
Click to enlarge
Do178Builder-trace-design-full.csv
This is similar to Do178Builder-trace-design.csv (see above), except that it additionally includes columns with the section numbers from the SRD and SDD documents.  Also, since some of the SRD and SDD sections may not contain requirements, there are generally more rows in the table.

The table is ordered according to the sequence in which the various objects were encountered in the XML project database, so it may be desirable to sort it on one or more columns.  For example, if you eliminated the two SRD columns and sorted on the low-level requirements column, you'd have a handy reference that would let easily find out which SDD section contained any given low-level requirement.  It's helpful in operations like this, of course, if you have some way to easily remove duplicate rows from the table.
Click to enlarge
Do178Builder-trace-verify.csv
This is a three-column table in which the first column is a high-level or low-level requirement, the second column is the section number of the requirements or design document from which the requirement comes, and third column is the section in the software verification cases and procedures (SVCP) containing the test case for that requirement.
Click to enlarge
Do178Builder-system.csv
This is a three-column table in which the first column is a system requirement, the second column is a high-level software requirement (DO-178B) or hardware requirement (DO-254), and the third column is the SRD or HRD section in which the software or hardware requirement is defined.

This table cannot be created from data maintained within the Do178Builder project database, because system requirements generally come from an external document (such as a customer-supplied spec).  Therefore, some preparation must be made to supply the data needed for the processing to take place, and that preparation consists of manually adding tags at appropriate places within the Do178Builder project database that reference the system requirements.  Because this tagging is manual, the external references need not necessarily be system requirements, but can be any external reference to input data, such as references to industry standards, to an Interface Control Document (ICD), etc.

An interesting thing can be done with this kind of table, if you are doing both DO-178B and DO-254 on the project, using two separate Do178Builder project databases.  What you can do is to append the Do178Builder-system.csv file for the DO-254 (hardware) data to the one for the DO-178B (software) data, and then sort on the system requirements column.  This gives you a list which shows in a uniform way all of the hardware and software requirements corresponding to any given system requirement, which is helpful in any analysis intended to insure that the system requirements have been adequately covered by the software and hardware requirements.
Click to enlarge
Do178Builder-implement.csv
(Not yet implemented.)  This will allow traceability between software requirements and source code.

I recommend several times above that the trace matrices can be sorted in various interesting ways.  This is true, but I should also mention that the multi-field method of designating document sections, by which I mean numbers like 1.2.3.4 and 5.4.3, is not really very sorting-friendly.  For example, with a straightforward ASCII sort, section 11.1.1 would precede section 6.1 in the sorting order.  Sadly, I don't have a good off-the-hand solution to offer you for that irritation.  The least-destructive way to handle this is to left-pad all fields in the section numbers with zeroes, so that all of the fields have the same width, such as 11.01.01 and 06.01.  This isn't a very good solution, because I can guarantee you that some DER or customer will scream loudly on encountering a table that refers to section 06.01 when the actual document has a section 6.1 instead.  Nevertheless, Do178Builder-utility does have a command-line switch "--sorting" which can be used to achieve such padding if you so desire.  One possible solution, I suppose, is to use the --sortable switch to pad the section number, sort the columns however you like within a spreadsheet program, and then do some post-processing to remove the leading zeroes somehow.

Do178Builder-utility allows you to select the way requirements are identified and the relevant document sections of the SRD, SDD, and SVCP in a pretty flexible way, using so-called regular expressions, though that flexibility is accompanied by a certain complexity in invoking the program.  A three-step process is used to identify high-level software requirements:
  1. All high-level software requirements must be within the SRD document.
  2. All high-level software requirements must be within sections that match a user-specified pattern.  For example, perhaps only sections 3.n.1.n.1 and 5.n.1.n.1 (where n is a possibly multi-digit decimal number) are candidates.
  3. High-level software requirements must be expressed in a certain way, according to the following 2-part evaluation:
Similar considerations apply for low-level requirements and for hardware requirements.

Identification of test cases within the SVCP document is somewhat similar.  There is no assumption that special language is used.  All test cases are identified by section number, and only those sections whose numbers match a user-supplied pattern.


Command-Line Options

A general rule for any use of Do178Builder-utility to create stand-alone trace matrices is that you should use Do178Builder itself with its --no-trace switch in order to prevent it from embedding traceability cross-references within the requirements, design, and test-case document it creates.


The syntax for using the utility is

Do178Builder-utility [OPTIONS] InputFile >LogFile

The InputFile is a Do178Builder XML project database, and the outputs comprise some subset of the various CSV files mentioned above.  Here is a list of OPTIONS:

Option
Description
Notes
--combine-srd-sdd
Like the Do178Builder option of the same name.  Causes the processing to assume that the SRD and SDD (or HRD and HDRD) form a single integrated document rather than two separate documents.

"--delimiter-implement=C"
When --trace-implement (see below is used), chooses the delimiter for the implementation data (source code, CAD files) appearing in the XML project database within <trace></trace> tags.  Usually, either space or a comma.  For any delimiter that is not a space, spaces surrounding the delimiter within the <trace></trace> tags is discarded.

The default is ','.
The quotation marks shown are necessary if the delimiter is a space or punctuation.

Not yet implemented.
"--delimiter-system=C"
When --trace-system (see below is used), chooses the delimiter for the system requirements appearing in the XML project database within <trace></trace> tags.  Usually, either space or a comma.  For any delimiter that is not a space, spaces surrounding the delimiter within the <trace></trace> tags are discarded.

The default is ','.
The quotation marks shown are necessary if the delimiter is a space or punctuation.

Not yet implemented.
--display
Display to the standard output a structural representation of the project database, in terms of all of the section headings and the documents they appear in.  (Not useful if any of the --trace-XXXX switches are used, since they output messages to stdout as well.)

--DO-254
The default assumption is that the input XML file contains DO-178B data.  This command-line switch (similarly to the identical switch in Do178Builder) changes the assumption to DO-254 (hardware) data instead, so the output trace matrices refer to the HRD, HDRD, and HTPR documents instead of the SRD, SDD, and SVCP documents.

--help
Displays a list of options.

"--high-label-pattern=P"
Defines a pattern (regular expression) used with the --trace-XXXX switches to identify labels for high-level software (hardware) requirements in the SRD (HRD).

The default is "--high-label-pattern=\[SR[0-9]+\]", meaning that strings of the form "[SRn]" (where any decimal number, possibly multiple-digit) are counted as high-level requirements.  The rationale for this default is simply that it's the identification I happen to be using right now in my work for high-level requirements.
The quotation marks shown are necessary if the contains a space or punctuation.
"--high-section-pattern=P" Defines a pattern (regular expression) used with the --trace-XXXX switches to identify sections  in the SRD (HRD) containing unique high-level software (hardware) requirements identified by section number.

The default is "--high-section-pattern=[[:space:]]shall[[:space:]]", meaning that if the word "shall" is found, and it is both preceded and followed by a space, then it is considered to be a requirement.
The quotation marks shown are necessary if the contains a space or punctuation.
"--high-section-range=P" Defines a pattern (regular expression) used with the --trace-XXXX switches to constrain the range of section numbers in which high-level software (hardware)requirements are sought. 

The default is to match every section of the SRD (or HRD) document, which is not too realistic.
The quotation marks shown are necessary if the contains a space or punctuation.
"--low-label-pattern=P" Defines a pattern (regular expression) used with the --trace-XXXX switches to identify labels for low-level software (hardware) requirements in the SDD (HDRD).

The default is "--low-label-pattern=\[SL[0-9]+\]", meaning that strings of the form "[SLn]" (where any decimal number, possibly multiple-digit) are counted as low-level requirements.  The rationale for this default is simply that it's the identification I happen to be using right now in my work for low-level requirements.
The quotation marks shown are necessary if the contains a space or punctuation.
"--low-section-pattern=P" Defines a pattern (regular expression) used with the --trace-XXXX switches to identify sections  in the SDD (HDRD) containing unique low-level software (hardware) requirements identified by section number.

The default is "--low-section-pattern=[[:space:]]shall[[:space:]]", meaning that if the word "shall" is found, and it is both preceded and followed by a space, then it is considered to be a requirement.
The quotation marks shown are necessary if the contains a space or punctuation.
"--low-section-range=P" Defines a pattern (regular expression) used with the --trace-XXXX switches to constrain the range of section numbers in which low-level software (hardware) requirements are sought. 

The default is to match every section of the SDD (or HDRD) document, which is not too realistic.
The quotation marks shown are necessary if the contains a space or punctuation.
--no-sed
Do NOT run 'sed' to translate the entity names in the input file.  This is for debugging only, and if you use it will undoubtedly cause the program to abort with an error message when it tries to parse the input file.

--regex-basic
Use POSIX Basic Regular Expression  syntax rather than POSIX Extended Regular Expression syntax, which is the default.

--regex-case-insensitive
Make regular-expression matching insensitive to upper/lower case distinction.

--sortable=N
With this switch, all numerical fields in a section number are left-padded with zeroes so that the fields are the same width NN must be 2 or 3.  For example, instead of document section 3.10.4.5, the output trace matrices would refer to section 03.10.04.05 (if the field-width is 2).  The motivation for such a step is to allow the trace tables to be more reasonably sorted when imported into spreadsheet programs.  For example, section "10.1.3" would precede section "6.5" in ASCII sort order, but section "06.05" would (more reasonably) precede section "10.01.03".  However, this is not without cost, as it affects all of the --XXXX-section-range command-line switches, and is unlikely to be understood easily be DERs or customers.  If you use this switch, you'll likely want to perform some post-processing to remove the padding afterward.

"--system-section-range=P"
Defines a pattern (regular expression) used with the --trace-system switches to constrain the range of section numbers in which system-requirements cross-references are sought.  In other words, only system-requirement cross-references  in sections of the SRD whose numbers match the pattern will appear in the output table.

There is no default, meaning that every SRD/HRD section is eligible, which is not a realistic assumption.

--trace
Activate all of the --trace-XXXX options listed below.

--trace-design
Output traceability data between SRD and SDD (or HRD and HDRD) into the file Do178Builder-trace-design.csv.

When using this switch, you may also want to use the --high-label-pattern, --high-section-pattern, --high-section-range, --low-label-pattern, --low-section-pattern, and --low-section-range switches (see above).

--trace-design-full
Same as --trace-design, but adds SRD/SDD (HRD/HDRD) section numbers, and creates the output file Do178Builder-trace-design-full.csv.

When using this switch, you may also want to use the --high-label-pattern, --high-section-pattern, --high-section-range, --low-label-pattern, --low-section-pattern, and --low-section-range switches (see above).

--trace-implement Output traceability data between SDD (or HDRD) and source code (or CAD), into Do178Builder-trace-implement.csv. Not yet implemented
--trace-system
Output traceability data between system requirements and SRD, into the file Do178Builder-trace-system.csv.

When using this switch, you may also want to use the --high-label-pattern, --high-section-pattern, --high-section-range, --system-section-range, and --delimiter-system switches (see above).

Using this switch requires special preparation of the Do178Builder project database, because system requirements are generally maintained in external documents (such as customer-supplied specs) rather than within the Do178Builder project database.  Cross-references to the system requirements have to be manually added to the project database, using appropriate tags.  This is process is described below.

--trace-verify
Output traceability data between SRD/SDD (or HRD/HDRD) and SVCP (or HTPR), in Do178Builder-trace-verify.csv.

When using this switch, you may also want to use the --high-label-pattern, --high-section-pattern, --high-section-range, --low-label-pattern, --low-section-pattern, --low-section-range, and --verify-section-range switches.

"--verify-section-range=P"
Defines a pattern (regular expression) used with the --trace-verify switches to constrain the range of section numbers in which test cases are sought.  In other words, only test cases in sections of the SVCP whose numbers match the pattern will appear in the output table.
The quotation marks shown are necessary if the contains a space or punctuation.  This switch has no default setting, so if you use --trace-verify (or --trace) without it, the program will abort.


Adding System-Requirement Cross-References

Creating a trace matrix interrelating the system requirements with the high-level software or hardware requirements is dependent on special preparation of the Do178Builder project database, because system requirements are generally maintained in external documents (such as customer-supplied specs) rather than within the Do178Builder project database.  Cross-references to the system requirements have to be manually added to the project database, using appropriate tags.  This sounds as if it may be a lot of work, but is not really—particularly when you consider that you can't really create the software requirements or hardware requirements anyway without essentially stepping through the system requirements one by one.  At any rate, adding the cross-reference tags is certainly less effort than creating a trace matrix manually, particularly if you reflect that you'll probably have to iterate the requirements several times, and therefore may have to generate the trace matrix more than once.

In its simplest form—when the system requirements to software/hardware requirements mapping is one-to-one or one-to-many—the method of adding the traceability references is to add tags to appropriate sections in your project database like so:

<trace>SystemRequirementLabel</trace>

For example, if you added a cross reference like "<trace>EASDD.12345</trace>", and below that (at sub-sections) in the SRD were defined the high-level software requirements "[SR0045]", "[SR0046]", and "[SR0047]", then the following references would appear in your system-requirements trace matrix:

"EASDD.12345","[SR0045]"
"EASDD.12345","[SR0046]"
"EASDD.12345","[SR0047]"

Where in your project database to add these tags is somewhat of an art.  The default project template already adds tags that look like "<trace>TBD</trace>" at appropriate places, and you'd be advised to simply fill in the TBDs.  The basic rules are these:
In a more complex case, you might have multiple system requirements that are relevant to the same software/hardware requirement.  This many-to-one mapping can be dealt with effectively either by adding multiple <trace> tags within the same section (not preferred, because it conflicts with Do178Builders's native-traceability functionality), or by adding a list of system requirements separated by delimiters within a single <trace> tag.  Any delimiter can be chosen (with the --delimiter-system command-line switch), but a comma is the default.  For example, if you had the cross references

<trace>EASDD.12345, EASDD.12346, EASDD.12347</trace>

and in a sub-section of the SRD the high-level requirement "[SR0050]" was defined, then the following would appear in your system trace matrix:

"EASDD.12345","[SR0050]"
"EASDD.12346","[SR0050]"
"EASDD.12347","[SR0050]"

(Extra spaces before or after the delimiter are ignored, but it may be useful to add them in case you ever want to switch to using Do178Builder's native traceability functionality, since Do178Builder simply displays verbatim whatever appears within the <trace> tags, and therefore it's your own responsibility to make it look nice.)

Since you must manually add the trace tags, there's no technical reason why the requirements being referenced have to all reside in the same external document.  For example, suppose the customer has supplied you with both a specification and an interface-control document (ICD), and you are treating both as containing requirements.  Then you might want to add the document name to the cross-references as well:

<trace>EASDD.12345, EASDD.12346, ICD 1.2.3.4</trace>

The technique becomes a little trickier when you have a many-to-many mapping of system requirements to software/hardware requirements.  For  example, suppose that you have 5 system requirements that relate to 7 software requirements, but you can't break it down any further than that.  Then 5×7=35 lines will appear in your system trace matrix to describe this relationship.  This kind of relationship is obviously less convincing to a DER or a customer than a one-to-one relationship is, and gives everyone far less confidence that you have properly analyzed the problem.

On the other hand, sometimes you would like to place several software/hardware requirements governed by several system requirements within the same SRD/HRD section not because you can't analyze the relationship better, because there is better clarity of exposition.  For example, you might wish to present those requirements in tabular form, but there is really a straightforward relationship between the individual system requirements and software requirements.  In this case, you can still proceed fairly easily by adding a construct like this:

<trace>{SoftwareRequirement}SystemRequirement</trace>

What a construct like this says is that the system-requirement cross-reference doesn't apply to all the software requirements below it, but merely to the particular software requirement referenced within the braces.   As an example, suppose that the three system requirements EASDD.12345, EASDD.12346, and EASDD.12347 each relate to one of the software requirements [SR0045], [SR0046], and [SR0047], respectively, but that for some reason you want to cover all of them within a single SRD section rather than in 3 separate SRD sections.  Then your cross-reference would look like this

<trace>{[SR0045]}EASDD.12345, {[SR0046]}EASDD.12346, {[SR0047]}EASDD.12347</trace>

and your system trace matrix would have the following 3 entries, rather than 3×3=9 entries:

"EASDD.12345","[SR0045]"
"EASDD.12346","[SR0046]"
"EASDD.12347","[SR0047]"

Note that delimiters from the --delimiter-system switch are not treated as delimiters within the braced expressions.

Incidentally, you can add multiple brace-qualifiers to a  given system requirement, so a cross-reference like this

<trace>{[SR0045]}{[SR0047]}EASDD.12345, {[SR0046]}EASDD.12346, {[SR0047]}EASDD.12347</trace>

would result in this trace matrix:

"EASDD.12345","[SR0045]"
"EASDD.12346","[SR0046]"
"EASDD.12345","[SR0047]"
"EASDD.12347","[SR0047]"

Another trick which may be useful is to use the brace-qualifier "{*}", as in

<trace>{*}EASDD.12345, {[SR0001]}EASDD.12346</trace>

This means that instead of adding a separate line to the trace matrix relating each high-level requirement to the system requirement, those high-level requirements are placed instead within a single line (a single cell) of the spreadsheet (though with newlines between each of the high-level requirements within the cell).  For example, suppose that the relevant high-level requirements were [SR0001], [SR0002], and [SR0003].  Then the trace matrix would look like

"EASDD.12345","[SR0001]\n[SR0002]\n[SR0003]"
"EASDD.12346","[SR0001]"

Why would this be useful?  After all, with all of those newlines, the trace matrix takes just as much physical space if one were to print it out.  Well, my notion is that you'd then manually edit the spreadsheet so that it looked something like this:

"EASDD.12345","[SR0001] through [SR0003]"
"EASDD.12346","[SR0001]"

I doubt you'd want to waste your time doing this for such a small example, but if (say) we were talking about an array of 50 high-level requirements related to a single system requirement, I'd think the simplification in presentation and in analysis would be obviously worth the small amount of effort needed.  And of course, it's really only useful if the high-level requirements in question fit neatly into an easily expressed range.

Finally, a trick that I think is useful sometimes is to use "(deleted)" or "(derived)" as the system requirement in the cross-reference:

<trace>(deleted)</trace>
<trace>SystemRequirement (deleted)</trace>      (e.g., <trace>EASDD.12345 (deleted)</trace>)
<trace>(derived)</trace>

I'm sure it's clear why "(deleted)" might be useful.  As for "(derived)", if there is no system-requirement cross-reference at all then Do178Builder-utility will automatically fill in "(derived)" when it creates the trace matrix.  But I think it's better to fill it in explicitly to show that you've thought about it and have deliberately chosen to mark the requirement as derived rather than that you've merely overlooked the requirement.


This page was last modified by Ron Burkey on 2008-04-07. Contact the Birds Project.