bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Alias
aliasSWE-111

Tabsetup
1. The Requirement
1. The Requirement
12. Rationale
23. Guidance
34. Small Projects
45. Resources
56. Lessons Learned
Div
idtabs-1

1. Requirements

5.2.3.1 The Software Design Description shall include: [SWE-111]

      a. Computer Software Configuration Item (CSCI)-wide design decisions/trade decisions.
      b. CSCI architectural design.
      c. CSCI decomposition and interrelationship between components:

        (1) CSCI components:

              (a) Description of how the software item satisfies the software requirements, including algorithms, data structures, and functional decomposition.
              (b) Software item I/O description.
              (c) Static/architectural relationship of the software units.
              (d) Concept of execution, including data flow, control flow, and timing.
              (e) Requirements, design and code traceability.
              (f) CSCI's planned utilization of computer hardware resources.

         (2) Rationale for software item design decisions/trade decisions including assumptions, limitations, safety and reliability related items/concerns or constraints in design documentation.

         (3) Interface design.

1.1 Notes

The documentation of the architectural design of a software system identifies and describes the architectural elements of the software, the external interfaces, and the interfaces between elements. The description includes element responsibilities (constraints on inputs and guarantees on outputs), and constraints on how the elements interact (such as message and data sharing protocols). The architectural design documentation includes multiple views of the architecture and identifies and supports the evaluation of the key quality attributes of the planned software product. The key quality attributes of the software will depend on the mission in which the software is to be used and the manner in which it is to be developed and deployed. They will usually include: performance, availability, maintainability, modifiability, security, testability and usability (operability.)

1.2 Applicability Across Classes

Classes C through E and Safety Critical are labeled with "P (Center) + SO." "P (Center)" means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement, while "SO" means that the requirement applies only for safety-critical portions of the software.

Class C and Not Safety Critical and Class D and Not Safety Critical are labeled with "P (Center.)" This means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement.

Classes F and G are labeled with "X (not OTS)." This means that this requirement does not apply to off-the-shelf software for these classes.


applicable
f*
g*
h0
ansc1
asc1
bnsc1
csc*
bsc1
esc*
cnscp
dnscp
dsc*
ensc0
Div
idtabs-2

2. Rationale

NPR 7150.2, NASA Software Engineering Requirements, section 5.2.3, states, "The Software Design Description describes the design of a CSCI (computer software configuration item). It describes the CSCI-wide design decisions, the CSCI architectural design, and the detailed design needed to implement the software." The software design process transforms the software requirements into a structured, organized set of information appropriate for implementing in code. This design is captured in the software design description (SDD), making the SDD a critical document in the software development process.

Div
idtabs-3

3. Guidance

When creating the software design description (SDD), the following minimum content is included. If the content is included in another document or tool, such as separate trade study documents, interface design documents, modeling or simulation tools, or data dictionaries, those documents or tools may be referenced in the SDD.

CSCI-wide design decisions/trade decisions

It is important to document decisions made during the design process, as well as the reasons those decisions were made. (See Rationale for software item design (Item 2 under CSCI decomposition and interrelationship between components) guidance below.) This information is useful for the implementation phase, as well as future software maintenance activities. Consider the following when capturing "decisions about the CSCI's behavioral design (how it will behave from a user's point of view, in meeting its requirements, and ignoring internal implementation) and other decisions affecting the selection and design of the software units that make up the CSCI":

sweref
096
096

  • Make Decisions based on trade studies, including the options considered or a reference to the document(s) that capture the trade study information.
  • Capture design decision dependencies on system states or modes.
    sweref
    096
    096
  • Capture design decisions "regarding inputs the CSCI will accept and outputs it will produce, including interfaces with other systems, hardware configuration items (HWCIs), CSCIs, and users."
    sweref
    096
    096
  • Capture design decisions "on CSCI behavior in response to each input or condition, including actions the CSCI will perform, response times, and other performance characteristics, description of physical systems modeled, selected equations, algorithms, or rules, and handling of invalid inputs or conditions."
    sweref
    096
    096
  • Capture design decisions "on how databases and data files will appear to the user."
    sweref
    096
    096
  • Capture the "selected approach to meeting safety, security, and privacy requirements."
    sweref
    096
    096
  • Capture design decisions "made in response to requirements, such as selected approach to providing required flexibility, availability, and maintainability."
    sweref
    096
    096

CSCI architectural design

"The architectural design documentation includes multiple views of the architecture and identifies and supports the evaluation of key quality attributes of the planned software product. The key quality attributes of the software will depend on the mission in which the software is to be used and the manner in which it is to be developed and deployed. They will usually include performance, availability, maintainability, modifiability, security, testability and usability (operability)."

sweref
090
090

The architectural design may be captured in a variety of ways but is typically captured in one or more diagrams. Consider including diagram conventions, as appropriate, so readers can better understand the architectural design captured in those diagrams. When capturing the architectural design, consider including:

  • A subsystem/component context diagram.
  • A system design diagram (such as a top-level data flow diagram or UML (Unified Modeling Language) diagram).
  • A "list of [software] subsystems, tasks, or major components – e.g., user interface, database, task management."
    sweref
    073
    073
  • A map or list of software units that make up each CSCI.

CSCI decomposition and interrelationship between components

  1. CSCI components
    1. Description of how the software item satisfies the software requirements, including algorithms, data structures, and functional decomposition.
      Consider including the following when describing how each software item satisfies the associated set of software requirements:
      • Description of functionality and operational modes, data storage concepts, and structures.
        sweref
        072
        072
      • Derived requirements.
        sweref
        073
        073
      • Functional allocations among the software subsystems.
      • Databases, data files, and shared data with safety-critical data marked.
        sweref
        276
        276
      • "Identify, state the purpose, and describe in detail the algorithms to be incorporated into the execution of the CSU. The algorithms shall be described in terms of the manipulation of input and local data elements and the generation of output data elements."
        sweref
        176
        176
    2. Software item input/output (I/O) description.
      When capturing the I/O description, consider including the following information, as appropriate:
      • Identification and formats of input and output data.
        sweref
        072
        072
      • Purpose, source and destination, data type, data representation, size, units of measure, limit/range, accuracy, precision/resolution.
        sweref
        387
        387
      • Identification of safety-critical input and output data used in interfaces.
        sweref
        276
        276
      • I/O data rates.
    3. Static/architectural relationship of the software units.
      Like the CSCI architectural design, the static/architectural relationship of software units is typically captured in one or more diagrams. Consider the following when capturing this information:
      • A subsystem/component context diagram.
        sweref
        072
        072
      • A system design diagram (such as a top-level data flow diagram or UML diagram).
        sweref
        072
        072
      • Design diagrams for the task
        sweref
        072
        072
         and descriptions of major modules.
        sweref
        073
        073
      • Identification of non-safety-critical units that can interact with safety-critical ones.
        sweref
        276
        276
      • Documentation of the positions and functions of safety-critical components in the design hierarchy.
        sweref
        276
        276
      • Relationship of this software to other software components in the system.
        sweref
        387
        387
    4. Concept of execution, including data flow, control flow, and timing.
      The concept of execution may be captured in "diagrams and descriptions showing the dynamic relationship of the software units, that is, how they will interact during CSCI operation."
      sweref
      096
      096
       Consider including the following information when capturing the concept of execution:
      • Interrupts and/or exception handling, including event, failure detection and correction (FDC), and error messages.
        sweref
        072
        072
      • End-to-end data flow description and/or diagrams.
        sweref
        073
        073
      • "Execution control, interrupt characteristics, initialization, synchronization, and control of the components...include finite state machines."
        sweref
        276
        276
      • Timing and sequencing diagrams.
      • States and modes of software operation, including the software units that execute in each state and mode, as well as the execution control and data flow between components in the different states and modes.
        sweref
        387
        387
      • Control and signal flow, interrupt priorities and interrupt handling, error detection and handling.
        sweref
        387
        387
      • "Dynamically controlled sequencing, state transition diagrams..., priorities among units..., concurrent execution, dynamic allocation and de-allocation, dynamic creation and deletion of objects, processes, tasks, and other aspects of dynamic behavior."
        sweref
        096
        096
      • Thread interactions.
    5. Requirements, design, and code traceability.
      Traceability is another type of information that is important for development and maintenance of the software because it allows development personnel to identify affected software products when a change or update is made. Consider the following when capturing the traceability information for the design. (See also the traceability guidance in this Handbook for SWE-059 and SWE-064.)
      • "Requirements trace or flow-down of system-level requirements to the subsystem, with any safety-critical requirements highlighted."
        sweref
        073
        073
      • Trace of each safety-critical component back to original safety requirements and how the requirement is implemented.
        sweref
        276
        276
      • Traceability between the architectural design and software components.
    6. CSCI's planned utilization of computer hardware resources.
      Consider the following when capturing the planned utilization of computer hardware resources for each CSCI:
      • "Utilization constraints (e.g., CPU, memory); how the software will adapt to changing margin constraints; performance estimates."
        sweref
        072
        072
      • "Estimates of computer hardware resources usage ... to ensure that the design is within the total hardware resource capacity."
        sweref
        001
        001
      • Storage and memory resource allocations across the software architecture.
      • Memory, bus, throughput estimates, and margins.
        sweref
        387
        387
      • Planned CSCI usage of processor capacity, I/O device capacity, auxiliary storage capacity, communication or network capacity.
        sweref
        096
        096
  2. Rationale for software item design decisions/trade decisions, including assumptions, limitations, safety and reliability-related items/concerns or constraints in design documentation.
    It is important to document the reasons for design decisions for the implementation phase, as well as future software maintenance activities. Design decisions need to be traceable to relevant trade studies and the associated reasoning behind those decisions. Consider the following when capturing the rationale for design decisions:
    • Alternatives that were part of the design process but that were excluded, along with the reasons for those exclusions, e.g., did not meet requirements, low probability of success, exceeded cost and/or schedule constraints.
      sweref
      001
      001
    • Assumptions made during discussions of design options.
    • Limitations of various design options that affected the design choice, e.g., technical, cost, schedule limitations.
    • Safety and reliability considerations in the design elements and interfaces for each software subsystem, task, or component.
      sweref
      073
      073
    • Design constraints, e.g., feasibility, coupling, extensibility, maintainability.
    • Design drivers, e.g., performance, reliability, usability, hardware considerations, established for the project that affected the software design.
    • "Design alternatives, including reuse of heritage software and/or COTS tradeoffs."
      sweref
      073
      073
    • Performance parameters that were part of the rationale, e.g., reliability, safety, affordability, schedule, risk.
      sweref
      001
      001
    • "Selection criteria (e.g., adherence to design standards, verifiability, ease of construction, reuse, use of COTS, safety)."
      sweref
      001
      001
    • "Assumptions about the environment including operating system, user interface, component, data management, data interchange, graphics, and network services, especially assumptions on which safety functions and computer security needs may be based."
      sweref
      387
      387
    • "Assumptions and conditions on which the utilization data are based (e.g., typical usage, worst-case usage, and assumption of certain events)."
      sweref
      096
      096
    • "Architectural element responsibilities (constraints on inputs and guarantees on outputs) and constraints on how the elements interact (such as message and data sharing protocols)."
      sweref
      090
      090
  3. Interface design
    Consider the following when capturing the interface characteristics of the software units. (See also the guidance in this Handbook for SWE-112, which describes the content for the interface design description document.) If all or part of this information is captured in one or more interface documents, those documents may be referenced here.
    • Internal interfaces between all components.
    • Operator interfaces.
    • Device interfaces.
    • Allocation of the software's external interface requirements to components.
    • "Identify the safety-critical ... interfaces throughout the design. Identify non-critical units that can interact with safety-critical ones."
      sweref
      276
      276
    • "Design of each interface in terms of:
      • Information description;
      • Initiation criteria;
      • Expected response;
      • Protocol and conventions;
      • Error identification, handling and recovery;
      • Queuing;
      • Implementation constraints;
      • Requirements relative to safety and computer security."
        sweref
        387
        387
    • Interface type and purpose.
    • Interface description, including data transmitted, messages transmitted, priority of interfaces, and messages transmitted across them.
      sweref
      387
      387

The Software Architecture Review Board

sweref
323
323
, a software engineering sub-community of practice, is a good resource of software design information, including sample documents, reference documents, and expert contacts.


Panel

Consult Center Process Asset Libraries (PALs) for Center-specific guidance, templates, and examples related to documenting the software design.


Additional guidance related to software design may be found in Topic 7.07 - Software Architecture Description and the following related requirements in this handbook:


SWE-056

Document Design

SWE-057

Software Architecture

SWE-058

Detailed Design

Div
idtabs-4

4. Small Projects

Projects with limited personnel or budgets need to consider the guidance and use of software design document templates from the local Center PAL, because a local tailoring via "P (Center)" may be applicable. Center Engineering Technical Authorities also have been empowered to provide specific relief when the software classification specifies required design description items, i.e., "X" in Requirements Mapping Matrix in NPR 7150.2.

Div
idtabs-5

5. Resources


refstable

toolstable

Div
idtabs-6

6. Lessons Learned

No Lessons Learned have currently been identified for this requirement. However, there are relevant lessons learned in the related requirements named in the guidance section. Lessons Learned related to software design may be found in the following related requirements in this handbook:


SWE-056

Document Design

SWE-057

Software Architecture

SWE-058

Detailed Design