D Pduapi Usermanual
D Pduapi Usermanual
D Pduapi Usermanual
User Manual
Version 3.6, June 2013
Preface I
Disclaimer II
1 Introduction 1
1.1 Modular vehicle communication interface concept and D-PDU API 1
1.2 D-PDU API products from Softing 4
1.2.1 D-PDU API software for vehicle communication interfaces 4
1.2.2 Diagnostic Tool Set with D-PDU API support 5
1.3 Documentation 6
1.3.1 Related standards 6
1.3.2 Further documents 6
2 System requirements 7
2.1 Hardware 7
2.2 Software 7
2.3 Licensing 8
3 Scope of delivery 9
3.1 System components 9
3.2 Configuration files 9
3.3 Applications 9
4 Installation 10
4.1 Software installation 10
4.2 Hardware installation 10
4.3 Test your installation 10
5 Uninstall 11
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!
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.
Disclaimer II
1 Introduction
1
In Figure 1 the structure of a MVCI system is depicted. It shows the system components
and corresponding ISO standards.
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.
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.
5
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.
/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.
6
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)
7
2.3 Licensing
The D-PDU API software is licensed per vehicle communication interface:
License bound to VCI Available for Softing VCIs EDICcard2, EDICpci, EDICusb,
serial number EDICblue, EDICwlan, CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE
and CANusb
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.
8
3 Scope of delivery
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.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.
10
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.
11
6 Integration of the D-PDU API
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.
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.)
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\).
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].
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:
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
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:
21
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.
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.
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.
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.
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.
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.
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
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
The PDUDestruct function call will deinitialize the D-PDU API. All internal resources are
destroyed or released.
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.
PDU_COPT_DELAY Wait the given time span before executing the next
ComPrimitive.
0x8005
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
29
7.1.3.2 PDUDestruct
Syntax
EXTERNC T_PDU_ERROR PDUDestruct()
Parameters
None
Function Description
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
Return value definition Description
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.
Function Description
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.
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.
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.
- 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)).
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
PDU_ERR_INVALID_HANDLE MVCI protocol module handle is not valid
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module is not connected
PDU_ERR_FCT_FAILED Command failed
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
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
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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
Function Description
The version information from a MVCI Protocol Module is returned.
When called the function validates all input parameters. Pointer parameters cannot be NULL.
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
PDU_ERR_INVALID_PARAMETERS pVersionData parameter is invalid ( NULL )
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink
handle is invalid
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before
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.
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before
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 Either the resource ID is invalid or one of the
reference pointers (pInputModuleList or
pOutputConflictList) are invalid (NULL).
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.
Function Description
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.
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.
- 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)).
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for pModuleList
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
Function Description
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.
- 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.
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:
- 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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
52
7.1.3.17 PDUUnlockResource
Syntax
EXTERNC T_PDU_ERROR PDUUnlockResource(UNUM32 hMod, UNUM32 hCLL,
UNUM32 LockMask)
Parameters
hMod Handle of MVCI Protocol Module.
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
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed
before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink
handle is invalid
PDU_ERR_RSC_LOCKED_BY_OTHER_CLL The requested resource is locked by a
different ComLogicalLink
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_RSC_NOT_LOCKED The resource is already in the unlocked
state
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.
Function Description
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.
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:
55
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed or no license available
(see above)
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
56
7.1.3.19 PDUDestroyComLogicalLink
Syntax
EXTERNC T_PDU_ERROR PDUDestroyComLogicalLink(UNUM32 hMod, UNUM32 hCLL)
Parameters
hMod Handle of MVCI Protocol Module.
hCLL Handle of ComLogicalLink to be destroyed.
Function Description
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.
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.
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed
before
PDU_ERR_INVALID_HANDLE Invalid MVCI Protocol Module or
ComLogicalLink handle
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI
Protocol Module was not successful
58
7.1.3.20 PDUConnect
Syntax
EXTERNC T_PDU_ERROR PDUConnect(UNUM32 hMod, UNUM32 hCLL)
Parameters
hMod Handle of MVCI Protocol Module.
hCLL Handle of ComLogicalLink to be connected to the vehicle interface.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink
handle is invalid
PDU_ERR_CLL_CONNECTED ComLogicalLink is already in the “online”
state
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI
Protocol Module was not successful
60
7.1.3.21 PDUDisconnect
Syntax
EXTERNC T_PDU_ERROR PDUDisconnect(UNUM32 hMod, UNUM32 hCLL )
Parameters
hMod Handle of MVCI Protocol Module.
hCLL Handle of ComLogicalLink to be disconnected to the vehicle interface
Function Description
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.
61
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle is invalid
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
63
7.1.3.23 PDUGetComParam
Syntax
EXTERNC T_PDU_ERROR PDUGetComParam( UNUM32 hMod, UNUM32 hCLL,
UNUM32 ParamId, PDU_PARAM_ITEM **pParamItem)
Parameters
hMod Handle of MVCI Protocol Module.
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed
before
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_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
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
64
7.1.3.24 PDUSetComParam
Syntax
EXTERNC T_PDU_ERROR PDUSetComParam( UNUM32 hMod, UNUM32 hCLL,
PDU_PARAM_ITEM *pParamItem)
Parameters
hMod Handle of MVCI Protocol Module.
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.
Function Description
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.
- After the function call PDUConnect the information of the ComParameter working
buffer will be moved to the ComParameter 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.
- 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.
66
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed
before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle or
ComLogicalLink handle is invalid
PDU_ERR_COMPARAM_NOT_SUPPORTED ComParameter is not supported, (e.g. type
PDU_PC_UNIQUE_ID)
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
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
67
7.1.3.25 PDUGetUniqueRespIdTable
Syntax
EXTERNC T_PDU_ERROR PDUGetUniqueRespIdTable(UNUM32 hMod, UNUM32 hCLL,
PDU_UNIQUE_RESP_ID_TABLE_ITEM **pUniqueRespIdTable)
Parameters
hMod Handle of MVCI Protocol Module.
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTE PDU API has not been constructed before
D
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 not connected
69
7.1.3.26 PDUSetUniqueRespIdTable
Syntax
EXTERNC T_PDU_ERROR PDUSetUniqueRespIdTable (UNUM32 hMod, UNUM32
hCLL, PDU_UNIQUE_RESP_ID_TABLE_ITEM *pUniqueRespIdTable)
Parameters
hMod Handle of MVCI Protocol Module.
hCLL Handle of ComLogicalLink.
pUniqueRespIdTable
Call-by-reference place which contains the Unique Response ID Table for the
ComLogicalLink. The Application allocates the item.
Function Description
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.
- When PDUConnect is called, the Unique Response Identifer working table is moved to
the active table.
70
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before
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_COMM_PC_TO_VCI_FAILED Communication between host and MVCI
Protocol Module was not successful
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module not connected
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
hMod Handle of MVCI Protocol Module
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.
Function Description
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.
- 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 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.
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.
- When a periodic send ComPrimitive starts it’s next transmission cycle, it will transition
to the state PDU_COPST_EXECUTING.
- 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.
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
75
Return value definition Description
PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI
Protocol Module was not successful
PDU_ERR_TEMPPARAM_NOT_ALLOWED Physical ComParameters cannot be
changed as a temporary ComParam
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle or
ComLogicalLink handle is invalid
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_CLL_NOT_STARTED Communication has not been started on the
ComLogicalLink yet. Thus a Send
ComPrimitive cannot be accepted in this
state
76
7.1.3.28 PDUCancelComPrimitive
Syntax
EXTERNC T_PDU_ERROR PDUCancelComPrimitive(UNUM32 hMod, UNUM32 hCLL,
UNUM32 hCoP)
Parameters
hMod Handle of MVCI Protocol Module
hCLL Handle of ComLogicalLink
hCoP Handle of the ComPrimitive, which shall be cancelled
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle,
ComLogicalLink handle or ComPrimitive
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_NOT_CONNECTED ComLogicalLink is not connected
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.
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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
Function Description
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
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
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].
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.
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.
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.
When the command is used:
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.
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.
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
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.
When the command is used:
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
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 */
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).
ItemType PDU_IT_IO_PROG_VOLTAGE
pData pointer PDU_IO_PROG_VOLTAGE_DATA structure
OutputData: NULL
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:
OutputData: Value settings for PDU_DATA_ITEM
ItemType PDU_IT_IO_UNUM32
pData UNUM32 ProgVoltage_mv; /* programming voltage in mv */
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.
InputData: Value settings for PDU_DATA_ITEM
ItemType PDU_IT_IO_BYTEARRAY
pData pointer PDU_IO_BYTEARRAY_DATA structure
OutputData: NULL
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.
OutputData: NULL
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.
The UniqueRespIdTable is used for USDT/UUDT frame handling plus flow control and
extended address handling.
OutputData: NULL
92
7.2.2.12 PDU_IOCTL_STOP_MSG_FILTER
OutputData: NULL
93
7.2.2.13 PDU_IOCTL_CLEAR_MSG_FILTER
InputData: NULL
OutputData: NULL
94
7.2.2.14 PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES (currently not supported)
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.
OutputData: NULL
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
OutputData: Value settings for PDU_DATA_ITEM
Having the cable ID, from the CDF file more information can be obtained, like short name,
description and DLCType (connector type).
96
7.2.2.16 PDU_IOCTL_SEND_BREAK (currently not supported)
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
ItemType PDU_IT_IO_UNUM32
pData UNUM32 IgnitionState; /* Evaluated state of switched vehicle
battery voltage.
0 = Ignition OFF
1 = Ignition ON*/
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.
99
The table below lists restrictions of the current D-PDU API implementation.
100
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
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.
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
103
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.
104
5. Press ”Open Loli” to create a ComLogicalLink. The LogicalLink dialog opens.
NumReceiveCycles
NumSendCycles
ComPrimitive buttons
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.
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.
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.
- 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.
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.
Also it is used for Flow Control Can transmission. The first entry in
the URID table is default for a physical request
CP_CanPhysReqExtAddr Can extended address for 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_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.
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
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:
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.
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
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.
111
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
112
• Tracing of D-PDU API Function calls on different information levels
113
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
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 Error code PDU_ERR_FUNCTION_FAILED plus the special value
behaviour 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:
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.
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.
117
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.
-<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>
118
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
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
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
122