HMS IXXAT FlexRay Owner's manual

The expert for industrial and automotive communication
Manual
IXXAT FlexRay Interface UCI
Programming Manual

IXXAT
Headquarter US Sales Office
IXXAT Automation GmbH IXXAT Inc.
Leibnizstr. 15 120 Bedford Center Road
D-88250 Weingarten USA-Bedford, NH 03110
Tel.: +49 (0)7 51 / 5 61 46-0 Phone: [phone]
Fax: +49 (0)7 51 / 5 61 46-29 Fax: [phone]
Internet: www.ixxat.de Internet: www.ixxat.com
e-Mail: [email protected] e-Mail: [email protected]
Support
In case of unsolvable problems with this product or other IXXAT products
please contact IXXAT in written form by:
Fax: +49 (0)7 51 / 5 61 46-29
e-Mail: [email protected]
For customers from the USA/Canada
Fax: [phone]
e-Mail: [email protected]
Cop
y
right
Duplication (copying, printing, microfilm or other forms) and the electronic
distribution of this document is only allowed with explicit permission of
IXXAT Automation GmbH. IXXAT Automation GmbH reserves the right to
change technical data without prior announcement. The general business
conditions and the regulations of the license agreement do apply. All rights
are reserved.
Document number: 4.02.0249.20001
Version: 1.13

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Contents
3
1INTRODUCTION............................................................................7
2OVERVIEW ...................................................................................8
3FUNCTIONAL DESCRIPTION ........................................................10
3.1 Communication ..................................................................10
3.2 Behavior of the receive-side FIFO .......................................10
3.2.1 Events ....................................................................................... 10
3.2.2 Overruns ................................................................................... 10
3.3 Behavior of the transmit-side FIFO .....................................10
3.3.1 Events ....................................................................................... 10
3.4 Timestamps of the receive messages .................................11
3.5 Reception of invalid messages ...........................................11
3.6 Reception of NULL frames ..................................................11
3.7 Status information .............................................................11
4CONTROLLER STATES .................................................................12
4.1 Status diagram FlexRay controller......................................12
4.1.1 Remark to the running state ...................................................... 13
5EXTERNAL INTERFACES ..............................................................14
5.1 SW interfaces......................................................................14
5.1.1 Exported functions .................................................................... 14
5.1.1.1 UCI_CreateInstance...................................................... 14
5.1.1.2 FormatError ................................................................. 18
5.1.2 IUciBoard3 ................................................................................ 18
5.1.2.1 GetInfo ........................................................................ 18
5.1.2.2 OpenController............................................................ 19
5.1.2.3 Test ............................................................................. 19
5.1.2.4 Download.................................................................... 20
5.1.2.5 ResetTimestamp........................................................... 20
5.1.2.6 GetSystemTime............................................................ 20
5.1.2.7 FormatError ................................................................. 21
5.1.3 IUciBoardPowerSave .................................................................. 21
5.1.3.1 SetTimeOut.................................................................. 21
5.1.3.2 GetTimeOut................................................................. 22
5.1.3.3 FormatError ................................................................. 22
5.1.4 IUciFlxCtrl .................................................................................. 22

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Contents
4
5.1.4.1 GetInfo........................................................................ 22
5.1.4.2 GetStatus .................................................................... 23
5.1.4.3 Init .............................................................................. 24
5.1.4.4 GetRxEventHandle ....................................................... 25
5.1.4.5 GetTxEventHandle ....................................................... 26
5.1.4.6 Start ............................................................................ 26
5.1.4.7 GetMsg ....................................................................... 26
5.1.4.8 GetTxMsgInfoCount..................................................... 28
5.1.4.9 GetTxMsgInfo.............................................................. 28
5.1.4.10 SendMsg ..................................................................... 29
5.1.4.11 Stop ............................................................................ 31
5.1.4.12 Reset ........................................................................... 32
5.1.4.13 Lock............................................................................. 32
5.1.4.14 Unlock......................................................................... 32
5.1.4.15 FormatError ................................................................. 33
5.1.5 IUciFlxMsgTrigger ...................................................................... 33
5.1.5.1 GetOutTriggerCount .................................................... 33
5.1.5.2 SetOutTrigger .............................................................. 33
5.1.5.3 ResetOutTrigger........................................................... 34
5.1.5.4 GetOutTrigger ............................................................. 34
5.1.5.5 GetInTriggerCount....................................................... 35
5.1.5.6 SetInTrigger ................................................................. 35
5.1.5.7 ResetInTrigger.............................................................. 36
5.1.5.8 GetInTrigger ................................................................ 36
5.1.5.9 Lock............................................................................. 36
5.1.5.10 Unlock......................................................................... 37
5.1.5.11 FormatError ................................................................. 37
5.1.6 Data types and structures .......................................................... 37
5.1.6.1 UCI_BOARDINFO ......................................................... 37
5.1.6.2 UCI_FLXINFO ............................................................... 39
5.1.6.3 UCI_FLXSTATUS........................................................... 42
5.1.6.4 UCI_FLXMSG ............................................................... 44
5.1.6.5 UCI_FLXSTATUSMSG ................................................... 45
5.1.6.6 UCI_FLXDATAMSG ...................................................... 48
5.1.6.7 UCI_FLXCONTROLMSG ................................................ 50
5.1.6.8 UCI_FLXCTRMSG_TXBUFFER ........................................ 51
5.1.6.9 UCI_FLXTXMSGINFO.................................................... 52

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Contents
5
5.1.6.10 UCI_FLXMSGOUTTRIGGER ........................................... 55
5.1.6.11 UCI_FLXMSGINTRIGGER............................................... 56
6ANNEX .......................................................................................57
6.1 Overview of the registers from Motorola / Freescale .........57
6.1.1 UCI_ FLXDATAMSG ................................................................... 57
6.1.2 UCI_ FLXSTATUSMSG ................................................................ 60
6.1.3 Status flags................................................................................ 60
6.1.4 Controller states version 9.0 (MFR4200) .................................... 61
6.1.5 Controller states version 10.x (MFR43x0) ................................... 61
6.2 Registration Functions (XATxxReg.DLL) ..............................62
6.2.1 Type Definitions of the Call-back Handler................................... 62
6.2.1.1 Call-back to list the registered PC/CAN-interfaces ......... 62
6.2.2 Function Definitions................................................................... 63
6.2.2.1 XAT_SelectHardware ................................................... 63
6.2.2.2 XAT_GetConfig............................................................ 64
6.2.2.3 XAT_EnumHWEntry..................................................... 65
6.2.2.4 XAT_FindHWEntry ....................................................... 66
6.2.2.5 XAT_SetDefaultHwEntry............................................... 69
6.2.2.6 XAT_GetDefaultHwEntry.............................................. 70
6.2.2.7 XAT_BoardCFG ............................................................ 70
6.2.2.8 HRESULT errorcodes..................................................... 71

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Introduction
7
1Introduction
The Virtual CAN Interfaces (VCI) is a powerful software package for the IXXAT
PC/CAN interfaces. It was designed for software developers who wish to develop
high-quality, hardware-independent CAN applications for the PC.
The Universal Controller Interface (UCI) is connected to a VCI-internal software
layer and offers a narrower and slightly faster programming interface than the
VCI. The UCI dispenses with multiple transmit and receive queues, as well as the
receive and remote buffers of the VCI API. One receive and one transmit queue of
fixed, hardware-dependent size is available per CAN and per FlexRay controller.
The UCI is also independent of the used hardware and is available for all IXXAT
interfaces supported by the VCI V2, in the following also referred to as boards.
No additional software installation is necessary in order to use UCI. After instal-
ling the VCI V2 and the VCI FlexRay Device Add-on, it is also possible to program
on the basis of UCI with the aid of additional header files.
Several instances of the UCI can be used in parallel, however only on different
boards and not simultaneously on the same board. The same applies to several
instances of the VCI and to UCI/VCI in parallel.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Overview
8
2Overview
The IXXAT FlexRay interface has one or more FlexRay bus connections. Communi-
cation between the IXXAT FlexRay interface and the PC occurs via receive and
transmit FIFOs.
The programming interface of the IXXAT FlexRay interface board described in this
document is based on COM technology. The board itself and the FlexRay control-
lers are thus represented by COM objects.
Fig. 2-1: PC FlexRay interface and programming interface
IXXAT FlexRay
Interface
FIFOs
Driver
Programming interface
Board
IUciBoard
IUciFlexRayCtrl
FlexRay
PC
MC
FlexRay
Controller
FlexRay
Controller
FlexRay
Rx FIFO
FlexRay
Tx FIFO

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Overview
9
The user first creates an instance of the UCI, which is equivalent to opening the
board. For this he calls the function UCI_CreateInstance()
exported from the
UCI. This function returns a pointer to the COM interface IUciBoard.
Via IUciBoard specific information on the IXXAT FlexRay interface can be called
up and controllers selectively opened. In turn, by opening a controller, a pointer
to the relevant controller COM interface is requested.
IUciFlxCtrl provides the access to the FlexRay controller. The controller is initia-
lized with certain operating modes and the hardware-specific communication
parameters are set. Furthermore, accesses to receive or transmit streams and en-
quiries of controller and bus states are carried out via the controller interface.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Functional description
10
3Functional description
3.1 Communication
The FlexRay messages are transferred via receive (RX) and transmit (TX) FIFOS. The
FIFOS are implemented in the PC and/or on the interface.
3.2 Behavior of the receive-side FIFO
3.2.1 Events
The UCI can be used event-triggered, i.e. the user program is able to wait for a
controller event. To retrieve this event handle the method GetRxEventHandle() has
to be called. If at least one message is available the RX event is set in the UCI and
in case of WaitForSingleObject() the function returns WAIT_OBJECT_0. After the
event is signaled at least one FlexRay message can be read with GetMsg() from
the RX FIFO.
3.2.2 Overruns
If a receive FIFO is not read out quickly enough, it may overrun and no further
messages can be entered. One of the message lost flags in the FlexRay status
message then tells you that an overrun has occurred before this status message.
You can also call the GetStatus() function to get the information if an overrun has
occurred at all.
3.3 Behavior of the transmit-side FIFO
3.3.1 Events
The UCI can be used event-triggered, i.e. the user program is able to wait for a
controller event. To retrieve this event handle the method GetTxEventHandle() has
to be called. Every time when a TX message was successfully transmitted a TX
event is signaled.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Functional description
11
3.4 Timestamps of the receive messages
Every message can have a 64-bit timestamp with a resolution of 100ns. The exact
timestamp of every FlexRay message can be calculated within the UCI and de-
pends on the settings made with the call of Init(). You can choose one of the
following types:
•Timestamp disable: No Timestamp available.
•Timestamp cycle: Each message from one cycle has the same time
stamp (timestamp of status message).
•Timestamp message: The timestamp of each message is calculated individual-
ly, taking the timestamp of the status message.
3.5 Reception of invalid messages
If desired, it is possible to receive invalid frames via the asynchronous receiver.
Therefore the Flag “Invalid Frames Enable” has to be set while calling Init() of the
FlexRay controller.
3.6 Reception of NULL frames
If desired, it is possible to disable the reception of NULL frames via the asyn-
chronous receiver. Therefore the Flag “NULL Frames Disable” has to be set while
calling Init() of the FlexRay controller.
3.7 Status information
Every FlexRay status message contains status information of the FlexRay control-
ler. You have access to following information:
•Controller clock correction
•Controller status (startup, normal, passive)
•Error flags
•Slot status counter (often used to count NULL frames)

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Controller states
12
4Controller states
4.1 Status diagram FlexRay controller
After a FlexRay controller interface has been requested for the first time, the con-
troller is in an un-initialized "open" status.
The operating mode is configured via Init(). The controller is in the "init/stopped"
status. To put the controller in "running" status call Start().In this status FlexRay
messages can be received and retrieved via GetMsg(). To get back in "in-
it/stopped" status call Stop(). In this status messages still available can be read
out of the receive FIFO.
Fig. 4-1: Status diagram FlexRay controller
The methods FormatError(), GetInfo() and GetStatus() can be called from any
state.
Reset( ) open
init/stopped
running
Stop( )
GetMsg() / SendMsg()
Stop()
Reset()
Init( )
GetMsg()
Start()
Reset()
Allowed functions:
Start( )
Init()
Reset()
GetRxEventHandle(), GetTxEventHandle()

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
Controller states
13
4.1.1 Remark to the running state
The “running” state includes the three states of the FlexRay controller itself. It can
be one of the following states:
•running startup: The FlexRay controller tries to integrate to or startup
a FlexRay network. If the controller is successful the
state switches itself to „running normal active“
without any user act. If the asynchronous receiver is
available the startup can be monitored.
•running normal active: The network is running, the FlexRay controllers are
synchronised. Reception and tranmission via the
communication controller is possible. On systems
with an MFR4200 communication controller the
asynchronous receiver is disabled meanwhile if
available. On systems with one or more MFR43x0
communication controller, the asynchronous
receiver can be enabled to receive NULL frames. If
the reception of invalid frames is enabled on this
system, invalid frames can be monitored, too.
•running normal passive: The FlexRay controller has lost the synchro-nisation
to the FlexRay network. The controller has to be
stopped and started again to regain the state of
„running normal active“. If the asynchronous
receiver is available FlexRay messages and NULL
frames (if enabled) of the other FlexRay nodes can
be monitored.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
14
5External interfaces
5.1 SW interfaces
5.1.1 Exported functions
5.1.1.1 UCI_CreateInstance
UCI_CreateInstance() creates a UCI instance for a board based on a board key.
This may include loading of firmware, setting up communication and resetting
the controllers. After successful creation of a UCI instance, UCI_Create-
Instance() returns a pointer to an IUciBoard interface.
The board key and the string with the additional, board-specific parameters are
provided equivalent to the VCI V2 programming interface via the board selection
dialog, the request of the standard interface, enumeration of the installed inter-
face or the search for a certain interface. For this, please read the description of
the functions XAT_SelectHardware(), XAT_GetDefaultHwEntry(),
XAT_EnumHWEntry() and XAT_FindHwEntry() taken from the VCI V2 pro-
gramming manual (see Annex section 6.2).
As different UCI DLLs have to be loaded for the different types of IXXAT PC inter-
faces, it is recommended to load these dynamically (see example on next page).
Prototype:
HRESULT WINAPI UCI_CreateInstance( DWORD dwKey,
PCHAR pStr,
LPUCIBOARD* ppBrd );
Parameters:
dwKey IN Board key
pStr IN
1) Pointer to zero-terminated string with additional, board-specific
parameters. The string is not necessary to run the device but the
user may provide following tags to control the behavior:
•URL://<IP or name>// *1)
•DISABLEPOPUP://<value>//
<value> is either “TRUE” or “FALSE” and controls the be-
havior of the UCI’s dialog windows. The value “TRUE” for-
bids the UCI to open any dialog window. This includes the
IP-Configuration, TX time budget overrun the heart beat
timeout dialog windows.
<IP or name> is equal to the numeric IP address or the
DNS name of the device to connect to.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
15
•ENABLE_HEARTBEAT://<value>// *1)
•DISABLE_HEARTBEAT_TIMEOUT_DIALOG://<value>//
<value> is either “TRUE” or “FALSE” and controls the be-
havior of the heart beat mechanism. The value “TRUE”
enables the line interruption recognition between the UCI
and the FlexRay device hardware.
*1)
•FORBID_LANMC_ADDON://<value>//
<value> is either “TRUE” or “FALSE” ” and controls the
behavior of the UCI’s heart beat timeout dialog window.
The value “TRUE” forbids the UCI to open the heart beat
timeout dialog window.
*1)
•DISABLE_AUTO_IRQTIME_SETTING://<value>//
<value> is either “TRUE” or “FALSE” and specifies if LAN
MC add-on modules and changes of the default settings
are allowed on the FlexRay device. The value “TRUE” for-
bids those modules and modified settings. If modules are
found or settings were changed while the value is “TRUE”
UciCreateInstance returns with the error code “ERROR_
DEVICE_REQUIRES_CLEANING”. The user than has to dis-
able or remove all LAN MC add-on modules and ensure
the default settings are not changed on the FlexRay de-
vice.
*1)
•IGNORE_TXBUFFER_TIMEBUDGET_WARNING://<value>//
<value> is either “TRUE” or “FALSE” ” and controls the
behavior of the TX buffer time budget overrun warning.
This flag is only evaluated if pop-up windows are disabled.
In this case setting this switch to TRUE ignores a TX buffer
time budget warning and proceeds initializing the FlexRay
controller without returning the error code
“RPC_S_OUT_OF_RESOURCES”.
<value> is either “TRUE” or “FALSE” ” and controls the
behavior of the automatic IRQ time setting for reception
of FlexRay messages. The value “TRUE” forbids the auto-
matic adjustment of the IRQ time and keeps the currently
configured value on the FlexRay device. The value “FALSE”
instead allows the UCI to calculate the IRQ time and to
overwrite it even if it was already lower than the new cal-
culated value! The default IRQ of 2500 µs is decrement
until it is lower by 50 µs than the configured FlexRay cycle
time in 500 µs steps. The lowest possible value is 500 µs,
so the smallest possible FlexRay cycle is 550 µs.

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
16
Note:
Problems while sending may occur without any
warning, if this switch is set to TRUE!
e.g. “
URL://169.254.200.1//DISABLEPOPUP://TRUE//
”
If not all values are given via pStr the UCI tries to extract the
missing values from the windows registry’s DEV_DATA section. If
the
URL
is still not found the user is prompted, by open
ing the
IP-Configuration dialog window, to select the device, if pop-ups
are allowed . The other values are set to default as follows:
•DISABLEPOPUP://FALSE//
•ENABLE_HEARTBEAT://FALSE//
•DISABLE_HEARTBEAT_TIMEOUT_DIALOG://FALSE//
*1)
•FORBID_LANMC_ADDON://FALSE//
*1)
•DISABLE_AUTO_IRQTIME_SETTING://FALSE//
*1)
•IGNORE_TXBUFFER_TIMEBUDGET_WARNING://FALSE//
*1)
ppBrd IN Pointer to reserved memory for return of interface pointer, where
ppBrd must not be set to ZERO.
ppBrd OUT Pointer to the IUciBoard interface of the created UCI instance.
Return value: UCI error codes
For detailed information about UCI error codes please take a look in the UCIerr.h
file.
The options and settings available for pStr marked with *1)
•FlexRay CCM
only apply to following
FlexRay devices:
•FlexRay CCM-E
•FRC-EP150
•ES520
•EDIC flex
All other options and settings available for pStr also apply to following FlexRay
device:
•FR-IB100

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
17
Example:
// definition of function pointer to UCI_CreateInstance
typedef HRESULT (WINAPI *PF_UCICREATE )( UINT32
, PCHAR
, LPUCIBOARD* );
XAT_BoardCFG sConfig;
DWORD dwTmp;
HRESULT hr = S_OK;
HMODULE hUci = 0;
PF_UCICREATE pfUciCreate = 0;
LPUCIBOARD pBoard = 0;
char szUCIDLL[32] = {0};
// open select hardware dialog
hr = XAT_SelectHardware( hwndParent
, &sConfig );
if ( 1 == hr )
{
// get name of UCI DLL for this board
hr = XAT_GetHwEntryVar( sConfig.board_no
, "UCI_DLL"
, szUCIDLL
, &dwTmp );
if ( S_OK == hr )
{
// load UCI library
hUci = LoadLibrary( szUCIDLL );
if ( NULL != hUci )
{
// get pointer to UCI_CreateInstance
pfUciCreate = (PF_UCICREATE)GetProcAddress( hUci
, "UCI_CreateInstance"
);
if ( NULL != pfUciCreate )
{
// create UCI instance
hr = pfUciCreate( sConfig.board_no
, sConfig.sz_CardAddString
, &pBoard );
if ( UCI_OK == hr )
{
// open FlexRay controller and proceed FlexRay communication
...
pBoard->Release();
pBoard = NULL;
}
}
}
}
}

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
18
5.1.1.2 FormatError
If UCI_CreateInstance() returns an error, an error description can be requested
via the function FormatError(). This is a zero-terminated string with max.
UCI_MAX_ERRSTR characters. For this, sufficient memory must be reserved via the
parameter pszError.
Prototype:
HRESULT WINAPI FormatError ( HRESULT hrError,
PCHAR pszError );
Parameters:
hrError IN UCI error code.
pszError IN Pointer to sufficient memory for receiving an error string.
pszError OUT Pointer to the error description.
Return value: UCI error codes
5.1.2 IUciBoard3
IUciBoard3 includes all methods form IUciBoard and IUciBoard2. In addition to
the methods of IUciBoard2 it provides the GetSystemTime() method.
5.1.2.1 GetInfo
Reading of board information via the UCI_BOARDINFO such as:
•version numbers
•number of CAN controllers supported
•number of byteflight controllers supported
•number of FlexRay controllers supported
Prototype:
virtual HRESULT __stdcall GetInfo ( LPUCI_BOARDINFO pInfo );
Parameter:
pInfo OUT Pointer to a structure UCI_BOARDINFO for the response data.
Return value: UCI error codes

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
19
5.1.2.2 OpenController
The OpenController() method enables access to a controller of the board by
returning a pointer to its COM interface.
Prototype:
virtual HRESULT __stdcall OpenController( REFIID rIID,
UINT8 bCtrlNo,
LPVOID *ppCtrl );
Parameters:
rIID IN GUID of the interface to be requested.
Opening of a CAN controller: __uuidof(IUciCanCtrl)
Opening of a byteflight controller: __uuidof(IUciBftCtrl)
Opening of a FlexRay controller: __uuidof(IUciFlxCtrl)
bCtrlNo IN Number of the requested controller (0..n).
ppCtrl IN Pointer to reserved memory for return of the interface pointer,
where ppCtrl must not be ZERO.
ppCtrl OUT Pointer to the interface requested under rIID.
Return value: UCI error codes
5.1.2.3 Test
Via this method a test is carried out via access to the board.
Prototype:
virtual HRESULT __stdcall Test( void );
Parameters: none
Return value: UCI error codes

Copyright IXXAT Automation GmbH
UCI Programming Manual FlexRay, V1.13
External interfaces
20
5.1.2.4 Download
Via the Download() method the controller firmware can be downloaded onto
the board. The file containing the firmware is defined via pszFilename.
Prototype:
virtual HRESULT __stdcall Download( PCHAR pszFilename );
Parameter:
pszFilename IN Name of the Hex-file.
Return value: UCI error codes
Remark:
The download function is only available for selected hardware. This function does
not apply to the IXXAT FlexRay interfaces and is therefore not implemented.
5.1.2.5 ResetTimestamp
Via the ResetTimestamp() method the timer of the board can be set to zero.
This function is not effective if external timers are used (e.g. ES600 for some-
IXXAT FlexRay interfaces like ES520).
Prototype:
virtual HRESULT __stdcall ResetTimestamp (DWORD dwReserved );
Parameter:
dwReserved IN Reserved for future used.
Return value: UCI error codes
5.1.2.6 GetSystemTime
Via the GetSystemTime() method the timer of the board can be read out asyn-
chronously to the reception of any type of messages. The timer value is returned
with 100ns resolution via the unsigned 64 bit pointer pqwSystemTime.
Prototype:
virtual HRESULT __stdcall GetSystemTime (PUINT64 pqwSystemTime);
Parameter:
pqwSystemTime OUT Timer value of the board with 100ns resolution
Return value: UCI error codes