ASAM FSX

History

Shortly after the first release of ASAM MDX, ASAM member companies realized the need for a standard, which covers the functional documentation of ECU software. They decided to keep the software architecture description and the functional description separate from each other and to develop a new standard for the latter purpose. The new standard  got the name ASAM FSX and is closely aligned with ASAM MDX. The foundations of ASAM FSX are the standard MSRSW and the so-called "FS use case" from Bosch. The first version of ASAM FSX was released early 2007.

The first revision of ASAM FSX got released four years later and focused on the harmonization with AUTOSAR 4.0 templates. Furthermore, variant handling for features had been introduced and some minor improvements were implemented.

 

Motivation

Software development becomes an increasingly distributed process between OEM, system suppliers and engineering service providers. Outsourced and distributed development poses the problem that the work results have to be merged and integrated back into one system. This is a challenge for software and for its technical documentation, alike.

A lot of companies use common word processing applications or their own documentation systems to create functional specifications. These systems are typically based on proprietary formats e.g. Word or PDF. This becomes a problem when different parties work on the same project. OEMs, which develop parts of the ECU software, would have to provide different documentation formats to their suppliers, depending on which formats they use. If OEMs refuse to do that and just supply one format, then suppliers have to process different types of functional documentation formats from their OEMs and merge them with their own documentation to create a complete documentation of the ECU software.

Consequently, integrated functional specifications often appear to be fragmented and inconsistent. Styling, layout and content structure may vary greatly across a document. Different documents aren't linked to each other by cross references and don't have shared tables of contents or indexes. This complicates readability and traceability within the documentation. Functional specifications that look like patched together can give a confusing and unprofessional impression to readers.

The exchanged proprietary documents, furthermore, do not allow for parsing and extraction of data like labels, revision numbers and status of the software. The exchanged data formats are mostly pure presentation formats, which do not support a defined document content structure. Authors are allowed to do everything everywhere. This severely inhibits the possibilities of document parsing and automated data processing.

Different formats, the lack of machine-readability and a lack of support for creating different versions of the documentation causes an increased workload for OEMs and suppliers. ASAM FSX overcomes those problems by defining an XML-based, machine-readable format for the creation, processing and exchange of functional documentation of ECU software. Data elements of the format are semantically well defined, have unique names and types. The documentation format does not include style information, which is a matter left to the generating tool. Technical documentation in the ASAM FSX format is scalable and allows print-on-demand scenarios.

The standard incorporates several further features, which are needed in automotive software documentation. Like with software, ASAM FSX understands conditional compilation, i.e. specific features can be added or removed from the documentation based upon system conditions. The standard is able to produces specific views, e.g. an internal and an external view upon the content. Translators can easily use ASAM FSX to add translations into different languages to an existing functional specification.

 

Application Areas

The primary application area for ASAM FSX is to write, generate and exchange the functional documentation of automotive, embedded software. The standard can be used prior to the software development process, for documenting requirements and the intended, functional behaviour of the software. The standard can further be used for documenting the software after it has been developed.

ASAM FSX is independent from specific software development processes. The standard format can be used for software development projects, that involve classical programming languages, such as C, and model-based development processes, where the controller software is implemented in simulation models.

 

Technical Content

File Format

The internal format of FSX-files is based upon the XML notation. The standard includes a schema definition file (.xsd) and a document type definition file (.dtd) for formal file validation.

The file should be encoded in the UTF-8 or ISO 8859-1 character set. UTF-8 allows the use of non-Latin characters like Chinese or Japanese, which is useful in descriptive texts inside the FSX-file such as in <LONG-NAME> or <DESC>.

Common Elements

Elements in ASAM FSX typically aggregate a group of standard elements. They provide standard information about the element such as the name or a description. Those elements are described in this chapter and are not repeated in subsequent chapters.

Element Description
<SHORT-NAME> Unique, meaningful name of the element.
<LONG-NAME> Brief, headline-style description of the element.
<DESC> Longer and more detailed description of the element.
<CATEGORY> Subdivides the meaning of the element in categories.
<ADMIN-DATA> Administrative data defining the revision history of an element, language and company-specific information.

The <SHORT-NAME> has a crucial function in ASAM FSX. Every identifiable element (i.e. it can be referenced) must have a unique short name. It shall provide an idea about the meaning of the element. The short name is the value of references (unidirectional associations) from other elements to this element. Aggregations of short-named elements will result in a concatenation of short names separated by "/".

Structure

<MSRSW> is the root element of the ASAM FSX XML structure, which aggregates the following top-level elements.

Element  Description
<CATEGORY> Has the fixed value "FSX".
<INTRODUCTION> Introductory description of the system.
<SW-SYSTEMS> Aggregates exactly one <SW-SYSTEM>, which is used to provide the functional description of the software inside of an ECU.
<MATCHING-DCIS> URL to a Document Control Instance file that defines validation rules against which the FSX-file should be checked.
<SDGS>  Is used to extend the standardized XML-format with non-standardized, application specific data.
<LOCS>  Locations of other documents that shall be linked with this document.
<PROJECT-DATA> Is deprecated and shall not be used any longer. It may be used for compatibility reasons to support older versions of ASAM FSX or MSRSW.

Software System

The top-level element <SW-SYSTEMS> contains the complete functional description of the system. The element aggregates one <SW-SYSTEM>, which may contain an <INTRODUCTION> text and an <ANNOTATIONS> text. <SW-SYSTEM> aggregates one <SW-COMPONENT-SPEC>, which aggregates one element of <SW-COMPONENTS>, one optional element of <SW-ROOT-FEATURES> and multiple optional elements of <CHAPTER>.

Element Description
<SW-COMPONENTS> Aggregates multiple <SW-FEATURE>.
<SW-ROOT-FEATURES> Contains a reference to the root feature of a software feature hierarchy.
<CHAPTER> Optional, multiple chapters allow to provide an overview description of the features of the software system.

Software Feature

The element <SW-FEATURE> contains the actual functional description of one, individual feature of the system. A feature typically describes one functional unit of the software system, e.g. the idle controller of an engine or the phase recognition of an ABS controller. A feature is not necessarily identical with a function or task of the ECU software architecture. A feature is primarily a logical unit for the purpose of documentation. When the feature represents an actual component of the software architecture, then its <CATEGORY> element has the value "FCT".

Element Description
<CATEGORY> The feature may be sub-structured via the category element. Two categories of features are available:

• STC - Structural Software Components: Features of the category STC can be used to further sub-structure and group a top-level feature. STC features have no representation in actual code and do not influence the runtime behavior. They just provide a logical structure of the feature.
• FCT - Functional Software Components: Features of the category FCT are typically implementation units of a feature and are the end-points of a feature structure. FCT features contain code and have an impact on runtime behavior.
<INTRODUCTION> Introductory description of the software feature.
<ANNOTATION> Notes about the software feature.
<SW-FEATURE-VARIANT> A feature may have several variants. This element provides the name and description of each variant.
<SW-FEATURE-DEF> The software feature definition describes the physical behavior of the feature. The standard recommends to provide a summary of the signal flow, describe its influence on the characteristics of the control unit and its properties. The feature description should have a chapter describing the purpose and a chapter providing an overview of the feature as a minimum. This element shall not describe any software engineering details.
<SW-FEATURE-DESC> The software feature description provides further details of the feature. It is primarily used to provide information in a pre-defined chapter structure. In automotive software design, features typically have several modes, e.g. "initialization", "normal", "monitoring", "shut_down", etc. This element allows to provide descriptions for repetitive items in a unified way.
<SW-TEST-DESC> Notes about testing the feature.
<SW-CALIBRATION-NOTES> Notes about the calibration of the feature.
<SW-MAINTENANCE-NOTES> Notes about the software maintenance of the feature.
<SW-DIAGNOSIS-NOTES> Notes about the diagnostics of the feature.
<SW-CARB-DOC> Notes needed for CARB.
<SW-FEATURE-DECOMPOSITION> For all features of category STC, this element contains a hierarchical list of references to subcomponents, which allows to describe the subcomponent structure of this feature. This information can be used to create a corresponding hierarchical chapter structure in the technical documentation.
<SW-FEATURE-VARIANT-OF> Contains a list of references to features, for which this feature is a variant. Each referenced feature also has an optional  system condition, which allows to select the effective variant.
<CHAPTER> Contains arbitrary, textual descriptions.
<VARIATION-POINT> Allows to define pre-build and post-build variation points within the feature.

Chapter

The core of the technical documentation are textual descriptions, supported by graphics, tables, formulas and other elements. The <CHAPTER> element contains those descriptions. Similar to HTML, the <CHAPTER> element aggregates many elements for structuring and formatting the text so that document generators can produce readable and well-formatted technical documents.

<CHAPTER> gives a description text a logical structure, but it does not include any information about the style, how the elements are supposed to be rendered or printed in an actual document. Style and presentation aspects of the technical documentation are intentionally not included in ASAM FSX. They are always company- and tool-specific and are to be configured directly in the document generation tool chain.

Element Description
<INTRODUCTION> Introductory description of the software feature.
<ANNOTATION> Notes about the software feature.
<P> Paragraph. Aggregates several other elements for further formatting, e.g. <TT> Technical Term,
Line Break, <XREF> Cross Reference, <XFILE> External File, <FT> Footnote, etc.
<VERBATIM> Preformatted text. Shall be rendered "as is".
<FIGURE> Reference to images, preferably in EPS format.
<FORMULA> Formula.
<LIST> Simple list
<DEF-LIST> List of referable items.
<LABELED-LIST> List with controlled indentation of text.
<NOTE> Note with icons placed aside the text, e.g. which denote "Caution", "Exercise", "Instruction" or other hints.
<TRACE> Traceable text, e.g. for requirements or constraints.
<STRUCTURED-REQ> Structured requirements.
<TABLE> Table. Compliant to the OASIS exchange table model.
<PRMS> Parameter tables.
<MSR-QUERY-P-1> Defines a query for a paragraph. Returns a paragraph-level element, such as <P>, <VERBATIM>, <LIST>, etc.
<TOPIC-1> Topical text unit.
<MSR-QUERY-TOPIC-1> Defines a query for a topic. Returns a <TOPIC-1> element.
<CHAPTER> Sub-chapter of this chapter.
<MSR-QUERY-CHAPTER> Defines a query for a chapter. Returns a <CHAPTER> element.
<VARIATION-POINT> Allows to define pre-build and post-build variation points within the chapter.

Handling of Multiple Languages

ASAM FSX supports multilingual text and graphic elements. Paragraphs <P>, descriptions <DESC>, long names <LONG-NAME>, graphics <L-GRAPHIC> and other elements may aggregated multiple <L-x> elements (x=1 to 10), whose content represent a different language. Available languages are defined in the <ADMIN-DATA>/<USED-LANGUAGES> section in the header of the FSXfile. This allows the author of a documentation element to write the text for this element in two or more languages. The document generator is then able to generate from one FSX source file individual documents for each defined language.

One characteristic feature of multiple language support in ASAM FSX is that the elements for multiple languages are placed on paragraph-level within the FSX XML structure. This significantly eases the translation process. Text translation is typically carried out sentence-by-sentence or paragraph-by-paragraph. The XML structure keeps paragraphs of same content but different language in a sequential order in one place.

Conditional Compilation

Similar to conditional compilation of C-code, ASAM FSX allows to express conditions for elements to be included or excluded from the generated documentation. Such elements aggregate the element <SW-SYSCOND>, which contains an expression in accordance with the formula language of the AUTOSAR Generic Structure Template. If the condition evaluates to "true", then the element will be printed. Conditional compilation is available for <SW-FEATURE>, <CHAPTER>, <LIST>,<DEF-LIST>, <LABELED-LIST>, <NOTE>, <TABLE>, <TRACE>, <STRUCTURED-REQ> and <TOPIC-1>.

Content Filtering

Besides conditional compilation, ASAM FSX knows the concept of "Content Filtering". Elements may have the attribute VIEW, which allows to define the detail level of information for a specific group of readers. For instance, the VIEW attribute may has the value "internal" for marking information that only internal staff embers shall be able to see, or "detail" for marking information that engineers directly involved in the development process of the feature shall be able to see.

 

Relation to Other Standards

ASAM FSX is tightly coupled with ASAM MDX. The latter contains a formal specification of the software architecture and data definition of ECU software. ASAM FSX adds means for describing the functional content of the software via text and graphics to the formal software description. ASAM FSX can be used standalone to generate the technical documentation of ECU software, but would then be restricted to a more functional description. Together with ASAM MDX, the technical documentation would also include all formal aspects of the software, including software components, their interfaces, owned data, scheduling and memory layout. ASAM CDF can be used to include initial values into the software documentation. 

AUTOSAR 4.0 adopted ASAM FSX in their templates. Elements in an AUTOSAR template may aggregate <CHAPTER>, <INTRODUCTION> or <DESC> elements as defined in ASAM FSX. This is specifically useful to document the behavior of software components in the AUTOSAR Software Component Template.

ASAM FSX has references to other standards. The standard uses the formula language of the AUTOSAR Generic Structure Template. Furthermore, ASAM FSX uses the open exchange table model of OASIS. Languages are identified via ISO 639-1:2002 language codes.

 

Industry Adaption

In-house developed tools and formats are still prevalent for authoring and generating the technical documentation of ECU software. ASAM FSX is primarily used in the automotive industry as an exchange format between companies and between different tool chains. It is known that Robert Bosch GmbH, Volkswagen AG and IVECO use ASAM FSX for this purpose. Daimler AG uses ASAM FSX also as the primary source for document generation.

 

List of Deliverables

The standard includes the following deliverables:

  • User's Guide
  • XSD and DTD schema files
Our newsletter informs you when a new standard version is released.
Subscribe