Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix last issues #34

Merged
merged 3 commits into from
Sep 1, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/examples/fmi_ls_xcp_manifest_example.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,6 @@
xmlns:fmi-ls="http://fmi-standard.org/fmi-ls-manifest"
fmi-ls:fmi-ls-name="org.fmi-standard.fmi-ls-xcp"
fmi-ls:fmi-ls-version="1.0.0"
fmi-ls:fmi-ls-description="Layered standard based on FMI 2 and FMI 3 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files."
fmi-ls:fmi-ls-description="Layered standard based on FMI 2.0 and FMI 3.0 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files."
containsXcpService="true"
supportsDirectMemoryAccessViaA2L="true"/>
35 changes: 19 additions & 16 deletions docs/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,10 @@
:revnumber: 1.0
:icons: font

Based on FMI 2 and FMI 3, this layered standard defines how to describe and implement XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files.
Based on FMI 2.0 and FMI 3.0, this layered standard defines how to describe and implement XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files.

_[Note: Although the document refers to versions 2.0 and 3.0 of the FMI standard, everything described in this document also applies to all subsequent minor versions._
_For further information on compatibility, see section https://fmi-standard.org/docs/3.0/#VersioningLayered[Versioning and Layered Standards] in the FMI 3.0 specification.]_

{empty} +
{empty}
Expand Down Expand Up @@ -119,7 +122,7 @@ This layered standard defines additional capability flags in the layered standar

|`fmi-ls-description`
| `\http://fmi-standard.org/fmi-ls-manifest`
| `Layered standard based on FMI 2 and FMI 3 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files.`
| `Layered standard based on FMI 2.0 and FMI 3.0 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files.`
| String with a brief description of the layered standard that is suitable for display to users.

|`containsXcpService`
Expand All @@ -137,6 +140,8 @@ See <<External XCP Service>>.

|====

The FMU must set at least one of the attributes `containsXcpService` or `supportsDirectMemoryAccessViaA2L` to `true` to comply with this layered standard.

An example of a manifest file for this layered standard is shown below:

[source, xml]
Expand All @@ -150,7 +155,7 @@ Independent of the selected implementation approach (see <<Rough Outline of the
The concepts defined in this chapter are common to both of the implementation approaches.
The definitions that are specific to the particular implementation types are defined in <<FMU with Integrated XCP Service>> and <<External XCP Service>>.

=== Structure of the FMU archive
=== Structure of the FMU Archive

A2L description files and other files needed for XCP support are placed in the `extra` directory: `/extra/org.fmi-standard.fmi-ls-xcp`.
The directory structure is analogous to the `binaries` directory structure and is shown below.
Expand Down Expand Up @@ -351,17 +356,17 @@ Therefore, if the XCP slave is embedded in the virtual ECU, the FMU shall expose

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

* **fixed structuralParameter (FMI 3 only):**
* **fixed structuralParameter (FMI 3.0 only):**
If the FMU defines the variables as `structuralParameters`, the XCP configuration can be changed during `Configuration Mode`.
When the XCP service is started in `fmi3ExitConfigurationMode`, it is configured and running before the simulation starts, i.e., before `Initialization Mode` is entered.
For FMI 3, this is the most flexible variant and should be preferred over the other variants.
For FMI 3.0, this is the most flexible variant and should be preferred over the other variants.

* **fixed parameter:**
If the FMU defines the variables as `parameters`, the FMU signals that it does not support `Configuration Mode`.
For FMI 3, this means, the XCP service is started at the latest when `Initialization Mode` is entered.
In case of FMI 2, the FMU should preferably start the XCP service in the `fmi2SetupExperiment` function.
For FMI 3.0, this means, the XCP service is started at the latest when `Initialization Mode` is entered.
In case of FMI 2.0, the FMU should preferably start the XCP service in the `fmi2SetupExperiment` function.
This allows for configuring the XCP service with the configuration parameters and ensuring that the service is running before the simulation starts.
This is the preferred variant for FMI 2.
This is the preferred variant for FMI 2.0.

* **constant output:**
If the FMU is restricted to a fixed XCP configuration, it shall at least announce its configuration to the outside.
Expand All @@ -383,9 +388,9 @@ _In this case, a combination of, e.g., `structuralParameters` and `constant outp
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._
_The FMU decides which protocol it uses in the 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`._
_This information may also be provided in the `documentation` directory inside the FMU.]_
Without knowing the concrete XCP slave implementation the importer cannot know if the different protocols can be used in parallel or only exclusively.
In the 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 in the corresponding setter function and provide a meaningful error message.
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.

Expand All @@ -394,7 +399,7 @@ The importer of an FMU is responsible for keeping all occurrences of the port nu

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

*Using FMI 3*, the FMU shall preferably expose its XCP configuration variables (see <<figure-xcp-configuration-parameters>>) as `structuralParameters` and start the XCP service during `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.
*Using FMI 3.0*, the FMU shall preferably expose its XCP configuration variables (see <<figure-xcp-configuration-parameters>>) as `structuralParameters` and start the XCP service during `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.
Expand All @@ -409,10 +414,10 @@ 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.

*Using FMI 2*, the FMU shall 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.
*Using FMI 2.0*, the FMU shall 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, or as `parameters` using FMI 2, the importer will not have control over whether the internal XCP service should be started.
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._
Expand Down Expand Up @@ -443,8 +448,6 @@ It is also possible that the FMU does contain an internal XCP slave implementati
In this case it is the choice of the importer whether to use the FMU internal XCP slave or its own implementation.
See <<starting-internal-xcp-service>> on how to deactivate the internal XCP service.

_[Note that the FMU must set at least one of the attributes `containsXcpService` or `supportsDirectMemoryAccessViaA2L` 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 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.

_[<<XCP-Communication-external-Slave>> shows a design where the XCP slave is implemented by the importer outside of the FMU._
Expand Down
2 changes: 1 addition & 1 deletion schema/fmi3LayeredStandardXcpManifest.xsd
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<xs:complexType>
<xs:attribute ref="fmi-ls:fmi-ls-name" use="required" fixed="org.fmi-standard.fmi-ls-xcp"/>
<xs:attribute ref="fmi-ls:fmi-ls-version" use="required"/>
<xs:attribute ref="fmi-ls:fmi-ls-description" use="required" fixed="Layered standard based on FMI 2 and FMI 3 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files."/>
<xs:attribute ref="fmi-ls:fmi-ls-description" use="required" fixed="Layered standard based on FMI 2.0 and FMI 3.0 for describing and implementing XCP support for FMUs, which can either provide an XCP service or allow direct memory access via A2L files."/>
<xs:attribute name="containsXcpService" type="xs:boolean" use="required">
<xs:annotation>
<xs:documentation xml:lang="en">
Expand Down