bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Error formatting macro: alias: java.lang.NullPointerException
SWE-112 - Interface Design Description
Unknown macro: {div3}

1. Requirements

5.2.4.1 The Interface Design Description shall include:
           a.    Priority assigned to the interface by the interfacing entity(ies).
           b.    Type of interface (e.g., real-time data transfer, storage-and-retrieval of data) to be implemented.
           c.    Specification of individual data elements (e.g., format and data content, including bit-level descriptions of data interface) that the interfacing entity(ies) will provide, store, send, access, and receive.
           d.    Specification of individual data element assemblies (e.g., records, arrays, files, reports) that the interfacing entity(ies) will provide, store, send, access, and receive.
           e.    Specification of communication methods that the interfacing entity(ies) will use for the interface.
           f.     Specification of protocols the interfacing entity(ies) will use for the interface.
           g.    Other specifications, such as physical compatibility of the interfacing entity(ies).
           h.    Traceability from each interfacing entity to the system or CSCI requirements addressed by the entity's interface design, and traceability from each system or CSCI requirement to the interfacing entities that address it.
           i.      Interface compatibility.
           j.      Safety-related interface specifications and design features.

1.1 Notes">1.1 Notes

NPR 7150.2 does not include any notes for this requirement.

1.2 Applicability Across Classes

This requirement applies to all classes and safety criticalities except:

  • Class D and not Safety Critical
  • Class E and not Safety Critical
  • Class H

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

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

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

Class

  A_SC 

A_NSC

  B_SC 

B_NSC

  C_SC 

C_NSC

  D_SC 

D_NSC

  E_SC 

E_NSC

     F      

     G      

     H      

Applicable?

   

   

   

   

    X

    P(C)

    X

   

    X

   

   

   

   

Key:    A_SC = Class A Software, Safety Critical | A_NSC = Class A Software, Not Safety Critical | ... | - Applicable | - Not Applicable
X - Applicable with details, read above for more | P(C) - P(Center), follow center requirements or procedures

Unknown macro: {div3}

2. Rationale

The Interface Design Description (IDD) describes the interface characteristics of one or more systems, subsystems, Hardware Configuration Items (HWCIs), Computer Software Configuration Items (CSCIs), manual operations, or other system components.  Typical NASA development projects are complex, multi-disciplined activities that consist of systems and systems of systems. These projects usually require integrated product teams working together to achieve the goals and objectives in a timely and cost efficient manner.  The execution of the software development lifecycle and its activities by the team requires multiple tasks and work products to be developed and accomplished in parallel.  To assure that the assembled systems and integrated systems function as intended, the interfaces for the software work products (components) and systems must be accurately defined, designed, controlled, and communicated.  A high quality interface design description document will fulfill these needs for the software development team. 

Unknown macro: {div3}

3. Guidance

The software interface design description document may be standalone or part of the software design description document (see SWE-111) or part of an electronic data system.  Center policies and procedures should be followed when determining which documentation approach should be used for a particular project.  It is important the interface design information be identified and tracked as the software systems is being developed, tested and operated.  Software interface design and requirements tend to drive software designs and can lead to a potential source of anomalies during the development and operational lifecycle.  The key to implementing this requirement is to have a good description of all software, hardware, operational and system interfaces and interactions during the design and operational phases of a development cycle.  The content of the interface design description is defined by PDR.  The preliminary interface design descriptions should be approximately 30% completed at PDR.  All interface components are to be defined by PDR.  The interface design descriptions are completed by CDR and updated as needed after CDR.  The final as build interface design description is documented as a part of the as build design documentation for operational use, software modification and potential software reuse applications.

The software development team should prepare an interface design document that describes the interface entity characteristics for all defined systems, subsystems, domains, hardware items, software items, manual operations and other system components.

The descriptions should contain the interface characteristics for systems or configuration items that participate in the interface (including human-system and human-human interfaces), standards and protocols, responsible parties, interface operational schedules, and any error handling routines. The software team should also define those interface characteristics that are existing or permanent, as well as those that are being developed or modified. The applicability of this requirement is highly dependent on the classification level for the software work product(s). The Appendix D, Requirements Mapping Matrix, for NPR 7150.2 shows the requirements for each classification level (see [SWE-020]).

An excellent way to begin the descriptions of the interfaces is with a context or state diagram. A suitably detailed diagram (showing the relationship of the interface with the overall activity) with legends and callouts will easily show the dependencies that must be controlled and satisfied in the software detailed design. Either a single diagram, or an interrelated set of diagrams, depending on the complexity of the software work product(s), may be the most appropriate choice.

As shown in the SWE-112 requirements text above, the software interface design description document is required to contain specific information. Below are suggestions for the type of information to consider for the named required content.

Document Content

The following paragraphs are based on the Department of Defense (DoD) Data Item Description "Interface Design Description (IDD)" document (DI-IPSC-81436A)7, along with supporting material from the GRC (GRC-SW-TPLT-IDD Interface Design Description (IDD) Template).

  • Assigned priority

This is the priority assigned to the interface by the interfacing entity(ies).The level of the priority allows the software to service higher priority queues ahead of lower priority queues. Complex priority values may allow timeouts and software interrupts to avoid the starving of lower priority interfaces.

  • Type of interface

The interface design description document should include characteristics about interface types (such as real-time data transfer, storage-and-retrieval of data, remote programming interface, etc.,) that will be implemented.

Factors like functionality, performance speed, the time needed to use the program, user satisfaction, and the rate of user errors are some criteria for the software development team to consider when designing an interface. The software interface testing should be specified in the software testing plan (see [SWE-104] and [SWE-114]).

The two most common ways of expressing interface information are alphabetically by parameter and for data-oriented interfaces, by layers with reference to a level-of-abstraction model such as the Open Systems Interconnection (OSI)-7 Layer model.8  In the latter case individual information items (e.g., requirements, or characteristics) are framed consistent with the layer definitions, and then specified by layer, 'physical' up to  'application' in that order of the OSI-7 Layer model.  Within a layer, control flow sequence is used where applicable to express information, otherwise alphabetically by parameter.

  • Specifications of individual data elements

The interface design description document should include characteristics about the individual data elements that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as

    • Names/identifiers
      1. Project-unique identifier
      2. Nontechnical (natural language) name
      3. Standard data element name
      4. Technical name (e.g., variable or field name in code or database)
      5. Abbreviation or synonymous names
    • Data type (alphanumeric, integer, etc.), indicating data types that are not defined until implementation such as C++ type overloading (templates) and dynamic typecasting
    • Size and format (i.e., length and punctuation of a character string or bit-level descriptions)
    • Units of measurement (i.e., meters, dollars, or nanoseconds)
    • Range or enumeration of possible values (i.e., 0 to 99)
    • Accuracy (how correct) and precision (number of significant digits)
    • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the data element may be updated and whether business rules apply
    • Security and privacy constraints
    • Sources (setting or sending entities) and recipients (using or receiving entities)
    • Safety criticality
  • Specifications of data element assemblies

The interface design description document should include characteristics about data element assemblies such as records, messages, files, arrays displays, reports, etc., that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as

    • Names/identifiers
      1. Project-unique identifier
      2. Nontechnical (natural language) name
      3. Technical name (e.g., record or data structure name in code or database)
      4. Abbreviations or synonymous names
    • Data elements in the assembly and their structure (number, order, grouping, and bit-level descriptions)
    • Medium (i.e., disk) and structure of data elements or assemblies on the medium
    • Visual and auditory characteristics of displays and other outputs (i.e., colors, layouts, fonts, icons and other display elements, beeps, and lights)
    • Relationships among assemblies, such as sorting or access characteristics
    • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the assembly may be updated and whether business rules apply
    • Security and privacy constraints
    • Sources (setting or sending entities) and recipients (using or receiving entities)
    • Safety criticality
  • Specifications of communication methods

The interface design description document should include characteristics about communication methods that the interfacing entity(ies) will use for the interface, such as* o   Project-unique identifier(s)

    • Communication links, bands, frequencies, media, and their characteristics
    • Message formatting
    • Flow control (i.e., sequence numbering and buffer allocation)
    • Data transfer rate, whether periodic or aperiodic, and interval between transfers
    • Routing, addressing, and naming conventions
    • Transmission services, including priority and grade
    • Security and privacy considerations, such as encryption, user authentication, compartmentalization, and auditing
    • Safety criticality
  • Specifications for communications protocol

The interface design description document should include characteristics about digital message formats and the rules for exchanging those messages. A protocol defines the syntax, semantics, and synchronization of communication, and the specified behavior is typically independent of how it is to be implemented. A protocol can therefore be implemented as hardware or software or both. Characteristics of protocols the interfacing entity(ies) will use for the interface include:* o   Project-unique identifier(s)

    • Priority or layer of the protocol
    • Packeting, including fragmentation and reassembly, routing, and addressing
    • Legality checks, error control, and recovery procedures
    • Synchronization, including connection establishment, maintenance, and termination
    • Status, identification, and any other reporting features
  • Other characteristics -

such as physical compatibility of the interfacing entity(ies) (dimensions, tolerances, loads, voltages, plug compatibility, etc.)

  • Traceability

Show the path from each interfacing entity to the system or CSCI requirement addresses by the design. To complete the bidirectional tracing of the requirements, show from each system or CSCI requirement to the interfacing entity that addresses it (see SWE-059 on bidirectional traceability)

  • Interface Compatibility

The interface design description document should contain information about the intended compatibility between or among the interfaces being developed. Specifically, will there be uniform or optional approaches to developing weak vs. strong compatibility? Will the compatibility of the software components interaction with their environment be characterized as optimistic or pessimistic in nature?

  • Safety-related interface specifications and design features.

Safety-critical OTS and reused software must undergo safety analysis that considers* o   Its ability to meet required safety functions

    • Extra functionality that may be present, even if not planned for use
    • The impact on safety
    • Interfaces to developed code

Additional analysis, testing, or a combination thereof should be performed to verify safety-critical OTS or reused software to the same level required of in-house developed software to the extent possible via black box testing.

The Contract Data Requirements List should specify whether deliverable data are to be delivered on paper or electronic media; may be delivered in developer format rather than in the format specified herein; and may reside in a computer-aided software engineering or other automated tool rather than in the form of a traditional document.

Best Practices

The software development team should solicit relevant stakeholder involvement to evaluate applicable system interface(s).

Whenever possible, the software development team should consider using an industry recognized standard for system interfaces.

Unknown macro: {div3}

4. Small Projects

The proper execution of interfaces among entities in software design activities is no less important for small projects than for large projects. Improper interface development, evaluation, and testing will cause any software work product to fail to function, regardless of the size of the project.

Smaller projects may benefit by using standard interface designs or IDD templates9 previously developed and cataloged in software reuse repositories, or by using personnel with previous experience on identical or similar interfaces. Where applicable the information required for this SWE-112 may be duplicated from IDD's written for previously developed software interfaces.  Extreme care should be used whenever deciding to reuse software. See [SWE-027] for information that may be applicable. See the Center's repository of best practices for additional guidance in this area (see [SWE-099]).

Unknown macro: {div3}

5. Resources

  1. NASA Systems Engineering Handbook, NASA/SP-2007-6105 Rev1, 2007
  2. NASA Systems Engineering Processes and Requirements with Change 1, NPR 7123.1A, 2009
  3. NASA Software Safety Standard, NASA STD 8719.13  (Rev B w/ Ch1 of 7/8/2004), 2004
  4. NASA Software Assurance Standard, NASA STD 8739.8, 2005
  5. NASA Space Flight Program and Project Management Requirements, NPR 7120.5D (NM-7120.81), 2009.
  6. Systems and software engineering ---Content of systems and software lifecycle process information products (Documentation), ISO/IEC 15289:2006(E)
  7. IDD-DID SW Interface Design Description, DI-IPSC-81436A, Department of Defense, 1999
  8. Expressing and Organizing Interface Information, Project Performance International, accessed WWW Jun 27, 2011
  9. Interface Design Description (IDD) Template, NASA GRC-SW-TPLT-IDD, 2009

5.1 Tools

Tools relative to this SWE may be found in the table below. You may wish to reference the Tools Table in this handbook for an evolving list of these and other tools in use at NASA. Note that this table should not be considered all-inclusive, nor is it an endorsement of any particular tool. Check with your Center to see what tools are available to facilitate compliance with this requirement.

Tool nameTypeOwner/SourceLinkDescriptionUser

IBM Rhapsody

COTS

IBM Rational

http://www-01.ibm.com/software/awdtools/rhapsody/ ...

"IBM® Rational® Rhapsody® family provides collaborative design and development for systems engineers and software developers creating real-time or embedded systems and software. Rational Rhapsody helps diverse teams collaborate to understand and elaborate requirements, abstract complexity visually using industry standard languages (UML, SysML, AUTOSAR, DoDAF, MODAF, UPDM), validate functionality early in development, and automate delivery of innovative, high quality products." (NOTE: Several versions are listed on the website for architecture, system engineering requirements analysis, design and model management, simulations to validate requirements and analyze architecture, and code generation. Unsure which versions are used within NASA. Listed requirements are those related to these topics.)

IV&V GSFC ?

Unknown macro: {div3}

6. Lessons Learned

Interface Control and Verification (Lessons Learned Entry 0569): Problems occurred during Mars Pathfinder spacecraft integration and test due to out of date or incomplete interface documentation. Investigation showed that the main wiring harness was built in accordance with(documentation) which had not been updated after design changes were made. In part this was due to independently prepared mechanical interface control drawings by the government and the contractor.  The MICD's should have had periodic verification for accuracy and compatibility. See the following for more information: http://www.nasa.gov/offices/oce/llis/0569.html

  • No labels