D pduapi user-manual

D-PDU API Software for Vehicle Communication Interfaces

User Manual Version 3.6, June 2013

SOFTING Automotive Electronics GmbH Richard-Reitzner-Allee 6 85540 Haar, Germany

Tel: +49 (0) 89 4 56 56 - 420 Fax: +49 (0) 89 4 56 56 - 399 [email protected]

www.softing.com

mailto:[email protected]

© 2013 SOFTING Automotive Electronics GmbH

No part of these instructions may be reproduced (printed material, photocopies, microfilm or other method) or processed, copied or distributed using electronic systems in any form whatsoever without prior written permission by SOFTING Automotive Electronics GmbH. Any violations will lead to compensation claims.

All rights reserved, in particular in the event that a patent is granted or that a utility model or a design is registered.

The producer reserves the right to make changes to the scope of supply as well as changes to technical data, even without prior notice.

Careful attention was given to the quality and functional integrity in designing, manufacturing and testing the system. However, no liability can be assumed for potential errors or for their effects, especially in terms of suitability of the system for a specific application. Should you find errors, please inform your distributor of the nature of these errors and the circumstances under which they occur. We will be responsive to all reasonable ideas and will follow up on them, taking measures to improve the product, if necessary.

All rights reserved.

Contents

Preface I

Disclaimer II

1 1 Introduction1.1 1 Modular vehicle communication interface concept and D-PDU API1.2 4 D-PDU API products from Softing1.2.1 4 D-PDU API software for vehicle communication interfaces

1.2.2 5 Diagnostic Tool Set with D-PDU API support

1.3 6 Documentation1.3.1 6 Related standards

1.3.2 6 Further documents

2 7 System requirements2.1 7 Hardware2.2 7 Software2.3 8 Licensing

3 9 Scope of delivery3.1 9 System components3.2 9 Configuration files3.3 9 Applications

4 10 Installation4.1 10 Software installation4.2 10 Hardware installation4.3 10 Test your installation

5 11 Uninstall

6 12 Integration of the D-PDU API6.1 12 General information6.2 13 D-PDU API system topologies6.3 15 D-PDU API functionality6.3.1 16 ComLogicalLinks

6.3.2 17 Communication protocols

6.3.3 18 ComParameters

6.3.4 19 ComPrimitives

6.4 20 D-PDU API tool integration

6.5 21 D-PDU API migration support

7 22 API reference7.1 22 API functions7.1.1 22 Overview

7.1.2 23 General usage

7.1.3 28 Details

7.2 81 IOCTL commands7.2.1 81 Overview

7.2.2 82 Details

7.3 99 Data types and structures7.4 99 Limitations

8 101 ComParameter reference

9 102 Demo and test application9.1 102 Demo application9.2 103 Interactive test application

10 112 D-PDU API Configuration Manager

11 114 D-PDU API Demonstrator

12 115 Appendix12.1 115 Error codes12.2 116 Troubleshooting12.3 117 Trace mechanism12.4 117 Support and maintenance12.5 118 Additional services12.6 118 RDF file

13 119 References and Index13.1 119 References13.2 120 Index of figures13.3 121 Index of tables

Preface

This documentation provides essential information on the D-PDU API software for vehicle communication interfaces from Softing. The following chapters cover:

• Short introduction to the MVCI concept and the D-PDU API

• System requirements and installation procedure

• Description of demo- and test applications

• Reference of D-PDU API functions, elements and ComParameters

• Reference of related documents

Preface I

Disclaimer

Warning!

Using this product can be dangerous. Please use it with care.

This software allows you to control and influence electronic communication systems in a vehicle. Thus your actions and applications can cause severe personal damages or damages to property. Therefore only persons may use this software

who have completely understood the possible consequences of their actions with this software or

who have been trained especially to use this software

Particularly using this software in a moving vehicle is only permitted for especially trained persons.

In case of other persons using this software, Softing Automotive Electronics GmbH hereby expressly gives notice that Softing’s warranty shall be limited to the correction of defects, and Softing Automotive Electronics GmbH hereby expressly disclaims any liability over and above the refunding of the price paid for this software.

Disclaimer II

1 Introduction

1.1 Modular vehicle communication interface concept and D-PDU API

The Modular vehicle communication interface (MVCI) project was initiated by several OEMs in 2001. The main objective is to achieve exchangeability of components in vehicle communication systems and thus have the ability to optimize systems in terms of functionality and costs.

The main use cases seen in the MVCI project are:

OEM-mergers

OEM cross vehicle platform ECUs

General applications with ODX (e.g. service testers, etc.)

OEM franchised dealer and aftermarket service outlet diagnostic tools

The MVCI concept defines general requirements for VCI hardware, API software and diagnostic MCD 3D server applications. To allow exchangeability of vehicle interfaces three compliance levels are defined (software compliance, electrical compliance and mechanical compliance).

After some preparatory work in small working groups the official standardization work in ISO started in 2004. The standardization activities are lead by task forces of ISO TC22 SC3 WG1. Since the MVCI standard is deeply related to ODX the standardization work of both standards was executed in joint activities in parallel with a close cooperation between ASAM and ISO. Below the task forces and ISO standard documents are listed:

ISO TC22 SC3 WG1 TF10: MVCI – ISO 22900

o ISO 22900-1 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 1: Hardware design requirements

o ISO 22900-2 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 2: D-PDU API (Diagnostic Protocol Data Unit Application Programmer Interface)

o ISO 22900-3 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 3: Server API (Application Programmer Interface)

ISO TC22 SC3 WG1 TF11: ODX – ISO 22901

o ISO 22901-1 (DIS) Road vehicles - Open diagnostic data exchange (ODX) - Part 1: Data model specification

Softing actively contributes to MVCI and ODX standardization since 2002.

1

In Figure 1 the structure of a MVCI system is depicted. It shows the system components and corresponding ISO standards.

Figure 1: MVCI system structure

In MVCI systems ODX data files are a central element (see Figure 2). They are initially created during engineering and hold information of diagnostic protocols and diagnostic data. During further steps along the process chain, like manufacturing, the ODX data are reused and extended by additional information. The single source principle allows data reuse for service applications and provides a direct and cost efficient feedback mechanism for all applications along the process chain.

2

Figure 2: Data exchange in MVCI systems

The open generic approach of MVCI sets no limits concerning applications, protocols or VCI capabilities. The D-PDU API (application programmer’s interface) provides a flexible generic API to vehicle communication interfaces with benefits as follows:

D-PDU API allows scalable systems with multiple VCIs, even from different suppliers

Standardized tool integration with one D-PDU API DLL per VCI supplier

No limitations and restrictions concerning protocol support

Usage directly by applications or in combination with D-server

Standardized communication parameters for standard protocols, defined for usage with ODX files

API specification allows high performance multilink applications

Flexibility for tool supplier and OEM

3

1.2 D-PDU API products from Softing

Since Softing actively contributes to D-PDU API, MVCI and ODX standardization work in ASAM and ISO for many years, Softing is able to offer a comprehensive D-PDU API product portfolio for DTS tools, EDIC, CAN and third-party hardware interfaces. Additional supplements, complementary products and services for complete MVCI solutions can be provided as well.

Figure 3 gives an overview about available D-PDU API products and solutions.

Figure 3: D-PDU API products and solutions from Softing

1.2.1 D-PDU API software for vehicle communication interfaces

The D-PDU API software for vehicle interfaces is available for EDIC and CAN interfaces from Softing. For third-party interfaces the Softing D-PDU API is also available on request. Supported protocols see chapter 6.3.2.

4

D-PDU API for EDIC vehicle interfaces from Softing

The D-PDU API software is available for the vehicle interfaces EDICcard2, EDICusb, EDICblue, EDICwlan and EDICpci.

Unlike other vehicle interfaces, the protocol stack is realized as embedded software with all EDIC interfaces. Reliable real-time behavior is ensured as the stack is executed directly on the interface hardware – independent of the PC.

D-PDU API for CAN vehicle interfaces from Softing

The D-PDU API software is available for the CAN interfaces CANcard2, CAN-AC2, CAN-PRO2-PCIE and CANusb. The protocol stack for CAN vehicle interfaces is part of the D-PDU API PC software. The available protocol performance is dependent on the system resources like processor performance or memory available for the protocol stack software.

D-PDU API software for third-party vehicle interfaces

Vehicle interfaces from third parties with a proprietary interface can be equipped with D-PDU API software on request. This means that existing interfaces can be integrated into new applications with a D-PDU API interface.

1.2.2 Diagnostic Tool Set with D-PDU API support

All DTS V7 products (with the Version 7.65 or higher) support Softing EDIC and CAN vehicle interfaces as well as some third-party vehicle interfaces with the Softing D-PDU API. The relevant protocol support depends on the interface being used.

5

6

1.3 Documentation

This document includes a description of system requirements, the scope of delivery and installation aspects. In addition it describes Softing specific addons, like demo code and the test application. The documentation gives a short overview about MVCI and the D-PDU API. It roughly explains the principles and functionality of the D-PDU API and contains information to the Softing specific implementation.

Therefore the availability or knowledge of the ISO specification is expected as precondition. The related ISO documentation is listed in chapter 1.3.1.

1.3.1 Related standards

Since MVCI and D-PDU API are standardized by ISO, the corresponding ISO standards are required in addition to this documentation to use the D-PDU API software. Below the related standard documents are listed. For a complete reference list, please see chapter 13.1.

/2/ ISO 22900-2 (DIS): specifies the complete D-PDU API, including API functions, data structures, parameters, sequence charts etc. This document is required for programming own applications or integrating MVCI system components. The document can be purchased at www.iso.org. Draft document versions are available to ISO standardization core team members only.

Note: The current implementation is based on the ISO 22900-2 specification V2.2.0.

/3/ ISO 22900-3 (DIS): specifies the D-Server API. This document is required for application programmers or integrators of diagnostic applications, which use 3D-servers. For pure D-PDU API applications this document is not required.

/4/ ISO 22901-1 (DIS): specifies the ODX data model. This document is required for users creating and maintaining ODX databases. For D-PDU API applications without ODX use this document is not required.

1.3.2 Further documents

In addition to this documentation the following files of the software distribution can be used for further information:

File name Description <InstDir>\DOC\Documentation_PDU-API_.....pdf

Protocol specific documentations

PDUAPI_Demonstrator\ PDU_API.H

Headerfile for D-PDU API applications with data types, structures and error codes

PDUAPI_Demonstrator\ PDUAPI_WRAPPER.H

Headerfile for D-PDU API applications with API function prototypes

VECOM\ MDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml

MDF file for D-PDU API applications (x,yy,zzz replaced by current version number)

VECOM\ CDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml

CDF file for D-PDU API applications (x,yy,zzz replaced by current version number)

Table 1: Software distribution documents

http://www.iso.org/

2 System requirements

2.1 Hardware

To use the D-PDU API software a PC and at least one of the supported vehicle communication interfaces is required. The specific hardware requirements are listed below:

A standard PC, capable to run Windows XP (32 Bit) or Windows 7 (32 Bit or 64 Bit)

At least one of the supported vehicle communication interfaces:

o Softing EDICcard2, EDICpci, EDICusb, EDICblue, EDICwlan

o Softing CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE, CANusb

2.2 Software

To use the D-PDU API software on a PC the following software requirements exist:

PC operating system: Windows XP with SP2 (at least), Windows 7 (32 Bit or 64 Bit)

For programming of own D-PDU API applications the following development tools are required:

o Microsoft Visual Studio 2005 or later (to use the enclosed D-PDU API Demonstrator source code)

Or

o Microsoft Visual Studio 6.0 (without using the enclosed D-PDU API Demonstrator source code)

Notes: The MS Visual Studio project of the enclosed D-PDU API Demonstrator code requires Visual Studio 2005!

7

8

2.3 Licensing

The D-PDU API software is licensed per vehicle communication interface:

License bound to VCI serial number

Available for Softing VCIs EDICcard2, EDICpci, EDICusb, EDICblue, EDICwlan, CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE and CANusb

Table 2: Licensing model

Notes:

The license check is executed during the API function call PDUCreateComLogicalLink. In case of a missing license the function will report an error code PDU_ERR_FUNCTION_FAILED plus a special value as ComLogicalLink handle. For details please see chapter 7.1.3.18.

3 Scope of delivery

3.1 System components

The D-PDU API software is delivered together with EDIC vehicle communication interfaces from Softing. For CAN vehicle communication interfaces the D-PDU API is available as well.

The D-PDU API software’s scope of delivery contains the following:

D-PDU API software on CD including:

o Setup program

o Configuration files (root file, MDF, CDF) [installed by setup]

o Demo application in source code [installed by setup]

o Interactive test application [installed by setup]

Installation notes

Protocol Documentation

During the installation process the software is installed and registry entries are made according to the ISO 22900-2 specification. After installation the Softing specific D-PDU API DLL “PDUAPI_SoftingAG_x.yy.zzz.dll” (with “x.yy.zzz” for version number) is available on the system. For details, please see chapter 4.1.

3.2 Configuration files

The installation process installs a root file according to the ISO 22900-2 – 9.7.2.1 specification or modifies an existing one (if available). In addition an module description file “MDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml” and cable description file “CDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml” are installed, which carry module and cable information for the Softing D-PDU API software distribution. The files have entries according to the current support of interface hardware and functionality (for details see chapters 2.1, 7 and 8).

3.3 Applications

To effectively support the user in developing his own applications using the D-PDU API or using D-PDU API applications two applications are enclosed in the D-PDU API software distribution:

Small demo application with source code to support the user to develop a custom application.

Interactive test application with graphical user interface to easily test the behaviour of the D-PDU API software or to make the first steps without programming.

For details concerning these applications please see chapter 9.

9

4 Installation

To use the D-PDU API software with a vehicle communication interface the D-PDU API software has to be installed before installation of the VCI hardware. Thereafter the installation can be tested.

4.1 Software installation

For EDIC vehicle communication interfaces from Softing the operating software is distributed as part of the D-PDU API software package.

Please make sure to install the software before the hardware is connected to or integrated in your system.

If no EDIC driver is available on your system the EDIC driver installation will be executed by default. Please select the EDIC type to be used with the D-PDU API software. In case that other VCI types than EDIC shall be used, please select any EDIC type as default (e.g. EDICcard2) and proceed with the setup process.

If Softing CAN hardware interfaces shall be used with D-PDU API software, please install the CAN drivers with the CAN-L2-API from your CAN installation disk delivered with your hardware. As an alternative the drivers are also available from the Softing web site www.softing.com.

If 3rd party hardware interfaces shall be used with the D-PDU API software, please install the drivers supplied by the hardware vendor.

During the installation process of the D-PDU API software for VCIs the software is installed and registry entries are made according to the ISO 22900-2 – 9.7.2.1 specification.

4.2 Hardware installation

After installation of the D-PDU API software and required driver software the VCI hardware has to be installed or integrated in the system. For details concerning hardware installation please see the hardware specific user manual supplied with the VCI hardware.

4.3 Test your installation

To test your installation the D-PDU API demo or test application can be used. Please make sure, that the licensed VCI hardware is connected to your PC. For details concerning the test application please see chapter 9.

Note: In case of trouble a trace mechanism can be activated. For further details please see chapter 12.3.

10

http://www.softing.com/

11

5 Uninstall

To uninstall the D-PDU API software from your system please select the entry “Softing D-PDU API for VCIs\Uninstall”.

Please regard, that additional VCI driver software has to be uninstalled separately.

6 Integration of the D-PDU API

6.1 General information

The D-PDU API is an application programmer’s interface for vehicle communication interfaces. It provides an open, standardized API according to the ISO 22900-2 specification including standardized communication protocols and –parameters. They are such defined to be used with ODX files. This offers the advantage of easy data reuse in many applications. The protocol handling is completely covered by the D-PDU API software, which reduces the effort for application implementation and maintenance. The D-PDU API’s ability to run parallel communication on multiple links offers high flexibility and easy scalability of vehicle communication systems. The event driven application interface and powerful communication mechanisms are valuable for event driven and parallel communication with ECUs.

The following chapters will give a short overview about key concepts and features. For details please refer to the ISO specification [ISO 22900-2].

The D-PDU API functions and IOCTL commands are referenced in chapter 7.

12

6.2 D-PDU API system topologies

The D-PDU API allows setting up scalable systems with different system topologies. Each tool supplier provides one D-PDU API DLL for his VCIs. The DLL is loaded dynamically by the client application.

Figure 4: D-PDU API system with single VCI module

13

If multiple VCIs shall be used in the system two possibilities exist. If the VCIs are provided from the same tool supplier, the tool supplier’s D-PDU API DLL already loaded by the client application will support multiple VCIs.

Figure 5: D-PDU API system with multiple VCI modules from one tool supplier

If the VCIs are provided from different tool suppliers, multiple D-PDU API DLLs are dynamically loaded by the client application – one per tool supplier.

Figure 6: D-PDU API system multiple VCI modules from different tool suppliers

14

6.3 D-PDU API functionality

The D-PDU API uses ComLogicalLinks for the communication with ECUs. A ComLogicalLink is a logical connection for ECU communication via one physical communication bus of a VCI module. A ComLogicalLink is created via the D-PDU API function call PDUCreateComLogicalLink (see chapter 7.1.3.18), specifiying a fixed assignment of module, bus and communication protocol by arguments.

ComParameters (= communication parameters) control the VCI’s protocol processing and behaviour for the ComLogicalLink. For standardized communication protocols the ComParameters are defined in the D-PDU API specification [ISO 22900-2 –B.4].

ComPrimitives are used to send and receive data to or from the ECU, as well as for updating ComParamter values. ComPrimitives combine the send/receive data with control data and additional information like timestamp values. The behaviour of send/receive ComPrimitives can be controlled by the ComPrimitive control data. Thus complex communication patterns with single or cyclic communication can be realized easily and flexibly (e.g. send/receive, send only, receive only etc.). Depending on the vehicle bus system and communication protocol being used, one or multiple ComPrimitives may be active at a time per each ComLogicalLink. This behaviour is controlled internally by the D-PDU API software. These capabilities may be different in D-PDU API implementations of different vendors (e.g. max. number of active ComPrimitives for CAN Layer 2 communication).

The D-PDU API provides powerful mechanisms to bind result data to request data. Thus the complexitiy of vehicle communication is removed from the application, which significantly reduces the application programming effort.

The D-PDU API effectively supports event driven communication using callback functions. For simple applications polling can be used as alternative.

15

6.3.1 ComLogicalLinks

A ComLogicalLink selects a resource when it is created. A resource is the physical hardware, the external pin(s), and the protocol to be used with the resource. If a resource is shareable, then another ComLogicalLink can be created with the same resource. A ComLogicalLink can be configured for a single ECU (physical addressing) and for multiple ECUs (functional addressing.)

Figure 7: D-PDU API system with 3 ComLogicalLinks on 1 resource

16

6.3.2 Communication protocols

The D-PDU API supports several standardized communication protocols.

For each of the standardized communication protocols defined in the D-PDU API specification a unique protocol name is defined. Since many protocols are typically composed as a combination of up to 3 communication layers (i.e. reduced/combined ISO OSI layer scope) the relevant ComParameters are assigned to up to 3 layers. Thus an easy reuse of already defined parameters is possible for multiple protocols. This is valuable especially for defining protocol variants (e.g. UDS protocol on different physical or transport layers). The table below gives a short overview. For more details about these protocols see the ISO D-PDU API specification [ISO 22900-2 – B.1.3]. For customer specific protocols see documentation in folder (<InstDir>\DOC\).

Table 3: Standardized communication protocols

17

6.3.3 ComParameters

The D-PDU API ComParameters allow full abstraction of all protocol knowledge into the VCI module. The combination of the unique protocol name defined for the standardized protocols and the associated ComParameters uniquely define a ComLogicalLink to one or multiple ECUs.

The ComParameters are assigned to 3 layers for easy reuse and combination of already existing parameters (e.g. UDS on different physical or transport layer):

Physical layer

Transport / Data link layer

Application layer

An additional parameter class value (e.g. timing parameter, bus parameter, etc.) allows easy structuring, data modeling and tool access.

The table below gives an example of the documentation used in the D-PDU API specification (E=ECU, T=Tester, S=Standard, O=Optional). For more details, please refer to the ISO specification [ISO 22900-2 – B.10].

Table 4: Communication parameter table (example)

18

In addition to the parameter tables the ISO specification gives detailed explanations of each ComParameter including parameter name type, range, resolution and default values. An example is shown in the table below:

Table 5: Communication parameters (example)

6.3.4 ComPrimitives

ComPrimitives provide powerful and flexible mechanisms to send and receive data. They support binding of request and response data and carry additional information (e.g. timestamp). Complex communication patterns (e.g. periodic, send/receive only, response on event, etc.) are effectively supported by control data. The following D-PDU API ComPrimitive types are defined

• PDU_COPT_STARTCOMM

• PDU_COPT_STOPCOMM

• PDU_COPT_SENDRECV

• PDU_COPT_DELAY

• PDU_COPT_UPDATEPARAM

• PDU_COPT_RESTORE_PARAM

For further details please refer to the ISO specification [ISO 22900-2 – D.1.2].

19

6.4 D-PDU API tool integration

The integration of D-PDU API VCIs in applications is realized via standardized description files.

• A root file is used for system wide integration of D-PDU API DLLs from different suppliers. It is the main entry point for applications. During installation each vendor’s setup routine adds the information about the vendor’s D-PDU API software to the root file.

• A MDF.xml file (=module description file) is used for each VCI. It describes the VCI‘s capabilities. Each vendor delivers the MDF file together with his VCI module.

• A CDF.xml file (= cable description file) is used for the description of the cable connection between VCI and vehicle. It is delivered by the tool supplier or cable supplier.

For more information about the description files and the integration of the D-PDU API in an application see the D-PDU API specification [ISO 22900-2 – 9.3].

20

21

6.5 D-PDU API migration support

The D-PDU API is designed to allow migration and reuse of existing hardware and software components in D-PDU API systems. In this context J2534 and RP1210a functionality is supported by the D-PDU API. The mapping of J2534/RP1210a functions and error codes to D-PDU API functions, ComParameters and error codes is described in the D-PDU API specification [ISO 22900-2 - 10]. The adaption and integration work is realized by additional software layers, which have to be optionally implemented if required. The figure below shows an example system structure with migrated components:

Figure 8: D-PDU API migration system example

7 API reference

Below the D-PDU API functions, IOCTL commands, data types and structure will be listed. In addition specific information and limitations of the current implementation will be described.

Note: In case of trouble during application programming a trace mechanism can be activated. For further details please see chapter 12.3.

7.1 API functions

7.1.1 Overview

The table below lists all D-PDU API functions and gives a short description. For details please refer to chapter 7.1.3.

Function Function overview

General

PDUConstruct The function is a constructor with optional, manufacturer-specific arguments. It must be called before any other D-PDU API function call for each D-PDU API implementation.

PDUDestruct This destructor must be the last function called in order to free all resources.

PDUModuleConnect The function is used to connect to a specific MVCI protocol module.

PDUModuleDisconnect The function is used to disconnect from a specific MVCI protocol module.

PDURegisterEventCallback A callback function is registered or unregistered for event notification.

PDUIoCtl I/O control functions of a MVCI Protocol Module or ComLogicalLink are inkoked.

Information

PDUGetVersion Version information for a specified MVCI Protocol Module and its D-PDU API implementation is returned by this function.

PDUGetStatus Runtime information from a MVCI Protocol Module, ComLogicalLink or ComPrimitive is returned.

PDUGetLastError Returns the code for the last generated error from a MVCI Protocol Module or ComLogicalLink.

PDUGetObjectId For a given shortname and PDUObjectType the Id is returned. Also the MDF file can be parsed.

Resource Management

PDUGetResourceIds According to the requested resource information, all matching resource Ids are returned.

PDUGetResourceStatus The status of the requested resource Id is returned.

PDUGetConflictingResources The function returns a list of resource Ids that are in conflict with the given resource Id.

PDUGetModuleIds If there are any MVCI Protocol Modules currently connected to the D-PDU API, their Ids are returned.

PDULockResource The requested resource Id is locked

PDUUnLockResource The locked requested resource Id is released.

22

Function Function overview

ComLogicalLink Handling

PDUCreateComLogicalLink A ComLogicalLink is created for a given D-PDUResource.

PDUDestroyComLogicalLink The ComLogicalLink is destroyed.

PDUConnect The created ComLogicalLink is physically connected to the communication line.

PDUDisconnect The connected ComLogicalLink is physically disconnected from the communication line.

PDUGetTimestamp The function obtaines the current time (hardware clock) from a MVCI Protocol Module.

Link and ComParameter Handling

PDUGetComParam The current value of specified ComParameter is returned

PDUSetComParam The specified ComParameter is set to given value. Any previous values are overwritten.

PDUGetUniqueRespIdTable A table of Unique Response Identifiersis returned. Each URID is associated with a set of ComParameters that uniquely define an ECU response.

PDUSetUniqueRespIdTable The table of Unique Response Identifiers is set. Each value is assigned by the Application.

Message Handling

PDUStartComPrimitive The ComPrimitive operation starts.

PDUCancelComPrimitive The current execution of the given ComPrimitive is cancelled.

PDUGetEventItem Retrieves the item data for a given event source

PDUDestroyItem The given item is destroyed.

Table 6: D-PDU API functions

7.1.2 General usage

In order to initialize the D-PDU API implementation and to prepare communication for one channel, the application has to go through a sequence of D-PDU API function calls. The demo applicatioin provides an example for the D-PDU API usage. For more information see chapter 9.1.

7.1.2.1 General usage of D-PDU API function calls

7.1.2.1.1 Initialization of the D-PDU API Library

The D-PDU API library is initialized by calling the PDUConstruct function. PDUGetModuleIds will return a list of the MVCI Protocol Modules available, their handles and module types. PDURegisterEventCallback may also be called and the global system callback will be registered.

7.1.2.1.2 Connecting to a MVCI Protocol Module

When calling PDUModuleConnect the D-PDU API library will connect to one or more MVCI Protocol Modules.

PDURegisterEventCallback may also be called and the module callback will be registered.

23

7.1.2.1.3 Setting up a ComLogicalLink

Based on the resource information PDUCreateComLogicalLink will create a ComLogicalLink. PDURegisterEventCallback may also be called to register the ComLogicalLink’s callback function.

PDUGetUniqueRespIdTable obtains a set of ComParameters for unique identification of ECUs.

PDUGetComParam returns the ComParameter item structures. PDUSetComParam sets the ComParameters for the ComLogicalLink.

When PDUSetUniqueRespIdTable is called the URID Table is configured based on the ECU responses expected to be received on the ComLogicalLink.

When calling PDUConnect the ComLogicalLink will connect to the communication line.

7.1.2.1.4 Initiating vehicle communications on a ComLogicalLink

PDUStartComPrimitive is used to start the vehicle communications on the ComLogicalLink. As parameters it may have PDU_COPT_STARTCOMM or PDU_COPT_SENDRECV. PDU_COPT_STARTCOMM ComPrimitive is used for initialization of ECU communication and to start sending tester present messages. Some protocols require that this is the first ComPrimitive being called. The PDU_COPT_SENDRECV ComPrimitive is used to begin vehicle communications for all other vehicle bus communications.

7.1.2.1.5 Communicating on a ComLogicalLink with the vehicle

PDUStartComPrimitive (with type PDU_COPT_SENDRECV) will set up and start ComPrimitives for vehicle bus communication (Send only, Send Receive, or Receive only).

In order to change ComParameters during communication the PDUSetComParam function is used.

PDUGetEventItem will retrieve event items and PDUDestroyItem will destroy event items from D-PDU API memory, when they are not needed any longer by the application.

7.1.2.1.6 Stopping the vehicle communication on a ComLogicalLink

PDUStartComPrimitive (with type PDU_COPT_STOPCOMM) will stop diagnostic communication on a ComLogicalLink.

7.1.2.1.7 Connecting to an additional MVCI Protocol Module

When a system event callback is received with an information type PDU_IT_INFO indicating that a new MVCI Protocol Module is detected by D-PDU API, the list of modules will change (PDU_INFO_MODULE_LIST_CHG).

The function PDUGetModuleIds returns the new list of available MVCI Protocol Modules and their handles and modules types. Any previously detected MVCI Protocol Modules will return the same hMod handles.

When calling PDUModuleConnect is called, a connection to the new MVCI Protocol Modules is established.

PDURegisterEventCallback may also be called to register the new module’s callback function.

24

7.1.2.1.8 Reconnecting to a MVCI module after loss of communication

When a module event callback is received, it indicates that communication to an MVCI protocol module is lost. The hMod information is part of the callback information.

When PDUModuleDisconnect is called, the hMod handle is no longer valid. Also all event items in the queues are freed, and any related module memory reserved by the D-PDU API library is released.

Wait for a system event callback with an information type PDU_IT_INFO indicating the list of modules has changed (PDU_INFO_MODULE_LIST_CHG).

The function PDUGetModuleIds returns the new list of available MVCI Protocol Modules and their handles and modules types. If communication is lost, the hMod will no longer be listed as available.

7.1.2.1.9 Disconnecting from a MVCI module

When PDUDisconnect is called, the ComLogicalLink is disconnected from the communication line.

PDUDestroyComLogicalLink destroys the ComLogicalLink.

PDURegisterEventCallback may also be called with a NULL parameter to unregister the module callback function. Thereafter no further events will be signalled to the application for that module.

PDUModuleDisconnect will disconnect a specific MVCI Protocol Module from the D-PDU API library and release all reserved memory resources.

7.1.2.1.10 Deinitialization of the D-PDU API library

The PDUDestruct function call will deinitialize the D-PDU API. All internal resources are destroyed or released.

7.1.2.2 Asynchronous communication

The D-PDU API is designed for asynchronous operation, i.e. API calls are immediately returned even though the requested activity might still be running or is still waiting for execution inside the D-PDU API implementation. The D-PDU API is designed for asynchronous calls, because all vehicle communication requirements (e.g. non cyclic, cyclic, event driven communication, etc.) and synchronous communication requirements resulting from SAE J2534 and RP1210a can be covered by this principle.

The D-PDU API functions allow the application to use both asynchronous and synchronous communication principles to exchange data with the D-PDU API:

Asynchronous Mode: In this case, the communication between application/server and the PDU API implementation is completely event driven. The application may register an application/server specific callback function by calling PDURegisterEventCallback. Any events occurring will cause the callback function to be invoked.

Synchronous Mode (Polling Mode): In this case, the application does not make usage of the callback mechanism. It initiates the PDU API functions just as in asynchronous mode. Instead of waiting for notification, it repeats requesting the status by calling the PDUGetStatus API function.

25

7.1.2.3 Synchronous communication

The PDU API does not support synchronous function calls, i.e. PDU API function calls do not wait until the requested service is finished before returning the call.

In order to cover synchronous function calls, as e.g. for SAE J2534 or RP1210a, the application or server has to operate the PDU API in polling mode or needs to provide a simple callback function. For SAE J2534 and RP1210a, synchronous calls as defined by these standards will be transparently mapped onto the asynchronous PDU API calls. This is done by optional compatibility layers.

26

7.1.2.4 Usage of ComPrimitives

A ComPrimitive is a basic communication element holding data and controlling the exchange of data between the PDU API implementation and the ECU. There are different types of ComPrimitives in order to describe different communication principles and to give an overview of the generic data exchange mechanism. Depending on the communication protocol used with a specific ComLogicalLink, each ComPrimitive has a different behavior and usage.

The following table describes the different ComPrimitive types.

ComPrimitive type/value Description

PDU_COPT_STARTCOMM 0x8001

The communication with the ECU is started; an optional request will be sent to the ECU. The detailed behaviour of this ComPrimitive is protocol dependent. This ComPrimitive is required as the first ComPrimitive for certain diagnostic protocols. The ComLogicalLink is put into PDU_CLLST_COMM_STARTED state, which allows for tester present messages to be enabled according to the ComParameter settings.

PDU_COPT_STOPCOMM 0x8002

The communication with ECU is stopped; an optional stop request will be sent to the ECU. The detailed behaviour is protocol dependent. The ComLogicalLink is put into PDU_CLLST_ONLIINE state and no further tester present messages will be sent. To begin communications again PDU_COPT_STARTCOMM ComPrimitive might be required by some protocols.

PDU_COPT_UPDATEPARAM 0x8003

The ComParameters and the UniqueRespIdTable related to a ComLogicalLink are copied from the working buffer to the active buffer. Before the update PDUSetComParam and/or PDUSetUniqueRespIdTable are called to pass the values to the D-PDU API, which modifies the working buffer.

PDU_COPT_SENDRECV 0x8004

Send request data and/or receive corresponding response data (single or multiple responses).

PDU_COPT_DELAY 0x8005

Wait the given time span before executing the next ComPrimitive.

PDU_COPT_RESTORE_PARAM 0x8006

Converse functionality of PDU_COPT_UPDATEPARAM. Copies ComParameters related to a ComLogicalLink from active buffer to working buffer.

Table 7: ComPrimitives

The following sections describe how to use ComPrimitives for different communication patterns known from automotive communication protocols. All actions described assume the D-PDU API has been initialized and a ComLogicalLink has been created. In addition to the D-PDU API function calls shown in the tables, additional API calls can be used for additional functions like status requests etc. Any memory allocation or deallocation is initiated by create, start and destroy calls and is handled within the D-PDU API.

27

7.1.3 Details

The subchapters below give a short description of the D-PDU API functions, parameters and error codes. For further details please see the ISO 22900-2 specification.

28

7.1.3.1 PDUConstruct

Syntax EXTERNC T_PDU_ERROR PDUConstruct(CHAR8* OptionStr, void *pAPITag)

Parameters

OptionStr PDUConstruct does NOT require a Softing specific OptionsStr. Therefore NULL is used as parameter

pAPITag An Application defined tag value. Used in event callbacks. The callbacks indicate status, errors and results for the PDU API library being used. This information can be used to determine which library is raising the callback.

Function Description

The D-PDU API library is initialized. The list of all available MVCI Protocol Modules and their supported resources is determined by the D-PDU API library. The library also creates internal structures, including a resource table. The state of the communication is offline. This means that no allocation of resources and no communication over vehicle interfaces take place.

The OptionStr is validated and all known and accessible MVCI Protocol Modules are detected.

Module IDs are assigned to all properly initialized MVCI Protocol Modules

A PDU_MODULE_DATA list is created. The list contains MVCI Protocol Modules, their module types, module handles, module status and additional vendor information strings.

An internal resource table stores all detected resources. For any resource query this table will be used. The query can be done via the functions PDUGetModuleIds, PDUGetConflictingResources, PDUGetResourceIds, PDUGetResourceStatus, PDULockResource, and PDUUnlockResource.

Return values

Return value definition Description

PDU_STATUS_NOERROR Function call successful

PDU_ERR_FCT_FAILED Function call failed

PDU_ERR_DEVICE_NOT_CONNECTED The D-PDU API implementation does not support any of the connected MVCI Protocol Modules

PDU_ERR_SHARING_VIOLATION Function called again without a previous destruct

PDU_ERR_INVALID_PARAMETERS There is at least one option attribute that has invalid parameters

PDU_ERR_VALUE_NOT_SUPPORTED The D-PDU driver does not support at least one of the option values

Table 8: PDUConstruct return values

29

7.1.3.2 PDUDestruct

Syntax EXTERNC T_PDU_ERROR PDUDestruct()

Parameters

None


All open communication links are closed and all communication resources are released. Internal memory segments are deallocated and system-level drivers disconnected. The execution of PDUDestruct does not result in any communication on the vehicle interfaces. PDUConstruct may be called again after execution of PDUDestruct.

The internal resource table is checked. Any open communication links are determined and closed. No communication takes place. All MVCI Protocol Modules detected before with PDUConstruct are de-initialised. All connections to connected MVCI Protocol Modules are closed. All internal memory resources are released.

Return values




PDU_ERR_DEVICE_NOT_CONNECTED The D-PDU API implementation does not support any of the MVCI Protocol Modules connected

Table 9: PDUDestruct return values

30

7.1.3.3 PDUModuleConnect

Syntax EXTERNC T_PDU_ERROR PDUModuleConnect (UNUM32 hMod)

Parameters

hMod Handle of the MVCI protocol module to be connected. The D-PDU API will establish connection to all detected MVCI protocol modules if the handle is set to PDU_HANDLE_UNDEF. The MVCI protocol module vendor will choose the interface type of the connection.


A connection to the specified MVCI protocol module is established and its system-level drivers are initialized. Available resources can be obtained from the specified MVCI protocol module. Internal structures are created, including a resource table. The state of the communication is offline. This means that no allocation of resources and no communication via vehicle interfaces take place.

It is determined if a connection to a MVCI protocol module is available. In this case the module must have the state PDU_MODST_AVAIL.

The communication with the specific MVCI protocol module is initialized.

All resources status values of the MVCI protocol module are determined.

The Module Status is set to PDU_MODST_READY. (Note: a callback can not be registered by the client before connection. Therefore no event callback is generated at that moment). If the Module Status is not in PDU_MODST_READY state, all D-PDU API function calls requiring a “hMod” parameter will return with error PDU_ERR_MODULE_NOT_CONNECTED. The following D-PDU API functions are allowed to be used prior to a PDUModuleConnect:

PDUGetResourceIds PDUGetObjectId PDUGetConflictingResources PDUGetStatus

The handle (hMod) remains valid from the beginning of the connection of the module until a PDUModuleDisconnect function call, even if there is a loss of communication with the module. In this way it is possible to maintain the event queues for the client application’s retrieval of event items.

Use Case specific behaviour

For the corresponding use cases a status event item is generated each time a MVCI Protocol Module changes it’s status:

Use Case:

Module State = PDU_MODST_AVAIL:

- Initial detection by the D-PDU API. - NO status event item is generated - For any API function call to the module the state must be PDU_MODST_READY

31

Use Case: Module State = PDU_MODST_UNAVAIL:

- Initial detection by the D-PDU API, but already in use by another client session - NO status event item is generated - A module may transition to PDU_MODST_UNAVAIL if the D-PDU API detects a loss

of communication to the module after being in the READY state.

Use Case: Module State Change = (PDU_MODST_AVAIL -> PDU_MODST_READY):

- The transition is made after a successful call to PDUModuleConnect. - API session between the module and the client application can be initiated - NO status event item can be generated (the function callback

PDURegisterEventCallback can be called in the state PDU_MODST_READY only).

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_UNAVAIL):

- The transition is made after a loss of communication to a module. - All ComPrimitives currently executing (i.e. periodic) and all ComPrimitives in the CoP

queue will be cancelled (PDU_COPST_CANCELLED). - All active ComLogicalLinks will go into the offline state (PDU_CLLST_OFFLINE). - In the case of losing communications to a module the event order is:

PDU_COPST_CANCELLED, PDU_CLLST_OFFLINE, and PDU_MODST_UNAVAIL.

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_NOT_READY):

- The transition is made when a condition occurs on the device which does not allow the execution of any further API calls. This may not be a permanent condition (e.g the module recovers from the not ready state (e.g. PDU_IOCTL_RESET)).

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_AVAIL):

- The transition is made after a successful call to PDUModuleDisconnect. - All resources are released for the module. - NO status event item is generated since further event items will not be queued for the

module.

Return values



PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before

PDU_ERR_INVALID_HANDLE Invalid MVCI protocol module handle

PDU_ERR_MODULE_FW_OUT_OF_DATE The version of the D-PDU API library is newer than the MVCI Protocol Module firmware. The MVCI Protocol Module firmware must be updated

PDU_ERR_API_SW_OUT_OF_DATE The MVCI Protocol Module firmware version is newer than the D-PDU API Library. The D-PDU API Library must be updated

PDU_ERR_FCT_FAILED Command failed

32

Table 10: PDUModuleConnect return values

7.1.3.4 PDUModuleDisconnect

Syntax EXTERNC T_PDU_ERROR PDUModuleDisconnect(UNUM32 hMod)

Parameters

hMod Handle of the MVCI Protocol Module to be disconnected. If set to PDU_HANDLE_UNDEF then the D-PDU API will disconnect from all previously connected MVCI protocol modules.


Any open communication links to the specified VCI module(s) are closed.The specified MVCI protocol module(s) is deinitialized. All internal memory associated with the MVCI protocol module(s) is released and system-level drivers are disconnected. The Module Status is set to PDU_MODST_AVAIL if communication has not been lost to the module (further event items are not allowed for the module, so no event callback is generated). The module handle (hMod) is still valid for further PDUModuleConnect calls. No communication on the vehicle interfaces is initiated due to the execution of PDUModuleDisconnect, but PDUModuleConnect may be called again. In the case that communication to the module has been lost the hMod handle is no longer valid. After all items have been retrieved from the module event queue the client application should call PDUModuleDisconnect.

Return values




PDU_ERR_INVALID_HANDLE MVCI protocol module handle is not valid

PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module is not connected


Table 11: PDUModuleDisconnect return values

33

7.1.3.5 PDURegisterEventCallback

Syntax EXTERNC T_PDU_ERROR PDURegisterEventCallback(UNUM32 hMod, UNUM32

hCLL, CALLBACKFNC EventCallbackFunction )

Parameters

hMod Module handle if a module/system event callback function shall be registered. If hCLL=PDU_HANDLE_UNDEF the callback function shall be used for PDUAPI system events.

hCLL ComLogicalLink handle, if a ComLogicalLink event callback function shall be registered. If no ComLogicalLink specific callback function shall be registered, the value PDU_HANDLE_UNDEF shall be passed. A callback registration to a ComLogicalLink can not be requested if a ComLogicalLink is already connected. If such a request is made an error is returned.

EventCallbackFunction

It can be used for event notification as a reference of callback function. If NULL the callback mechanism is deactivated.


The function is used to register or unregister a callback function for event notification which is by default deactivated.

The input parameter’s handles are validated. If all handles are PDU_HANDLE_UNDEF it is an event registration for D-PDU API system events. The request type is determined. It may be a register or a un-register request.

The callback function pointer is added or removed to the proper object (System, Module, ComLogicalLink).

Return values




PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before

PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle or ComLogicalLink handle is invalid

PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol Module was not successful

PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been connected

PDU_ERR_CLL_CONNECTED ComLogicalLink is in the ONLINE state; registration of a new callback can not be accepted

Table 12: PDURegisterEventCallback return values

34

7.1.3.6 EventCallback

Syntax void EventCallback (T_PDU_EVT_DATA eventType, UNUM32 hMod, UNUM32 hCLL, void *pCllTag, void *pAPITag)

Parameters

eventType Type of event which occurred.

hMod Handle of MVCI Protocol Module (in case of a system event callback it has the value PDU_HANDLE_UNDEF).

hCLL Handle of ComLogicalLink causing the event (if not from a ComLogicalLink it has the value PDU_HANDLE_UNDEF).

pCllTag Tag value for a ComLogicalLink. If hCLL = PDU_HANDLE_UNDEF, then the tag is ignored. It provides information about the source of the event and is application specific.

pAPITag Tag value for the PDU API. It provides information about the source of the event and is application specific.

Function description

The prototype must be implemented and registered by the application. When PDURegisterEventCallback is called the D-PDU API registers the application’s callback function, so that the callback function will be called for each event furtheron. The callback function receives the event type, a handle of the resource causing the event and an application-specific tag. The event may be processed by the application immediately or it may be passed to an internal thread.

To avoid unnecessary blocking of the D-PDU API software, short runtime duration of the function is highly recommended. The D-PDU API thread is used when the function is called. The application’s callback function will post an event to wake another thread to process the event data. During the callback routine only PDUGetEventItem calls are allowed.

Return values

None

35

7.1.3.7 PDUIoCtl

Syntax EXTERNC T_PDU_ERROR PDUIoCtl(UNUM32 hMod, UNUM32 hCLL, UNUM32 IoCtlCommandId, PDU_DATA_ITEM *pInputData, PDU_DATA_ITEM **pOutputData)

Parameters

hMod Handle of the specific MVCI Protocol Module, which shall be controlled by the I/O control command specified. In order to specify module related commands, the parameter hCLL must be set to PDU_HANDLE_UNDEF

hCLL Handle of the ComLogicalLink, which shall be controlled by the specified I/O control command.

IoCtlCommandId

ID of the I/O control command. The supported ID’s by a specific MVCI Protocol Module can be found in the MVCI MDF.

pInputData Input data item for the specified command. If no input data is required, NULL is used as parameter value. The application creates and manages the input data item.

pOutputData Call-by-reference place for storing the output data item pointer. If NULL is used, then the D-PDU API implementation will not allocate or fill the output data item. If a valid address is provided, the D-PDU API implementation will allocate a PDU_DATA_ITEM and fill in the output data of the specified command. A reference is stored in *pOutputData. After usage, PDUDestroyItem is called and the allocated data item is freed.


Used to execute functions or set values for a MVCI Protocol Module. Each specified IOCTL function is identified by an ID number and has its own input and output values.

The MVCI MDF (Module Description File) contains the I/O controls supported by a specific MVCI Protocol Module. When the function is called all input parameters are validated. The application allocates an input data structure to be taken by the function. From this structure the required information is extracted and the command is executed. The output data is allocated and filled in the call-by-reference variable pOutputData. When calling PDUDestroyItem from the application the OutputData structure is released.

36

Return values





PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink handle is invalid

PDU_ERR_ID_NOT_SUPPORTED The MVCI Protocol Module does not support the ID of I/O control

PDU_ERR_INVALID_PARAMETERS pInputData or pOutputData reference pointer for an IOCTL Command are invalid (NULL). The specified IOCTL expects at least one valid reference pointer



Table 13: PDUIoCtl return values

37

7.1.3.8 PDUGetVersion

Syntax EXTERNC T_PDU_ERROR PDUGetVersion( UNUM32 hMod, PDU_VERSION_DATA

*pVersionData )

Parameters

hMod Handle of the MVCI Protocol Module for which the version information is returned.

pVersionData Call-by-reference place for storing the version information


The version information from a MVCI Protocol Module is returned.

When called the function validates all input parameters. Pointer parameters cannot be NULL.

The PDU_VERSION_DATA structure (allocated by the client application) is filled.

Return values





PDU_ERR_INVALID_PARAMETERS pVersionData parameter is invalid ( NULL )



PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle is invalid

Table 14: PDUGetVersion return values

38

7.1.3.9 PDUGetStatus

Syntax EXTERNC T_PDU_ERROR PDUGetStatus( UNUM32 hMod, UNUM32 hCLL, UNUM32

hCoP, T_PDU_STATUS *pStatusCode, UNUM32 *pTimestamp, UNUM32 *pExtraInfo)

Parameters

hMod Handle of MVCI Protocol Module for which the status code is to be requested. In order for the status of only one module to be returned, hCLL and hCoP must be set to PDU_HANDLE_UNDEF.

hCLL Handle of ComLogicalLink for which the status code is to be requested. In order for the status of only one ComLogicalLink to be returned hCop must be set to PDU_HANDLE_UNDEF.

hCoP Handle of ComPrimitive for which the status code is to be requested.

pStatusCode Call-by-reference place for storing the status code.

pTimestamp Call-by-reference place for storing timestamp in microseconds.

pExtraInfo Call-by-reference place for storing additional information. pExtraInfo returns 0 for ComPrimitives. For MVCI Protocol Modules and ComLogicalLinks, pExtraInfo contains additional information defined by the MVCI Protocol Module supplier. If no information is available, the function returns 0.


The function returns runtime information from a MVCI Protocol Module, ComLogicalLink or ComPrimitive. When called the function validates all input parameters. The latest status information for the specified handle (Module or ComLogicalLink or CoP) is returned. The information is stored in the memory allocated by the client application. The status PDU_MODST_NOT_READY is returned in the case that the D-PDU API detects a PC software version out-of-date with the MVCI Protocol Module Firmware.

39

Return values





PDU_ERR_INVALID_PARAMETERS pStatusCode, pTimestamp or pExtraInfo is invalid (NULL)


PDU_ERR_INVALID_HANDLE MVCI Protocol Module, ComPrimitive or ComLogicalLink handle is invalid

Table 15: PDUGetStatus return values

40

7.1.3.10 PDUGetLastError

Syntax EXTERNC T_PDU_ERROR PDUGetLastError( UNUM32 hMod, UNUM32 hCLL,

T_PDU_ERR_EVT *pErrorCode, UNUM32 *phCoP, UNUM32 *pTimestamp, UNUM32 *pExtraErrorInfo)

Parameters

hMod Handle of MVCI Protocol Module for which the error code is requested. To return the last error of the MVCI Protocol Module, hCLL must be set to PDU_HANDLE_UNDEF.

hCLL Handle of ComLogicalLink for which the error code is requested.

phCoP phCoP will contain the handle of the ComPrimitive if the last error belonged to that ComPrimitive, else phCoP is set to PDU_HANDLE_UNDEF.

pErrorCode Call-by-reference place for storing the error code. pErrorCode will contain PDU_ERR_EVT_NOERROR if no last error has been stored for the specified handle.

pTimestamp Call-by-reference place for storing timestamp.

pExtraErrorInfo

Call-by-reference place for storing extra error information. The ExtraErrorInfo code can be found in the MDF file.


The function returns the code for the last error from a MVCI Protocol Module or ComLogicalLink, which occurred for the handle. To perform error handling the client application should read the error events from the event queues to get the chronological order of events.

Notes:

This function has been added for J2534 support via an additional software wrapper. It is not needed, if the application evaluates the error event items from the queues associated with callback functions.

In case the LAST error is already removed from the event queue by the time this function is called, the hCoP handle is no longer valid because the hCoP already finished and its associated resources are freed. When the function is called all input parameters are validated. The pointer parameters cannot be NULL. The last error information for the specified handle (Module or ComLogicalLink) is stored in the memory allocated by the client application. If there is a ComPrimitive error than the ComPrimitive handle is returned with the error code.

41

Return values





PDU_ERR_INVALID_PARAMETERS pErrorCode, pTimestamp or pExtraErrorInfo is invalid (NULL)

PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol Module was not sucessfull



Table 16: PDUGetLastError return values

42

7.1.3.11 PDUGetObjectId

Syntax EXTERNC T_PDU_ERROR PDUGetObjectId(T_PDU_OBJT pduObjectType, CHAR8*

pShortname, UNUM32 *pPduObjectId)

Parameters

pduObjectType Enumeration ID of object type.

pShortname Pointer to the shortname of object.

pPduObjectId Call-by-reference place where the PDU Object ID for "Shortname" of pduObjectType is stored. The ID value will be PDU_ID_UNDEF if there is no valid Object Id for the requested object type and shortname.


Depending on the given item or type given as inputs, the item ID is determined. We can also obtain the item ID by parsing the MDF file.

When the function is called all input parameters are validated. Pointer parameters cannot be NULL.The ID of the requested object is returned. The response parameter pPduObjectId is filled with the information.

Return values





PDU_ERR_MODULE_FW_OUT_OF_DATE The D-PDU API library version is newer than the MVCI Protocol Module firmware. We must update the MVCI Protocol Module firmware.

PDU_ERR_API_SW_OUT_OF_DATE The MVCI Protocol Module firmware version is newer than the D-PDU API Library. We must update the D-PDU API Library.

PDU_ERR_INVALID_PARAMETERS There is at least one invalid parameter (ObjectType, ShortName), or the pointer to the pPduObjectId is NULL.

Table 17: PDUGetObjectId return values

43

7.1.3.12 PDUGetResourceIds

Syntax EXTERNC T_PDU_ERROR PDUGetResourceIds(UNUM32 hMod, PDU_RSC_DATA

*pResourceIdData, PDU_RSC_ID_ITEM **pResourceIdList)

Parameters

hMod Handle of MVCI Protocol Module. If the value of the handle is PDU_HANDLE_UNDEF then the connected modules return their resource Ids and the module handles which support the PDU_RSC_DATA elements

pResourceIdData

Call-by-reference place for the resource Id data information for a particular module type.

pResourceIdList

Call-by-reference place where the Resource Id list for the selected resource data is stored. When PDUDestroyItem is called the item is destroyed.


The function returns a list of resource ids from the D-PDU API for a given module. The module must support the resource data information (protocol, bus type and pin(s)). PDUGetObjectId returns the object Ids for the resource data information.

A reference to a memory object of PDU_RSC_DATA type is given by the caller. The object refers to a single set resource data information (pResourceIdData). A PDU_IT_RSC_ID object (pResourceIdList) is generated by the D-PDU API. The object has a list of resource Id’s that match the given resource data information. After using the resource Id list information, the function PDUDestroyItem may be called by the application in order to release the D-PDU API memory.

The function validates the input parameters; pointer parameters cannot be NULL. Thereafter the function takes the pResourceIdData structure as allocated by the application. Memory for the pResourceIdList result information is allocated and the required information from pResourceIdData structure is extracted and the correct list of resource Ids is determined, that match the resource data requested.

44

Return values








PDU_ERR_INVALID_PARAMETERS The pResourceIdData or pResrouceIdList reference pointer is invalid (NULL)

Table 18: PDUGetResourceId return values

45

7.1.3.13 PDUGetResourceStatus

Syntax EXTERNC T_PDU_ERROR PDUGetResourceStatus(PDU_RSC_STATUS_ITEM

*pResourceStatus)

Parameters pResourceStatus

Call-by-reference place where the status of all requested resource Ids is stored. Before calling the function the data structure is pre-filled with the resource Ids of interest.


The function returns resource status information from the D-PDU API. The pResourceStatus structure contains all the resources for which the status shall be retrieved. The same structure is used when determining the resource status for each requested resource Id.

A reference to a memory object that is an input/output resource status item (pResourceStatus) is given by the caller. The caller-supplied memory object is of type PDU_RSC_STATUS_ITEM. Also a pointer to the data item object is provided, specifying the correct type PDU_IT_RSC_STATUS, and the number of PDU_RSC_STATUS_DATA objects for which the status shall be retrieved. The D-PDU API validates the object and then fills in the output portions of the structure.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. pResourceStatus structure is allocated by the application. For each requested resource Id the status information is filled.

Return values






PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle contained in the pResourceStatus strucutre is invalid

PDU_ERR_INVALID_PARAMETERS pResourceStatus, or one or more invalid resource ids is invalid (NULL)

Table 19: PDUGetResourceStatus return values

46

7.1.3.14 PDUGetConflictingResources

Syntax EXTERNC T_PDU_ERROR PDUGetConflictingResources(UNUM32 resourceId, PDU_MODULE_ITEM *pInputModuleList, PDU_RSC_CONFLICT_ITEM **pOutputConflictList)

Parameters

resourceId The resource identifier used for conflict checking. It can be obtained from the MDF file and from PDUGetResourceId function.

pInputModuleList

List of modules to determine conflicts against. In this structure hMod and ModuleType need to be valid.

pOutputConflictList

Call-by-reference place where the information for each conflicted resource is stored.


The function returns a list of resources that conflict and therefore cannot be selected at the same time as resources. The conflict may be caused when resources use the same pin or the same controller. From the MDF and CDF file information is extracted for all modules and module types. Conflicting resources may be found even in a one-vendor D-PDU API system. The system-integrator is responsible for any conflicting resources when MVCI Protocol Modules belonging to different vendors are connected by a Y-cable and more than one MVCI Protocol Module is connected to a vehicle. The application will decide which group of modules are connected to a single vehicle. Therefore pInputModuleList will be filled correctly.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. All resource conflicts of ResourceId between the modules listed in pInputModuleList are determined. Memory for the PDU_RSC_CONFLICT_ITEM structure is allocated. The call-by-reference variable pOutputConflictList is filled. When PDUDestroyItem is called from the application pOutputConflictList is released.

47

Return values







PDU_ERR_INVALID_PARAMETERS Either the resource ID is invalid or one of the reference pointers (pInputModuleList or pOutputConflictList) are invalid (NULL).

Table 20: PDUGetConflictingResources return values

48

7.1.3.15 PDUGetModuleIds

Syntax EXTERNC T_PDU_ERROR PDUGetModuleIds(PDU_MODULE_ITEM **pModuleIdList)

Parameters pModuleIdList

Pointer for storing the pointer to Module Type Ids and the Module handles for all modules that are connected to the D-PDU API.


The function returns the module type Id, module handle information, vendor specific string information, and module status from the D-PDU API. D-PDU API assigns a handle (hMod) to all MVCI Protocol Modules detected by the D-PDU API. The module type is given by the ModuleTypeId. Using hMod information we can access individual modules.

When a change in the list of MVCI Protocol Modules is detected by the D-PDU API an information callback occurs. In order to obtain the new list of available MVCI protocol modules the client application should call PDUGetModuleIds again. The module handles (hMod) for already detected modules are not changed.

An already connected module maintains its handle (hMod) even after the communication to the module is lost. In this case, only after a PDUModuleDisconnect or PDUDestruct the module handle is destroyed.

A status change shows that changes to a module connection have occurred. This happens during PDUModuleConnect, PDUModuleDisconnect, loss of communications with a MVCI Protocol Module and connection by another D-PDU API session.

The function validates input parameter; pointer parameter cannot be NULL. PDU_MODULE_ITEM structure is allocated and the call-by-reference variable pModuleIdList is filled. When calling PDUDestroyItem from the application the D-PDU API structure (pModuleIdList) is freed. The D-PDU API will generate a unique handle for each MVCI Protocol Module interface type supported. The handle is no longer valid and will be removed from the list of detected modules if detection of a module or module interface type is lost and the handle was in the state PDU_MODST_AVAIL. In case the module or module interface type is re-detected, a new module handle is generated. Each time the list of module handles changes, an information event is generated to indicate that a new list of MVCI Protocol Module handles is available. Use Case specific behaviour

When a MVCI Protocol Module changes status, a status event item is generated. The following list describes each status change use case.

Use Case: Module State = PDU_MODST_AVAIL:

- Initial detection by the D-PDU API. - NO status event item is generated - For any API function calls to the module, the state must be PDU_MODST_READY

49

Use Case: Module State = PDU_MODST_UNAVAIL:

- Initial detection by the D-PDU API, but already in use by another client session - NO status event item is generated - A module may transition to PDU_MODST_UNAVAIL if the D-PDU API detects a loss

of communication to the module after being in the READY state.

Use Case: Module State Change = (PDU_MODST_AVAIL -> PDU_MODST_READY):

- The transition is made after a successful call to PDUModuleConnect. - API session between the module and the client application can be made - NO status event item can be generated (the function callback

(PDURegisterEventCallback) can only be called in the state PDU_MODST_READY).

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_UNAVAIL):

- The transition is made after a loss of communication to a module. - All ComPrimitives currently executing (i.e. periodic) and all ComPrimitives in the CoP

queue will be cancelled (PDU_COPST_CANCELLED). - All active ComLogicalLinks will go into the offline state (PDU_CLLST_OFFLINE). - In the case of losing communications to a module the order of events is:

PDU_COPST_CANCELLED, PDU_CLLST_OFFLINE, and PDU_MODST_UNAVAIL.

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_NOT_READY):

- The transition is made when a condition occurs on the device which does not allow the execution of any further API calls. This may not be a permanent condition (the module recovers from the not ready state (e.g. PDU_IOCTL_RESET)).

Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_AVAIL):

- The transition is made after a successful call to PDUModuleDisconnect. - All resources are freed for the module. - NO status event item is generated since further event items will not be queued for the

module.

Return values




PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for pModuleList


Table 21: PDUGetModelIds return values

50

7.1.3.16 PDULockResource

Syntax EXTERNC T_PDU_ERROR PDULockResource(UNUM32 hMod, UNUM32 hCLL, UNUM32

LockMask)

Parameters

hMod Handle of MVCI Protocol Module.

hCLL Handle of ComLogicalLink to be granted exclusive access to it’s resource.

LockMask Bit encoded mask for type of locking request to a physical resource:

Bit 0: 1=LockPhysicalComParams

Request lock to modify physical ComParameters

Bit 1: 1=LockPhysicalTransmitQueue

Request lock for transmit operations


The function PDULockResource will give a ComLogicalLink exclusive privilege of a physical resource. This is usefull in case of an application that needs to have the physical bus protected from multiple ComLogicalLinks which share the physical resource. These exclusive rights to the physical resource are allocated based on the LockMask value. Once the resource is locked, another call of PDULockResource from a different ComLogicalLink will fail.

This locking of the resource does not affect the monitoring or receiving of messages from a physical resource.

The function validates all input parameters. If no other locks and currently active transmissions can be found on the resource, the status of the ComLogicalLink's resource is set. Otherwise the value PDU_ERR_RSC_LOCKED or PDU_ERR_FCT_FAILED is returned.


Transmit Queue Lock:

- When the transmit queue is locked, this will force a SUSPEND_TX_QUEUE to all other ComLogicalLinks sharing the physical resource.

- Any new ComLogicalLink have their ComPrimitive queue in the SUSPEND_TX_QUEUE mode.

- A RESUME_TX_QUEUE is sent to all ComLogicalLinks sharing the physical resource when the lock on the transmit queue is released.

- If there are any enabled tester present messages, they will be stopped when a ComPrimitive queue is suspended.

Physical ComParameter Lock:

- Any ongoing transmissions will not be terminated by a lock on the physical ComParameters (ComParameter ActiveBuffer)

51

- Calls to PDU_COPT_UPDATEPARAM for physical ComParameters on a second ComLogicalLink will lead to an error event for the second ComLogicalLink (PDU_ERR_EVT_RSC_LOCKED).

Automatic unlocking:

- If PDUDestroyComLogicalLink or PDUDisconnect are called, then an automatic unlock will occur.

Change of lock status:

- The other ComLogicalLinks that are sharing the physical resource are informed whenever the lock status of a resource changes through an information callback (PDU_IT_INFO)

- The current lock state of the physical resource can be determined by a client application by calling the PDUGetResourceStatus function.

Return values







PDU_ERR_RSC_LOCKED The requested resource is already in the “locked” state

Table 22: PDULockResource return values

52

7.1.3.17 PDUUnlockResource

Syntax EXTERNC T_PDU_ERROR PDUUnlockResource(UNUM32 hMod, UNUM32 hCLL,

UNUM32 LockMask)

Parameters


hCLL Handle of ComLogicalLink unlocking the resource.

LockMask Bit encoded mask for type of locking request to a physical resource:

Bit 0: 1=LockPhysicalComParams

Request lock to modify physical ComParameters

Bit 1: 1=LockPhysicalTransmitQueue

Request lock for transmit operations


The function PDUUnlockResource releases the lock type on the resource the ComLogicalLink is connected to. The condition is that the lock type was previously locked by the same ComLogicalLink.

When the function is called all input parameters are validated and the status of the ComLogicalLink's resource is set.

Return values






PDU_ERR_RSC_LOCKED_BY_OTHER_CLL The requested resource is locked by a different ComLogicalLink


PDU_ERR_RSC_NOT_LOCKED The resource is already in the unlocked state

Table 23: PDUUnlockResource return values

53

7.1.3.18 PDUCreateComLogicalLink

Syntax EXTERNC T_PDU_ERROR PDUCreateComLogicalLink(UNUM32 hMod, PDU_RSC_DATA *pRscData, UNUM32 resourceId, void *pCllTag, UNUM32 *phCLL, PDU_FLAG_DATA *pCllCreateFlag )

Parameters

hMod Handle of MVCI Protocol Module

pRscData This parameter defines the settings for a ComLogicalLink. It represents a Resource DataObject. -Unknown Resource Scheme: This parameter must always have a valid value (cannot be NULL) and the resourceId parameter must be PDU_ID_UNDEF. -Specific Resource Id Scheme: This parameter must be NULL and the resourceId parameter must have a valid value.

resourceId Resource Id that maps to the resource data objects defined in the D-PDU API Resource Table. The settings for the ComLogicalLink are based on this information. -Unknown Resource Scheme: This parameter must be set to PDU_ID_UNDEF and the parameter pRscData must not be NULL. -Specific Resource Id Scheme: This parameter must be valid and the parameter pRscData must be set to NULL. Based on the resourceId value resource objects are selected from the D-PDU API Resource Table.

pCllTag An Application defined tag value. Used in event callbacks as additional information for status, errors and result events for the ComLogicalLink.

phCLL Call-by-reference place for storage of ComLogicalLink handle.

pCllCreateFlag

Call-by-reference place to store flag bits used to create a ComLogical Link


Based on a specified Resource Id the function creates a ComLogicalLink. After the logical link was created it’s internal resources are reserved. Also the communication state is offline. This means that no vehicle communication is performed. However, at this point the MVCI Protocol Module hardware is ready for communication.

In order to determine conflicting resources, the MDF and CDF file content is used. Also the D-PDU API gives a list of conflicts for a given resource (PDUGetConflictingResources) across multiple MVCI Protocol Modules that belong to a single vendor.

A ComLogicalLink can be created either by using a specified set of resource items (bus type, protocol, and pins) or by using a predefined resource id.

In case of an Unknown Resource Id Scheme PDUCreateComLogicalLink is called with a set of resources for the link (protocol id, bus type id, pin ids). No checking is done in advance, if that set of resources is supported by the device, if the resources are available or if this request might conflict with another one.

54

Although there is no need to check for availability and conflicts, multi-connection applications are supported. In this case PDUCreateComLogicalLink is called multiple times followed by corresponding calls to PDUConnect. Resource requests may be reordered by the D-PDU API implementation, so that no resource conflicts will occur.

In case of a Specific Resource Id Scheme only the predefined ResourceId is used as a parameter of PDUCreateComLogicalLink. This ID is determined by either reading the MDF file or by calling PDUGetResourceId. Availability and conflicts may be checked by the application at any time by calling PDUGetResourceStatus and PDUGetConflictingResources.

In general the function PDUCreateComLogicalLink validates all input parameters; pointer parameters cannot be NULL. The function checks if the resource is still available. In case of availability the resource is marked as "in use" in the resource table.

If a ComLogicalLink uses PDULockResource, that link will have exclusive rights to modify the physical ComParameters for the resource. All ComLogicalLinks, which share a physical resource, may modify the physical ComParameters. Each ComLogicalLinks sharing a physical resource will read the last values set, since there is only one set of physical ComParameters at a time.

When a ComLogicalLink is created, the event status item (PDU_CLLST_OFFLINE) is not generated. It must be assumed by the application that OFFLINE is the initial status after creation. This is required since the event callback function has not yet been defined by the application for the ComLogicalLink.

When a ComLogicalLink’s status changes, a status event item is generated. The status transition between PDU_CLLST_OFFLINE and CLLST_ONLINE is related to the execution of the API function PDUConnect and PDUDisconnect. When the status is CLLST_ONLINE a status transition between CLLST_ONLINE and CLLST_COM_STARTED can be initiated by executing the ComPrimitives PDU_COPT_STARTCOMM and PDU_COPT_STOPCOMM.

Important note:

In addition to the core D-PDU API functionality described above, the license check is executed during the API function call PDUCreateComLogicalLink. In case of a missing license the function will report an error code PDU_ERR_FUNCTION_FAILED plus special value PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle. The special value is defined in file pdu_api.h as follows:

#define PDU_CLLHDL_LICENSE_CHECK_FAILED 0x80000000

55

Return values



PDU_ERR_FCT_FAILED Function call failed or no license available (see above)


PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for phCLL, invalid NULL pointer for pCllCreateFlag, or invalid resource id


PDU_ERR_RESOURCE_BUSY Resource busy. Resource already in use


PDU_ERR_INVALID_HANDLE Invalid MVCI Protocol Module handle

Table 24: PDUCreateComLogicalLink return values

56

7.1.3.19 PDUDestroyComLogicalLink

Syntax EXTERNC T_PDU_ERROR PDUDestroyComLogicalLink(UNUM32 hMod, UNUM32 hCLL)

Parameters


hCLL Handle of ComLogicalLink to be destroyed.


This function will destroy the given ComLogicalLink. All input parameters are validated. All unread items in the ComLogicalLink’s event queue are destroyed. The ComPrimitives for the ComLogicalLink are cancelled. No PDU_COPST_CANCELLED event is generated, because the handle of the ComLogicalLink is no longer valid.

If PDUGetEventItem was used, the returned event item will remain “reserved” by the application. PDUDestroyItem will release any “reserved” memory. The ComLogicalLink is disconnected from the physical resource. The D-PDU API releases the physical resource from the ComLogicalLink. The hCLL handle loses its validity. During this function call no other event items will be queued.


Shared resource behaviour

In the case of a shared resource the physical ComParameters remain unchanged. If the sharing ComLogicalLinks are not in the PDU_CLLST_OFFLINE state, the physical resource remains connected to the physical bus. Any lock on the physical ComParameters and/or the physical transmit queue will be automatically removed. A change in lock status will determine an information callback to the shared ComLogicalLinks.

Non-shared resource behaviour

If the resource is not shared by other ComLogicalLinks, then it becomes available to the whole system (PDU_RSCST_AVAIL_NOT_IN_USE).

57

Return values





PDU_ERR_INVALID_HANDLE Invalid MVCI Protocol Module or ComLogicalLink handle



Table 25: PDUDestroyComLogicalLink return values

58

7.1.3.20 PDUConnect

Syntax EXTERNC T_PDU_ERROR PDUConnect(UNUM32 hMod, UNUM32 hCLL)

Parameters


hCLL Handle of ComLogicalLink to be connected to the vehicle interface.


This function physically connects a ComLogicalLink to the vehicle interface. When the function is called the communication state of the ComLogicalLink must be "offline". After execution, the state changes to "online". The function must be called before executing any communication to the vehicle ECU. When the function is called all input parameters are validated. ComParameters are copied from the working buffer into the active buffer. The physical ComParameters, that have been locked, are not changed. If there are one or more physical ComParameters, which do not match the actual list of locked physical ComParameters, an error event item is generated for the ComLogicalLink (PDU_ERR_EVT_RSC_LOCKED). Even in this non-matching case the ComLogicalLink will still transition to the ONLINE state. The working table of Unique Response Identifiers is added into the active table. ComLogicalLink filters are configured and enabled. The URID table is used for the filter configuration, except in the case the client application has configured filters prior to PDUConnect. This may be done by calling any of the following PDUIoctl functions: PDU_START_MSG_FILTER, PDU_CLEAR_MSG_FILTER, and PDU_STOP_MSG_FILTER. Any client application configuration will override any D-PDU API internal configuration using the URID table. Next follows the physical connection to the vehicle bus, which must not be done during PDUConnect or when a PDU_COPT_STARTCOMM is required to obtain the physical bus parameters. The function call concludes with the state of the ComLogicalLink changing to PDU_CLLST_ONLINE. Also an event is generated indicating the new state.

59

Return values






PDU_ERR_CLL_CONNECTED ComLogicalLink is already in the “online” state



Table 26: PDUConnect return values

60

7.1.3.21 PDUDisconnect

Syntax EXTERNC T_PDU_ERROR PDUDisconnect(UNUM32 hMod, UNUM32 hCLL )

Parameters


hCLL Handle of ComLogicalLink to be disconnected to the vehicle interface


The function will physically disconnect the ComLogicalLink from the vehicle interface. No more communication to the vehicle ECU will take place. When the function is called, the state of the ComLogicalLink must be "online" or "com_started”. After the function is executed, the communication state changes to "offline".

When the function is called input parameters are validated. The ComLogicalLink will be set to “disconnected” in the internal resource table, so that no other new ComPrimitives will be initiated. The active ComPrimitives and the idle ones found in the ComPrimitive queue will be cancelled. The ComParameter values and ComLogicalLink filters will not be reset to their default values. They are maintened for a future reconnection. The ComLogicalLink is physicaly disconnected from the resource and the resource is released. Behaviour in case of shared resources

The physical ComParameters remain unchanged, if the resource is shared by another ComLogicalLink. The physical resource remains connected to the physical bus, if the resource is shared by another ComLogicalLink. This is valid only if the sharing ComLogicalLinks are NOT in the PDU_CLLST_OFFLINE state. The lock will automatically be removed, if the ComLogcialLink had a lock on the physical ComParameters and/or the physical transmit queue. Any change in the lock status is indicated to the shared ComLogicalLinks through an information callback.

61

Return values








PDU_ERR_CLL_NOT_CONNECTED ComLogicalLink is not connected

Table 27: PDUDisconnect return values

62

7.1.3.22 PDUGetTimestamp

Syntax EXTERNC T_PDU_ERROR PDUGetTimestamp(UNUM32 hMod, UNUM32 *pTimestamp)

Parameters

hMod Handle of MVCI Protocol Module for which the timestamp is to be requested.

pTimestamp Call-by-reference place for storing timestamp in microseconds.


The current time (derived directly from the hardware clock) is obtained from a MVCI Protocol Module. Timestamps are internally generated based on the value of this time. The timestamps are returned by PDUGetStatus and have the same unit and resolution as the hardware clock. When the function is called all input parameters are validated; pointer parameters cannot be NULL. The latest status information for the specified handle (Module) is returned and stored in the memory allocated by the client application.

Return values





PDU_ERR_INVALID_PARAMETERS pTimestamp is invalid ( NULL )

PDU_ERR_COMM_PC_O_VCI_FAILED Communication between host and MVCI Protocol Module was not successful



Table 28: PDUGetTimestamp return values

63

7.1.3.23 PDUGetComParam

Syntax EXTERNC T_PDU_ERROR PDUGetComParam( UNUM32 hMod, UNUM32 hCLL, UNUM32 ParamId, PDU_PARAM_ITEM **pParamItem)

Parameters


hCLL Handle of ComLogicalLink for which the ComParameter is to be requested.

ParamId ID value of the ComParam, which is to be requested. The ComParameter’s IDs are specified in the MDF file.

pParamItem Call-by-reference place for storing the item with the requested ComParameter from the MDF file according to the specified ParamId. The PDUDestroyItem function will release the item from the application after use.


The function obtains from the working buffer a value for a communication or a bus ComParameter. This value is the same as the value, that would be found in the MVCI Protocol Module after executing all previous ComPrimitives from the ComPrimitive queue and taking into consideration changes made by the logical link via PDUSetComParam.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. Memory is allocated for the PDU_PARAM_ITEM result. The ComParameter information is filled from the ComParameter working buffer.

Return values





PDU_ERR_INVALID_HANDLE MVCI Protocol Module Handle or ComLogicalLink handle is invalid

PDU_ERR_INVALID_PARAMETERS ComParameter ID or pointer for pParamItem is invalid (NULL)


PDU_ERR_COMPARAM_NOT_SUPPORTED ComParameter is not supported, e.g., because it is of type PDU_PS_ECU, PDU_PS_OPTIONAL or PDU_PC_UNIQUE_ID

Table 29: PDUGetComParam return values

64

7.1.3.24 PDUSetComParam

Syntax EXTERNC T_PDU_ERROR PDUSetComParam( UNUM32 hMod, UNUM32 hCLL,

PDU_PARAM_ITEM *pParamItem)

Parameters


hCLL Handle of ComLogicalLink for which the ComParameter shall be set.

pParamItem ComParameter item structure with the ComParameter element to be set. Obtained by calling PDUGetComParam(). Before calling this function the structure has to be filled with the desired ComParameter value (min value, max value and default value) by the application. This value information is taken from the MDF file by the application.


The function transfers a ComParameter setting to the D-PDU API for the specified ComLogicalLink. The ComParameter is stored in a working buffer ComParameter set. By calling several times PDUSetComParam, multiple ComParameter changes can be obtained. The working buffer ComParameter set holds all ComParameter changes. It becomes active for the ComLogicalLink in the case PDUConnect is called or when a ComPrimitive of type PDU_COPT_UPDATEPARAM is issued. For individual ComPrimitives a temporary set of ComParameter changes may be used.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. The parameter data are copied to the ComParameter working buffer. Use Case specific behaviour

Use Case: "ComLogicalLink, not connected":

- After the function call PDUConnect the information of the ComParameter working buffer will be moved to the ComParameter active buffer.

Use Case: "ComLogicalLink, connected":

- When PDUStartComPrimitive of type PDU_COPT_UPDATEPARAM is called, the working buffer is copied to the queued active buffer. Also the ComPrimitive is queued in the ComLogicalLink’s internal ComPrimitive Queue.

- When the ComPrimitive starts execution (a ComPrimitive event of PDU_COPST_EXECUTING type) the ComParameter queued active buffer will be moved to the ComLogicalLinks active buffer.

65

- If the state of the ComLogicalLink is PDU_CLLST_COMM_STARTED and tester present handling is activated, any change of tester present ComParameters determines the tester present message to be sent immediately (before the initial tester present cyclic time).

- Before any transmission the protocol handler must wait for P3Min time.

Use Case: "ComLogicalLink, connected" and ComPrimitive active with enabled TempParamUpdate-Flag:

- The ComParameters from the working buffer are used by this ComPrimitive until the ComPrimitive is finished; the ComParameters from the active buffer will NOT be used.

- Even if the “Active” or “Working” buffers are modified by any subsequent calls to the PDUSetComParam function, the ComParameters for the ComPrimitive will not change.

- When the PDUStartComPrimitive function call returns, the ComParameter Working Buffer is restored to the Active Buffer.

- The TempParamUpdate Flag can not be used to change Physical ComParameters.

Use Case: Change of Physical BusType ComParameter:

- A PDU_PC_BUSTYPE ComParameter is of physical type. For each physical resource there is only one set of physical ComParameters. This is why they cannot be changed temporarily using the TempParamUpdate Flag.

- The physical ComParameters may be modified by any ComLogicalLink that shares the physical resource.

- If PDULockResource is used by a ComLogicalLink, that ComLogicalLink will have exclusive rights to modify the physical ComParameters for the resource. Any other modifications brought by another ComLogicalLink, after a PDU_COPT_UPDATEPARAM ComPrimitive, will determine the D-PDU API to generate an error event item (PDU_ERR_EVT_RSC_LOCKED). The error event reports, that the requested change operation is not possible.

Use Case: Change of Unique ID Type ComParameter:

- Changes to PDU_PC_UNIQUE_ID ComParameters are not allowed via the PDUSetComParam function. Only the API functions PDUSetUniqueRespIdTable and PDUGetUniqueRespIdTable are allowed to use this type of ComParameter.

Use Case: Change of Tester Present (PDU_PC_TESTER_PRESENT) Type ComParameter:

- PDU_PC_TESTER_PRESENT ComParameters cannot be modified temporarily by using the TempParamUpdate flag in the PDU_COP_CTRL_DATA data structure. After enabling tester present handling the message is sent immediately before the initial tester present cyclic time (CP_TesterPresentTime) expires. After the initial transmission the periodic transmission of tester present messages begins.

66

Return values






PDU_ERR_COMPARAM_NOT_SUPPORTED ComParameter is not supported, (e.g. type PDU_PC_UNIQUE_ID)


PDU_ERR_INVALID_PARAMETERS One of the following invalid conditions: -Invalid ComParameter ID -Invalid ComParameter data structure -pParamItem NULL pointer -Defined ComParameter value cannot be supported by the MVCI Protocol Module hardware/software

Table 30: PDUSetComParam return values

67

7.1.3.25 PDUGetUniqueRespIdTable

Syntax EXTERNC T_PDU_ERROR PDUGetUniqueRespIdTable(UNUM32 hMod, UNUM32 hCLL, PDU_UNIQUE_RESP_ID_TABLE_ITEM **pUniqueRespIdTable)

Parameters


hCLL Handle of ComLogicalLink.

pUniqueRespIdTable

Call-by-reference place for storing the Unique Response ID Table for the ComLogicalLink; after use PDUDestroyItem will release the item allocated by the D-PDU API.


The function returns information of all unique response identifiers configured for the ComLogicalLink. Each unique response identifier is associated with a list of PDU_PC_UNIQUE_ID ComParameters.

If PDUGetUniqueRespIdTable is called before PDUSetUniqueRespIdTable, the returned structure contains the ComParameter information for a single unique response only. In this case the UniqueRespIdentifier is set to PDU_ID_UNDEF. Using this information the correct set of ComParameters can be determined. This set is used by the Protocol as unique ECU response identification.

PDUGetUniqueRespIdTable uses the same mechanisms for handling ComParameters in an internal working table as described for PDUGetComParams. This is because the Unique Response ID Table is a structure holding ComParameters.

PDU_PC_UNIQUE_ID ComParameters can only be used with Unique Response ID Table functions. They cannot be used with functions PDUGetComParam() or PDUSetComParam().

When the function is called all input parameters are validated; pointer parameters cannot be NULL. The PDU_UNIQUE_RESP_ID_TABLE_ITEM structure is allocated. If the table has not been previously set by PDUSetUniqueRespIdTable, then only one entry will be allocated. In this case the UniqueRespIdentifier will be PDU_ID_UNDEF. The table structure for the ComLogicalLink is filled. The table elements depend on the selected protocol for the ComLogicalLink. The number of ComParameters in the list also depends on the protocol. There can be one or more entries in the table.

68

Return values




PDU_ERR_PDUAPI_NOT_CONSTRUCTED

PDU API has not been constructed before



PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module not connected

PDU_ERR_INVALID_PARAMETERS Invalid pointer pUniqueRespIdTable (NULL)

Table 31: PDUGetUniqueRespIdTable return values

69

7.1.3.26 PDUSetUniqueRespIdTable

Syntax EXTERNC T_PDU_ERROR PDUSetUniqueRespIdTable (UNUM32 hMod, UNUM32 hCLL, PDU_UNIQUE_RESP_ID_TABLE_ITEM *pUniqueRespIdTable)

Parameters


hCLL Handle of ComLogicalLink.

pUniqueRespIdTable

Call-by-reference place which contains the Unique Response ID Table for the ComLogicalLink. The Application allocates the item.


The function sets Unique Response Id Table information for a ComLogicalLink. Any response from a specific ECU (functional or physical responses) is uniquely defined by a set of ComParameters contained in the response identifier. The UniqueRespIdentifier is assigned by the application, with a valid range of 0x0 - 0xFFFFFFFF.

The table is used to define physical responses, functional responses and monitored messages. The list of ComParameters contains all addressing type modes (functional/physical). Thus any message from a specific ECU is mapped to a unique ECU identifier. The UniqueRespIdentifier for an ECU variant can be used without the need for interpretation of protocol-specific information.

PDUSetUniqueRespIdTable handles ComParameters in an internal working Buffer (the same way PDUGetComParams does). This is because the Unique Response ID Table is a structure holding ComParameters. When executing a PDU_COPT_UPDATEPARAM ComPrimitive via the PDUStartComPrimitive function, the new table becomes active.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. All ComParameter entries in the table must be of PDU_PC_UNIQUE_ID type. The table for ECU Response Handling is stored in a working buffer. Use Case specific behaviour

Use Case: "ComLogicalLink, not connected":

- When PDUConnect is called, the Unique Response Identifer working table is moved to the active table.

Use Case: "ComLogicalLink, connected":

- When a PDU_COPT_UPDATEPARAM ComPrimitive is executing via the PDUStartComPrimitive function, the ComPrimitive is queued in the ComLogicalLink’s internal ComPrimitive Queue, and a copy of the URID Table is stored in a queued active table. For all subsequent ComPrimitives, the queued active table is used.

- When the ComPrimitive’s status changes to PDU_COPST_EXECUTING, the queued active Unique Response Identifier table will be moved to the ComLogicalLinks active table.

70

Return values





PDU_ERR_COMPARAM_NOT_SUPPORTED One of the ComParameters in the list is not of the type PDU_PC_UNIQUE_ID

PDU_ERR_INVALID_PARAMETERS The pointer pUniqueRespIdTable is invalid (NULL)


PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module not connected


Table 32: PDUSetUniqueRespIdTable return values

71

7.1.3.27 PDUStartComPrimitive

Syntax EXTERNC T_PDU_ERROR PDUStartComPrimitive(UNUM32 hMod, UNUM32 hCLL, T_PDU_COPT CoPType, UNUM32 CoPDataSize, UNUM8 *pCoPData, PDU_COP_CTRL_DATA *pCopCtrlData, void *pCoPTag, UNUM32 *phCoP )

Parameters


hCLL Handle of ComLogicalLink for which the ComPrimitive shall be started

CoPType Type of the ComPrimitive, which shall be started

CoPDataSize Size of data for the ComPrimitive; No data is supplied if the value is 0.

pCoPData Reference of the buffer holding the data; NULL in case of no supplied data

pCoPCtrlData

Pointer to the control data structure for the ComPrimitive; NULL in case of no supplied control data. The PDU_COP_CTRL_DATA structure is not used for the ComPrimitives of type PDU_COPT_UPDATEPARAM and PDU_COPT_RESTORE_PARAM.

pCoPTag Application-specific tag value, that provides additional information about the

event source. The value is bound to the ComPrimitive and provided to the application when event items are fetched from the event queue.

phCoP Call-by-reference place for storing the unique ComPrimitive handle. This handle is assigned by the D-PDU API to the new ComPrimitive.


The function creates a ComPrimitive (used for sending/receiving data) of a given type. The execution of the ComPrimitive is initiated and it depends on the ComPrimitive type and the protocol implementation. The pCoPData indicates the D-PDU data to be sent. Additional control over the execution is given by the PDU_COP_CTRL_DATA structure. Via the call-by-reference element phCoP the ComPrimitive handle (which has been assigned by the D-PDU API) is stored for further API function calls. The API function PDUGetStatus() returns the ComPrimitive's status. The status can also be retrieved as an event item. When the status of the Com Primitive is PDU_COPST_FINISHED or PDU_COPST_CANCELLED, the D-PDU API will destroy the ComPrimitive internally and no more result items will be queued for that ComPrimitive in the ComLogicalLink’s event queue. Thus no more operations can be executed for the destroyed ComPrimitive (otherwise a PDU ERROR PDU_ERR_INVALID_HANDLE is returned)

When the function is called, all input parameters are validated; required pointer parameters cannot be NULL. The state of the resource used by the ComLogicalLink is checked. If the resource is currently unavailable, an error is returned.

The ComPrimitive is placed into the ComPrimitive Queue. The correct set of ComParameters is mapped to the ComPrimitive. If the flag TempParamUpdate is not set (=value 0), the ComPrimitive uses the ComParameters from the “Active” buffer. If the flag TempParamUpdate is set (=value 1), the ComPrimitive uses the ComParameters from the “Working” buffer

72

The ComPrimitive’s ComParameters are effective until the ComPrimitive is finished or cancelled. Even modifications of the “Active” or “Working” buffer by function calls PDUSetComParam or PDUStartComPrimitive with type PDU_COPT_UPDATEPARAM will not change the active ComPrimitive’s ComParameters.

The ComPrimitive uses the UniqueRespIdTable from the “Active” table. Temporary UniqueRespIdTables are not supported. The ComPrimitive’s UniqueRespIdTable remains effective until the ComPrimitive is finished. Even modifications of the “Active” or “Working” buffer by function calls PDUSetUniqueRespIdTable or PDUStartComPrimitive with type PDU_COPT_UPDATEPARAM will not change the active ComPrimitive’s UniqueRespIdTable.

The status of ComPrimitive is set to PDU_COPST_IDLE, when it is placed in the queue.


Use Case: Initial receive handling

- The UniqueRespIdentifer table and ComParameters from the currently active SendRecv ComPrimitive are used by the transport layer for initial receive handling of frames/messages.

- The current active ComParameter buffer will be used, when the ComLogicalLink has no active SendRecv ComPrimitive.

- When the frame/message is bound to a ComPrimitive, the set of ComParameters being attached to the ComPrimitive is used for any further processing (e.g. receive timing).

Use Case: CLL State = PDU_CLLST_OFFLINE

- This is the initial state when the ComLogicalLink is created (PDUCreateComLogicalLink) and when the ComLogicalLink is disconnected from the vehicle bus (via PDUDisconnect or loss of communication to a module).

- While this state is active, no ComPrimitives can be added to the ComLogicalLink queue (result = PDU_ERR_CLL_NOT_CONNECTED).

- For ComPrimitive queueing to be allowed, the state must be PDU_CLLST_ONLINE.

Use Case: CLL State Change = (any state -> PDU_CLLST_OFFLINE)

- This state transition is made after a successful function call to PDUDisconnect or a loss of communication to a module.

- All ComPrimitives currently executing and all ComPrimitives in the ComPrimitive queue will be cancelled. A status event item PDU_COPST_CANCELLED is generated for each active ComPrimitive for the ComLogicalLink.

- If communication to a module is lost, the event order is: PDU_COPST_CANCELLED, PDU_CLLST_OFFLINE, PDU_MODST_UNAVAIL.

Use Case: CLL State Change = (PDU_CLLST_OFFLINE -> PDU_CLLST_ONLINE)

- The transition to this state is made after a successful call of the function PDUConnect.

- For vehicle protocols that require an initialization sequence, the ComLogicalLink must be in the state PDU_CLLST_COM_STARTED to allow regular transmit operations on the vehicle bus. In this ComLogicalLink state Receive only ComPrimitives can be used to monitor the vehicle bus.

73

Use Case: CLL State Change = (PDU_CLLST_ONLINE -> PDU_CLLST_COM_STARTED)

- The state transition is made, when a ComPrimitive type PDU_COPT_STARTCOMM has been executed successfully.

- If tester present handling is enabled, the message is sent immediately, before the initial tester present cycle time. Thereafter the periodic tester present cycles begins.

- Tester Present messages are enabled in the state PDU_CLLST_COM_STARTED only.

Use Case: CLL State Change = (PDU_CLLST_COM_STARTED -> PDU_CLLST_ONLINE)

- The state transition is made after successful execution of the ComPrimitive with type PDU_COPT_STOPCOMM.

- When this ComPrimitive successfuly executes or when the ComLogicalLink transitions to PDU_CLLST_OFFLINE, all ComPrimitives currently executing and all ComPrimitives in the queue are cancelled. A status event item PDU_COPST_CANCELLED is generated for each active ComPrimitive of the ComLogicalLink.

Specific behaviour for status changes of ComPrimitives

Upon status changes of ComPrimitives, an event item is generated. The relevant use cases are described in the list below:

Use Case: ComPrimitive State Change (IDLE -> EXECUTING)

- The status of the ComPrimitive is set to PDU_COPST_EXECUTING, when a ComPrimitive is removed from the CoP Queue for execution.

- For ComPrimitives of type PDU_COPT_UPDATEPARAM the queued active buffer is copied to the ComLogicalLinks active buffer and the state is set to PDU_COPST_FINISHED.

- In the case, that the ComLogicalLink is in the state PDU_CLLST_COMM_STARTED and tester present handling is enabled, any changes to one of the tester present ComParmeters will determine the tester present message to be sent right away, before the initial tester present cyclic time.

- The protocol handler must always wait the defined P3Min time, until transmit Operation is allowed.

- For ComPrimitives of type PDU_COPT_RESTORE_PARAM, the active buffer is copied to the working buffer and the state is set to PDU_COPST_FINISHED immediately.

- If the length of a ComPrimitive’s data can not be handled by the protocol, an error event PDU_ERR_EVT_PROT_ERR is generated and the ComPrimitive’s state will change to FINISHED. A protocol handler may use defined ComParameters to validate a ComPrimitive’s size in advance. In this case it would reject a ComPrimitive due to the PDU data’s length.

74

Use Case: ComPrimitive State Change (EXECUTING -> WAITING)

- When a periodic send ComPrimitive has finished each of it’s periodic cycles, it will transition to the state PDU_COPST_WAITING.

Use Case: ComPrimitive State Change (WAITING -> EXECUTING)

- When a periodic send ComPrimitive starts it’s next transmission cycle, it will transition to the state PDU_COPST_EXECUTING.

Use Case: ComPrimitive State Change (EXECUTING -> FINISHED)

- When a ComPrimitive has finished it’s execution, it will transition to the state PDU_COPST_FINISHED.

- A periodic send ComPrimitive will transition to the FINISHED state after it’s last send cycle (for NumSendCycles > 1, but not infinite [-1] ).

- A ComPrimitive will always transition to the FINISHED state after completion of it’s operation - independent if successfuly or unsuccessfuly.

Use Case: ComPrimitive State Change (any state -> CANCELLED)

- A ComPrimitive will transition to the PDU_COPST_CANCELLED state when: o The function PDUDisconnect was called for the ComLogicalLink. o The function PDUDestroyComLogicalLink was called for the ComLogicalLink. o The function PDUCancelComPrimitive was called for the ComPrimitive. o A ComPrimitive of type PDU_COPT_STOPCOMM has completed and there

were other ComPrimitives currently executing or in the ComPrimitive queue.

Return values






PDU_ERR_TX_QUEUE_FULL The ComLogicalLink’s transmit queue is full and thus the ComPrimitive could not be queued

PDU_ERR_RSC_LOCKED_BY_OTHER_CLL The ComLogicalLink's resource is currently locked by another ComLogicalLink

PDU_ERR_INVALID_PARAMETERS Either invalid NULL pointer for phCoP, pCopData or pCopCtrlData, or the expected response structure for a ComPrimitive with (NumReceiveCycles != 0) is NULL or has 0 entries

75



PDU_ERR_TEMPPARAM_NOT_ALLOWED Physical ComParameters cannot be changed as a temporary ComParam



PDU_ERR_CLL_NOT_STARTED Communication has not been started on the ComLogicalLink yet. Thus a Send ComPrimitive cannot be accepted in this state

Table 33: PDUStartComPrimitive return values

76

7.1.3.28 PDUCancelComPrimitive

Syntax EXTERNC T_PDU_ERROR PDUCancelComPrimitive(UNUM32 hMod, UNUM32 hCLL,

UNUM32 hCoP)

Parameters


hCLL Handle of ComLogicalLink

hCoP Handle of the ComPrimitive, which shall be cancelled


The function cancels the operation being executed currently for the defined ComPrimitive.

When the function is called input parameters are validated. Then the ComPrimitive is removed from the ComPrimitive Queue. The status of ComPrimitive is set to PDU_COPST_CANCELLED. If the status of the ComPrimitive is already PDU_COPST_FINISHED, the function will return with success.

Return values





PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle, ComLogicalLink handle or ComPrimitive handle is invalid




Table 34: PDUCancelComPrimitive return values

77

7.1.3.29 PDUGetEventItem

Syntax EXTERNC T_PDU_ERROR PDUGetEventItem(UNUM32 hMod, UNUM32 hCLL,

PDU_EVENT_ITEM **pEventItem)

Parameters

hMod Handle of the MVCI Protocol Module, for which the event item shall be retrieved. If a system event item shall be retrieved, the parameter is set to PDU_HANDLE_UNDEF and the hCLL handle is ignored.

hCLL Handle of the ComLogicalLink for which the event item shall be retrieved; the value PDU_HANDLE_UNDEF is used, if an item shall be retrieved for the MVCI Protocol Module.

pEventItem Call-by-reference place for storing the pointer to the event item corresponding to the defined event, hMod and hCLL. NULL is returned, if no result item is available.


The function returns an event item data (PDU_EVENT_ITEM) for the specified event source. In order to identify the event source PDUEventItem uses a reference of an MVCI Protocol Module or ComLogicalLink as input parameter. Based on the returned event item, the application evaluates the item type. Then it can access the item-specific data.

When the function is called all input parameters are validated; pointer parameters cannot be NULL. The memory for the PDU_EVENT_ITEM data is allocated and the event item information is filled for the specified handle (Module or ComLogicalLink). The event item is allocated and managed by the D-PDU API. Thereafter the event item entry is removed from the queue. However, the memory for the item remains allocated. The function call PDUDestroyItem() is used to destroy the item.

78

Return values





PDU_ERR_CLL_NOT CONNECTED ComLogicalLink is not connected


PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for pEventItem



PDU_ERR_EVENT_QUEUE_EMPTY No more event items are available

Table 35: PDUGetEventItem return values

79

7.1.3.30 PDUDestroyItem

Syntax EXTERNC T_PDU_ERROR PDUDestroyItem( PDU_ITEM *pItem)

Parameters

pItem Pointer to the item, which shall be destroyed


The function destroys the defined item, which can be of any D-PDU API item type (the item data type has to be casted appropriately).

When the function is called all input parameters are validated; pointer parameters cannot be NULL. The type of the item, which shall be destroyed, is validated too. Thereafter the reserved memory of the item is released by the D-PDU API.

Return values





PDU_ERR_INVALID_PARAMETERS Invalid item type or the pItem parameter is NULL

Table 36: PDUDestroyItem return values

80

7.2 IOCTL commands

7.2.1 Overview

The table below lists all IOCTL commands for the D-PDU API function PDUIoctl and gives a short description. For details please refer to the D-PDU API specification [ISO 22900-2 – 9.5.1].

IOCTL short name Purpose

PDU_IOCTL_RESET Reset the MVCI Protocol Module

PDU_IOCTL_CLEAR_TX_QUEUE Clear the ComLogicalLink’s transmit queue

PDU_IOCTL_SUSPEND_TX_QUEUE Suspend the ComLogicalLink’s transmit queue and stop the queue processing. This may be helpful when filling up a ComLogicalLink's queue with ComPrimitives.

PDU_IOCTL_RESUME_TX_QUEUE Resume the ComLogicalLink’s transmit queue and start the queue processing

PDU_IOCTL_CLEAR_RX_QUEUE Clear the ComLogicalLink’s event queue

PDU_IOCTL_READ_VBATT Read the battery voltage on pin 16 of the MVCI module

PDU_IOCTL_SET_PROG_VOLTAGE Set the programmable voltage on the defined DLC connector pin (resource). In the InputData (PDU_DATA_ITEM) the voltage and pin information are specified.

PDU_IOCTL_READ_PROG_VOLTAGE Read the programmable voltage

PDU_IOCTL_GENERIC Provides the functionality to exchange generic data between application and MVCI module. Thus supplier specific MVCI module functionality can be controlled.

PDU_IOCTL_SET_BUFFER_SIZE Sets the buffer size limit

PDU_IOCTL_START_MSG_ FILTER Starts filtering of received messages on the defined ComLogicalLink.

PDU_IOCTL_STOP_MSG_FILTER Stops the defineded filter

PDU_IOCTL_CLEAR_MSG_FILTER Clears all defined message filters for the specific ComLogicalLink

PDU_IOCTL_SET_EVENT_QUEUE_ PROPERTIES

Sets parameters for a ComLogicalLink’s event queue

PDU_IOCTL_GET_CABLE_ID Get the cable Id information of the cable, which is currently connected to the MVCI module

PDU_IOCTL_SEND_BREAK Generates a UART break signal on the defined ComLogicalLink

PDU_IOCTL_READ_IGNITION_SENSE_STATE Reads the current ignition sense state from the defined pin on the vehicle connector

Table 37: D-PDU API IOCTL commands

81

7.2.2 Details

The D-PDU API IOCTL commands are described in detail in the D-PDU API specification [ISO 22900-2 – 9.5.1].

7.2.2.1 PDU_IOCTL_RESET

This command is used to reset the MVCI Protocol Module with the specified handle. The handle is used as a parameter in the PDUIoctl() function. The command is executed synchronously (returns after finishing the reset procedure).

InputData: NULL

OutputData: NULL

When the command is used:

All activities currently being executed by the MVCI Protocol Module are cancelled (without proper termination).

All existing ComLogicalLinks are suspended and receive and transmit queues are cleared.

All associated ComPrimitives and received data items are destroyed. All existing ComLogicalLinks are destroyed. All hardware properties of the MVCI Protocol are reset to the default settings.

After the command has finished, the MVCI Protocol Module is in initial state with a timestamp base being reset to zero.

The command will not affect the resource table which is set up after the start up of the module. Because of this fact, the a PDUConstruct function call is not necessary after a reset command.

Return Value Description

PDU_STATUS_NOERROR Function call successful.

PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API construct has not been called before



PDU_ERR_FCT_FAILED Reset command failed

Table 38: PDU_IOCTL_RESET return values

82

7.2.2.2 PDU_IOCTL_CLEAR_TX_QUEUE

This command is used to clear the transmit queue of the ComLogicalLink with the handle being passed as parameter to the PDUIoctl() function.


All ComPrimitive items are destroyed internally in the D-PDU API. If destroyed ComPrimitive items are being called by the application an error will be

reported.

InputData: NULL

OutputData: NULL

The command PDU_IOCTL_SUSPEND_TX_QUEUE shoud be executed before PDU_IOCTL_CLEAR_TX_QUEUE in order to avoid an overlapping of operations of queue processing and queue clearing.




PDU_ERR_INVALID_HANDLE Invalid ComLogicalLink handle

PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol Module failed


Table 39: PDU_IOCTL_CLEAR_TX_QUEUE return values

83

7.2.2.3 PDU_IOCTL_SUSPEND_TX_QUEUE

This command is used to suspend the transmit queue's processing for the ComLogicalLink with the handle, which has been passed as parameter to the PDUIoctl() function.

InputData: NULL

OutputData: NULL

If the command is executed before a PDU_IOCTL_RESUME_TX_QUEUE command, a steady processing of ComPrimitives can be achieved by filling up the ComLogicalLink's queue with ComPrimitives to be processed sequentially with minimum time delay.




PDU_ERR_INVALID_HANDLE ComLogicalLink handle is invalid



Table 40: PDU_IOCTL_SUSPEND_TX_QUEUE return values

84

7.2.2.4 PDU_IOCTL_RESUME_TX_QUEUE

This command is used to resume the transmit queue's processing for the ComLogicalLink with the handle, which has been passed as parameter to the PDUIoctl() function.

InputData: NULL

OutputData: NULL







Table 41: PDU_IOCTL_RESUME_TX_QUEUE return values

85

7.2.2.5 PDU_IOCTL_CLEAR_RX_QUEUE

This command is used to clear the event queue for the ComLogicalLink, which handle is passed as an input parameter to the PDUIoctl() function.


All event items in the event queue of the ComLogicalLink are cleared and automatically destroyed. These event items are result data, information about errors or status changes.

PDUDestroyItem is internally called by the D-PDU API for each item in the event queue.

InputData: NULL

OutputData: NULL







Table 42: PDU_IOCTL_CLEAR_RX_QUEUE return values

86

7.2.2.6 PDU_IOCTL_READ_VBATT

This command is used to read the voltage on pin 16 of the MVCI Protocol Module's connector. The handle is used as a parameter of the PDUIoctl() function. The voltage is written to the UNUM32 value (4 data bytes) of the PDU_DATA_ITEM structure. It is used as InputData by reference.

InputData: NULL

OutputData: Value settings for PDU_DATA_ITEM

ItemType PDU_IT_IO_UNUM32

pData UNUM32 Vbat_mv; /* vehicle battery in mv */




D-PDU API construct has not been called before.

PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle is not valid.

PDU_ERR_COMM_PC_TO_VCI_FAILED

Communication between host and MVCI Protocol Module was not successful.

PDU_ERR_INVALID_PARAMETERS

At least one of the parameters is invalid (pInputData and/or pOutputData)

PDU_ERR_FCT_FAILED Command failed.

Table 43: PDU_IOCTL_READ_VBATT return values

87

7.2.2.7 PDU_IOCTL_SET_PROG_VOLTAGE

This command is used to set the programmable voltage on the specified Pin of the DLC connector. The handle is used as a parameter of the PDUIoctl() function.

PDU_DATA_ITEM contains information about the voltage and pin. PDU_DATA_ITEM is passed as InputData.

Valid range of values is: 5000mV - 20000mV (limited to 100 mA with a resolution of +/-100 millivolts).

InputData: Value settings for PDU_DATA_ITEM

ItemType PDU_IT_IO_PROG_VOLTAGE

pData pointer PDU_IO_PROG_VOLTAGE_DATA structure

OutputData: NULL

PDU IOCTL programming voltage description

Coded value of voltage Meaning

0x00001388 – 0x00004E20 5000 mV – 20000 mV

0xFFFFFFFE SHORT_TO_GROUND (zero impedance)

0xFFFFFFFF VOLTAGE_OFF (high impedance)





PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink handle is invalid.


At least one of the parameters is invalid (pInputData and/or pOutputData)

PDU_ERR_RESOURCE_BUSY Resource is busy; the application has to execute the command again.


PDU_ERR_VOLTAGE_NOT_SUPPORTED

The voltage is not supported by the MVCI Protocol Module.



PDU_ERR_MUX_RSC_NOT_SUPPORTED

The specified pin / Resource are not supported by the MVCI Protocol Module.

Table 44: PDU_IOCTL_SET_PROG_VOLTAGE return values

88

7.2.2.8 PDU_IOCTL_READ_PROG_VOLTAGE

This command is used to read the feedback of the programmable voltage from the voltage source. The voltage source is set by the command PDU_IOCTL_SET_PROG_VOLTAGE. The MVCI Protocol Module handle is passed as parameter to the PDUIoctl() function.

The PDU_DATA_ITEM structure passed as InputData by reference contains the voltage written as an UNUM32 value (4 data bytes).

InputData:



pData UNUM32 ProgVoltage_mv; /* programming voltage in mv */





PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink handle is invalid.




At least one of the parameters is invalid (pInputData and/or pOutputData).


Table 45: PDU_IOCTL_READ_PROG_VOLTAGE return values

89

7.2.2.9 PDU_IOCTL_GENERIC (currently not supported)

A generic message is sent by the application to its drivers, passing the Data buffer down to the associated MVCI Protocol Module hardware. The message is neither intercepted nor interpreted.

The PDU_DATA_ITEM structure has the element "Data" as a free form buffer of bytes. The structure is passed as InputData by reference.


ItemType PDU_IT_IO_BYTEARRAY

pData pointer PDU_IO_BYTEARRAY_DATA structure

OutputData: NULL



PDU_ERR_INVALID_PARAMETERS At least one of the parameters is invalid (pInputData and/or pOutputData).



Table 46: PDU_IOCTL_GENERIC return values

90

7.2.2.10 PDU_IOCTL_SET_BUFFER_SIZE (currently not supported)

This command sets the maximum buffer size of the received PDU on a ComLogicalLink. Its value is specified in the UNUM32 value (4 data bytes) of the PDU_DATA_ITEM structure being passed as InputData by reference.


ItemType PDU_IT_ IO_UNUM32

pData UNUM32 MaxRxBufferSize; /* maximum size of a received PDU for the ComLogicalLink */

OutputData: NULL







Table 47: PDU_IOCTL_SET_BUFFER_SIZE return values

91

7.2.2.11 PDU_IOCTL_START_MSG_FILTER

This command starts filtering incoming messages for the specified ComLogicalLink.

Each ComLogicalLink can support a minimum of 64 filters. All the defined message filters of a ComLogicalLink are deleted by calling

PDUDestroyComLogicalLink Only when the ComLogicalLink is in PDU_CLLST_ONLINE state the filtering becomes

active. If there are no filters configured by the application, the D-PDU API automatically

determines a set of filters by using the PDU_PC_UNIQUE_ID ComParameters configured for the ComLogicalLink.

If there are filters set by the application using the IOCTL filter commands they will override any filters internally configured by the D-PDU API.

All Protocols:

Pass filters and block filters will be applied to all received messages, but not to indications or loopback messages.

Messages that match a pass filter can still be blocked by a block filter.

For ISO 15765:

Pass filters and block filters are applied to CAN ID filtering, but not to indications or loopbacks of CAN IDs.

The UniqueRespIdTable is used for USDT/UUDT frame handling plus flow control and extended address handling.


ItemType PDU_IT_ IO_FILTER

pData pointer PDU_IO_FILTER_LIST structure

OutputData: NULL





PDU_ERR_INVALID_HANDLE ComLogicalLink handle is invalid.


Communication between host and MVCI Protocol Module was not sucessful.




Table 48: PDU_IOCTL_START_MSG_FILTER return values

92

7.2.2.12 PDU_IOCTL_STOP_MSG_FILTER

This command removes the specified filter from the ComLogicalLink.



pData UNUM32 FilterNumber; /* Filter Number to stop */

OutputData: NULL









At least one of the parameters is invalid (pInputData and/or pOutputData) or the Filter Number is invalid.


Table 49: PDU_IOCTL_STOP_MSG_FILTER return values

93

7.2.2.13 PDU_IOCTL_CLEAR_MSG_FILTER

This command removes all message filters from the ComLogicalLink.

InputData: NULL

OutputData: NULL






PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol Module was not successful.


Table 50: PDU_IOCTL_CLEAR_MSG_FILTER return values

94

7.2.2.14 PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES (currently not supported)

This command sets the properties of the ComLogicalLink event queue.

There are two properties associated with an event queue: - the event queue size - the queuing mechanism to be used

The command must be used before calling the PDUConnect function. A PDU_ERR_CLL_CONNECTED error will be returned by the function if the ComLogicalLink is already connected.

In case of the ComLogicalLink reaches the maximum size of the event queue the behaviour of the queuing mechanism is set by the queue mode.

There are three types of queue modes:

Queue Mode Type Description

Unlimited Mode This is the Default Mode for the ComLogicalLink. Memory is allocated for every item being placed on the event queue. The QueueSize is ignored.

Limited Mode The ComLogicalLink’s event queue has a maximum size. When this value is reached no new items will be placed on the event queue and the new items are discarded.

Circular Mode When the maximum size of the ComLogicalLink’s event queue is reached, then the oldest event item in the queue is deleted. In this way the new event items will be placed in the event queue.

PDU_EVT_DATA_LOST event is generated when the maximum size of the ComLogicalLink’s event queue is reached and no result items are created. This means that no PDU_IT_ERROR items are placed on the event queue.


ItemType PDU_IT_ IO_EVENT_QUEUE_PROPERTY

pData pointer PDU_IO_EVENT_QUEUE_PROPERTY_DATA structure

OutputData: NULL





PDU_ERR_INVALID_HANDLE Invalid ComLogicalLink handle.

PDU_ERR_CLL_CONNECTED ComLogicalLink is already in the “online” state.



Table 51: PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES return values

95

7.2.2.15 PDU_IOCTL_GET_CABLE_ID (currently not supported)

This command informs the application which cable is currently connected to a MVCI Protocol Module.

InputData: NULL



pData UNUM32 CableId; /* Cable Id from CDF */

Having the cable ID, from the CDF file more information can be obtained, like short name, description and DLCType (connector type).





PDU_ERR_CABLE_UNKNOWN Cable is unknown.

PDU_ERR_NO_CABLE_DETECTED No cable is detected.




PDU_ERR_FCT_FAILED The MVCI Protocol Module doesn’t support cable detection.

Table 52: PDU_IOCTL_GET_CABLE_ID return values

96

7.2.2.16 PDU_IOCTL_SEND_BREAK (currently not supported)

This command is used to send a break signal on the ComLogicalLink.

This type of signal can only be sent on certain physical layers. A PDU_ERR_FCT_FAILED is returned if the link does not support the break feature.

- UART Break signals are longer than the time it takes to send a complete byte plus Start, Stop and Parity bits and are caused by sending continuous (0) values (no Start or Stop bits). In case the UART cannot distinguish between a Framing Error and a Break, the Framing Error detection is used to identify Breaks.

- The timing of the transition from active to passive determine a SAE J1850 Break signal and must be longer than 240µs. No maximum length is specified but it must not be excessively long.

The ComLogicalLink's handle is passed as a parameter to the PDUIoctl() function.

InputData: NULL

OutputData: NULL






PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol Module was not successful.


Table 53: PDU_IOCTL_SEND_BREAK return values

97

7.2.2.17 PDU_IOCTL_READ_IGNITION_SENSE_STATE

This command is used to read the Switched Vehicle Battery Voltage (Ignition on/off) pin (pin number is 24 of the MVCI module chassis connector for ISO 22900-1) and determine the state of the ignition switch.

If the DLC pin number is 0 it means that the Switched Vehicle Battery Voltage will be read from the MVCI Protocol Module pin 24 and not from a DLC pin.

In order to determine the state of the ignition the permanent positive battery voltage from the vehicle is first read (UBATvehicle (pin 16 on the DLC)) and then the specified switched vehicle battery voltage pin. Ignition ON will be +/- 2 volts of the permanent vehicle battery voltage



pData UNUM32 DLCPinNumber; /* Pin number of the vehicles data link connector which contains the vehicle switched battery voltage. If DLCPinNumber = 0, then the ignition sense is routed to pin 24 of the MVCI Protocol Module*/



pData UNUM32 IgnitionState; /* Evaluated state of switched vehicle battery voltage. 0 = Ignition OFF 1 = Ignition ON*/










Table 54: PDU_IOCTL_READ_IGNITION_SENSE_STATE return values

98

7.3 Data types and structures

The D-PDU API data types and structures are described in detail in the D-PDU API specification [ISO 22900-2 – 11.1]. For additional information of D-PDU API applications with data types, structures and error codes, see the PDUAPI_Demonstrator\PDU_API.h headerfile.

7.4 Limitations

The table below lists the functionality and limitations of the Softing D-PDU API implementation.

Functionality Support and Limitations Notes

Supported VCIs Softing EDICcard2, EDICpci, EDUCusb, EDICblue, EDICwlan, EDICnet

Softing CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE, CANusb

Number of VCIs per system

Unlimited Number depends on system memory and performance

Supported protocols KWP2000 on CAN

KWP2000 on K-Line

ISO UDS on CAN

ISO RAW CAN

ISO OBD on CAN

ISO OBD on K-Line

For more information to the supported protocols see the corresponding protocol documentation.

Number of multiple parallel ComLogicalLinks per VCI and BusType

32 ComLogicalLinks for CAN protocols per can bus

1 ComLogicalLink for K-Line protocols per UART

The ISO RAW CAN protocol only supports 16 ComLogicalLinks

Number of multiple parallel ComPrimitives per ComLogicalLink

Not supported

Table 55: D-PDU API implementation limitations

99

100

The table below lists restrictions of the current D-PDU API implementation.

Functionality Restrictions of current implementation

IOCTL commands The following IOCTL commands are not supported:

• PDU_IOCTL_SET_BUFFER_SIZE • PDU_IOCTL_GET_CABLE_ID • PDU_IOCTL_START_MSG_FILTER,

PDU_IOCTL_STOP_MSG_FILTER, PDU_IOCTL_CLEAR_MSG_FILTER

• PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES • PDU_IOCTL_SEND_BREAK • PDU_IOCTL_GENERIC • PDU_IOCTL_CLEAR_RX_QUEUE

Message Filtering Message filtering is not supported by the Softing D-PDU API.

ComPrimitive types and handling Periodic ComPrimitives currently not supported by the Softing D-PDU API.

Expected response handling PDU_ID_UNDEF-URID not yet fully supported by the Softing D-PDU API MVCI module management Removing and inserting of VCI module during runtime not supported; use

PDUDestruct and PDUConstruct after changes of modules.

Raw mode Raw mode is only supported for the ISO RAW CAN protocol.

Raw mode is currently not supported for diagnostic protocols.

Table 56: D-PDU API implementation restrictions

8 ComParameter reference

Communication protocols The current implementation of the Softing D-PDU API software for VCIs supports the following communication protocols:

Protocol Protocol short name

KWP2000 on CAN ISO_14230_3_on_ISO_15765_2

KWP2000 on Kline ISO_14230_3_on_ISO_14230_2

ISO UDS on CAN ISO_15765_3_on_ISO_15765_2

ISO RAW CAN ISO_11898_RAW

ISO OBD CAN ISO_OBD_on_ISO_15765_4

ISO OBD on Kline ISO_OBD_on_K_Line

Table 57: Protocol support For more information about the supported ComParamaters for these protocols, see the documentation of the protocols.

101

9 Demo and test application

Note: In case of trouble during application programming a trace mechanism can be activated. For further details please see chapter 12.3.

9.1 Demo application

To effectively support application programmers a demo application with source code is included in the D-PDU API software distribution. The demo application includes source code and workspace files for Microsoft Visual Studio 2005. The files are located in the subdirectory .\PDUAPI_Demonstrator of the installation directory. The table below lists all related files:

File name Description PDU_API.H Headerfile for D-PDU API applications with

data types, structures and error codes PDUAPI_Demonstrator.cpp Demonstrator source code PDUAPI_Demonstrator.vcproj Microsoft Visual studio project file PDUAPI_WRAPPER.H Wrapper file for D-PDU API applications with

API function prototypes (Headerfile) PDUAPI_Wrapper.cpp Wrapper file for D-PDU API applications with

API function prototypes (Sourcefile)

Table 58: Demo application files

To use the project please execute the following steps:

Make sure that the D-PDU API software is installed

Make sure that a supported VCI is installed

Make sure that a valid license is available (license file and licensed hardware)

Make sure that Microsoft Visual Studio 2005 is installed

Start Microsoft Visual Studio 2005

Load the Demonstrator project (PDUAPI_Demonstrator.vcproj)

Adapt the variable “UsedModuleIndex” at PDUAPI_Demonstrator.cpp to select the hardware interface to be used

Build the PDUAPI_Demonstrator project

Execute the PDUAPI_Demonstrator project

A command line window will appear; please enter the D-PDU API version which you want to use; use debugging functionalities of Visual Studio for detailed analysis

102

9.2 Interactive test application

The D-PDU API Test Application is an API frontend tool for the customer, which allows using the API with the D-PDU API module without programming. Thus it can be used to verify the behaviour of a D-PDU API Module, e.g. during system integration by sending and receiving of PDU data.

The current version includes the following dialogues: - PduApiTest (Main) dialog - Logical-Link dialog(s) - UniqueResponseIdTable dialog - ComParameter dialog - Transmit Flags dialog - About Softing dialog

Figure 9: D-PDU API test application

103

104

How to use the D-PDU API test application described step by step:

1. The first step is to select the PDU-API Version using the combobox “Select PDU API Version”. This is a way to test if the VCI module plus D-PDU API software was properly installed. No error should appear in the log.

2. Next follows the parsing of the MDF file. The MVCI Module Description File (MDF) describes all ComParameters, I/O controls, bus types, protocols and resources supported by a specific MVCI Protocol Module. In addition, if the D-PDU API implementation supports more than one type of MVCI Protocol Modules, the MDF may list and describe all supported modules. All definitions of ComParameters, bus types, protocols, etc., inside the configuration description files may be shared among the module definition in the same file. Please press the button “Parse MDF file” to activate the parsing process.

If the MDF.xml file of the tested module is correct and the parsing of the MDF.xml file is completed successfuly the “Select MVCI Module” combobox is filled with the PDU-API modules (VCI module names). All detected VCI modules currently connected to the PC are listed in the “Selected MVCI Module” combobox of the main dialog. For the selected D-PDU API the path of the corresponding PDUAPI.dll, MDF.xml and CDF.xml files are displayed in the log window of the main dialog. If the pdu_api_root.xml is not found or an error occurred (e.g. the path of the selected module’s MDF file is not correct), the parsing will not suceed and an error message is displayed in the log window of the dialog.

An example of a pdu_api_root.xml can be found in 12.6.

3. Now choose the interface which shall be connected and click on the “PDUModuleConnect” button. The D-PDU API function PDUModuleConnect [ISO_22900_2 – 9.4.29] will be executed.

4. After the successful execution of PDUModuleConnect with no errors in the log window the “Select Protocol”, “Select Bustype” and the “Select DLC Pin(s)” comboboxes will be filled out with the resources of the current selected module.

Choose the desired protocol, bustype and DLC Pin(s) which shall be used to create the Logical Link.

The number of matching resource IDs must be at least 1 in order to be able to create a LogicalLink. This number is displayed in the log window. If no matching resource ID is found, please adjust the settings in the comboboxes MVCI module, protocol, bustype and pins accordingly.

5. Press ”Open Loli” to create a ComLogicalLink. The LogicalLink dialog opens.

Figure 10: D-PDU API test application-Open Logical Link

Edit PDU data for the ComPrimitives

CycleTime parameter for ComPrimitves

ComPrimitive buttons

NumSendCycles

NumReceiveCycles

List of started ComPrimitives

6. ”Edit Loli Params” allows the user to modify the value of a ComLogicalLink’s ComParameter (=ComParam). Each ComParameter is individually selected and modified. Set Param is used to validate the modified value. The value must be in the range specified by the standard [ISO_22900_2 – B.5].

A complete set of ComParameter values for the current LogicalLink can be saved to a file using the “Save” button. Another option is to load a ComParameter file. If the PduApiTest.ini file is found and contains parameters for the current protocol the values are loaded, otherwise the operation is aborted and one or more error messages are added in the log window of the Logical-Link dialog.

If the ComParameter values found in the ini file are correct, the Protocol ComParameters array is updated with these values. In case of errors the Protocol ComParameters array values are

105

not changed and one or more error messages are displayed in the LogicalLink dialog’s log window. The latest used ComParameter values for the current protocol are saved automatically in the pduapitest.ini file when the Logical-Link dialog is closed.

Figure 11: D-PDU API test application-Edit ComParameters

7. The Unique Response ID table is a structure holding ComParameters, which are required to uniquely identify a connection to an ECU. They typically contain addressing information like CAN identifiers or source/target addresses. For details please see Table 59: Communication Parameters. Each Unique Response Identifier is associated with a set of ComParameters of type PDU_PC_UNIQUE_ID, used to uniquely define an ECU response.

For each protocol there is a different set of URID tables that can be loaded. The URID table values in the pduapitest.ini file will be updated when the Logical-Link dialog is closed.

Figure 12: D-PDU API test application- Edit URID Table

106

Getting the URID tables:

- If the pduapitest.ini file is found and contains URID table entries for the current protocol, then the current URID tables will be displayed in the “Edit URID Table” dialog, else a error message is added in the log window of the Logical-link.

- If no URID table was set in the D-PDU API, the returned table has UNDEF values. - If a valid URID table was set in the D-PDU API, then the returned tables have to be

identical with the ones that were previously set.

Setting the URID tables: - During the initialization of the Logical-Link dialog, if a valid URID table is found in the

pduapitest.ini file then this table will be set, otherwise the default URID table will be set.

- The URID tables in the D-PDU API can be updated each time the “Edit URID Table” dialog is closed with OK and no error was found in the tables. After the “Edit URID Table” dialog is closed the edited URID table will be copied and the new URID data structure is created.

- The new URID table is set with the PDUSetUniqueRespIdTable function, and the result is displayed in the log window.

Editing the URID tables:

- Each URID table identifier and parameter value can be edited - If an invalid URID table identifier or parameter value is edited an error message is

generated. - New URID tables and parameters can be added in the tree control using right-click

context menus. - The existing URID and parameters can be removed from the tree control with a right

mouse click. - The tables in the tree control can be saved in files with a click on the “Save” button. - The URID tables can be loaded from a file with a click on the “Load” button. - On Cancel the URID tables are not set in the D-PDU API.

Figure 13: D-PDU API test application-URID Table

107

These are the possible ComParameters that can be found in an URID table for CAN diagnostics.

ComParam Description

CP_CanPhysReqFormat CAN Id format for a physical request.

Also it is used for Flow Control Can transmission. The first entry in the URID table is default for a physical request

CP_CanPhysReqId CAN Id for physical request.


CP_CanPhysReqExtAddr Can extended address for physical request.


CP_CanRespUSDTFormat CAN Id format for a USDT response.

Usage: response handling

CP_CanRespUSDTId CAN Id for a USDT response.

Usage: response handling. Set the value to 0xFFFFFFFF, if the ComParameter shall not be used.

CP_CanRespUSDTExtAddr CAN extended address for a USDT response.

Usage: response handling.

CP_CanRespUUDTFormat CAN Id format for a UUDT response.

Used for response handling.

CP_CanRespUUDTExtAddr CAN Id extended address for a UUDT response.

Usage: response handling.

CP_CanRespUUDTId CAN Id for a UUDT response.

Usage: response handling. Set the value to 0xFFFFFFFF, if the ComParameter shall not be used.

Table 59: Communication Parameters

8. After completing these settings and PDUConnect has been called successfuly, sending and receiving of diagnostic services is possible.

When PDUConnect is called, the ComLogicalLink physically connects to the vehicle interface. The communication state of the ComLogicalLink must be "offline" when the function is called. After execution, the state changes to "online". The calling of this function is required before any communication to the vehicle ECU can take place.

9. Now ComPrimitives can be created and sent. The ComPrimitive’s behaviour can be configured using the ComPrimitive’s PDU data and control parameters in the “Edit PDU” frame of the LogicalLink dialog:

a. PDU data are directly defined at the “Edit PDU”combobox. Previously defined data combination can be recalled using the combobox list values.

b. TX Count defines the number of send operations (=”NumSendCycles”)

c. RX Count defines the number of receive operations (=”NumReceiveCycles”)

d. Cycle Time defines the time interval for cyclic operations (=”CycleTime”)

108

e. TempParamUpdate allows to use an updated set of ComParameter just for the next ComPrimitive. The ComParameters are defined using the “EditLoliParams” dialog.

f. Edit Tx Flags allows to specify the ComParameter’s TX flag settings

Figure 14: D-PDU API test application-Transmit Flags

g. The ComParameters are created using the buttons in the “ComPrimitives” frame. For each ComParameter type a specific button exists:

STARTCOMM

The STARTCOMM ComPrimitive initializes the diagnostic communication with the ECU and starts tester present messages according to the ComParameter settings.

SEND/RECEIVE

SEND/RECEIVE ComPrimitives are used for generic communication operations. In combination with the ComPrimitive control parameters described above, the following communication patterns can be initiated:

- SEND ONLY (NumReceiveCycles = 0)

The ComPrimitive is considered to be a send only ComPrimitive if the number of receive cycles is equal to zero and the number of send cycles is not equal to zero.

- RECEIVE ONLY (NumSendCycles = 0)

The ComPrimitive is considered to be a receive only ComPrimitive if the number of send cycles is equal to zero and the number of receive cycles is not equal to zero. In this case, the value NumReceiveCycle is used to identify messages that match the ExpectedResponseStructure by monitoring the vehicle bus.

- SEND and RECEIVE (NumReceiveCycles!= 0 NumSendCycles!= 0)

In this case, each time the ComPrimitive is sent, it will try to deliver the number of responses specified in NumReceiveCycles. If this receive cycles number is not reached before a receive timeout occurs, an error event is generated by the ComPrimitive. The error event indicates that a receive timeout occurred. A cyclic transmission continues even after a receive timeout occured. The periodic ComPrimitive will not transition to PDU_COPST_FINISHED by itself.

109

- IS-MULTIPLE Multiple Expected Responses (NumReceiveCycles = -2),

The receive timer is reset every time a received message matches the ExpectedResponseStructure. If there is no matching in the given time span an error event is generated. No error is generated if at least one matching response was received until the receive timeout occurs.

- IS-CYCLIC Infinite Responses (NumReceiveCycles = -1),

The ComPrimitive is placed into a receive only mode after the ComLogicalLink finishes the transmission and receives the first positive response. In this mode responses are still received from the cyclic ComPrimitive while other ComPrimitives can be transmitted. The ComPrimitive status changes to PDU_COPST_FINISHED if there is a cyclic receive timeout. If no receive timeout occurs, the application must use PDUCancelComPrimitive in order to stop and finish the ComPrimitive.

The ComPrimitive transitions to PDU_COPST_FINISHED and the status item is placed on the ComLogicalLink’s Event Queue once all the expected responses are received and all transmission send cycles are completed.

DELAY

The Delay ComPrimitive, causes a delay according to the given time span, before the next ComPrimitive is executed.

UPDATEPARAM

The ComParameters related to a ComLogicalLink are copied from the working buffer to the active buffer. Before the update PDUSetComParam is called, so that the values are passed to the D-PDU API, which modifies the values in the working buffer.

The working buffer holds the temporary ComParameter values. To modify the values in the working buffer the API function PDUSetComParam is used. The API function PDUGetComParam returns these values.

The values from the working buffer are not currently used for communication. These values are copied in the active buffer using the UPDATEPARAM ComPrimitive. The active buffer holds the values that are currently used for communication. All ComParameter editing is performed in the working buffer. UPDATEPARAM has the purpouse to apply these modifications. For further details please see the ISO specification ISO 22900-2.

RESTOREPARAM

The ComParameters related to a ComLogicalLink are copied from the active buffer to the working buffer. To obtain the values from the active buffer the RESTOREPARAM ComPrimitive and thereafter PDUGetComParam API function can be used.

Cancel Primitive

The ComPrimitive selected by the combobox list entry will be cancelled after pressing the “CancelPrimitive” button.

110

111

STOPCOMM

The diagnostic communication with the ECU will be stopped by sending the PDU_COPT_STOPCOMM ComPrimitive. The behaviour depends on the protocol. The ComLogicalLink’s status changes to PDU_CLLST_ONLIINE state and no further tester present messages will be sent.

10. PDUDisconnect

Physically disconnects the ComLogicalLink from the communication line. Communication resources and internal memory segments are freed. Also system-level drivers are disconnected.

11. Exit

After disconnecting (“PDUDisconnect” Button) the ComLogicalLink, it can be destroyed by pressing the “Exit” button (PDUDestroyComLogicalLink [ISO 22900-2 – 9.4.10] will be executed). The ComLogicalLink dialog will be closed afterwards.

10 D-PDU API Configuration Manager

The D-PDU API Configuration Manager, delivered with the Softing D-PDU API software enables the user to execute the basic settings in a confortable manner.

These settings include:

• Configuration of EDIC interface modules connected to the D-PDU API Software

• Testing the EDIC interface for correct installation

112

113

• Tracing of D-PDU API Function calls on different information levels

• Logging of communication data on the bus between testequipment and vehicle

11 D-PDU API Demonstrator

The demonstrator code which is available after the D-PDU API installation provides a sequence of steps that can be followed in a communication process from the initial connection to the D-PDU API Library, passing through the setting up a ComLogicalLink, starting vehicle communications and finishing with the disconnection from the D-PDU API library.

114

12 Appendix

12.1 Error codes

All error codes of the Softing D-PDU API implementation are listed in the MDF file. In addition the error codes are listed in the corresponding protocol documentation.

115

12.2 Troubleshooting

Below additional troubleshooting help is provided for possible cases, which might occur in a Softing D-PDU API software installation.

Trouble case License not found

System behaviour

Error code PDU_ERR_FUNCTION_FAILED plus the special value PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle is reported upon function call PDUCreateComLogicalLink.

Measure

For both license mechanisms a license file is used to carry the license information. The license file is distributed on the distribution CD and installed by the setup program.

To use the D-PDU API software the interface and the associated license file are required. In case of licensing via USB hardlock dongle the associated dongle has to be connected to the PC.

Notes

The license check is executed during the API function call PDUCreateComLogicalLink. In case of a missing license the function will report an error code PDU_ERR_FUNCTION_FAILED plus special value PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle. The special value is defined in file pdu_api.h as follows:

#define PDU_CLLHDL_LICENSE_CHECK_FAILED 0x80000000

For further details please see chapter 7.1.

Trouble case ComParameter not supported

System behaviour

When PDUSetComParamis called, it returns with error code PDU_ERR_COMPARAM_NOT_SUPPORTED, because the D-PDU API implementation doesn’t support the specified ComParameter.

Measure

Ignore the error and continue in your application setting the other ComParameters. Please be aware, that the specific functionality of the unsupported ComParameter will be missing. However - since only a few ComParameters are not supported at the moment - many applications can be used without implications.

Notes

Please see the respective protocol documentation for a list of supported ComParameters.

Trouble case Internal error code reported as extra error code

System ehaviour

A function call returns with additional (extra) error code described as internal error in chapter 12.1.

Measure Please check your application code and your ComParameters. If the problem still occurs, please contact Softing.

Notes

Table 60: Troubleshooting

116

12.3 Trace mechanism

Softing’s D-PDU API software implementation includes a trace mechanism on API level. When using the D-PDU API, different levels of trace information can be activated to support the user in case of errors as well as to provide full tracing information on the Softing D-PDU API software stack.

Use the Softing D-PDU API Configuration Manager to activate the API trace mechanism. It can be started from the Windows Start Menu: Start Alle Programme Softing D-PDU API for VCIs <version number> Softing D-PDU API Configuration Manager.

The resulting trace information is written to the file "Softing_PDU_API_Trace.txt. When the selected size for the trace file is reached, the file is renamed to Softing_PDU_API_TraceOld.txt and an existing *Old.txt file is overwritten.

12.4 Support and maintenance

The D-PDU API software implementation from Softing includes free installation support. Maintenance work is done in context with product release cycles. Further maintenance or application support is optional and can be offered on request.

To send support requests please use the support form our website www.softing.com.

117

http://www.softing.com/

118

12.5 Additional services

Softing customers are supported in a target-oriented manner in their projects. Engineering services for custom specific integration and design as well as consulting services are offered on request. Particularly with new projects in connection with D-PDU API, D-Server and ODX – particularly with problems on migration of old systems – Softing can implement its existing expertise to great effect.

12.6 RDF file

The RDF (root description file) is a xml file which holds information regarding every D-PDU API installed on the system. The xml tags for this file are defined in the D-PDU API specification [ISO 22900-2 – F.1].

The “SHORT_NAME” tag represent a simbolic name for the installed D-PDU API.

The three URI elements (LIBRARY_FILE URI, MODULE_DESCRIPTION_FILE URI, CABLE_DESCRIPTION_FILE URI) contain the full path to the D-PDU API dll, the MDF.xml (Module Description File) file and the CDF.xml (Cable Description File) file.

The remaining tags are not necessary.

-<MVCI_PDU_API_ROOT

- <MVCI_PDU_API>

<SHORT_NAME>EDIC_D_PDU_API_x.yy.zz </SHORT_NAME>

<DESCRIPTION>EDIC D-PDU API Implementation</DESCRIPTION>

<SUPPLIER_NAME>Softing AG</SUPPLIER_NAME>

<LIBRARY_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz /vecom/PDUAPI_SoftingAG_x.yy.zz.dll" />

<MODULE_DESCRIPTION_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz /vecom/MDF_SoftingAG_EDIC-PDU-API_x.yy.zz.xml" />

<CABLE_DESCRIPTION_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz /vecom/CDF_SoftingAG_EDIC-PDU-API_x.yy.zz.xml" />

</MVCI_PDU_API>

</MVCI_PDU_API_ROOT>

13 References and Index

13.1 References

/1/ ISO 22900-1 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 1: Hardware design requirements

/2/ ISO 22900-2 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 2: D-PDU API (Diagnostic Protocol Data Unit Application Programmer Interface)

/3/ ISO 22900-3 (DIS) Road vehicles -- Modular vehicle communication interface (MVCI) - Part 3: Server API (Application Programmer Interface)

/4/ ISO 22901-1 (DIS) Road vehicles - Open diagnostic data exchange (ODX) - Part 1: Data model specification

/5/ ISO 11898: Road vehicles - Interchange of digital information; Controller area network (CAN) for high-speed communication

Notes: The ISO specifications can be purchased at www.iso.org.

119

http://www.iso.org/

13.2 Index of figures

Figure 1: MVCI system structure 2

Figure 2: Data exchange in MVCI systems 3

Figure 3: D-PDU API products and solutions from Softing 4

Figure 4: D-PDU API system with single VCI module 13

Figure 5: D-PDU API system with multiple VCI modules from one tool supplier 14

Figure 6: D-PDU API system multiple VCI modules from different tool suppliers 14

Figure 7: D-PDU API system with 3 ComLogicalLinks on 1 resource 16

Figure 8: D-PDU API migration system example 21

Figure 9: D-PDU API test application 103

Figure 10: D-PDU API test application-Open Logical Link 105

Figure 11: D-PDU API test application-Edit ComParameters 106

Figure 12: D-PDU API test application- Edit URID Table 106

Figure 13: D-PDU API test application-URID Table 107

Figure 14: D-PDU API test application-Transmit Flags 109

120

13.3 Index of tables

Table 1: Software distribution documents 6

Table 2: Licensing model 8

Table 3: Standardized communication protocols 17

Table 4: Communication parameter table (example) 18

Table 5: Communication parameters (example) 19

Table 6: D-PDU API functions 23

Table 7: ComPrimitives 27

Table 8: PDUConstruct return values 29

Table 9: PDUDestruct return values 30

Table 10: PDUModuleConnect return values 33

Table 11: PDUModuleDisconnect return values 33

Table 12: PDURegisterEventCallback return values 34

Table 13: PDUIoCtl return values 37

Table 14: PDUGetVersion return values 38

Table 15: PDUGetStatus return values 40

Table 16: PDUGetLastError return values 42

Table 17: PDUGetObjectId return values 43

Table 18: PDUGetResourceId return values 45

Table 19: PDUGetResourceStatus return values 46

Table 20: PDUGetConflictingResources return values 48

Table 21: PDUGetModelIds return values 50

Table 22: PDULockResource return values 52

Table 23: PDUUnlockResource return values 53

Table 24: PDUCreateComLogicalLink return values 56

Table 25: PDUDestroyComLogicalLink return values 58

Table 26: PDUConnect return values 60

Table 27: PDUDisconnect return values 62

Table 28: PDUGetTimestamp return values 63

Table 29: PDUGetComParam return values 64

Table 30: PDUSetComParam return values 67

Table 31: PDUGetUniqueRespIdTable return values 69

Table 32: PDUSetUniqueRespIdTable return values 71

Table 33: PDUStartComPrimitive return values 76

Table 34: PDUCancelComPrimitive return values 77

Table 35: PDUGetEventItem return values 79

Table 36: PDUDestroyItem return values 80

121

122

Table 37: D-PDU API IOCTL commands 81

Table 38: PDU_IOCTL_RESET return values 82

Table 39: PDU_IOCTL_CLEAR_TX_QUEUE return values 83

Table 40: PDU_IOCTL_SUSPEND_TX_QUEUE return values 84

Table 41: PDU_IOCTL_RESUME_TX_QUEUE return values 85

Table 42: PDU_IOCTL_CLEAR_RX_QUEUE return values 86

Table 43: PDU_IOCTL_READ_VBATT return values 87

Table 44: PDU_IOCTL_SET_PROG_VOLTAGE return values 88

Table 45: PDU_IOCTL_READ_PROG_VOLTAGE return values 89

Table 46: PDU_IOCTL_GENERIC return values 90

Table 47: PDU_IOCTL_SET_BUFFER_SIZE return values 91

Table 48: PDU_IOCTL_START_MSG_FILTER return values 92

Table 49: PDU_IOCTL_STOP_MSG_FILTER return values 93

Table 50: PDU_IOCTL_CLEAR_MSG_FILTER return values 94

Table 51: PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES return values 95

Table 52: PDU_IOCTL_GET_CABLE_ID return values 96

Table 53: PDU_IOCTL_SEND_BREAK return values 97

Table 54: PDU_IOCTL_READ_IGNITION_SENSE_STATE return values 98

Table 55: D-PDU API implementation limitations 99

Table 56: D-PDU API implementation restrictions 100

Table 57: Protocol support 101

Table 58: Demo application files 102

Table 59: Communication Parameters 108

Table 60: Troubleshooting 116