From 5cc67923fdfbceccde742876b60767ca1a2d3081 Mon Sep 17 00:00:00 2001 From: Andreas Junghanns Date: Tue, 27 Jun 2023 11:27:07 +0200 Subject: [PATCH] Changes after review --- docs/index.adoc | 112 +++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 58 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index ad92391..51997f2 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -49,7 +49,7 @@ This layered standard describes how an FMU advertises its XCP capabilities to im === How to Read This Document -This document is about how to describe and implement XCP support for FMUs, either by an FMU internal XCP slave implementation or an external XCP slave. +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, <>, which are used by both implementation types, are described once. The standard document is in HTML allowing use of in-document links. @@ -63,36 +63,34 @@ Conventions used in this document: * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in https://tools.ietf.org/html/rfc2119[RFC 2119] (regardless of formatting and capitalization). -=== Rough Outline of the Approach +=== Outline of the Approach There are alternative implementations depending on the use case and data availability: . The FMU implements an XCP slave which provides access to measurement and calibration variables of the virtual ECU and handles the communication protocol with the XCP master in the MCD tool. - The necessary information for an MCD tool is given in a description file which follows the https://www.asam.net/standards/detail/mcd-2-mc/[ASAM MCD-2 MC] standard (aka A2L, also ASAP2) and customarily carries the file extension `.a2l`. + The necessary information for an MCD tool is given in a description file which follows the https://www.asam.net/standards/detail/mcd-2-mc/[ASAM MCD-2 MC] standard (aka A2L, also <>) and customarily carries the file extension `.a2l`. For further details see <>. . An external XCP slave implementation accesses the memory of the virtual ECU to expose the XCP protocol to the MCD tool. - In this case, the importer needs to provide such an XCP slave implementation together with the A2L description file. + In this case, the importer needs to provide such an XCP slave implementation using the A2L description file. `fmi3IntermediateUpdateCallback` calls or the clocks mechanism could be used to synchronize DAQ lists. For further details see <>. -_[It is also possible for an FMU to support both, internal and external XCP services._ +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.]_ +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. -=== Comments about this Approach +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. -_[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 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.]_ +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. [#common-concepts] == Layered Standard Manifest File @@ -100,7 +98,7 @@ _The XCP/A2L approach can not only be used for virtual ECUs, but also for plant This layered standard defines additional capability flags in the layered standard manifest file. <> shows the content of `fmi-ls-manifest.xml`. -.`fmiLayeredStandardManifest` attribute details. +.`fmiLayeredStandardManifest` Attribute Details. [[table-schema-fmi-ls-xcp-attributes]] [cols="1,1,1,2",options="header"] |==== @@ -125,12 +123,12 @@ This layered standard defines additional capability flags in the layered standar | String with a brief description of the layered standard that is suitable for display to users. |`containsXcpService` -| +| | `true` or `false` | If `true`, the FMU contains its own XCP slave implementation. See <>. |`supportsExternalXcpService` -| +| | `true` or `false` | If `true`, the FMU allows the importer to access its memory via an external XCP service. See <>. @@ -196,11 +194,11 @@ Any files that shall be accessible to the FMU at runtime must (also) be placed i 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 `.a2l` is associated with an FMU binary named `.{dll,so}`. +The root name of the A2L file shall be identical to the model identifier and is case sensitive, i.e., a variable description named `.a2l` is associated with an FMU binary named `.{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 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. +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 <>) and on the FMU format (binary or source code FMU). See <> and <>, respectively, for detailed information about address resolution. @@ -210,7 +208,7 @@ See <> and <>, respect 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 shall be `localhost`, i.e. `127.0.0.1`, which fits in many cases. +The default IP address assigned by the FMU exporter shall 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. @@ -225,16 +223,16 @@ An FMU may be delivered as source code together with a `buildDescription.xml` fi 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 his application in the A2L file. -The A2L file might be fragmentary as the details of the A2L description depend on the binary for the target platform. -Especially the real addresses are not known until the FMU binary is built. +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 <> or <>, 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 <>). -The FMU importer is responsible for ensuring that the target-specific information in the A2L file fits to the target platform for which a source code FMU is built. +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}. +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}`. === Variable Visibility @@ -245,7 +243,7 @@ This standard expressly does not restrict the relationship between both sets of _[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.]_ +_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.]_ === Numeric Effects of XCP Access @@ -266,7 +264,7 @@ The following sections describe how to configure and handle the internal XCP sla The FMU states that it contains an internal XCP slave implementation with the `containsXcpService` attribute in the `fmi-ls-manifest.xml` file. -_[<> shows a typical design where the XCP slave (in the FMU) communicates with the XCP master (in the MCD tool) using a separate network channel, e.g. the IP stack of the host OS._ +_[<> shows a typical design where the XCP slave (in the FMU) communicates with the XCP master (in the MCD tool) using a separate network channel, e.g., the IP stack of the host OS._ _Thus, the communication of the XCP service is not mixed with the simulated network communication of the ECU wrapped in the FMU._ footnote:[The network communication of FMUs is described by another layered standard. The details of network communication are out of scope here.] @@ -295,7 +293,7 @@ _Note that blocking OS calls should be avoided, because they may have an effect === Configuring the XCP Protocol Settings Sometimes it is necessary for the FMU importer to override the default IP address and/or port number which was assigned by the FMU exporter in the A2L file (see <>). -Furthermore, it might be 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. +Furthermore, it might be 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 shall expose three structural parameters with pre-defined names in the `modelDescription.xml`, which are used to configure the embedded XCP slave (see <>): @@ -322,7 +320,7 @@ Therefore, if the XCP slave is embedded in the virtual ECU, the FMU shall expose Type: UInt16 Causality: structuralParameter Variability: fixed - Start: + Start: ---- The importer of an FMU is responsible for keeping all occurrences of the IP address and port number consistent. @@ -339,29 +337,32 @@ If the value of structural parameter `org.fmi-standard.fmi-ls-xcp.EnableInternal 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.EnableInternalXcpService` is `false`, the internal XCP service must not be started and no XCP operations must be performed by the FMU during simulation. +If `org.fmi-standard.fmi-ls-xcp.EnableInternalXcpService` is `false`, the internal XCP service must not be started, the network resources must not be used and no XCP server actions must be performed by the FMU during simulation. If `Configuration Mode` was not entered and the value of structural parameter `org.fmi-standard.fmi-ls-xcp.EnableInternalXcpService` 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 does not support `Configuration Mode` it is not able to control whether or not the internal XCP service shall be started._ -_In this case the default value of the `start` attribute of variable `org.fmi-standard.fmi-ls-xcp.EnableInternalXcpService` determines if the XCP service is started.]_ +If the importer does not support `Configuration Mode`, it is not able to control whether or not the internal XCP service shall be started. +In this case the default value of the `start` attribute of variable `org.fmi-standard.fmi-ls-xcp.EnableInternalXcpService` 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.EnableInternalXcpService` to change the behavior of the internal XCP service._ +_The `start` value merely reflects the default behavior coded into the FMU.]_ [#address-resolution-internal] === Memory Address Resolution 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. +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. +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 https://www.asam.net/standards/detail/mcd-2-mc/[ASAM MCD-2 MC] standard for more information on symbol links and automatic address update. -_[Note that, if the FMU exporter does not use real addresses in the A2L file in the binary FMU case, or does not provide symbol links in the source code FMU case, attribute `supportsExternalXcpService` in the `fmi-ls-manifest.xml` file must be set to `false` (see <>).]_ +If the FMU exporter does not use real addresses in the A2L file in the binary FMU case, or does not provide symbol links in the source code FMU case, attribute `supportsExternalXcpService` in the `fmi-ls-manifest.xml` file must be set to `false` (see <>). == External XCP Service @@ -374,7 +375,7 @@ See <> on how to deactivate the internal XCP serv _[Note that the FMU must set at least one of the attributes `containsXcpService` or `supportsExternalXcpService` to `true` to make use of this layered standard.]_ -Although the XCP behavior for an internal and an external service is the same from the perspective of the XCP master, the operation of the external XCP service differs from the internal one in some points that are described in this chapter. +Although the XCP behavior for an internal and an external service is the same from the perspective of the MCD tool (XCP master), the operation of the external XCP service differs from the internal one in some points that are described in this chapter. _[<> shows a design where the XCP slave is implemented by the importer outside of the FMU._ _In this variant the XCP communication uses the IP stack of the host OS analogous to the design in <>.]_ @@ -389,19 +390,18 @@ image::images/XCP-Communication-external-Slave.svg[width=80%, align="center"] 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 is the one who has to make XCP service calls and who is responsible for creating events for its XCP service. -However, in contrast to the FMU in the approach with an internal XCP slave, the importer does not necessarily have the knowledge about the inner structure of the virtual ECU and therefore it is not able to create specific events, e.g. one event for each task. - -This means, by default, the importer can only make XCP calls at certain points in time disregarding specific task-related XCP events, e.g. at communication points in Co-Simulation. -The importer must create an event channel for this basic measurement raster and must write the corresponding event definition to the `IF_DATA XCP` section in the A2L file. +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 an 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. -_[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.]_ +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 ot 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 ticking. +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`. [#starting-external-xcp-service] === Starting and Stopping the XCP Service @@ -412,11 +412,9 @@ _[Preferably, the start-up is performed sometime during the `Instantiated` state [#address-resolution-external] === Memory Address Resolution -Dependent on the FMU format, dealing with memory addresses of variables in the A2L file differs. +Depending on the FMU format, dealing with memory addresses of variables in the A2L file differs. -Since the used XCP service does not come along with the FMU, it has no knowledge about the address mechanisms that might be used in the A2L file. -Therefore, in the binary FMU case, the A2L file must contain real addresses, which are relative to the base address of the FMU binary. -On the other hand, the external XCP slave must interpret the address values as real addresses as well. +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. @@ -432,15 +430,13 @@ Therefore, this constellation is not applicable to this layered standard and the Limitations for binary FMUs: -* Normally only variables in the memory segments owned by the main FMU binary `{.dll, .so}` are accessible by the XCP service, i.e. variables defined in source code modules and in statically linked libraries. +* Normally only variables in the memory segments owned by the main FMU binary `{.dll, .so}` are accessible by the XCP service, i.e., variables defined in source code modules and in statically linked libraries. Accessing variables in the memory of indirectly loaded dynamic libraries requires a special implementation which is out-of-scope for this layered standard. -Limitations for variant <>: - -* This layered standard does not describe how the importer can determine the different memory segments within the built FMU. -Therefore, page handling is not supported in the case of an external XCP service. - [bibliography] == References - [[[PW13]]] Preston-Werner, T. (2013): **Semantic Versioning 2.0.0**. https://semver.org/spec/v2.0.0.html +- [[[ASAP2]]] ASAM MCD-2 MC. https://www.asam.net/standards/detail/mcd-2-mc/ +- [[[RFC2119]]] RFC 2119. https://tools.ietf.org/html/rfc2119 +- [[[LICENSE]]] FMI License text. https://raw.githubusercontent.com/modelica/fmi-standard/master/LICENSE.txt