ASAM XIL

Generic Simulator Interface

Part 2 of 5

C# API Technology Reference Mapping

Rules
Version 2.2.0
Date: 2020-03-13

Base Standard

© by ASAM e.V., 2020

Disclaimer

This document is the copyrighted property of ASAM e.V.

Any use is limited to the scope described in the license terms. The license
terms can be viewed at www.asam.net/license
 Table of Contents

Table of Contents

Foreword 5

1 Introduction 6
1.1 Overview .......................................................................................................... 6
1.2 Development Environment ............................................................................. 6
1.3 Generation of packages with respect to Namespaces.................................. 6
1.4 Delivered Components.................................................................................... 6
1.4.1 ASAM.XIL.Interfaces .............................................................................. 7
1.4.2 ASAM.XIL.Implementation ..................................................................... 7
1.4.3 ASAM.XIL.TestSuite .............................................................................. 7
1.4.4 ExampleVendor.XIL ............................................................................... 7
1.4.5 ASAM.XIL.MSI ....................................................................................... 7

2 Coding and naming conventions 8

2.1 Names for Interfaces and Classes ................................................................. 8
2.2 Properties ........................................................................................................ 8
2.3 Method Signatures .......................................................................................... 8
2.3.1 Return Types ......................................................................................... 8
2.3.2 Parameter Types ................................................................................... 8
2.4 Enumerations .................................................................................................. 8

3 Mapping of types 9
3.1 Mapping of ASAM Data Types ........................................................................ 9
3.2 Mapping of XIL Types ..................................................................................... 9
3.2.1 XIL Arrays .............................................................................................. 9
3.2.2 XIL Collections ..................................................................................... 10
3.2.3 XIL Enumerators .................................................................................. 10
3.2.4 XIL Data Types .................................................................................... 10
3.3 Disposable ..................................................................................................... 10

4 Exception Handling 11

5 Deprecated Elements 12

6 System initialisation and client access 13

7 Interfaces and Classes 15

8 Distribution of Standard Assemblies 16

8.1 Installation ..................................................................................................... 16
8.2 Deinstallation ................................................................................................. 16
8.3 Repair ............................................................................................................. 16
ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 3
 Table of Contents

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 4

 Foreword

FOREWORD

The XIL standard is developed by ASAM to standardize the communication between test
automation software and X-in-the-loop testbenches. It supports testbenches at all stages in
the software development process – such as MIL1, SIL2, HIL3.

The application of the XIL standard allows users to combine the software and hardware tools
independent of the vendor, thus enabling the reuse of the existing programmed tests for
subsequent development stages (e.g. reuse of test cases for function models in software
tests at a HIL simulator). This results in reduced costs for test programming and reduced
training costs for testers.

The standard is divided into the following parts:

 Core specification
 Mapping rules for C# and Python
 C# implementation and usage examples
 C# test suite

The core specification includes a conceptual description (Programmer’s Guide), the UML
model (technology independent interface definition) of the Testbench and Framework API as
well as various file format specifications.

The mapping rules define the transformation of the technology independent definitions into
C# and Python specific representations. They include the C# interfaces and Python classes
generated from the technology neutral UML model as well as standard implementations of a
few, very fundamental interface classes (only C#).

The C# implementation and usage examples contain programming examples in C# which

demonstrate how to implement and use the XIL interfaces. They also contain source code of
common vendor independent base functions and components. The example
implementations are intended to help test case developers and XIL vendors. They can be
used and integrated into their products.

The C# test suite provides a set of test cases for the XIL Testbench API to help vendors and
users to verify standard conformance of their C# implementations. The test cases are
provided as C# source code. They can be automatically executed using the NUnit4 test
framework and therefore easily integrated into automated build and test tool chains.

1
Model-in-the-Loop
2
Software-in-the-Loop
3
Hardware-in-the-Loop
4
NUnit: http://nunit.org
ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 5
 Introduction

1 INTRODUCTION

1.1 OVERVIEW
ASAMs goal has always been to define technology independent standards. Therefore the
object model of the XIL API is defined in UML. This UML model is mapped to different
programming languages. As a result of the mapping process, all XIL API classes are
available in each of the supported programming languages either as interface definitions or
using native data types.

These mapping rules shall describe the transformation from the generic UML Model to C#
specific interfaces, which shall be used by each client and server for implementation
purpose.

1.2 DEVELOPMENT ENVIRONMENT

The assemblies delivered with the XIL standard are built with target version .NET Framework
4.0.
The C# project files have been created with Microsoft Visual Studio 2015.

Note: The minimum target version that servers and clients have to be built for is .NET
Framework 4.0. There are no further restrictions or recommendations by the XIL
standard. Vendors are free to build their servers and clients for any higher target
version induced by technical or other parameters outside the XIL scope. However,
vendors must declare the minimum .NET Framework version required by their XIL
software in the documentation. It is recommended that installers of XIL servers and
clients ensure that a .NET Framework is installed which version is greater or equal
than the required minimum version. That means the installer would also install the
.NET Framework or upgrade an existing installation if necessary.

1.3 GENERATION OF PACKAGES WITH RESPECT TO NAMESPACES

Namespaces are built according to the folder hierarchy in the UML diagram, including the
package name.

1.4 DELIVERED COMPONENTS

The C# language reference includes the following components:
 ASAM.XIL.Interfaces
 ASAM.XIL.Implementation
 ASAM.XIL.TestSuite
 ExampleVendor.XIL
 ASAM.XIL.MSI
A Microsoft Visual Studio 2015 solution file is provided which contains all components.

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 6

 Introduction

1.4.1 ASAM.XIL.INTERFACES

The C# project “ASAM.XIL.Interfaces.csproj” contains all C# interfaces required for XIL API
V2.2. The file structure widely follows the namespace scheme and start with
ASAM.XIL.Interfaces.
After compiling the project, an interface DLL ASAM.XIL.Interfaces.dll is created.
All source code is provided in C# language.

1.4.2 ASAM.XIL.IMPLEMENTATION

Different implementation folders are contained:

 Framework
 Framework.Test
 FrameworkFactory
 ManifestReader
 Testbench
 Testbench.Test
 TestbenchFactory

This implementations can be taken over in own projects, because it is running code for the
respective parts of the technology reference.

1.4.3 ASAM.XIL.TESTSUITE

The TestSuite allows checking of vendor specific Testbench implementations independent

from a running cross test. Tests are realized as NUnit tests. To execute this tests a data
model for the Testbench is also contained. The NUnit tests are restricted to the MAPort and
EESPort. The result evaluation is realized by the NUnit 3 Testadapter, which is integrated
into the Visual Studio project.

1.4.4 EXAMPLEVENDOR.XIL

Contains numerous example implementations and respective unit tests, which are separated
in the following projects:
 ExampleVendor.XIL.Framework
 ExampleVendor.XIL.Framework.IntegrationTest
 ExampleVendor.XIL.FrameworkClient
 ExampleVendor.XIL.Testbench
 ExampleVendor.XIL.TestbenchClient

1.4.5 ASAM.XIL.MSI

The project ASAM.XIL.MSI.csproj creates a setup file, which is used to install the following
components in the Windows global assembly cache (GAC):
 ASAM.XIL.Implementation.Framework.dll
 ASAM.XIL.Implementation.FrameworkFactory.dll
 ASAM.XIL.Implementation.ManifestReader.dll
 ASAM.XIL.Implementation.Testbench.dll
 ASAM.XIL.Implementation.TestbenchFactory.dll
 ASAM.XIL.Interfaces.dll

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 7

 Coding and naming conventions

2 CODING AND NAMING CONVENTIONS

Class names, method names, attribute names, and parameter names of the C# source code
have been taken directly from the UML model.

2.1 NAMES FOR INTERFACES AND CLASSES

The C# reference for XIL API strictly separates interfaces from implementation code.
Therefore all classes except Exceptions of the UML diagram have been translated into C#
interfaces. The C# interface names start with the capital “I”, followed by the class name of
the UML model. Additionally the stereotype <<interface>> is used to mark such interfaces.

Example:
UML model: BaseValue=> C# interface: IBaseValue

A corresponding C# implementation has to have the same name as the UML class name.

2.2 PROPERTIES
Methods in the UML model which start with “get” or “set” have been translated into C#
properties (get, set). E.g. the methods getMinBufferSize and getMaxBufferSize of
the Capture class in the UML diagram are mapped to C# as
1 long MinBufferSize { get; set; }

2.3 METHOD SIGNATURES

2.3.1 RETURN TYPES

All return types are either of type void, C# base types or XIL-API interfaces.

2.3.2 PARAMETER TYPES

All parameter types are either C# base types or XIL API interfaces.

2.4 ENUMERATIONS
The value names of enumerations in the UML model start with “e” followed by capital
characters. Enumeration classes in the generic UML model are directly mapped to C#
enums. If not explicitly specified differently, numerical values start with 0.

1 public enum DataType

2 {
3 eNO_TYPE = 0,
4 eBOOLEAN = 1,
5 ...
6 }

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 8

 Mapping of types

3 MAPPING OF TYPES

3.1 MAPPING OF ASAM DATA TYPES

Data types of the UML class model have been mapped to the .NET type system. Basic types
such as bool or double are used where possible.

Table 1 Mapping of ASAM data types to C# Data Types

UML data type C# data type

A_BOOLEAN bool
A_INT8 sbyte
A_INT16 short
A_INT32 int
A_INT64 long
A_UINT8 byte
A_UINT16 ushort
A_UINT32 uint
A_UINT64 ulong
A_FLOAT32 float
A_FLOAT64 double
A_UNICODE2STRING String
A_BYTEFIELD IList<byte>

3.2 MAPPING OF XIL TYPES

3.2.1 XIL ARRAYS

Table 2 Mapping of XIL Arrays to C# Data Types

UML data type C# data type

<TYPE>[] IList<TYPE>
<TYPE>[][] IList<IList<TYPE>>

Ilist in C# has an index in the range of int.

Note: TYPE stands for signed elements with stereotype <<data type>> and standard
specific interfaces (<AnyObject>).

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 9

 Mapping of types

3.2.2 XIL COLLECTIONS

Table 3 Mapping of XIL Collections to C# Data Types

UML data type C# data type

<TYPE>NamedCollection IDictionary<string,TYPE>
<TYPE>IndexCollection IList<TYPE>
StringNamedCollection IDictionary<string,string>
<TYPE>By<TYPE>Collection IDictionary<TYPE, TYPE>
First Replacement Part: Value First Replacement Part: Key
Second Replacement Part: Key Second Replacement Part: Value

Note: TYPE stands for signed elements with stereotype <<data type>> and standard
specific interfaces (<AnyObject>).

Note: Mapping of the <TYPE>By<TYPE>Collection changes the sequence of the

replacement parts.

3.2.3 XIL ENUMERATORS

C# interfaces corresponding to iterable ASAM XIL interfaces do not inherit the
GetEnumerator methods from the generic model. They are derived from
IEnumerable<<ANYTYPE>> instead. Thereby <ANYTYPE> is replaced by the type
specification of the associated <ANYTYPE>Enumerator interface that is given as return type
of the GetEnumerator method. <ANYTYPE>Enumerator interfaces of the generic model
are not mapped to any C# class.

3.2.4 XIL DATA TYPES

Table 4 Mapping of XIL Data Types to C# Data Types

UML data type C# data type

AnyObject dynamic
Type Type

3.3 DISPOSABLE
Disposable will be deleted in the interface Reference. Interfaces derived from Disposable will
be derived from the C# IDisposable Interface

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 10

 Exception Handling

4 EXCEPTION HANDLING

The exception handling of XIL API integrates with the standard exception handling defined by
the .NET Framework. All Exception classes will be mapped to abstract Exception classes
(without prefix "I" at the class name).
The class Exception will be deleted, the standard type System.Exception classes is
used instead. So the implementation Classes of all Exceptions are derived from the
System.Exception.

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 11

 Deprecated Elements

5 DEPRECATED ELEMENTS

Methods, properties and interfaces which have been assigned the deprecated stereotype in
the generic UML model are annotated with the Obsolete attribute in the generated C# files.
For example the annotation of a deprecated interface looks like

[Obsolete("This interface is deprecated and might be removed in a future version of

the standard. So XIL clients are strongly recommended to use the replacement specified
in the API documentation and the Programmer's Guide Appendix.", false)]

This annotation will result in compiler and IDE warnings if deprecated elements are used. It
will help users to detect the use of deprecated elements in their code.

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 12

 System initialisation and client access

6 SYSTEM INITIALISATION AND CLIENT ACCESS

Entry points for client access to a XIL System are the FrameworkFactory and
TestbenchFactory interface. Implementation classes of these interfaces are delivered with
the ASAM XIL Technology Reference within the Implementation Package. These rely on the
Implementation Manifest files provided by XIL vendors. Both factories support instance
creation for different vendors at the same time.

Vendors are free to provide their own implementations of FrameworkFactory and

TestbenchFactory. Please see the vendor’s system documentation to figure out which factory
implementation has to be used and how to get access to a vendor specific factory if provided.

The following source code listing illustrates how to obtain access to a vendor’s Framework
and Testbench implementation using the ASAM implementation of FrameworkFactory and
TestbenchFactory.

using ASAM.XIL.Implementation.FrameworkFactory.Framework;
using ASAM.XIL.Implementation.TestbenchFactory.Testbench;
using ASAM.XIL.Interfaces.Framework;
using ASAM.XIL.Interfaces.Testbench;
using ASAM.XIL.Interfaces.Testbench.MAPort;

// creation of Framework instance

FrameworkFactory frameworkFactory = new FrameworkFactory();
IFramework vendorFramework =
frameworkFactory.CreateVendorSpecificFramework("ExampleVendor", "4.4");

// creation of Testbench and Port instances

TestbenchFactory testbenchFactory = new TestbenchFactory();
ITestbench vendorTestbench =
testbenchFactory.CreateVendorSpecificTestbench("ExampleVendor ", "PlatformAPI", "1.3");
IMAPort vendorMaPort = vendorTestbench.MAPortFactory.CreateMAPort("EnvironmentModel");

Note: Without special provisioning the TestbenchFactory and the FrameworkFactory

implementations included in a certain XIL release can only create instances of
Testbench and Framework implementations that are based on the same XIL
release. The cause of this limitation is the binding of both factories to a certain
Testbench and Framework interface definition. It defaults to the
ASAM.XIL.Interfaces.dll assembly version belonging to the factories’ XIL version.

This limitation becomes relevant when client applications need to combine multiple
Testbench or Framework implementations that do not share a common XIL version.
In this case there would not be a single Factory version that can instantiate all of
them. However, there are different approaches to overcome this problem:
o Apply assembly binding redirection (see: https://docs.microsoft.com/en-
us/dotnet/framework/configure-apps/redirect-assembly-versions) to redirect
ASAM.XIL.Interfaces used by your Testbench- and FrameworkFactory to
the lowest version that any of your Testbench or Framework
implementations is based on. However, for this to work properly, all referenced

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 13

 System initialisation and client access

XIL versions must be binary compatible to the one selected by the redirection.
Also all the used Testbench and Framework implementations must be
binary compatible to that XIL version. Note that with this approach new
methods and functionalities in servers based on more recent XIL versions are
not available to the client.
o Load and call all XIL functions dynamically at runtime using System.Reflection
and handle any version mismatches programmatically.”

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 14

 Interfaces and Classes

7 INTERFACES AND CLASSES

Interfaces will be clearly separated from the implementation.

A client application (XIL-User) which uses the XIL API should only use the interfaces (except
TestBenchFactory, FrameworkFactory). This guarantees a maximal independence from XIL
API implementations coming from different tool manufacturers.
See ExampleVendor.XIL sources for more details of using the C# interfaces in own code.

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 15

 Distribution of Standard Assemblies

8 DISTRIBUTION OF STANDARD ASSEMBLIES

8.1 INSTALLATION
To install generic ASAM assemblies (implementation and interfaces) into the Global
Assembly Cache (GAC), the setup, that is delivered with the standard, has to be executed.
There is an unattended mode, that allows the setup to run without user interaction. The
unattended mode can be activated using the command line parameter “/passive”.
The ASAM setup decides, whether and which files need to be installed.

8.2 DEINSTALLATION
If a tool, that uses an implementation of the XIL API, is deinstalled, the ASAM setup must
not be executed. Even if the deinstalled tool was the last consumer of the binaries, the
assemblies will remain installed. The user can remove the assemblies manually using the
system panel.

8.3 REPAIR
The setup has a repair mode, that can be chosen, if the setup is called once again. If
installed files are missing on the computer, they are installed again.

ASAM XIL C# API Technology Reference Mapping Rules Version 2.2.0 16

E-mail: [email protected]
Internet: www.asam.net

© by ASAM e.V., 2020