FMI Layered Standard for XCP (fmi-ls-xcp)

FMI 3.0 was extended also with virtual Electronic Control Units (virtual ECUs) in mind. Engineers can measure into ECUs using the XCP protocol and A2L variable descriptions:

This layered standard describes how an FMU advertises its XCP capabilities to importers and MCD (Measurement - Calibration - Diagnostics) tools using the XCP protocol.

This document is about how to describe and implement XCP support for FMUs, either by an FMU with integrated XCP service or how to use an external XCP service to access data inside the FMU. To keep the descriptions brief and redundancy low, common concepts, which are used by both implementation types, are described once.

The standard document is in HTML allowing use of in-document links. By pressing "t", the table of contents can be displayed on the left side or hidden.

In key parts of this document, non-normative examples are used to help understand the standard.

Conventions used in this document:

There are alternative implementations depending on the use case and data availability:

It is also possible for an FMU to have an integrated XCP service and allow memory access for an external XCP service.

The importer might also use the A2L address, type, layout and scaling information to use direct memory access into the virtual ECU. As this approach does not use the standardized XCP protocol it is not further described in this layered standard.

This layered standard will have no effect on the FMU interface, nor the C-API behavior. If the XCP slave is implemented inside the FMU, it is recommended that it runs in its own thread and leaves the rest of the operation of the FMU unaffected.

The A2L/XCP standards allow to measure and calibrate variables synchronously to different types of events. These so called event channels are either time-based, angular-based, or non-deterministic, and are identified by a unique event channel number (aka measurement raster). The XCP service must be invoked with the defined event channel number in the thread which is executed for an event. Calibration and communication with the XCP master is typically performed in a background thread. The background thread must always be responsive to the XCP master within the defined communication timeout. Refer to the A2L/XCP standards for more information.

The XCP/A2L approach can not only be used for virtual ECUs, but also for plant models, if the FMU exporter generates an appropriate A2L file.

A2L description files and other files needed for XCP support are placed in /extra/org.fmi-standard.fmi-ls-xcp. [This allows these files to be added and modified after the FMU has been created without affecting any checksums.] The directory structure is analogous to the binaries directory structure, specific to the FMI version. The structure for an FMI 3.0 FMU is shown below. Details are described in the following sections.

When shipping an FMU with XCP/A2L support, it is recommended to provide the necessary information to the importer in the file documentation/fmi-ls-xcp.{txt|html}. For example, this might concern additional information on how to build the final A2L file, if the FMU is delivered as source code.

The A2L description depends on the FMU binary, for example, regarding memory addresses, and byte order. If an FMU archive contains multiple binaries for different platforms, the associated A2L files are placed into separate subdirectories below /extra/org.fmi-standard.fmi-ls-xcp following the same scheme as in the binaries directory, see Section 3.1. It is highly advisable that all A2L files in the FMU use the same XCP configuration, i.e., the same protocol (TCP/UDP), the same ports, and so on.

Note that the A2L files placed under the extra directory are not accessible to the FMU at runtime. Any files that shall be accessible to the FMU at runtime must (also) be placed into the resources directory as defined by the FMI standard.

A2L files may have a considerable size. If size is a concern, it may be decided to supply just a single platform and A2L file with an FMU.

The root name of the A2L file shall be identical to the model identifier and is case sensitive, i.e., a variable description named <modelIdentifier>.a2l is associated with an FMU binary named <modelIdentifier>.{dll|so}.

All format versions of the A2L standard are allowed and it is the responsibility of the MCD tool to handle each format version correctly.

This layered standard forbids the use of the including mechanism of additional A2L files to simplify complete extraction and copying of the A2L file to a location where it is accessible by the MCD tool.

The handling of address information in the A2L file depends on the selected implementation approach for the XCP slave (FMU-internal or external, see Section 1.3) and on the FMU format (binary or source code FMU). See Section 4.3 and Section 5.3, respectively, for detailed information about address resolution.

The A2L description shall include IF_DATA XCP elements to help MCD tools to connect and interact with the XCP service of the FMU more reliably and without user interaction. Parts of the IF_DATA XCP description depend on the machine where the FMU binary is executed, for example, the IP address and port.

The default IP address assigned by the FMU exporter should be localhost, i.e., 127.0.0.1, which fits in many cases. The requirement for the port number is, that it must be unique on the machine where the FMU binary is executed. Typically, a certain range of ports is reserved for this purpose. The FMU importer is responsible for checking if any conflicts of the defined IP addresses and port numbers occur in the context of the simulated system.

In the case of an internal XCP service, it is sometimes necessary for the FMU importer to override the default IP address and/or port number which was assigned by the FMU exporter. For more information about how to configure and handle the XCP service, see Section 4.1. In the case of an external XCP service the connection settings are under the control of the importer.

An FMU may be delivered as source code together with a buildDescription.xml file. This case requires a common understanding of the A2L workflow between the FMU exporter and importer. In practice there are different flavors of the workflow depending on the specific use case.

The FMU exporter shall describe the measurement variables (MEASUREMENT), calibration parameters (CHARACTERISTIC) and related A2L elements of its application in the A2L file. The A2L file is necessarily incomplete as the details of the A2L description depend on the binary for the target platform. For example, the real addresses and memory segments are not known until the FMU binary is built. For information on how to deal with memory addresses refer to Section 4.3 or Section 5.3, respectively.

The A2L description is placed directly into the folder /extra/org.fmi-standard.fmi-ls-xcp if it is target-independent, or in target-specific subfolders otherwise (see Section 3.1).

The FMU importer is responsible for ensuring that the target-specific information in the A2L file is adapted to the target platform for which a source code FMU is built, before making the A2L file available to the MCD tool.

If additional information for the build process and A2L creation is required, it should be provided by the FMU exporter in /documentation/fmi-ls-xcp.{txt|html}.

The modelDescription.xml file publishes a certain set of variables and parameters. The A2L file also publishes a set of FMU variables and parameters. This standard expressly does not restrict the relationship between both sets of variables.

[As a matter of fact, it is quite likely that the variables published in modelDescription.xml is a minimal set required for connectivity reasons. The A2L file might publish a much larger set of variables and parameters that the user can selectively choose to measure or calibrate.

From the viewpoint of an MCD tool, the details of the variable access are transparent, i.e., this information is encapsulated in the A2L file.]

While measurement of FMU internal variables does not have a numeric effect on the FMU, so called calibration does. Calibration is the tuning of FMU internal parameters. Such changes will affect the numeric behavior of the FMU. If the FMU contains controller code, numeric stability or energy preservation laws are of lesser concern. On the other hand, plant models offering XCP access for parameter calibration may introduce surprising numerical effects in solvers that might require proper handling, like resetting solvers with every XCP write action.

It is therefore necessary to synchronize XCP variable access (read and write) with the state of the FMU. [For instance is time not linear in Model Exchange and Intermediate Variable Access might also introduce surprising measurements in Co-Simulation. Appropriate care must be taken when to serve XCP master requests to ensure simulation and measurement integrity.]

To avoid collisions in a simulation system with several XCP services, it can be necessary for the FMU importer to override the default port number the FMU listens on, which was assigned by the FMU exporter in the XCP slave implementation and in the A2L file (see Section 3.4).

Besides the listen port number, the user may also want to change or restrict the listen IP address, which is the IP address of the network interface to which the socket of the XCP service is bound and where it is listening for XCP client commands. In most cases, the listen IP address will be set to INADDR_ANY, i.e., 0.0.0.0, allowing connections from any available network interface. However, it is possible to restrict the XCP service to, e.g., only allow local connections by setting the listen IP address to 127.0.0.1.

Furthermore, it is likely valuable for the user to have the possibility to deactivate the internal XCP service to avoid certain problems with the environment, e.g., with anti-virus software or firewalls or when running the FMU in a container. The importer might also want to use an external XCP service even when an internal XCP service is available.

Therefore, if the XCP slave is embedded in the virtual ECU, the FMU should expose the following variables with pre-defined names in the modelDescription.xml file, which are used to configure the embedded XCP slave (see Section 4.2):

All variables that are defined must be defined as scalars with one of the following causality/variability combinations:

[The variables above do not necessarily have to share the same causality/variability combination. However, e.g., a mixture of structuralParameters and parameters is not sensible. If Configuration Mode is supported, then structuralParameters should be used. On the other hand, an FMU could have parts of its XCP configuration fixed while leaving others configurable. In this case, a combination of, e.g., structuralParameters and constant outputs could make sense.]

The configuration variables are duplicated for both transport layers, TCP and UDP, as it is technically possible to have an XCP slave that uses TCP and UDP channels in parallel. The FMU shall only provide the corresponding variables for the protocols it supports.

Without knowing the concrete XCP slave implementation the importer cannot know if the different protocols can be used in parallel or only exclusively. In case the XCP service is not multi-session capable and both of the variables org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip are set to true, the FMU must return an error and provide a meaningful error message when exiting Configuration Mode. This information may also be provided in the documentation directory inside the FMU.

The importer of an FMU is responsible for keeping all occurrences of the port number consistent, i.e., in both the FMU configuration and in the A2L file.

Since an XCP slave is implemented inside the FMU, the FMU is responsible for starting and stopping the internal XCP service.

Using FMI 3.0, the FMU should preferably expose its XCP configuration variables (see XCP Configuration Variables) as structuralParameters and start the XCP service during the first invocation of fmi3ExitConfigurationMode and shut it down during fmi3Terminate, if the FMU has no explicit power-up signal to simplify user interactions between simulator and MCD tool. If the FMU contains a virtual ECU with power-up control (K15), all built-in OS and Basic Software services (including XCP) should follow the normal power-up protocol.

If the simulator puts the FMU in Configuration Mode and sets the structural parameters org.fmi_standard.fmi_ls_xcp.[Tcp|Udp]ListenIpAddress and org.fmi_standard.fmi_ls_xcp.[Tcp|Udp]ListenPortNumber, the XCP slave shall use those parameters to set up the communication connection for the XCP protocol.

If the value of structural parameter org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip is true, the XCP slave must be responsive for XCP commands on the corresponding channel (TCP/UDP) after leaving Configuration Mode. Thus, it is possible for the XCP master to perform calibration during the Instantiated state, for example, to set parameters before entering Initialization Mode. Note that reading values of calculated variables, which depend on an initialization function, is only possible after entering the Initialized super state with fmi3ExitInitializationMode.

If org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip is false, the internal XCP service must not be started with TCP/UDP, the network resources must not be used and no XCP service actions must be performed by the FMU on this channel during simulation. If both parameters are false the XCP service must not be started at all.

If Configuration Mode was not entered and the value of variable org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip is true, the FMU must start the XCP service in fmi3EnterInitializationMode at the latest. In this case, it is not possible to perform calibration before Initialization Mode is entered or to configure the XCP connection settings.

If the importer re-enters Configuration Mode and reconfigures the parameters it is up to the FMU if it reacts to the parameter change or not.

Using FMI 2.0, the FMU should preferably expose its XCP configuration variables as parameters and start the XCP service during the first call of fmi2SetupExperiment and shut it down during fmi2Terminate if the FMU has no explicit power-up signal to simplify user interactions between simulator and MCD tool. The importer is responsible for calling fmi2SetupExperiment at least once and setting the parameters before fmi2SetupExperiment is called.

If the FMU does not expose its XCP configuration variables as structuralParameters using FMI 3.0, or as parameters using FMI 2.0, the importer will not have control over whether the internal XCP service should be started. In this case, the default value of the start attribute of variable org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip determines if the XCP service is started.

[Note that it is not possible to manually change the start value for org.fmi_standard.fmi_ls_xcp.EnableXcpOn[Tcp|Udp]Ip in the modelDescription.xml file to change the behavior of the internal XCP service. The start value merely reflects the default behavior coded into the FMU.]

Dependent on the FMU format and the XCP slave implementation inside the FMU, dealing with memory addresses of variables in the A2L file differs.

If the FMU is in binary format, i.e., it is shipped with a shared library, the FMU exporter must provide values for the ECU addresses inside the A2L file and the XCP slave inside the FMU is responsible for resolving the physical addresses from the address field values. [These address field values can be either real addresses or fixed target-independent indices that are used by the XCP slave implementation for getting variables during runtime.]

If the FMU is only shipped with source code, it is not possible to determine the memory addresses before building the binary, i.e., real addresses cannot be provided by the exporter in the A2L file. In this case the address field values in the A2L file must be either fixed target-independent indices, which allow the FMU to resolve the addresses at runtime, or the A2L file only contains linker symbol links (SYMBOL_LINK). In the latter case, the importer or an external A2L tool is responsible for determining the actual variable addresses from the symbol links. These addresses must be relative to the base address of the built FMU binary. Refer to the ASAM MCD-2 MC standard for more information on symbol links and automatic address update.

If the FMU exporter does not use real (offset) addresses in the A2L file in the binary FMU case, or does not provide symbol links in the source code FMU case, attribute supportsDirectMemoryAccessViaA2L in the fmi-ls-manifest.xml file must be set to false (see Section 5.3).

For an external XCP service no structural parameters for the XCP configuration are needed, because the importer has the entire control over the XCP service and is responsible for its configuration. [The importer should allow the user to set IP address and port number analogous to the variant with an internal XCP service.]

When an external XCP service is used, the importer has to make XCP service calls and is responsible for creating events for its XCP service. However, in contrast to the FMU with internal XCP support, the importer does not have the knowledge about the inner structure of the virtual ECU and therefore it is not able to create specific XCP events, e.g., one event for each task.

This means, by default, the importer can only make XCP calls at certain points in time, e.g., at communication points in Co-Simulation, ignoring specific task-related XCP events. The importer is responsible for matching the IF_DATA XCP section in the A2L file to the implementation of the XCP service. If necessary, the IF_DATA XCP section must be added or replaced in the A2L file delivered with the FMU, before making it available to the MCD tool. For example, the importer can create an event channel for a basic measurement raster and write the corresponding event definition into the IF_DATA XCP section of the A2L file.

If a Co-Simulation FMU announces that it makes use of the intermediate update callback function (attribute providesIntermediateUpdate = true of the Co-Simulation element), the importer may also create another event for the intermediate update raster and call the XCP service in each fmi3IntermediateUpdateCallback with the event channel number of this event.

Furthermore, if the FMU contains clocks, the importer might also provide the user with the ability to create separate XCP events for each clock. In this case the simulator is responsible for handling the mapping between clock and XCP event and must call the XCP service with the corresponding event channel when the associated clock is active just before leaving Event Mode.

Since the XCP slave is implemented outside the FMU, the importer is responsible for starting and stopping the external XCP service. [Preferably, the start-up is performed sometime during the Instantiated state of the FMU to allow the XCP master to set parameters before entering Initialization Mode.]

Depending on the FMU format, dealing with memory addresses of variables in the A2L file differs.

In the binary FMU case, the A2L file must contain real addresses, which are relative to the base address of the FMU binary, allowing the external XCP slave to access the memory of the FMU correctly.

Since the external XCP slave can only make use of real addresses and in the case of source code FMUs there are no real addresses available yet, the A2l file must contain linker symbol links (SYMBOL_LINK). In this case, analogous to the use of an internal XCP slave, the importer or an external A2L tool is responsible for determining the actual variable addresses from the symbol links.