ASAM FSX

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.

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.

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.

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>.

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.

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 "/".

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>.

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".

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.

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.

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>.

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.

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.

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.

The Standard includes the following deliverables:

• User's Guide
• XSD and DTD schema files