Bus Custom Code Interface

Bus Custom Code Interface

Handling
Release 2024-A – May 2024
How to Contact dSPACE
Mail: dSPACE GmbH
Rathenaustraße 26
33102 Paderborn
Germany
Tel.: +49 5251 1638-0
E-mail: info@dspace.de
Web: https://www.dspace.com

How to Contact dSPACE Support

If you encounter a problem when using dSPACE products, contact your local dSPACE
representative:
§ Local dSPACE companies and distributors: https://www.dspace.com/go/locations
§ For countries not listed, contact dSPACE GmbH in Paderborn, Germany.
Tel.: +49 5251 1638-941 or e-mail: support@dspace.de

You can also use the support request form: https://www.dspace.com/go/supportrequest. If

you are logged on to mydSPACE, you are automatically identified and do not have to add
your contact details manually.

If possible, always provide the serial number of the hardware, the relevant dSPACE License
ID, or the serial number of the CmContainer in your support request.

Software Updates and Patches

dSPACE strongly recommends that you download and install the most recent patches
for your current dSPACE installation. Visit https://www.dspace.com/go/patches for the
software updates and patches themselves and for more information, such as how to
receive an automatic notification when an update or a patch is available for your dSPACE
software.

Important Notice
This publication contains proprietary information that is protected by copyright. All rights
are reserved. The publication may be printed for personal or internal use provided all the
proprietary markings are retained on all printed copies. In all other cases, the publication
must not be copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form, in whole or in part, without the prior written consent
of dSPACE GmbH.

© 2019 - 2024 by:

dSPACE GmbH
Rathenaustraße 26
33102 Paderborn
Germany

This publication and the contents hereof are subject to change without notice.

AURELION, AUTERA, ConfigurationDesk, ControlDesk, MicroAutoBox, MicroLabBox,

SCALEXIO, SIMPHERA, SYNECT, SystemDesk, TargetLink, and VEOS are registered
trademarks of dSPACE GmbH in the United States or other countries, or both. Other
brand names or product names are trademarks or registered trademarks of their respective
companies or organizations.
 Contents

Contents

About This Document 7

Basics on the Bus Custom Code Interface 9

Introduction to the Bus Custom Code Interface............................................. 10
Basic Principles of the Bus Custom Code Interface......................................... 12
Run-Time Behavior of Code That Uses Functions of the Bus Custom
Code Interface.............................................................................................. 15
Integrating Functions of the Bus Custom Code Interface in the User
Code............................................................................................................. 17
Overview of the Handles and Their Functions................................................ 20
Using Bus Custom Code Functions with Bus Implementation
Software....................................................................................................... 23
Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTrigg
ering Function in the User Code.................................................................... 26
Restrictions for Working with the Bus Custom Code Interface....................... 31

Examples of Implementing User-Specific Functionalities

via the Bus Custom Code Interface 33
Example of Implementing User-Specific PDU Functionalities via the
Bus Custom Code Interface........................................................................... 33
Example of Implementing Secure Onboard Communication (SecOC)
via the Bus Custom Code Interface................................................................ 41

API Reference of the Bus Custom Code Interface 57

Handles of the Bus Custom Code Interface............................................................. 58
DsBusCustomCodeHandle............................................................................. 58
DsBusCustomCodeCommunicationClusterHandle......................................... 59
DsBusCustomCodeEcuHandle....................................................................... 60
DsBusCustomCodePduHandle....................................................................... 60
DsBusCustomCodePduFeatureHandle............................................................ 61
DsBusCustomCodeSecOCPduFeatureHandle..................................... ............ 62
DsBusCustomCodeSecOCRxPduFeatureHandle.............................................. 64
DsBusCustomCodeSecOCTxPduFeatureHandle.............................................. 66
DsBusCustomCodeSecuredIPduHandle.......................................................... 68
DsBusCustomCodeSignalHandle....................................................... ............ 70

3
May 2024 Bus Custom Code Interface Handling
 Contents

DsBusCustomCodeUserCodePduFeatureHandle............................................. 71
DsBusCustomCodeUserPortHandle................................................................ 72

Functions of the Bus Custom Code Interface.......................................................... 74

DsBusCustomCode_getDescriptor................................................................. 78
DsBusCustomCode_getName........................................................................ 80
DsBusCustomCodePdu_getCanChannelName............................................... 81
DsBusCustomCodePdu_getCanFrameTriggering............................................ 82
DsBusCustomCodePdu_getIsTx..................................................................... 85
DsBusCustomCodePdu_getLinFrameTriggering.............................................. 86
DsBusCustomCodePdu_getSduDataPtr.......................................................... 88
DsBusCustomCodePdu_getSduLength.............................................. ............ 89
DsBusCustomCodePduFeature_getFeatureDataPtr......................................... 90
DsBusCustomCodePduFeature_getPdu.......................................................... 91
DsBusCustomCodePduFeature_setFeatureDataPtr............................. ............ 93
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffse
t.................................................................................................................... 94
DsBusCustomCodeSecOCPduFeature_getKeyAsString................................... 96
DsBusCustomCodeSecOCPduFeature_getKeyLength..................................... 97
DsBusCustomCodeSecOCPduFeature_getKeyPtr............................................ 98
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffse
t.................................................................................................................. 100
DsBusCustomCodeSecOCPduFeature_setKeyLength.................................... 102
DsBusCustomCodeSecOCPduFeature_setKeyPtr.......................................... 103
DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValu
e................................................................................................................. 105
DsBusCustomCodeSecOCRxPduFeature_getEnableVerification.......... .......... 106
DsBusCustomCodeSecOCRxPduFeature_getVerificationResult........... .......... 108
DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValu
e................................................................................................................. 109
DsBusCustomCodeSecOCRxPduFeature_setVerificationResult...................... 111
DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType........ .......... 112
DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValu
e................................................................................................................. 114
DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication............... 115
DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCal
culation....................................................................................................... 117
DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset................ 119
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticat
orPtr................................................................................................. .......... 120
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessVal
ue............................................................................................................... 121
DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValu
e................................................................................................................. 123
DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName............................ 124

4
Bus Custom Code Interface Handling May 2024
 Contents

DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength.................... 126
DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPosition. .......... 127
DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength...................... .......... 128
DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength......................... 130
DsBusCustomCodeSecuredIPdu_getAuthenticPdu....................................... 131
DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts..... .......... 132
DsBusCustomCodeSecuredIPdu_getAuthenticationRetries........................... 134
DsBusCustomCodeSecuredIPdu_getDataId.................................................. 135
DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttempts............ 136
DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFactor.......... 138
DsBusCustomCodeSecuredIPdu_getFreshnessValueId.................................. 139
DsBusCustomCodeSecuredIPdu_getFreshnessValueLength................ .......... 141
DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength....................... 142
DsBusCustomCodeSecuredIPdu_getKeyId.................................................... 143
DsBusCustomCodeSecuredIPdu_getMessageLinkLength.............................. 144
DsBusCustomCodeSecuredIPdu_getMessageLinkPosition.................. .......... 146
DsBusCustomCodeSecuredIPdu_getRxSecurityVerification........................... 147
DsBusCustomCodeSecuredIPdu_getSecuredAreaLength.............................. 149
DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset..................... .......... 151
DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWindo
w................................................................................................................ 152
DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu....................... 153
DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness......................... 155
DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp....................... 156
DsBusCustomCodeSignal_getEndianness.......................................... .......... 158
DsBusCustomCodeSignal_getLength........................................................... 159
DsBusCustomCodeSignal_getStartBitPosition.............................................. 160
DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts................ 162
DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals............. 163
DsBusCustomCodeUserCodePduFeature_getResult........................... .......... 164
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTrigg
ering........................................................................................................... 166
DsBusCustomCodeUserCodePduFeature_getUserPorts................................ 168
DsBusCustomCodeUserCodePduFeature_getUserSignals............................. 170
DsBusCustomCodeUserCodePduFeature_setResult...................................... 171
DsBusCustomCodeUserPort_getDirection.................................................... 173
DsBusCustomCodeUserPort_getPortData.................................................... 174
DsBusCustomCodeUserPort_setPortData..................................................... 176

Index 179

5
May 2024 Bus Custom Code Interface Handling
 Contents

6
Bus Custom Code Interface Handling May 2024
 About This Document

About This Document

Content Introduces you to the Bus Custom Code interface. The Bus Custom Code
interface is a common API interface provided by dSPACE that is supported
by bus implementation software, such as the Bus Manager or the FlexRay
Configuration Package. By using the Bus Custom Code interface, you can
integrate user code implementations that provide user-specific bus functionality
in bus implementation software.

This document introduces you to the fields of application and to the basic
principles of working with the Bus Custom Code interface. Additionally, it
provides reference information on the handles and functions of the Bus Custom
Code interface.

Target group This document is primarily intended for engineers who implement user-specific
bus functionality via user code implementations in bus implementation software.

Required knowledge You must be familiar with the C programming language.

Symbols dSPACE user documentation uses the following symbols:

Symbol Description
Indicates a hazardous situation that, if not avoided,
V DANGER
will result in death or serious injury.
Indicates a hazardous situation that, if not avoided,
V WARNING could result in death or serious injury.
Indicates a hazardous situation that, if not avoided,
V CAUTION could result in minor or moderate injury.
Indicates a hazard that, if not avoided, could result in
NOTICE
property damage.
Indicates important information that you should take
Note
into account to avoid malfunctions.
Indicates tips that can make your work easier.
Tip

7
May 2024 Bus Custom Code Interface Handling
 About This Document

Symbol Description
Indicates a link that refers to a definition in the
glossary, which you can find at the end of the
document unless stated otherwise.
Follows the document title in a link that refers to
another document.

Naming conventions dSPACE user documentation uses the following naming conventions:

%name% Names enclosed in percent signs refer to environment variables for

file and path names.

<> Angle brackets contain wildcard characters or placeholders for variable

file and path names, etc.

Special Windows folders Windows‑based software products use the following special folders:

Common Program Data folder A standard folder for application-specific

program data that is used by all users.
%PROGRAMDATA%\dSPACE\<InstallationGUID>\<ProductName>
or
%PROGRAMDATA%\dSPACE\<ProductName>\<VersionNumber>

Documents folder A standard folder for application‑specific files that are

used by the current user.
%USERPROFILE%\Documents\dSPACE\<ProductName>\<VersionNumber>

Local Program Data folder A standard folder for application-specific

program data that is used by the current user.
%USERPROFILE%\AppData\Local\dSPACE\<InstallationGUID>\
<ProductName>

Accessing dSPACE Help and After you install and decrypt Windows‑based dSPACE software, the
PDF files documentation for the installed products is available in dSPACE Help and as PDF
files.

dSPACE Help (local) You can open your local installation of dSPACE Help:
§ On its home page via Windows Start Menu
§ On specific content using context-sensitive help via F1

PDF files You can access PDF files via the icon in dSPACE Help. The PDF
opens on the first page.

dSPACE Help (Web) Independently of the software installation, you can

access the Web version of dSPACE Help at https://www.dspace.com/go/help.
To access the Web version, you must have a mydSPACE account.
For more information on the mydSPACE registration process, refer to
https://www.dspace.com/faq?097.

8
Bus Custom Code Interface Handling May 2024
 Basics on the Bus Custom Code Interface

Basics on the Bus Custom Code Interface

Where to go from here Information in this section

Introduction to the Bus Custom Code Interface....................................... 10

Introduces you to the Bus Custom Code interface and the supporting bus
implementation software tools.

Basic Principles of the Bus Custom Code Interface................................... 12

Introduces you to the modules of the Bus Custom Code interface, its
handles, and the syntax, data sources, and return values of its functions.

Run-Time Behavior of Code That Uses Functions of the Bus

Custom Code Interface............................................................................ 15
Provides information on the initialization phase and execution phase
of code that uses functions of the Bus Custom Code interface, and
on the execution sequence of user code and other features of bus
implementation software.

Integrating Functions of the Bus Custom Code Interface in the

User Code............................................................................................... 17
Provides an overview of the required actions for integrating functions of
the Bus Custom Code interface in the user code.

Overview of the Handles and Their Functions........................................... 20

Provides a graphical overview of the handles and functions of the Bus
Custom Code interface.

Using Bus Custom Code Functions with Bus Implementation

Software................................................................................................. 23
Provides basic information on using Bus Custom Code functions with
different bus implementation software tools and mapping between each
function and the bus implementation software with which it can be
used.

Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTri
ggering Function in the User Code.......................................................... 26
Provides detailed information on implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTrig
gering function in the user code depending on the specific use
scenario.

9
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Restrictions for Working with the Bus Custom Code Interface................. 31

Provides information on the restrictions that apply when working with
the Bus Custom Code interface.

Introduction to the Bus Custom Code Interface

Overview The Bus Custom Code interface is a dSPACE API interface that is supported
by bus implementation software, such as the Bus Manager or the FlexRay
Configuration Package. By using the Bus Custom Code interface, you can
implement user code in executable applications, i.e., in real‑time applications
and/or offline simulation applications. Via user code, you can provide
additional functionality to the bus implementation software, such as user-
specific algorithms for calculating authentication information in secure onboard
communication scenarios. However, the additionally supported functionality
depends on the specific bus implementation software.

Because the Bus Custom Code interface is supported by various dSPACE

software tools, a user code implementation can be used by all of these
dSPACE software tools and on various dSPACE platforms, such as SCALEXIO,
MicroAutoBox II/III, or VEOS.

Bus implementation software The Bus Custom Code interface is supported by bus implementation software,
supporting the Bus Custom i.e., by the following dSPACE software tools:
Code interface § ConfigurationDesk
§ Bus Manager (stand-alone)
§ RTI CAN MultiMessage Blockset
§ FlexRay Configuration Package
§ Ethernet Configuration Package

Depending on the dSPACE software tool, not all of the functionalities provided
by the Bus Custom Code interface might be supported.

User code and the Bus Custom The Bus Custom Code interface lets you implement user code and its
Code interface functionalities in executable applications, i.e., in real-time applications and/or
offline simulation applications.

User code User code is C code or C++ code that contains user-specific
algorithms. You can use user-specific algorithms to provide additional
functionality to the bus implementation software, for example, for calculating
checksum or counter signal values or generating authentication information in
secure onboard communication (SecOC) scenarios. A user code implementation
consists of one or more source files (*.c, *.cpp) and optional include files (*.h,
*.hpp).

10
Bus Custom Code Interface Handling May 2024
 Introduction to the Bus Custom Code Interface

Bus Custom Code interface The Bus Custom Code interface is a C-based
API interface provided by dSPACE. The interface is required to implement user
code and its functionalities in executable applications. In general, the Bus
Custom Code interface lets you do the following:
§ Specify a user code ID for each user code implementation. This ID is required
to unambiguously reference specific user code implementations in the bus
implementation software.
§ Initialize the functionalities provided by user code in the executable
application.
§ Exchange data between the user code and the bus implementation software,
for example, to access properties of secured IPDUs or write calculated
checksum values to ISignals of a PDU.
For more information, refer to Basic Principles of the Bus Custom Code Interface
on page 12.

Implementing user code in To implement user code in executable applications, you must extend the user
executable applications code by functions of the Bus Custom Code interface, e.g., to write data to
or read data from the user code. For more information, refer to Integrating
Functions of the Bus Custom Code Interface in the User Code on page 17.

Additionally, you must add the user code implementation (e.g., source files and
include files) to the bus implementation software. For more information, refer to:

Bus Implementation Refer to …

Software
ConfigurationDesk: Bus Working with User Code (ConfigurationDesk Bus Manager
Manager in Implementation Guide )
ConfigurationDesk
Bus Manager (stand-alone) Working with User Code (Bus Manager (Stand-Alone)
Implementation Guide )
RTI CAN MultiMessage Secure Onboard Communication Page (RTICANMM
Blockset MainBlock) (RTI CAN MultiMessage Blockset Reference )
FlexRay Configuration General Page (FlexRay Configuration Tool Reference )
Package
Ethernet Configuration Contact dSPACE Support
Package (www.dspace.com/go/supportrequest).

11
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Basic Principles of the Bus Custom Code Interface

Modules of the Bus Custom The Bus Custom Code interface is a C-based API interface that consists of three
Code interface modules:

Module Purpose
DsBusCustomCode Provides common type definitions and function declarations that are independent of a specific
use scenario.
DsBusCustomCode_SecOC Provides type definitions and function declarations that are required if you want to implement
secure onboard communication (SecOC) via user code in executable applications, i.e., in
real‑time applications and/or offline simulation applications.
DsBusCustomCode_PduUserCode Provides type definitions and function declarations that are required if you want to implement
additional PDU-based functionalities via user code in executable applications, such as user-
specific algorithms for calculating checksum signal values.

Note

The DsBusCustomCode_PduUserCode module can be used only with the Bus Manager,
i.e., only the Bus Manager can parameterize the functions of this module. You cannot
use this module with any other bus implementation software.

The following illustration provides an overview of the three modules.

DsBusCustomCode module

Common type definitions and

function declarations for:
§ Communication clusters
§ ECUs
§ PDUs
§ Signals

DsBusCustomCode_SecOC module DsBusCustomCode_PduUserCode module

Type definitions and function declarations for Type definitions and function declarations for
secured IPDUs and SecOC-related features in PDUs to use the PDU User Code feature of the
secure onboard communication scenarios Bus Manager

For an overview of the handles and functions that are provided by the modules,
refer to Overview of the Handles and Their Functions on page 20.

Addressing elements via The Bus Custom Code interface uses handles to address elements such as
handles PDUs and access their data at run time. For each element that is affected by
the user code, a unique handle is generated during the initialization phase
of the executable application (i.e., real-time application or offline simulation
application). Via these handles, functions of the Bus Custom Code interface can
get and set data, even across subsequent function calls. The generated handles
are persistent at run time.

12
Bus Custom Code Interface Handling May 2024
 Basic Principles of the Bus Custom Code Interface

Syntax of Bus Custom Code Almost all functions provided by the Bus Custom Code interface use the same
functions syntax, as shown in the following example:

/* Get the length of a PDU */

DsBusCustomCodePdu_getSduLength(pduHandle, &IPdu_SduLength);
1 2 3 4 5 6

/* Set a pointer to a user-defined data structure related to a PDU feature */

DsBusCustomCodePduFeature_setFeatureDataPtr(PduFeatureHandle, featureDataPtr);
1 2 3 4 5 6

Position Purpose
1 Constant prefix
Used by all functions of the Bus Custom Code interface.
2 Handle identification
Determines the handle type that is addressed by the function and expected as
the function's first parameter.
3 Get/set definition
Determines whether data is read from (get) or written to (set) the element
that is addressed by the function.
4 Addressed element
Determines the element that is addressed by the function and expected as the
function's second parameter.
5 First function parameter
Handle type that is expected according to position 2.
6 Second function parameter
Element that is addressed according to position 4.

Working with return values The Bus Custom Code interface provides return values that indicate whether
functions of the Bus Custom Code interface are executed correctly. For example,
the return values can indicate that a required parameter is not specified or an
addressed handle is invalid.

However, the return values of the Bus Custom Code interface do not provide
the results of user code functionalities, e.g., whether a received counter value
matches the expected counter value.

For this purpose, you can specify user-defined return values. You can pass such
user-defined return values to suitable set functions of the Bus Custom Code
interface, e.g., to the DsBusCustomCodeUserCodePduFeature_setResult
function of the DsBusCustomCode_PduUserCode module.

Parameter data of Bus Custom In general, the functions of the Bus Custom Code interface can be used for the
Code functions following purposes:
§ Exchange data between the code that is generated by the bus implementation
software and the user code.
§ Store run-time data and provide it to the user code during subsequent
function calls. In this case, the data is handled in the user code and not

13
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

directly exchanged with the bus implementation software code. For example,
this applies to data that is accessed by the user code via a data pointer.

The data that is exchanged via the bus implementation software code and the
user code can have different data sources, as shown in the following table.

Data Source Description

Communication matrix, e.g., The data is provided to the user code via the
AUTOSAR-specific attributes bus implementation software code if the following
conditions are fulfilled:
§ The required attributes and their values are
specified in the communication matrix.
§ The related bus implementation software evaluates
the required attributes.
Settings that are specified by the Depending on the settings and the bus
user in the bus implementation implementation software, the bus implementation
software, e.g., constant property software code can provide the data to the user code
values or enabled run-time as follows:
parameters § Constant value
§ TRC file variable
§ Model variable
Run-time data that is received on The bus implementation software code can pass this
the bus, e.g., current PDU data data directly to the user code.
User code, e.g., authentication Depending on the bus implementation software, the
information that is calculated in bus implementation software code can provide the
the user code received data via TRC file variables and/or model
variables to the executable application.

If a Bus Custom Code get function is called and no data source provides data to
a function parameter, the function returns PARAMETER_NOT_SET and no data is
written to the function's output parameter.

Tip

Depending on the relevance of individual Bus Custom Code functions in

your use scenario, it might be useful to specify a default value beforehand
in case a function returns PARAMETER_NOT_SET. This increases the fault
tolerance of the user code, for example, if an addressed communication
matrix attribute is not specified in the communication matrix.

Related topics Basics

Examples of Implementing User-Specific Functionalities via the Bus Custom Code

Interface................................................................................................................................... 33

14
Bus Custom Code Interface Handling May 2024
 Run-Time Behavior of Code That Uses Functions of the Bus Custom Code Interface

Run-Time Behavior of Code That Uses Functions of the Bus Custom Code
Interface

Initialization phase and In general, an initialization phase and an execution phase can be distinguished
execution phase to characterize the run-time behavior of code that uses functions of the Bus
Custom Code interface, as shown in the following illustration.

Initialization phase Execution phase

Bus implementation

1. Uses Bus Custom Code functions to set run-time

1. Uses Bus Custom Code functions to:
software code

handle data.
§ Generate handles
2. Calls the
§ Set initial values for handle parameters
DsBusCustomCode_onPduFeatureExecution
2. Calls the
function.
DsBusCustomCode_onApplicationInit
3. Uses Bus Custom Code functions to get run-time
function.
handle data.

generate/get/set get/set

onPduFeatureExecution
onApplicationInit

Code interface

Code interface
Bus Custom

Bus Custom
Implements functions for: Implements functions for:
§ Generating handles
§ Getting handle data
§ Getting handle data § Setting handle data
§ Setting handle data

get/set get/set

§ Implements the
§ Implements the DsBusCustomCode_onPduFeatureExecution
implementation

DsBusCustomCode_onApplicationInit function.
function.
User code

§ Uses Bus Custom Code functions and standard

§ Uses Bus Custom Code functions and standard C/C++ operations in this function, e.g., to:
C/C++ operations in this function, e.g., to: § Get initial and/or run-time handle data
§ Get initial handle data § Get/set data pointers if required
§ Initialize user code § Execute user code
§ Set data pointers if required § Set run-time handle data

Initialization phase During the initialization phase of the executable

application (i.e., real-time application or offline simulation application), the code
that is generated by the bus implementation software uses functions of the Bus
Custom Code interface to generate and initialize handles and their parameters.
Then, the code calls the DsBusCustomCode_onApplicationInit function.
The DsBusCustomCode_onApplicationInit function is the main function for
initializing the user code for each PDU to which the user code is applied to.
It must be implemented in the user code implementation. Within this function,
Bus Custom Code functions and common C/C++ operations can be used to get
initial handle data, specify user-defined data structures, and set data pointers to
access the data structures, for example.

15
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Tip

The DsBusCustomCode_onApplicationInit function does not influence

the real-time performance of the user code during the execution phase.
For optimum performance, it is therefore recommended to implement time-
consuming operations such as malloc or non-deterministic function calls in
the DsBusCustomCode_onApplicationInit function.

Execution phase In general, when the executable application is running, the

execution of the code that is generated by the bus implementation software
is PDU-based: When a PDU that is affected by the user code is received or
to be transmitted on the bus, the code uses Bus Custom Code functions to
write the current run-time data to the related handles. Then, the code calls the
DsBusCustomCode_onPduFeatureExecution function.
The DsBusCustomCode_onPduFeatureExecution function is the main
function for executing the user code. It must be implemented in the user code
implementation. Within this function, Bus Custom Code functions and common
C/C++ operations can be used to access handle data, provide the data to
algorithms of the user code, and execute the user code. If required, you can
get or set data pointers to access user-defined data structures, for example. The
results of the executed user code can be written to the related handles as new
data.
After the DsBusCustomCode_onPduFeatureExecution function was executed,
the code that is generated by the bus implementation software reads the new
handle data and provides it to the executable application, e.g., to transmit the
data on the bus.

Note

Only relevant when using the Bus Manager:

When you use the DsBusCustomCodeUserCodePduFeature_
getRuntimeCanFrameTriggering function of
the DsBusCustomCode_PduUserCode module, the
DsBusCustomCode_onPduFeatureExecution function might be
executed too early to access the actual run‑time data.
Depending on your use scenario, you have to use the
DsBusCustomCode_onFrameTransmissionExecution function instead
to access the run‑time data. Refer to Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
Function in the User Code on page 26.

Execution sequence of user Even though the code that is generated by the bus implementation software is
code and other features of PDU-based, user code can also affect signals and frames of the related PDUs.
bus implementation software Additionally, signals, PDUs, and frames can be affected by other features of
the bus implementation software, e.g., by bus configuration features of the Bus
Manager. Basically, the execution sequence of the user code and other features
of the bus implementation software depends on whether the PDU is a TX or an
RX PDU, as shown in the following example.

16
Bus Custom Code Interface Handling May 2024
 Integrating Functions of the Bus Custom Code Interface in the User Code

Trigger transmission of TX PDU Receive RX PDU on the bus

Execute signal-based Execute frame-based

features features

Execute PDU-based Execute PDU-based

Execute user code Execute user code
features features

Execute frame-based Execute signal-based

features features

Transmit PDU data on the bus Provide PDU data, e.g., to a

mapped behavior model

However, the exact behavior depends on the following factors:

§ The used bus implementation software and the software-specific architecture
to configure bus communication.
§ The configured bus communication.
For example, there can be several calls of user code functions while other
features are executed between the calls.
§ The PDU type to which the user code is applied.
For example, if user code for secure onboard communication (SecOC) is
applied to a contained IPDU, the execution sequence can be as follows:
§ Before transmission, the user code is applied to the contained IPDU, e.g.,
the contained IPDU is secured. Then, the contained IPDU is included in the
container IPDU. Before transmission, other features might be applied to the
container IPDU and/or its related frame.
§ When the container IPDU is received, other features might be applied to
the container IPDU and/or its related frame before the contained IPDU is
extracted. After the contained IPDU is extracted, the user code is applied to
the contained IPDU, e.g., the received authentication information is verified.

Integrating Functions of the Bus Custom Code Interface in the User Code

Overview To implement user code and its functionalities in executable applications (i.e.,
in real‑time applications and/or offline simulation applications), you must extend
the user code by functions of the Bus Custom Code interface. Some functions
of the Bus Custom Code interface are mandatory, regardless of the specific use
scenario. Additionally, there are mandatory and optional functions depending on
the use scenario.

Mandatory user code ID For each user code implementation, one unique user code ID must be specified.
The user code ID is required to unambiguously reference specific user code
implementations in the bus implementation software.

17
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

To specify the user code ID, exactly one source file of a user code implementation
must start with the following definition:

1 #define DS_BUS_CUSTOM_FEATURE_NAME <user code ID>

The user code ID must be a unique C-compliant string, i.e., only letters, numbers,
and '_' are allowed. However, the first character must not be a number. The
string must be at least one character long and the recommended maximum
string length is 64 characters.

Note

§ There must not be any definitions, includes, function calls, etc. before the
definition of the user code ID.
§ If a user code implementation consists of multiple source files, only one
source file must contain the definition of the user code ID.
§ To use functions of the Bus Custom Code interface at run time, their
function definitions must be included in the source file that contains the
definition of the user code ID.

Mandatory functions For each user code implementation,

the DsBusCustomCode_onApplicationInit and
DsBusCustomCode_onPduFeatureExecution functions must be implemented
exactly once. The following example shows the required syntax for implementing
the functions.
1 Std_ReturnType DsBusCustomCode_onApplicationInit(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Initialization of the user code. */
4 return E_OK;
5 }
6
7 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
8 {
9 /* Execution of the user code (PDU-based). */
10 return E_OK;
11 }

Note

Both functions must be implemented exactly once in the source file that
contains the definition of the user code ID.

18
Bus Custom Code Interface Handling May 2024
 Integrating Functions of the Bus Custom Code Interface in the User Code

The specific initialization and execution of the user code depends on your use
scenario.

Tip

Especially if you work with complex user code implementations, it might

be useful to implement these functions as empty functions at an early
development stage. When you do this and you generate the executable
application, source file settings, such as path specifications, includes, etc.
are tested. This lets you check at an early development stage whether
settings of the source file are implemented correctly.

Use-scenario-specific content Mandatory include files Depending on your use scenario, you must include
one of the following include files in your user code implementation:

Use Scenario Include

Implementing user-specific PDU features in executable applications (e.g., 1 #include <DsBusCustomCode_PduUserCode.h>
checksum or counter signal value calculation).

Note

This use scenario is supported only by the Bus Manager and not by
any other bus implementation software.

Implementing secure onboard communication in executable 1 #include <DsBusCustomCode_SecOC.h>

applications.

Note

The include file must be included in the source file that contains the
definition of the user code ID.

Additional mandatory function If you want to use the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function to access data of simulated TX CAN PDUs, you have
to implement the DsBusCustomCode_onFrameTransmissionExecution
function in your user code. Refer to Implementing
the DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
Function in the User Code on page 26.

Note

This use scenario is supported only by the Bus Manager and not by any
other bus implementation software.

Additional required extensions Additional required extensions of the user

code depend on your use scenario. For examples, refer to:
§ Example of Implementing User-Specific PDU Functionalities via the Bus Custom
Code Interface on page 33

19
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

§ Example of Implementing Secure Onboard Communication (SecOC) via the

Bus Custom Code Interface on page 41

General recommendations To ensure optimum run‑time performance and predictable run‑time behavior,
note the following points for integrating functions of the Bus Custom Code
interface in your user code:
§ The DsBusCustomCode_onApplicationInit function does not influence
the real-time performance of the user code during the execution phase.
For optimum performance, it is therefore recommended to implement time-
consuming operations such as malloc or non-deterministic function calls in
the DsBusCustomCode_onApplicationInit function.
§ Use the DSBUSCUSTOMCODE_CHECK_NULL and DSBUSCUSTOMCODE_TRY
macros, which are defined by the common DsBusCustomCode module, to
check each pointer and function parameter once as early as possible.

§ Structure the DsBusCustomCode_onPduFeatureExecution function in three

parts:
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function that applies to each applicable PDU,
4 * regadless of the PDU direction.
5 * Among others, declare the following variable that is used by the If-Else loop of part 2 and 3: */
6 boolean isTx = FALSE;
7
8 /* Part 2 and 3: If-Else loop that checks whether the PDU is a TX PDU. */
9 if (isTx)
10 {
11 /* Part 2: Executed only if the PDU is a TX PDU. */
12 }
13 else
14 {
15 /* Part 3: Executed only if the PDU is an RX PDU. */
16 }
17 return E_OK;
18 }

Overview of the Handles and Their Functions

Overview The Bus Custom Code interface provides a set of handles that let you access
elements such as PDUs or PDU features. For specific handles, functions are
available that let you access element properties: Get functions provide a read
access to properties, set functions provide write access.

The following illustrations provide a graphical overview of the public handles and
functions that are provided by the modules of the Bus Custom Code interface.

20
Bus Custom Code Interface Handling May 2024
 Overview of the Handles and Their Functions

Handles and functions The following illustration provides an overview of the handles and functions of
provided by the common the common DsBusCustomCode module, and the inheritance of the functions.
DsBusCustomCode module

Bus Custom Code

DsBusCustomCodeHandle

Inherited functions Get Functions Inherited functions

getDescriptor: char*
getName: char*

Set Functions
Communication Cluster -- Signal
DsBusCustomCodeCommunicationClusterHandle DsBusCustomCodeSignalHandle

Inherited functions

Inherited functions
Get Functions Get Functions
-- getEndianness: DsBusCustomCode_ByteOrderType
getLength: uint32
Set Functions getStartBitPosition: uint32
--
Set Functions
--

Inherited functions
ECU PDU
DsBusCustomCodeEcuHandle DsBusCustomCodePduHandle

Get Functions Get Functions

-- getCanChannelName: char*
getCanFrameTriggering: DsBusCustomCodeCanFrameTriggeringType
Set Functions getIsTx: boolean
-- getLinFrameTriggering: DsBusCustomCodeLinFrameTriggeringType
getSduDataPtr: uint8*
getSduLength: uint32

Set Functions
--

PDU Feature
DsBusCustomCodePduFeatureHandle

Get Functions
getCommunicationCluster: DsBusCustomCodeCommunicationClusterHandle
getEcu: DsBusCustomCodeEcuHandle
getFeatureDataPtr: uint8*
getPdu: DsBusCustomCodePduHandle

Set Functions
setFeatureDataPtr(uint8*): void

21
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Handles and functions The following illustration provides an overview of the handles and functions of
provided by the the DsBusCustomCode_SecOC module, and the inheritance of the functions.
DsBusCustomCode_SecOC
module

Inherits functions from Bus Custom Code Inherits functions from

DsBusCustomCodeHandle

PDU Feature PDU

DsBusCustomCodePduFeatureHandle DsBusCustomCodePduHandle

Inherits functions from Inherits functions from

SecOC PDU Feature Secured IPDU

DsBusCustomCodeSecOCPduFeatureHandle DsBusCustomCodeSecuredIPduHandle

Get Functions Get Functions

getAuthenticatorPositionOffset: sint32 getAuthAlgorithmName: char*
getKeyAsString: char* getAuthDataFreshnessLength: uint16
getKeyLength: uint32 getAuthDataFreshnessStartPosition: uint16
getKeyPtr: uint8* getAuthenticationBuildAttempts: uint16
getAuthenticationRetries: uint32
Set Functions getAuthenticPdu: DsBusCustomCodePduHandle
setAuthenticatorPositionOffset: sint32 getAuthInfoTxLength: uint32
setKeyLength(uint32): void getAuthPduHeaderLength: uint8
setKeyPtr(uint8*): void getDataId: uint16
getFreshnessCounterSyncAttempts: uint32
getFreshnessTimestampPeriodFactor: uint32
Inherited functions
getFreshnessValueId: uint16
getFreshnessValueLength: uint32
getFreshnessValueTxLength: uint32
getKeyId: uint32
SecOC TX PDU Feature SecOC RX PDU Feature getMessageLinkLength: uint16
DsBusCustomCodeSecOCTxPduFeatureHandle DsBusCustomCodeSecOCRxPduFeatureHandle getMessageLinkPosition: uint16
Get Functions Get Functions getRxSecurityVerification: boolean
getAuthenticationType: uint32 getCalculatedFreshnessValue: uint64 getSecuredAreaLength: uint32
getCalculatedFreshnessValue: uint64 getEnableVerification: uint32 getSecuredAreaOffset: uint32
getEnableAuthentication: uint32 getVerificationResult: uint32 getTimeStampRxAcceptanceWindow: uint64
getEnableFreshnessValueCalculation: uint32 getUseAsCryptographicIPdu: boolean
getFreshnessValueOffset: sint64 Set Functions getUseAuthDataFreshness: boolean
getUserDefinedAuthenticatorPtr: uint8* setCalculatedFreshnessValue(uint64): void getUseFreshnessTimestamp: boolean
getUserDefinedFreshnessValue: uint64 setVerificationResult(uint32): void
Set Functions
Set Functions --
setCalculatedFreshnessValue(uint64): void

22
Bus Custom Code Interface Handling May 2024
 Using Bus Custom Code Functions with Bus Implementation Software

Handles and The following illustration provides an overview of the handles and functions
functions provided by of the DsBusCustomCode_PduUserCode module, and the inheritance of the
the DsBusCustomCode_ functions.
PduUserCode module

Inherits functions from Inherits functions from

Bus Custom Code
DsBusCustomCodeHandle

PDU Feature User Port

DsBusCustomCodePduFeatureHandle DsBusCustomCodeUserPortHandle

Get Functions
getDirection: boolean
getPortData: float64

Inherits functions from Set Functions

setPortData: float64

User Code PDU Feature

DsBusCustomCodeUserCodePduFeatureHandle

Get Functions
getResult: uint32
getNumberOfUserSignals: uint32
getUserSignals: DsBusCustomCodeSignalHandle*
getNumberOfUserPorts: uint32
getUserPorts: DsBusCustomCodeUserPortHandle*
getRuntimeCanFrameTriggering: DsBusCustomCodeRuntimeCanFrameTriggeringType
Set Functions
setResult: uint32

Using Bus Custom Code Functions with Bus Implementation Software

Using Bus Custom Code In general, user code that uses functions of the Bus Custom Code interface can
functions with different be used with all bus implementation software tools. However, not all functions
bus implementation software of the Bus Custom Code interface can be used with each bus implementation
tools software tool. For example, because of the following reasons:
§ A function requires data of a specific communication matrix attribute but this
attribute is not evaluated by a bus implementation software tool.
§ A function requires data from a property of the bus implementation software
but this property is not available for a bus implementation software tool.

If a function cannot be used with a bus implementation software tool, the

behavior is one of the following:
§ The tool sets an internal constant value, which is often 0. If the user code calls
the function, the user code gets this constant value.
§ The tool does not parameterize the function parameters at all. If the user code
calls the function, the function returns E_PARAMETER_NOT_SET.

For more information on function parameters and return values, refer to Basic
Principles of the Bus Custom Code Interface on page 12.

23
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Mapping of Bus Custom The following table provides an overview of the public Bus Custom Code
Code functions to bus functions and with which bus implementation software tool they can be used.
implementation software

Bus Custom Code Function Usable with …

Bus RTI CAN FlexRay Ethernet
Manager MultiMessage Configuration Configuration
Blockset Package Package
DsBusCustomCode_getDescriptor ✓ ✓ ✓ ✓
DsBusCustomCode_getName ✓ ✓ ✓ ✓
DsBusCustomCodePdu_getCanChannelName ✓ ✓ - -
DsBusCustomCodePdu_getCanFrameTriggering ✓ ✓ - -
DsBusCustomCodePdu_getIsTx ✓ ✓ ✓ ✓
DsBusCustomCodePdu_getLinFrameTriggering ✓ - - -
DsBusCustomCodePdu_getSduDataPtr ✓ ✓ ✓ ✓
DsBusCustomCodePdu_getSduLength ✓ ✓ ✓ ✓
DsBusCustomCodePduFeature_getFeatureDataPtr ✓ ✓ ✓ ✓
DsBusCustomCodePduFeature_getPdu ✓ ✓ ✓ ✓
DsBusCustomCodePduFeature_setFeatureDataPtr ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset ✓ ✓ - -
DsBusCustomCodeSecOCPduFeature_getKeyAsString ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCPduFeature_getKeyLength ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCPduFeature_getKeyPtr ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset ✓ ✓ - -
DsBusCustomCodeSecOCPduFeature_setKeyLength ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCPduFeature_setKeyPtr ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCRxPduFeature_getEnableVerification ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCRxPduFeature_getVerificationResult ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCRxPduFeature_setVerificationResult ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue - ✓ - ✓
DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication - ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalculation ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset - ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr - ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue ✓ ✓ ✓ ✓
DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue - ✓ - ✓
DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName ✓ - - -
DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength ✓ - - -
DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPosition ✓ - - -
DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength ✓ ✓ ✓ ✓

24
Bus Custom Code Interface Handling May 2024
 Using Bus Custom Code Functions with Bus Implementation Software

Bus Custom Code Function Usable with …

Bus RTI CAN FlexRay Ethernet
Manager MultiMessage Configuration Configuration
Blockset Package Package
DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength ✓ ✓ - -
DsBusCustomCodeSecuredIPdu_getAuthenticPdu ✓ ✓ ✓ ✓
DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts ✓ - ✓ -
DsBusCustomCodeSecuredIPdu_getAuthenticationRetries ✓ - ✓ -
DsBusCustomCodeSecuredIPdu_getDataId ✓ ✓ ✓ ✓
DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttempts ✓ - - -
DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFactor ✓ - ✓ -
DsBusCustomCodeSecuredIPdu_getFreshnessValueId ✓ ✓ ✓ -
DsBusCustomCodeSecuredIPdu_getFreshnessValueLength ✓ ✓ ✓ ✓
DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength ✓ ✓ ✓ ✓
DsBusCustomCodeSecuredIPdu_getKeyId ✓ ✓ ✓ ✓
DsBusCustomCodeSecuredIPdu_getMessageLinkLength ✓ ✓ ✓ -
DsBusCustomCodeSecuredIPdu_getMessageLinkPosition ✓ ✓ ✓ -
DsBusCustomCodeSecuredIPdu_getRxSecurityVerification ✓ - - -
DsBusCustomCodeSecuredIPdu_getSecuredAreaLength ✓ - - -
DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset ✓ - - -
DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWindow ✓ - ✓ -
DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu ✓ ✓ ✓ -
DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness ✓ - - -
DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp ✓ ✓ ✓ -
DsBusCustomCodeSignal_getEndianness ✓ - - -
DsBusCustomCodeSignal_getLength ✓ - - -
DsBusCustomCodeSignal_getStartBitPosition ✓ - - -
DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts ✓ - - -
DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals ✓ - - -
DsBusCustomCodeUserCodePduFeature_getResult ✓ - - -
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering ✓ - - -
DsBusCustomCodeUserCodePduFeature_getUserPorts ✓ - - -
DsBusCustomCodeUserCodePduFeature_getUserSignals ✓ - - -
DsBusCustomCodeUserCodePduFeature_setResult ✓ - - -
DsBusCustomCodeUserPort_getDirection ✓ - - -
DsBusCustomCodeUserPort_getPortData ✓ - - -
DsBusCustomCodeUserPort_setPortData ✓ - - -

25
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
Function in the User Code

Overview The DsBusCustomCode_PduUserCode module provides the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function, which can provide the actual run‑time frame triggering of a CAN frame
or the CAN identifier of a simulated RX J1939‑compliant IPDU to the user code.

Note

The DsBusCustomCode_PduUserCode module can be used only with

the Bus Manager, i.e., only the Bus Manager can parameterize the
functions of this module. You cannot use this module with any other bus
implementation software.

The requirements for implementing the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function in the user code differ depending on the following use scenarios:
Use The transmission of CAN PDUs is simulated, i.e., TX CAN PDUs are assigned
scenario 1 to the Simulated ECUs part of a bus configuration.
Refer to Realizing use scenario 1 on page 27.
Use One or more of the following:
scenario 2 § The reception of CAN PDUs is simulated, i.e., RX CAN PDUs are assigned
to the Simulated ECUs part of a bus configuration.
§ Received CAN PDUs are inspected, i.e., CAN PDUs are assigned to the
Inspection part of a bus configuration.
§ CAN PDUs are manipulated before they are transmitted, i.e., CAN PDUs
are assigned to the Manipulation part of a bus configuration.
Refer to Realizing use scenario 2 on page 28.

If you want to implement the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function for both use scenarios in the use code, different user code
implementations might be required. Refer to Using different user code
implementations on page 30.

Note

The following examples focus on the usage of the

DsBusCustomCodeUserCodePduFeature_
getRuntimeCanFrameTriggering function. They do not contain general
mandatory elements that are required to implement functions of the
DsBusCustomCode_PduUserCode module in the user code. For an example
that contains these elements, refer to Example of Implementing User-
Specific PDU Functionalities via the Bus Custom Code Interface on
page 33.

26
Bus Custom Code Interface Handling May 2024
 Implementing the DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering Function in the User Code

Realizing use scenario 1 Requirements You have to implement the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function in the DsBusCustomCode_onFrameTransmissionExecution function
if you want to access the respective run‑time data of TX PDUs that are assigned
to the Simulated ECUs part of a bus configuration.
The DsBusCustomCode_onFrameTransmissionExecution function
must be implemented in the source file that
contains the DsBusCustomCode_onApplicationInit and
DsBusCustomCode_onPduFeatureExecution functions as follows:
1 Std_ReturnType DsBusCustomCode_onApplicationInit(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Initialization of the user code.
4 * For an example, refer to Initializing the user code for each PDU on page 35. */
5 return E_OK;
6 }
7 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
8 {
9 /* Execution of any Bus Custom Code function of the user code (PDU-based).
10 * For an example, refer to Executing the user code for each PDU on page 36. */
11 return E_OK;
12 }
13 Std_ReturnType DsBusCustomCode_onFrameTransmissionExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
14 {
15 /* Execution of the DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering function
16 * for TX simulation (frame-based).
17 * For an example, refer to Example on page 28. */
18 return E_OK;
19 }

Moreover, you have to enable the execution of the

DsBusCustomCode_onFrameTransmissionExecution function in the Bus
Manager. Refer to:
§ Bus Manager in ConfigurationDesk: Applying User Code to PDUs
(ConfigurationDesk Bus Manager Implementation Guide ).
§ Bus Manager (stand‑alone): Applying User Code to PDUs (Bus Manager (Stand-
Alone) Implementation Guide ).

Restrictions Concerning the

DsBusCustomCode_onFrameTransmissionExecution function, note the
following points:
§ When the execution of the function is enabled in the Bus Manager, it is
executed only for TX PDUs that are assigned to the Simulated ECUs part of a
bus configuration and that are directly included in a frame. The function is not
executed for any of the following PDUs:
§ RX PDUs
§ PDUs that are assigned to the Inspection or Manipulation part of a bus
configuration.
§ TX PDUs that are assigned to the Simulated ECUs part and that are
included in other PDUs, i.e., the function is not executed for any of the
following PDUs:
§ Static‑part IPDUs and dynamic‑part IPDUs of multiplexed IPDUs
§ Authentic IPDUs of non‑cryptographic secured IPDUs
§ Contained IPDUs of container IPDUs

27
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

§ The intended use of the function is to only implement the access to

the run‑time frame triggering of simulated TX PDUs. To ensure predictable
run‑time behavior, do not use this function in any other contexts.

Example The following code extract is an example of implementing the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function for use scenario 1.
1 Std_ReturnType DsBusCustomCode_onFrameTransmissionExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare required handles, data pointers, and variables, for example, the following: */
4 char* featureDescriptor;
5 DsBusCustomCodeUserPortHandle* UserPorts;
6
7 /* Declare a struct that will be used to store the run-time CAN frame triggering data. */
8 DsBusCustomCodeRuntimeCanFrameTriggeringType My_RuntimeCanStruct;
9
10 /* Access the PduFeatureHandle and its data.
11 * Check the PduFeatureHandle via the DSBUSCUSTOMCODE_CHECK_NULL macro. */
12 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);
13 DSBUSCUSTOMCODE_TRY(g_DsBusCustomCodeDefaultDescriptor, DsBusCustomCode_getDescriptor(PduFeatureHandle,
14 &featureDescriptor));
15
16 /* Access the user ports of the PDU User Code feature of the PDU.
17 * Get the user port array of the PDU from the PDU's PduFeatureHandle. */
18 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getUserPorts(PduFeatureHandle,
19 &UserPorts));
20
21 /* Get the run-time CAN frame triggering data and store the data in the My_RuntimeCanStruct struct. */
22 DSBUSCUSTOMCODE_TRY(featureDescriptor,
23 DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering(PduFeatureHandle, &My_RuntimeCanStruct));
24
25 /* Write the data of the My_RuntimeCanStruct struct to the user ports. */
26 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[0],
27 My_RuntimeCanStruct.Identifier));
28 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[1],
29 My_RuntimeCanStruct.AddressingMode));
30 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[2],
31 My_RuntimeCanStruct.FrameBehavior));
32 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[3],
33 My_RuntimeCanStruct.BitRateSwitch));
34
35 return E_OK;
36 }

Realizing use scenario 2 Requirements You have to implement the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function in the DsBusCustomCode_onPduFeatureExecution function if you
want to access the respective run‑time data of the following PDUs:
§ RX PDUs that are assigned to the Simulated ECUs part of a bus configuration.
§ PDUs that are assigned to the Inspection part of a bus configuration.
§ PDUs that are assigned to the Manipulation part of a bus configuration.
It is recommended to structure the
DsBusCustomCode_onPduFeatureExecution function in three parts (refer to
General recommendations on page 20). When you do this, implement the

28
Bus Custom Code Interface Handling May 2024
 Implementing the DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering Function in the User Code

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function as follows:
§ To access the data of PDUs that are assigned to the Manipulation part,
implement the DsBusCustomCodeUserCodePduFeature_
getRuntimeCanFrameTriggering function in that part that is only executed
for TX PDUs.
§ To access the data of RX PDUs that are assigned to the Simulated ECUs
part or of PDUs that are assigned to the Inspection part, implement the
DsBusCustomCodeUserCodePduFeature_
getRuntimeCanFrameTriggering function in that part that is only executed
for RX PDUs.

Example The following code extract is an example of implementing the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
function for use scenario 2.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare required handles, data pointers, and variables, for example, the following: */
4 boolean isTx = FALSE;
5 struct UserCode_FeatureData* featureDataPtr;
6 char* featureDescriptor;
7 DsBusCustomCodePduHandle pduHandle;
8 DsBusCustomCodeUserPortHandle* UserPorts;
9
10 /* Declare a struct that will be used to store the run-time CAN frame triggering data. */
11 DsBusCustomCodeRuntimeCanFrameTriggeringType My_RuntimeCanStruct;
12
13 /* Access the PduFeatureHandle and its data.
14 * Check the PduFeatureHandle via the DSBUSCUSTOMCODE_CHECK_NULL macro. */
15 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);
16 DSBUSCUSTOMCODE_TRY(g_DsBusCustomCodeDefaultDescriptor, DsBusCustomCode_getDescriptor(PduFeatureHandle,
17 &featureDescriptor));
18 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getFeatureDataPtr(PduFeatureHandle,
19 (uint8**)&featureDataPtr));
20
21 /* Access the PduHandle and its data.
22 * Get the PduHandle of the PDU from the PDU's PduFeatureHandle.
23 * Get the direction of the PDU from its PduHandle. */
24 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getPdu(PduFeatureHandle, &pduHandle));
25 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getIsTx(pduHandle, &isTx));
26
27 /* If the PDU is a TX PDU, the If part of the If-Else loop is executed. */
28 if (isTx)
29 {
30 /* Access the user ports of the PDU User Code feature of the TX PDU.
31 * Get the user port array of the TX PDU from the PDU's PduFeatureHandle. */
32 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getUserPorts(PduFeatureHandle,
33 &UserPorts));
34
35 /* Get the run-time CAN frame triggering data and store the data in the My_RuntimeCanStruct struct.
36 * The function can get the data only if the TX PDU is assigned to the Manipulation part. */
37 DSBUSCUSTOMCODE_TRY(featureDescriptor,
38 DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering(PduFeatureHandle, &My_RuntimeCanStruct));
39
40 /* Write the data of the My_RuntimeCanStruct struct to the user ports. */
41 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[0],
42 My_RuntimeCanStruct.Identifier));
43 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[1],
44 My_RuntimeCanStruct.AddressingMode));

29
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

45 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[2],
46 My_RuntimeCanStruct.FrameBehavior));
47 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[3],
48 My_RuntimeCanStruct.BitRateSwitch));
49
50 }
51 /* If the PDU is an RX PDU, the Else part of the If-Else loop is executed. */
52 else
53 {
54 /* Access the user ports of the PDU User Code feature of the RX PDU.
55 * Get the user port array of the RX PDU from the PDU's PduFeatureHandle. */
56 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getUserPorts(PduFeatureHandle,
57 &UserPorts));
58
59 /* Get the run-time CAN frame triggering data and store the data in the My_RuntimeCanStruct struct.
60 * The function can get the data only if the RX PDU is assigned to the Simulated ECUs or Inspection part. */
61 DSBUSCUSTOMCODE_TRY(featureDescriptor,
62 DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering(PduFeatureHandle, &My_RuntimeCanStruct));
63
64 /* Write the data of the My_RuntimeCanStruct struct to the user ports. */
65 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[0],
66 My_RuntimeCanStruct.Identifier));
67 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[1],
68 My_RuntimeCanStruct.AddressingMode));
69 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[2],
70 My_RuntimeCanStruct.FrameBehavior));
71 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[3],
72 My_RuntimeCanStruct.BitRateSwitch));
73
74 }
75 return E_OK;
76
77 }

Using different user code In general, you can use the same user code implementation for both use
implementations scenarios. Only if you want to access the run‑time data of TX PDUs that are
assigned to the Simulated ECUs part and of PDUs that are assigned to the
Manipulation part, you have to use different user code implementations.

Tip

In many cases, it is useful to work with two user code implementations

when you use functions of the DsBusCustomCode_PduUserCode module:
§ Use one user code implementation to access PDUs that are assigned to
the Simulated ECUs and Inspection parts.
§ Use another user code implementation to access PDUs that are assigned
to the Manipulation part.

Related topics Basics

Integrating Functions of the Bus Custom Code Interface in the User Code................................ 17

30
Bus Custom Code Interface Handling May 2024
 Restrictions for Working with the Bus Custom Code Interface

References

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering.............................. 166

Restrictions for Working with the Bus Custom Code Interface

Overview If you work with the Bus Custom Code interface, the following restrictions apply.

Restrictions for working with The Bus Custom Code interface is specified in the <bus custom code module
the files of the Bus Custom name>.c, <bus custom code module name>.h, and <bus custom code
Code interface module name>_Internal.h files. These files are automatically installed when
you install a bus implementation software tool.

The following restrictions apply to the files:

§ Do not make any manual changes to the files.
§ Do not change the installation path of the files.
§ Do not work with local copies of the files.
§ Do not explicitly add the files to the bus implementation software.
You must add only the files of the user code implementation to the bus
implementation software. The files of the Bus Custom Code interface are
automatically accessed by the bus implementation software.

Restrictions for using reserved The Bus Custom Code interface provides functions that are reserved for internal
functions use only. These functions are specified in the <bus custom code module
name>_Internal.h files. Do not use any of these functions in your user code.

Restrictions for using The DsBusCustomCode_PduUserCode module can be used only with the Bus
the DsBusCustomCode_ Manager. You cannot use this interface with any other bus implementation
PduUserCode module software.

31
May 2024 Bus Custom Code Interface Handling
 Basics on the Bus Custom Code Interface

32
Bus Custom Code Interface Handling May 2024
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

Examples of Implementing User-Specific

Functionalities via the Bus Custom Code Interface

Where to go from here Information in this section

Example of Implementing User-Specific PDU Functionalities via the

Bus Custom Code Interface..................................................................... 33
Provides a detailed example of user code that implements user‑specific
PDU functionalities and that is to be used with the PDU User Code
feature of the Bus Manager.

Example of Implementing Secure Onboard Communication

(SecOC) via the Bus Custom Code Interface............................................. 41
Provides a detailed example of user code that implements user-specific
algorithms for secure onboard communication (SecOC). The user code
can be used with different bus implementation software tools to
implement secure onboard communication in executable applications.

Example of Implementing User-Specific PDU Functionalities via the Bus

Custom Code Interface

Overview Via the DsBusCustomCode_PduUserCode module of the Bus Custom Code

interface, you can implement user-specific PDU functionalities in executable
applications, i.e., in real‑time applications and/or offline simulation applications.

Note

The DsBusCustomCode_PduUserCode module can be used only with

the Bus Manager, i.e., only the Bus Manager can parameterize the
functions of this module. You cannot use this module with any other bus
implementation software.

33
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

The following is an example of a source file of a user code implementation that

implements user-specific algorithms for checksum and counter value calculation.

At run time, the algorithms apply to all PDUs for which the PDU User Code
feature of the Bus Manager is added and that reference the user code ID of this
source file.

The source file of this example consists of the following parts:

§ Defining the user code ID on page 34
§ Including required include files on page 34
§ Defining return values on page 34
§ Saving current counter data on page 35
§ Initializing the user code for each PDU on page 35
§ Executing the user code for each PDU on page 36

Defining the user code ID The first element in the source file is the definition of a user code ID, which is
named UserCRCDemo in this example:
1 /* Start of user code source file */
2 /* Define user code ID */
3 #define DS_BUS_CUSTOM_FEATURE_NAME UserCRCDemo

For each user code implementation, one unique user code ID must be specified.
To apply the algorithms of the user code implementation to a PDU, you must
reference the specified user code ID via the PDU User Code feature of this PDU
in the ConfigurationDesk application.

Including required include After the definition of the user code ID, required include files are included:
files
1 /* Mandatory include file */
2 #include <DsBusCustomCode_PduUserCode.h>
3
4 /* Further required include files */
5 #include <stdio.h>
6 #include <stdlib.h>

Including the DsBusCustomCode_PduUserCode.h file is mandatory.

The file provides type definitions and function declarations of the
DsBusCustomCode_PduUserCode module of the Bus Custom Code interface.
Additionally, it includes type definitions and function declarations of the
common DsBusCustomCode module.

The stdio.h and stdlib.h files are header files of the standard C library,
providing definitions and declarations of the C library. It depends on your user
code whether including these files and/or other include files is required.

Defining return values In this example, the following return values are defined to provide status
information on the received counter and checksum values at run time:
1 #define CUSTOM_CRC_OK 0x00 /* Expected checksum value received */
2 #define CUSTOM_CRC_FAILED 0x01 /* Unexpected checksum value received */

34
Bus Custom Code Interface Handling May 2024
 Example of Implementing User-Specific PDU Functionalities via the Bus Custom Code Interface

3 #define CUSTOM_CRC_COUNTER_FAILED 0x02 /* Unexpected counter value received */

4 #define CUSTOM_CRC_COUNTER_INITIALIZED 0x04 /* Counter initialized */

In this example, the definition of these return values is global, i.e., the values can
be used by all functions of this source file.

Tip

If you define such return values, it is recommended to define reasonable

values, e.g., according to related AUTOSAR definitions.

Saving current counter data At run time, functions of this user code example require access to the
initialization state of the counter and the current counter value. In most cases,
the current counter value is the value that was calculated during the previous
execution of the PDU User Code feature.

To provide access to the required data, the following structure is specified:

1 /* Struct to store counter data */
2 struct UserCode_FeatureData
3 {
4 uint32 counter_value; /* Current counter value */
5 uint32 counter_is_initialized; /* Flag indicating whether the counter is initialized */
6 };

Tip

In the following, this structure is accessed by the featureDataPtr pointer.

The featureDataPtr pointer is used to pass the data of the structure to
PDU handles.

Initializing the user code for The user code must be initialized for each PDU to which the PDU
each PDU User Code feature is added. For this purpose, you must implement the
DsBusCustomCode_onApplicationInit function. During the initialization
phase of the executable application, this function is called for each PDU that
is affected by the PDU User Code feature.

In this example, the user code is initialized for each PDU as follows:
1 Std_ReturnType DsBusCustomCode_onApplicationInit(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare data pointers. */
4 uint8* featureDataPtr;
5 char* featureDescriptor;
6 struct UserCode_FeatureData* featureInstanceData;
7
8 /* Execute the DSBUSCUSTOMCODE_CHECK_NULL macro to check whether the PduFeatureHandle is NULL.
9 * If it is, a message is written to the application log and the DsBusCustomCode_onApplicationInit function
10 * returns E_NOT_OK. */
11 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);
12 DsBusCustomCode_getDescriptor(PduFeatureHandle, &featureDescriptor);
13
14 /* Create an instance of the UserCode_FeatureData struct to store PDU-specific feature data.
15 * Assign the instantiated struct to the featureInstanceData pointer.

35
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

16 * Check the pointer via the DSBUSCUSTOMCODE_CHECK_NULL macro. */

17 featureInstanceData = (struct UserCode_FeatureData*)malloc(sizeof(struct UserCode_FeatureData));
18 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, featureInstanceData);
19
20 /* Initialize the counter of the PDU with 0. */
21 featureInstanceData->counter_value = 0;
22 featureInstanceData->counter_is_initialized = 0;
23
24 /* Assign the instantiated UserCode_FeatureData struct via its featureInstanceData pointer to
25 * the featureDataPtr pointer.
26 * Assign the featureDataPtr pointer to the PDUFeatureHandle.
27 * Execute the DSBUSCUSTOMCODE_TRY macro to check whether the DsBusCustomCodePduFeature_setFeatureDataPtr
28 * function is called successfully.
29 * If it is not, a message is written to the application log and the DsBusCustomCode_onApplicationInit
30 * function returns E_NOT_OK. */
31 featureDataPtr = (uint8*)featureInstanceData;
32 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_setFeatureDataPtr(PduFeatureHandle,
33 featureDataPtr));
34
35 /* Return whether DsBusCustomCode_onApplicationInit function is implemented correctly. */
36 return E_OK;
37 }

Tip

§ The DsBusCustomCode_onApplicationInit function does not

influence the real-time performance of the user code
during the execution phase. For optimum performance, it is
therefore recommended to implement time-consuming operations
such as malloc or non-deterministic function calls in the
DsBusCustomCode_onApplicationInit function.
§ The DSBUSCUSTOMCODE_CHECK_NULL and DSBUSCUSTOMCODE_TRY
macros are defined by the common DsBusCustomCode module. For
optimum performance, it is recommended to use these macros to check
each pointer and function parameter once at an early stage of the code
execution, i.e., as early as the DsBusCustomCode_onApplicationInit
function, if possible.
§ By using the DsBusCustomCodePduFeature_setFeatureDataPtr
function, you can assign a pointer to any handle. At run time, you can
access the handle and its current data by calling the pointer at any time in
the DsBusCustomCode_onPduFeatureExecution function.

Executing the user code for To execute the user code for each PDU to which the PDU User Code feature is
each PDU added, you must implement the DsBusCustomCode_onPduFeatureExecution
function. This function is called each time the transmission of an affected PDU
is triggered or the PDU is received. With each function call, PDU data (e.g.,
direction, payload length) and data of the PDU User Code feature (e.g., function
port values) is provided to the user code.

In this example, the DsBusCustomCode_onPduFeatureExecution function is

structured in three parts, as shown in the following overview.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function that applies to each PDU to which

36
Bus Custom Code Interface Handling May 2024
 Example of Implementing User-Specific PDU Functionalities via the Bus Custom Code Interface

4 * the PDU User Code feature is added, regadless of the PDU direction. */
5
6 /* Part 2 and 3: If-Else loop that checks whether the PDU is a TX PDU. */
7 if (isTx)
8 {
9 /* Part 2: Executed only if the PDU is a TX PDU. */
10 }
11 else
12 {
13 /* Part 3: Executed only if the PDU is an RX PDU. */
14 }
15 return E_OK;
16 }

For more information on the individual parts, refer to:

§ Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution
function on page 37
§ Part 2: TX-related part of the DsBusCustomCode_onPduFeatureExecution
function on page 38
§ Part 3: RX-related part of the DsBusCustomCode_onPduFeatureExecution
function on page 39

Part 1: Common part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed for
each PDU to which the PDU User Code feature is added, regardless of whether
the PDU is a TX PDU or an RX PDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare required handles, data pointers, and variables, for example, the following: */
4 boolean isTx = FALSE;
5 struct UserCode_FeatureData* featureDataPtr;
6 char* featureDescriptor;
7 DsBusCustomCodePduHandle pduHandle;
8 uint8* IPdu_SduDataPtr;
9 uint32 IPdu_SduLength;
10 DsBusCustomCodeSignalHandle* Signals;
11 uint32 SignalCount;
12 uint32 ISignalCounterPos;
13 uint32 ISignalCrcPos;
14 DsBusCustomCodeUserPortHandle* UserPorts;
15 uint32 UserPortTxCount;
16 uint32 UserPortRxCount;
17 boolean portIsOut;
18 float64 dataFromInPorts[3];
19 float64 dataForOutPorts[] = {1, 2, 3};
20 uint8 tmpcrcval;
21 uint32 tmpPos;
22 uint32 tmpCounterPos;
23 uint32 tmpCrcPos;
24 ...
25
26 /* Access the PduFeatureHandle and its data.
27 * Check the PduFeatureHandle via the DSBUSCUSTOMCODE_CHECK_NULL macro. */
28 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);
29 /* Get the descriptor of the PduFeatureHandle. */
30 DSBUSCUSTOMCODE_TRY(g_DsBusCustomCodeDefaultDescriptor, DsBusCustomCode_getDescriptor(PduFeatureHandle,
31 &featureDescriptor));
32 /* Get the data structure that is addressed via the featureDataPtr pointer, i.e., the data of the
33 * related UserCode_FeatureData struct that was created during the execution of the

37
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

34 * DsBusCustomCode_onApplicationInit function. */
35 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getFeatureDataPtr(PduFeatureHandle,
36 (uint8**)&featureDataPtr));
37
38 /* Access the PduHandle and its data.
39 * Get the PduHandle of the PDU from the PDU's PduFeatureHandle. */
40 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getPdu(PduFeatureHandle, &pduHandle));
41 /* Get properties of the PDU from its PduHandle */
42 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduLength(pduHandle, &IPdu_SduLength));
43 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduDataPtr(pduHandle, &IPdu_SduDataPtr));
44 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getIsTx(pduHandle, &isTx));
45
46 /* Access the user signals of the PDU.
47 * Get the user signal array of the PDU from the PDU's PduFeatureHandle. */
48 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getUserSignals(PduFeatureHandle,
49 &Signals));
50 /* Get the number of user signals of the PDU from the PDU's PduFeatureHandle. */
51 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals(
52 PduFeatureHandle, &SignalCount));
53
54 /* Get the start bit position of the first two signals in the signal array.
55 * Assign the ISignalCrcPos and ISignalCounterPos variables to the start bit position. */
56 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSignal_getStartBitPosition(Signals[0], &ISignalCrcPos));
57 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSignal_getStartBitPosition(Signals[1],
58 &ISignalCounterPos));
59
60 /* Access the user ports of the PDU.
61 * Get the user port array of the PDU from the PDU's PduFeatureHandle. */
62 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getUserPorts(PduFeatureHandle,
63 &UserPorts));
64
65 /* Specify initial values for some variables of each PDU feature handle. */
66 tmpcrcval = 0;
67 tmpPos = IPdu_SduLength;
68 tmpCounterPos = ISignalCounterPos >> 3;
69 tmpCrcPos = ISignalCrcPos >> 3;
70
71 /* End of part 1, i.e., end of the common part of the DsBusCustomCode_onPduFeatureExecution function. */
72
73 /* Part 2 and 3: If-Else loop that checks whether the PDU is a TX PDU. */
74 if (isTx)
75 {
76 /* Part 2: Executed only if the PDU is a TX PDU.
77 * For details, see below. */
78 }
79 else
80 {
81 /* Part 3: Executed only if the PDU is an RX PDU.
82 * For details, see below. */
83 }
84
85 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
86 return E_OK;
87 }

Part 2: TX-related part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed only
if the PDU is a TX PDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function. */

38
Bus Custom Code Interface Handling May 2024
 Example of Implementing User-Specific PDU Functionalities via the Bus Custom Code Interface

4 ...
5
6 /* If-Else loop that checks whether the PDU is a TX PDU.
7 * Part 2: If the PDU is a TX PDU, the If part of the If-Else loop is executed. */
8 if (isTx)
9 {
10 /* Write the counter value to the allocated position of the PDU's payload. */
11 if (IPdu_SduLength > tmpCounterPos)
12 IPdu_SduDataPtr[tmpCounterPos] = (++(featureDataPtr->counter_value) & 0xFF);
13
14 /* Iterate over the PDU's data buffer and calculate the new checksum value. */
15 while (tmpPos)
16 {
17 tmpPos--;
18
19 /* Exclude the CRC position from the checksum calculation. */
20 if (tmpPos != tmpCrcPos)
21 tmpcrcval += (0xFF ^ IPdu_SduDataPtr[tmpPos]);
22 }
23
24 /* Write the calculated checksum value to the allocated position of the PDU's payload. */
25 if (IPdu_SduLength > tmpCrcPos)
26 IPdu_SduDataPtr[tmpCrcPos] = tmpcrcval;
27
28 /* Get the number of user ports of the PDU from the PDU's PduFeatureHandle. */
29 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts(PduFeatureHandle,
30 &UserPortTxCount));
31
32 /* Iterate over the user port array. */
33 for (uint32 i = 0; i < UserPortTxCount; i++)
34 {
35 /* Get the direction of the user port that is accessed in the user port array. */
36 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_getDirection(UserPorts[i], &portIsOut));
37
38 /* Check whether the direction of the accessed user port is In */
39 if (!portIsOut)
40 {
41 /* In case of an inport, get the port data and store it in the dataFromInPorts array */
42 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_getPortData(UserPorts[i],
43 &dataFromInPorts[i]));
44 }
45 }
46 }
47 /* End of part 2, i.e., end of the TX-related part of the DsBusCustomCode_onPduFeatureExecution function. */
48
49 /* Part 3: If the PDU is an RX PDU, the Else part of the If-Else loop is executed. */
50 else
51 {
52 /* For details, see below. */
53 }
54
55 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
56 return E_OK;
57 }

Part 3: RX-related part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed only
if the PDU is an RX PDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function. */

39
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

4 ...
5
6 /* If-Else loop that checks whether the PDU is a TX PDU. */
7 if (isTx)
8 {
9 /* Part 2: If the PDU is a TX PDU, the If part of the If-Else loop is executed. */
10 ...
11 }
12 /* Part 3: If the PDU is an RX PDU, the Else part of the If-Else loop is executed. */
13 else
14 {
15 uint32 status = CUSTOM_CRC_OK;
16 /* Check whether the RX counter has been initialized. */
17 if (IPdu_SduLength > tmpCounterPos)
18 {
19 /* If the RX counter has not been initialized yet, initialize it with the received counter value. */
20 if (!featureDataPtr->counter_is_initialized)
21 {
22 featureDataPtr->counter_value = IPdu_SduDataPtr[tmpCounterPos];
23 status |= CUSTOM_CRC_COUNTER_INITIALIZED;
24 featureDataPtr->counter_is_initialized = 1;
25 }
26 /* If the RX counter has already been initialized, increase the local counter value and
27 * compare it with the received counter value. */
28 else
29 {
30 featureDataPtr->counter_value++;
31 if ((featureDataPtr->counter_value & 0xFF) != IPdu_SduDataPtr[tmpCounterPos])
32 {
33 featureDataPtr->counter_is_initialized = 0;
34 status |= CUSTOM_CRC_COUNTER_FAILED;
35 }
36 }
37 }
38 /* Iterate over the PDU's data buffer and calculate the expected checksum value. */
39 if (IPdu_SduLength > tmpCrcPos)
40 {
41 while (tmpPos)
42 {
43 tmpPos--;
44 if (tmpPos != tmpCrcPos)
45 tmpcrcval += (0xFF ^ IPdu_SduDataPtr[tmpPos]);
46 }
47 /* Compare the expected checksum value with the received checksum value. */
48 if (tmpcrcval != IPdu_SduDataPtr[tmpCrcPos])
49 {
50 status |= CUSTOM_CRC_FAILED;
51 }
52 }
53 /* Get the number of user ports of the PDU from the PDU's PduFeatureHandle. */
54 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts(PduFeatureHandle,
55 &UserPortRxCount));
56 /* Iterate over the user port array. */
57 for (uint32 i = 0; i < UserPortRxCount; i++)
58 {
59 /* Get the direction of the user port that is accessed in the user port array. */
60 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_getDirection(UserPorts[i], &portIsOut));
61 /* Check whether the direction of the accessed user port is Out */
62 if (portIsOut)
63 {
64 /* In case of an outport, write the data of the dataForOutPorts array to the outport */
65 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeUserPort_setPortData(UserPorts[i],
66 dataForOutPorts[i]));

40
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

67 }
68 }
69 /* Write the result to the Result function port of the PDU User Code feature. */
70 DsBusCustomCodeUserCodePduFeature_setResult(PduFeatureHandle, status);
71 }
72
73 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
74 return E_OK;
75 }

Related topics Basics

Applying User Code to PDUs (ConfigurationDesk Bus Manager Implementation

Guide )
Applying User Code to PDUs (Bus Manager (Stand-Alone) Implementation
Guide )
Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering Function in
the User Code.......................................................................................................................... 26

Example of Implementing Secure Onboard Communication (SecOC) via the

Bus Custom Code Interface

Overview Via the DsBusCustomCode_SecOC module of the Bus Custom Code interface,
you can implement secure onboard communication (SecOC) in executable
applications, i.e., in real‑time applications and/or offline simulation applications.

The following example is an extract of the UserCode_SecOC.c source file.

The UserCode_SecOC.c source file implements user-specific algorithms for
calculating and verifying authentication information by using functions of the
DsBusCustomCode_SecOC module.

Tip

The UserCode_SecOC.c file is part of a demo user code implementation

for implementing secure onboard communication. The demo user code
implementation is available on demand. For more information, contact
dSPACE Support (www.dspace.com/go/supportrequest).

The source file of this example consists of the following parts:

§ Defining the user code ID on page 42
§ Including required include files on page 42
§ Defining return values on page 42
§ Saving current data provided by Crypto Service Manager and Freshness Value
Manager on page 43
§ Initializing the user code for each secured IPDU on page 43
§ Executing the user code for each secured IPDU on page 46

41
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

Defining the user code ID The first element in the source file is the definition of a user code ID, which is
named SecOC in this example:
1 /* Start of the UserCode_SecOC.c source file */
2 /* Define user code ID */
3 #define DS_BUS_CUSTOM_FEATURE_NAME SecOC

For each user code implementation, one unique user code ID must be specified.
To apply the algorithms of the user code implementation to secured IPDUs, the
specified user code ID must be referenced in the bus implementation software.

Including required include After the definition of the user code ID, required include files are included:
files
1 /* Mandatory include file */
2 #include <DsBusCustomCode_SecOC.h>
3
4 /* Further required include files */
5 #include <dsstd.h>
6 #include <stdio.h>
7 #include <stdlib.h>
8 #include <string.h>
9
10 #include "UserCode_SecOCHelper.h"
11 #include "UserCode_Csm.h"
12 #include "UserCode_Fvm.h"

Including the DsBusCustomCode_SecOC.h file is mandatory. The file provides

type definitions and function declarations of the DsBusCustomCode_SecOC
module of the Bus Custom Code interface. Additionally, it includes type
definitions and function declarations of the common DsBusCustomCode
module.

It depends on your user code whether including further files is required. In this
example, the following include files are required:

Include File Purpose

dsstd.h dSPACE-specific header file, providing platform-
dependent type definitions for dSPACE systems.
§ stdio.h Header files of the standard C library, providing
§ stdlib.h definitions and declarations of the C library.
§ string.h
§ UserCode_SecOCHelper.h Header files of the dSPACE demo user code
§ UserCode_Csm.h implementation. These files are examples on how
§ UserCode_Fvm.h user code can provide required helper functions and
implement functionalities of the AUTOSAR Crypto
Service Manager and Freshness Value Manager.

Defining return values In this example, return values are defined to provide the verification result of
received and verified authentication information. Additionally, a return value is
defined that indicates whether all required parameters are successfully initialized
during the initialization phase.

42
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

1 #define SECOC_VERIFICATIONSUCCESS 0x00 /* Verification successful */

2 #define SECOC_VERIFICATIONFAILURE 0x01 /* Verification failed */
3 #define SECOC_FRESHNESSFAILURE 0x02 /* Verification failed because of an unexpected freshness value */
4 #define SECOC_MESSAGELINKERFAILURE 0x03E /* Verification failed because of an unexpected message linker value */
5 #define SECOC_VERIFICATIONNOTEXECUTED 0x03F /* Verification not executed */
6
7 #define SECOC_FEATUREDATAINITIALIZED 0x3e0d8212 /* Parameters successfully initialized */

In this example, the definition of these return values is global, i.e., the values can
be used by all functions of this source file.

Tip

If you define such return values, it is recommended to define reasonable

values, e.g., according to related AUTOSAR definitions.

Saving current data provided At run time, functions of the user code require access to the current data of
by Crypto Service Manager the implemented functionalities of the AUTOSAR Crypto Service Manager (CSM)
and Freshness Value Manager and Freshness Value Manager (FVM). To provide access to this data, the following
structure is specified:
1 /* Struct to store current feature data */
2 struct UserCode_FeatureData
3 {
4 uint8* CsmJobHandle; /* Handle providing current data of the Crypto Service Manager functionalities */
5 uint8* TimeBaseHandle; /* Handle providing current data of the Freshness Value Manager functionalities */
6 uint32 isInitialized; /* Flag indicating whether the all required parameters are initialized */
7 };

Initializing the user code for The user code must be initialized for each secured IPDU. For this purpose, you
each secured IPDU must implement the DsBusCustomCode_onApplicationInit function. During
the initialization phase of the executable application, this function is called for
each secured IPDU.

The following code is an extract of the

DsBusCustomCode_onApplicationInit function as it is implemented in the
UserCode_SecOC.c source file.
1 Std_ReturnType DsBusCustomCode_onApplicationInit(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare required handles, data pointers, and variables, for example, the following: */
4 DsBusCustomCodePduHandle securedIPdu_PduHandle, authenticIPdu_PduHandle;
5 DsBusCustomCodeEcuHandle ecuHandle;
6 DsBusCustomCodeCommunicationClusterHandle communicationClusterHandle;
7 uint32 authenticIPdu_SduLength;
8 char* keyAsString;
9 uint32 keyLength;
10 uint8* featureDataPtr;
11 static uint8 isInitialized = 0;
12 ...
13
14 /* Execute the DSBUSCUSTOMCODE_CHECK_NULL macro to check whether the PduFeatureHandle is NULL.
15 * If it is, a message is written to the application log and the DsBusCustomCode_onApplicationInit function
16 * returns E_NOT_OK.
17 * Get the descriptor of the PduFeatureHandle. */
18 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);

43
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

19 DsBusCustomCode_getDescriptor(PduFeatureHandle, &featureDescriptor);
20
21 /* Create an instance of the UserCode_FeatureData struct to store PDU-specific feature data.
22 * Assign the instantiated struct to the featureInstanceData pointer.
23 * Check the pointer via the DSBUSCUSTOMCODE_CHECK_NULL macro. */
24 struct UserCode_FeatureData* featureInstanceData = (struct UserCode_FeatureData*)rtlib_malloc(sizeof(struct
25 UserCode_FeatureData));
26 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, featureInstanceData);
27 memset(featureInstanceData, 0, sizeof(struct UserCode_FeatureData));
28
29 /* Assign the instantiated UserCode_FeatureData struct via its featureInstanceData pointer to
30 * the featureDataPtr pointer.
31 * Assign the featureDataPtr pointer to the PDUFeatureHandle.
32 * Execute the DSBUSCUSTOMCODE_TRY macro to check whether the DsBusCustomCodePduFeature_setFeatureDataPtr
33 * function is called successfully.
34 * If it is not, a message is written to the application log and the DsBusCustomCode_onApplicationInit
35 * function returns E_NOT_OK. */
36 featureDataPtr = (uint8*)featureInstanceData;
37 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_setFeatureDataPtr(PduFeatureHandle,
38 featureDataPtr));
39
40 /* Call the UserCode_SecOC_Init function of the demo user code implementation to initialize required
41 * user code functions etc. */
42 UserCode_SecOC_Init();
43
44 /* Initialize the time base. Depending on the bus implementation software, the bus communication is either
45 * communication-cluster-based or ECU-based. Therefore, there can be one time base per communication cluster
46 * or ECU. By initialzing the time base as follows, no software-specific adaptions are required:
47 * For cluster-based bus communication, the time base is initialized for the cluster via the first If-Else loop.
48 * For ECU-based bus communcation, the cluster-based initialization of the time base is overwritten by an
49 * ECU-based initialization via the second If-Else loop.
50 * Check the handles and function calls via the DSBUSCUSTOMCODE_CHECK_NULL and DSBUSCUSTOMCODE_TRY macros. */
51 returnValue = DsBusCustomCodePduFeature_getCommunicationCluster(PduFeatureHandle, &communicationClusterHandle);
52 if (returnValue == E_OK)
53 {
54 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, communicationClusterHandle);
55 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCode_getName(communicationClusterHandle,
56 &communicationClusterName));
57 USERCODE_DEBUG_PRINT("Communication Cluster: %s\n", communicationClusterName);
58 timeBaseName = communicationClusterName;
59 }
60 else
61 {
62 /* No cluster available. */
63 communicationClusterHandle = NULL_PTR;
64 communicationClusterName = NULL_PTR;
65 USERCODE_DEBUG_PRINT("No Communication Cluster defined.\n");
66 timeBaseName = NULL_PTR;
67 }
68
69 returnValue = DsBusCustomCodePduFeature_getEcu(PduFeatureHandle, &ecuHandle);
70 if (returnValue == E_OK)
71 {
72 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, ecuHandle);
73 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCode_getName(ecuHandle, &ecuName));
74 USERCODE_DEBUG_PRINT("ECU: %s\n", ecuName);
75 /* If ECU available, initialize time base ECU-based. */
76 timeBaseName = ecuName;
77 }
78 else
79 {
80 /* No ECU available. */
81 ecuHandle = NULL_PTR;

44
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

82 ecuName = NULL_PTR;
83 USERCODE_DEBUG_PRINT("No ECU defined.\n");
84 timeBaseName = communicationClusterName;
85 }
86 USERCODE_DEBUG_PRINT("Timebase name: %s\n", timeBaseName);
87
88 /* Get the secured IPDU and its related authentic IPDU via their handles.
89 * Check the handles and function calls via the DSBUSCUSTOMCODE_CHECK_NULL and DSBUSCUSTOMCODE_TRY macros. */
90 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getPdu(PduFeatureHandle,
91 &securedIPdu_PduHandle));
92 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, securedIPdu_PduHandle);
93 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getAuthenticPdu(securedIPdu_PduHandle,
94 &authenticIPdu_PduHandle));
95 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCode_getName(securedIPdu_PduHandle, &securedIPduName));
96 USERCODE_DEBUG_PRINT("Secured IPDU: %s\n", securedIPduName);
97
98 /* Get parameters that are required by the bus real-time code, such as the authentic IPDU payload length or
99 * the key ID. */
100 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduLength(authenticIPdu_PduHandle,
101 &authenticIPdu_SduLength));
102 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getKeyId(securedIPdu_PduHandle, &keyId));
103 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCode_getName(authenticIPdu_PduHandle, &authenticPduName));
104 USERCODE_DEBUG_PRINT("Authentic IPDU: %s\n", authenticPduName);
105
106 /* Get the complete length of the freshness value.
107 * Calculate the data length that is to be authenticated by taking the related AUTOSAR calculation method
108 * into account. */
109 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getFreshnessValueLength(securedIPdu_PduHandle,
110 &freshnessValueLength));
111 dataToAuthentictatorLength = sizeof(uint16) + authenticIPdu_SduLength + (freshnessValueLength + 7) / 8;
112
113 /* Call the demo user code function that creates a CMAC/AES128-compliant Crypto Service Manager handle
114 * (CsmJobHandle) for the calculated authenticated length. */
115 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_SecOCHelper_Create_CryptoJob_For_CMAC_AES_128_Authentication(
116 &featureInstanceData->CsmJobHandle, dataToAuthentictatorLength));
117
118 /* Initialize the access to the OEM-specific key that is used for calculating the authenticator.
119 * To access the key, it must be provided by a user-specific function, e.g., getKeyFromKeyID. */
120 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCPduFeature_setKeyPtr(PduFeatureHandle, keyPtr));
121 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCPduFeature_setKeyLength(PduFeatureHandle,
122 keyLength));
123 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_Csm_KeyElementSet(featureInstanceData->CsmJobHandle, keyId,
124 CRYPTO_KE_MAC_KEY, keyPtr, keyLength));
125
126 /* Call the demo user code function that creates a Freshness Value Manager instance. */
127 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_SecOC_Fvm_Init(timeBaseName, &featureInstanceData->
128 TimeBaseHandle));
129
130 /* Get the required secured IPDU parameters and check whether they are set by using the
131 * DSBUSCUSTOMCODE_TRY macro */
132 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduLength(securedIPdu_PduHandle,
133 &securedIPdu_SduLength));
134 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getIsTx(securedIPdu_PduHandle, &isTx));
135 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getDataId(securedIPdu_PduHandle, &dataId));
136 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength(
137 securedIPdu_PduHandle, &freshnessValueTxLength));
138 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength(securedIPdu_PduHandle,
139 &authInfoTxLength));
140
141 /* Set the SECOC_FEATUREDATAINITIALIZED return value after initializing all parameters successfully. */
142 featureInstanceData->isInitialized = SECOC_FEATUREDATAINITIALIZED;
143
144 /* Return whether DsBusCustomCode_onApplicationInit function is implemented correctly. */

45
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

145 return E_OK;

146 }

Tip

§ The DsBusCustomCode_onApplicationInit function does not

influence the real-time performance of the user code
during the execution phase. For optimum performance, it is
therefore recommended to implement time-consuming operations
such as malloc or non-deterministic function calls in the
DsBusCustomCode_onApplicationInit function.
§ The DSBUSCUSTOMCODE_CHECK_NULL and DSBUSCUSTOMCODE_TRY
macros are defined by the common DsBusCustomCode module. For
optimum performance, it is recommended to use these macros to check
each pointer and function parameter once at an early stage of the code
execution, i.e., as early as the DsBusCustomCode_onApplicationInit
function, if possible.
§ By using the DsBusCustomCodePduFeature_setFeatureDataPtr
function, you can assign a pointer to any handle. At run time, you can
access the handle and its current data by calling the pointer at any time in
the DsBusCustomCode_onPduFeatureExecution function.

Executing the user code for To execute the user code for each secured IPDU, you must implement the
each secured IPDU DsBusCustomCode_onPduFeatureExecution function. This function is called
each time the transmission of a secured IPDU is triggered or a secured IPDU is
received. With each function call, PDU data (e.g., direction, payload length) is
provided to the user code.

In the UserCode_SecOC.c source file, the

DsBusCustomCode_onPduFeatureExecution function is structured in three
parts, as shown in the following overview.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function that applies to each secured IPDU,
4 * regadless of its direction. */
5
6 /* Part 2 and 3: If-Else loop that checks whether the secured IPDU is a TX IPDU. */
7 if (isTx)
8 {
9 /* Part 2: Executed only if the secured IPDU is a TX secured IPDU. */
10 }
11 else
12 {
13 /* Part 3: Executed only if the secured IPDU is an RX secured IPDU. */
14 }
15 return E_OK;
16 }

For more information on the individual parts, refer to:

§ Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution
function on page 47

46
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

§ Part 2: TX-related part of the DsBusCustomCode_onPduFeatureExecution

function on page 50
§ Part 3: RX-related part of the DsBusCustomCode_onPduFeatureExecution
function on page 53

Part 1: Common part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed for
each secured IPDU, regardless of whether it is a TX secured IPDU or an RX
secured IPDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Declare required handles, data pointers, and variables. Among others, the following: */
4 DsBusCustomCodePduHandle securedIPdu_PduHandle;
5 uint32 securedIPdu_SduLength;
6 uint8* securedIPdu_SduDataPtr;
7 DsBusCustomCodePduHandle authenticIPdu_PduHandle;
8 uint8* featureDataPtr;
9 Crypto_JobType* Crypto_Job;
10 uint8* csmJobHandle;
11 uint16 messageLinkLength = 0;
12 uint16 messageLinkPosition = 0;
13 char* featureDescriptor;
14 ...
15
16 /* Access the PduFeatureHandle and its data.
17 * Check the handle by using the DSBUSCUSTOMCODE_CHECK_NULL macro. */
18 DSBUSCUSTOMCODE_CHECK_NULL(g_DsBusCustomCodeDefaultDescriptor, PduFeatureHandle);
19 DsBusCustomCode_getDescriptor(PduFeatureHandle, &featureDescriptor);
20
21 /* Get the data structure that is addressed via the featureDataPtr pointer, i.e., the data of the related
22 * UserCode_FeatureData struct that was created during the execution of the
23 * DsBusCustomCode_onApplicationInit function. */
24 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getFeatureDataPtr(PduFeatureHandle,
25 (uint8**)&featureDataPtr));
26
27 /* Check whether the initialization of the PduFeatureHandle was successfull.
28 * If not, return E_NOT_OK and exit DsBusCustomCode_onPduFeatureExecution. */
29 if (SECOC_FEATUREDATAINITIALIZED != ((struct UserCode_FeatureData*)featureDataPtr)->isInitialized)
30 {
31 return E_NOT_OK;
32 }
33
34 /* Get the secured IPDU via its securedIPdu_PduHandle.
35 * Check the handle by using the DSBUSCUSTOMCODE_CHECK_NULL macro.
36 * Get required secured IPDU parameters. */
37 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePduFeature_getPdu(PduFeatureHandle,
38 &securedIPdu_PduHandle));
39 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, securedIPdu_PduHandle);
40
41 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduLength(securedIPdu_PduHandle,
42 &securedIPdu_SduLength));
43 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduDataPtr(securedIPdu_PduHandle,
44 &securedIPdu_SduDataPtr));
45 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getIsTx(securedIPdu_PduHandle, &isTx));
46
47 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getDataId(securedIPdu_PduHandle, &dataId));
48 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getFreshnessValueLength(securedIPdu_PduHandle,
49 &freshnessValueLength));
50 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength(
51 securedIPdu_PduHandle, &freshnessValueTxLength));

47
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

52 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getKeyId(securedIPdu_PduHandle, &keyId));

53 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength(securedIPdu_PduHandle,
54 &authInfoTxLength));
55
56 /* Get the length of the secured header of the authentic IPDU in bytes.
57 * If the value of the related parameter is not set, set the value to 0.
58 * If a logical error occurs (e.g., an invalid handle), return E_NOT_OK and
59 * exit DsBusCustomCode_onPduFeatureExecution. */
60 returnValue = DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength(securedIPdu_PduHandle, &authPduHeaderLength);
61 if (returnValue == E_PARAMETER_NOT_SET)
62 {
63 authPduHeaderLength = 0;
64 }
65 else if (returnValue != E_OK)
66 {
67 return E_NOT_OK;
68 }
69 /* Convert the byte-based header length in a bit-based value. */
70 securedIPduAuthenticIPduPosition = authPduHeaderLength * 8;
71
72 /* Get the authentic IPDU via its authenticIPdu_PduHandle.
73 * Check the handle by using the DSBUSCUSTOMCODE_CHECK_NULL macro.
74 * Get required authentic IPDU parameters. */
75 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getAuthenticPdu(securedIPdu_PduHandle,
76 &authenticIPdu_PduHandle));
77 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, authenticIPdu_PduHandle);
78
79 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduLength(authenticIPdu_PduHandle,
80 &authenticIPdu_SduLength));
81 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodePdu_getSduDataPtr(authenticIPdu_PduHandle,
82 &authenticIPdu_SduDataPtr));
83
84 /* Determine the acutal length of the authentic IPDU according to AUTOSAR:
85 * If no secured header is specified, the actual length is derived from the authenticIPdu_SduLength parameter.
86 * If a secured header is specified, the acutal length is read from the header by using the related demo user
87 * code function.
88 * The actual length can be equal or smaller than the SDU length. If the actual length is bigger than the SDU
89 * length, this indicates a logical error in determining the actual length. In this case, return E_NOT_OK and
90 * exit DsBusCustomCode_onPduFeatureExecution. */
91 if (authPduHeaderLength == 0)
92 {
93 authenticIPdu_ActualLength = authenticIPdu_SduLength;
94 }
95 else if (authPduHeaderLength == 1)
96 {
97 uint8* header = securedIPdu_SduDataPtr;
98 authenticIPdu_ActualLength = USER_CODE_INT8_FROM_BE(*header);
99 }
100 else if (authPduHeaderLength == 2)
101 {
102 uint16* header = (uint16*) securedIPdu_SduDataPtr;
103 authenticIPdu_ActualLength = USER_CODE_INT16_FROM_BE(*header);
104 }
105 else if (authPduHeaderLength == 4)
106 {
107 uint32* header = (uint32*) securedIPdu_SduDataPtr;
108 authenticIPdu_ActualLength = USER_CODE_INT32_FROM_BE(*header);
109 }
110 else
111 {
112 return E_NOT_OK;
113 }
114

48
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

115 if (authenticIPdu_ActualLength > authenticIPdu_SduLength)

116 {
117 return E_NOT_OK;
118 }
119
120 /* Get whether the secured IPDU is configured as cryptographic IPDU.
121 * If the value of the related parameter is not set, set the value to FALSE, i.e., the secured IPDU is not
configured as
122 * cryptographic IPDU.
123 * If a logical error occurs (e.g., an invalid handle), return E_NOT_OK and
124 * exit DsBusCustomCode_onPduFeatureExecution. */
125 returnValue = DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu(securedIPdu_PduHandle,
126 &useAsCryptographicPdu);
127 if (returnValue == E_PARAMETER_NOT_SET)
128 {
129 useAsCryptographicPdu = FALSE;
130 }
131 else if (returnValue != E_OK)
132 {
133 return E_NOT_OK;
134 }
135
136 /* If the secured IPDU is configured as cryptographic IPDU, get the message link length.
137 * If the function is executed without logical errors and a message link length is specified, get the message
138 * link position. However, regardless of whether a message linker is specified, the authentic IPDU is not
139 * included in the cryptographic IPDU.
140 * If the secured IPDU is not configured as cryptographic IPDU, include the authentic IPDU with its acutal
141 * length in the secured IPDU.
142 * Use the result of the If-Else loop to calculate the authenticator position and message linker position in
143 * the secured IPDU. */
144 if (useAsCryptographicPdu)
145 {
146 uint16 linkLength;
147 returnValue = DsBusCustomCodeSecuredIPdu_getMessageLinkLength(securedIPdu_PduHandle, &linkLength);
148 if (returnValue == E_OK && linkLength > 0)
149 {
150 messageLinkLength = linkLength;
151 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getMessageLinkPosition(
152 securedIPdu_PduHandle, &messageLinkPosition));
153 }
154
155 securedIPduFreshnessValuePosition = securedIPduAuthenticIPduPosition;
156 }
157 else
158 {
159 securedIPduFreshnessValuePosition = securedIPduAuthenticIPduPosition + authenticIPdu_ActualLength * 8;
160 }
161
162 securedIPduAuthenticatorPosition = securedIPduFreshnessValuePosition + freshnessValueTxLength;
163 securedIPduMessageLinkerPosition = securedIPduAuthenticatorPosition + authInfoTxLength;
164
165 /* Get the length of the secured area, i.e., the length of the authentic IPDU that is to be secured.
166 * If the function is executed without logical errors and a secured area length is specified, get the secured
167 * area offset.
168 * If the sum of secured area length and secured area offset is bigger than the actual length, this indicates a
169 * logical error in getting the secured area length and/or offset. In this case, return E_NOT_OK and
170 * exit DsBusCustomCode_onPduFeatureExecution.
171 * Pass the accessed and validated values to the actualSecuredAreaLength and
172 * actualSecuredAreaOffset variables. */
173 {
174 uint32 areaLength;
175 returnValue = DsBusCustomCodeSecuredIPdu_getSecuredAreaLength(securedIPdu_PduHandle, &areaLength);
176 if (returnValue == E_OK && areaLength > 0)

49
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

177 {
178 securedAreaLength = areaLength;
179 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset(
180 securedIPdu_PduHandle, &securedAreaOffset));
181
182 if (securedAreaOffset + securedAreaLength > authenticIPdu_ActualLength)
183 {
184 return E_NOT_OK;
185 }
186
187 actualSecuredAreaOffset = securedAreaOffset;
188 actualSecuredAreaLength = securedAreaLength;
189 }
190 /* If no secured area length is specified, set the actual secured area offset to 0 and use the entire
191 * actual length of the authentic IPDU as the actual secured area length. */
192 else
193 {
194 actualSecuredAreaOffset = 0;
195 actualSecuredAreaLength = authenticIPdu_ActualLength;
196 }
197 }
198
199 /* Access the run-time data that is written to the UserCode_FeatureData struct by using the CsmJobHandle.
200 * Get the applicable crypto job by calling the related demo user code function.
201 * Check the user code function and its Crypto_Job parameter by using the DSBUSCUSTOMCODE_TRY and
202 * DSBUSCUSTOMCODE_CHECK_NULL marcros. */
203 csmJobHandle = ((struct UserCode_FeatureData*)featureDataPtr)->CsmJobHandle;
204 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_CryptoJob_Get(csmJobHandle, &Crypto_Job));
205 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, Crypto_Job);
206 /* End of part 1, i.e., end of the common part of the DsBusCustomCode_onPduFeatureExecution function */
207
208 /* Part 2 and 3: If-Else loop that checks whether the secured IPDU is a TX IPDU. */
209 if (isTx)
210 {
211 /* Part 2: Executed only if the secured IPDU is a TX secured IPDU.
212 * For details, see below. */
213 }
214 else
215 {
216 /* Part 3: Executed only if the secured IPDU is an RX secured IPDU.
217 * For details, see below. */
218 }
219
220 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
221 return E_OK;
222 }

Part 2: TX-related part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed only
if the secured IPDU is a TX secured IPDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function. */
4 ...
5
6 /* If-Else loop that checks whether the secured IPDU is a TX IPDU.
7 * Part 2: If the secured IPDU is a TX IPDU, the If part of the If-Else loop is executed. */
8 if (isTx)
9 {
10 /* Declare local variables and get required TX secured IPDU parameters. */
11 uint32 enableAuthentication;

50
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

12 uint32 enableFreshnessValueCalculation;
13 uint32 authenticatonType;
14 sint64 freshnessValueOffset;
15
16 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalculation(
17 PduFeatureHandle, &enableFreshnessValueCalculation));
18 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication(
19 PduFeatureHandle, &enableAuthentication));
20 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType(
21 PduFeatureHandle, &authenticatonType));
22 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset(
23 PduFeatureHandle, &freshnessValueOffset));
24
25 /* If the secured IPDU is configured as cryptographic IPDU and a message link length is specified, call the
26 * related demo user code function to copy the required authentication information to the
27 * message link length. */
28 if (useAsCryptographicPdu)
29 {
30 if (messageLinkLength > 0)
31 {
32 UserCode_SecOCHelper_CopyBits(securedIPdu_SduDataPtr, securedIPduMessageLinkerPosition,
33 authenticIPdu_SduDataPtr, messageLinkPosition, messageLinkLength);
34 }
35 }
36 /* If the secured IPDU is not configured as cryptographic IPDU, copy the authentic IPDU to the secured IPDU,
37 * if required. Whether copying is required depends on the bus implementation software.
38 * Specifying the copying as follows increases the performance and no software-specific adaptions
39 * are required. */
40 else
41 {
42 if (securedIPdu_SduDataPtr != authenticIPdu_SduDataPtr)
43 {
44 memcpy(securedIPdu_SduDataPtr + authPduHeaderLength, authenticIPdu_SduDataPtr,
45 authenticIPdu_ActualLength);
46 }
47 }
48
49 /* If calculating the freshness value in the user code is disabled, get the user-defined freshness value. */
50 if(enableFreshnessValueCalculation == 0)
51 {
52 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue(
53 PduFeatureHandle, &freshnessValue));
54 }
55 /* If calculating the freshness value in the user code is enabled, copy the calculated freshness value and
56 * the specified TX length to local variables.
57 * Copying the data to local variables with defined data types avoids problems, e.g., if the freshness value
58 * manager specifies different data types for the accessed variables. */
59 else
60 {
61 uint32 txFreshnessLength = freshnessValueTxLength;
62 uint64 txFreshnessValue;
63 UserCode_SecOC_GetTxFreshness(((struct UserCode_FeatureData*)featureDataPtr)->TimeBaseHandle, 0,
64 (uint8*)&txFreshnessValue, &txFreshnessLength);
65 freshnessValue = txFreshnessValue;
66 }
67 USERCODE_DEBUG_PRINT("TX Freshness Value 0x%llX\n", freshnessValue);
68
69 /* Write the applicable freshness value (i.e., user-defined or calculated in user code) to the
70 * freshnessValue parameter.
71 * If specified, add the feshness offset value to the freshness value. */
72 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue(
73 PduFeatureHandle, freshnessValue));
74 freshnessValue += freshnessValueOffset;

51
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

75
76 /* If caluclating the authenticator in the user code is disabled, get the user-defined authenticator value
77 * via the AuthenticatorPtr. */
78 if (enableAuthentication == 0)
79 {
80 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr(
81 PduFeatureHandle, &AuthenticatorPtr));
82 DSBUSCUSTOMCODE_CHECK_NULL(featureDescriptor, AuthenticatorPtr);
83 authenticatorLength = (authInfoTxLength + 7) / 8;
84 }
85 /* If caluclating the authenticator in the user code is enabled, call the related demo user code function
86 * for calculating the authenticator. */
87 else
88 {
89 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_SecOCHelper_PrepareDataToAuthenticator(dataId,
90 authenticIPdu_SduDataPtr + actualSecuredAreaOffset, actualSecuredAreaLength, freshnessValue,
91 freshnessValueLength, Crypto_Job->PrimitiveInputOutput->inputPtr, &Crypto_Job->PrimitiveInputOutput->
92 inputLength));
93 USERCODE_DEBUG_PRINTDATA("TX Data to Auth", Crypto_Job->PrimitiveInputOutput->inputPtr, Crypto_Job->
94 PrimitiveInputOutput->inputLength);
95
96 AuthenticatorPtr = Crypto_Job->PrimitiveInputOutput->outputPtr;
97 authenticatorLength = Crypto_Job->jobPrimitiveInfo->primitiveInfo->resultLength;
98
99 /* According to AUTOSAR, the Crypto Service Manager expects a pre-set outputLengthPtr. Therefore, set
100 * the outputLengthPtr to the expected authenticator length. */
101 *(Crypto_Job->PrimitiveInputOutput->outputLengthPtr) = authenticatorLength;
102
103 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_Csm_MacGenerate(csmJobHandle, Crypto_Job->
104 PrimitiveInputOutput->mode, Crypto_Job->PrimitiveInputOutput->inputPtr, Crypto_Job->
105 PrimitiveInputOutput->inputLength, Crypto_Job->PrimitiveInputOutput->outputPtr, Crypto_Job->
106 PrimitiveInputOutput->outputLengthPtr));
107 }
108 USERCODE_DEBUG_PRINTDATA("TX MAC", AuthenticatorPtr, authenticatorLength);
109
110 /* If invalidating the authentication value is enabled, invert the most significant bit of the
111 * authenticator. */
112 if (authenticatonType != 0)
113 {
114 USERCODE_DEBUG_PRINT("====== *** MAC MANIPULATION *** ======\n");
115 AuthenticatorPtr[0] ^= 0x80;
116 USERCODE_DEBUG_PRINTDATA("TX Manipulated MAC", AuthenticatorPtr, authenticatorLength);
117 }
118
119 /* Copy the TX freshness value (i.e., the truncated freshness value) to the secured IPDU by calling the
120 * related demo user code function. */
121 uint64 freshnessValue_BigEndian = USER_CODE_INT64_TO_BE(freshnessValue);
122 uint8* freshnessPtr = (uint8*)&freshnessValue_BigEndian;
123 uint32 startpos = 64 - freshnessValueTxLength;
124 UserCode_SecOCHelper_CopyBits(securedIPdu_SduDataPtr, securedIPduFreshnessValuePosition, freshnessPtr,
125 startpos, freshnessValueTxLength);
126
127 /* Copy the TX authenticator value (i.e., the truncated authenticator value) to the secured IPDU by calling
128 * the related demo user code function. */
129 UserCode_SecOCHelper_CopyBits(securedIPdu_SduDataPtr, securedIPduAuthenticatorPosition, AuthenticatorPtr, 0,
130 authInfoTxLength);
131 USERCODE_DEBUG_PRINTDATA("TX AuthenticIPdu", authenticIPdu_SduDataPtr, authenticIPdu_ActualLength);
132 USERCODE_DEBUG_PRINTDATA("TX SecuredIPdu", securedIPdu_SduDataPtr, securedIPdu_SduLength);
133 }
134 /* End of part 2, i.e., end of the TX-related part of the DsBusCustomCode_onPduFeatureExecution function */
135
136 /* Part 3: If the secured IPDU is an RX IPDU, the Else part of the If-Else loop is executed. */
137 else

52
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

138 {
139 /* For details, see below. */
140 }
141
142 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
143 return E_OK;
144 }

Part 3: RX-related part of the

DsBusCustomCode_onPduFeatureExecution function The following part
of the DsBusCustomCode_onPduFeatureExecution function is executed only
if the secured IPDU is an RX secured IPDU.
1 Std_ReturnType DsBusCustomCode_onPduFeatureExecution(DsBusCustomCodePduFeatureHandle PduFeatureHandle)
2 {
3 /* Part 1: Common part of the DsBusCustomCode_onPduFeatureExecution function. */
4 ...
5
6 /* If-Else loop that checks whether the secured IPDU is a TX IPDU. */
7 if (isTx)
8 {
9 /* Part 2: If the secured IPDU is a TX IPDU, the If part of the If-Else loop is executed. */
10 ...
11 }
12 /* Part 3: If the secured IPDU is an RX IPDU, the Else part of the If-Else loop is executed. */
13 else
14 {
15 /* Declare and initialize local variables. */
16 boolean useAuthDataFreshness = FALSE;
17 uint16 authDataFreshnessLength = 0;
18 uint16 authDataFreshnessStartPosition = 0;
19 uint32 verificationEnable;
20
21 /* If the secured IPDU is not configured as cryptographic IPDU, copy the data bytes of the secured IPDU to
22 * the authentic IPDU, if required. Whether copying is required depends on the bus implementation software.
23 * Specifying the copying as follows increases the performance and no software-specific adaptions
24 * are required. */
25 if (!useAsCryptographicPdu)
26 {
27 if (authenticIPdu_SduDataPtr != securedIPdu_SduDataPtr)
28 {
29 memcpy(authenticIPdu_SduDataPtr, securedIPdu_SduDataPtr + authPduHeaderLength,
30 authenticIPdu_ActualLength);
31 }
32 }
33 USERCODE_DEBUG_PRINTDATA("RX AuthenticIPdu", authenticIPdu_SduDataPtr, authenticIPdu_ActualLength);
34 USERCODE_DEBUG_PRINTDATA("RX SecuredIPdu", securedIPdu_SduDataPtr, securedIPdu_SduLength);
35
36 /* Get the enable state for verifying received authentication information.
37 * If disabled, set the verification result to SECOC_VERIFICATIONNOTEXECUTED. Then, exit
38 * DsBusCustomCode_onPduFeatureExecution with E_OK. */
39 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_getEnableVerification(
40 PduFeatureHandle, &verificationEnable));
41 if (verificationEnable == 0)
42 {
43 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_setVerificationResult(
44 PduFeatureHandle, SECOC_VERIFICATIONNOTEXECUTED));
45 USERCODE_DEBUG_PRINT("Verification not executed\n");
46 return E_OK;
47 }
48
49 /* If verification is enabled, perform the verification in the following sequence to increase the
50 * performance. */

53
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

51
52 /* Check if a message linker is specified. If it is, first verify the message linker by calling the
53 * related demo user code function.
54 * If the user code function indicates an error, set the verification result to SECOC_MESSAGELINKERFAILURE.
55 * Then, exit DsBusCustomCode_onPduFeatureExecution with E_OK. */
56 if (messageLinkLength > 0 && authenticIPdu_ActualLength * 8 >= messageLinkLength)
57 {
58 Std_ReturnType result = UserCode_SecOCHelper_CompareBits(securedIPdu_SduDataPtr,
59 securedIPduMessageLinkerPosition, authenticIPdu_SduDataPtr, messageLinkPosition, messageLinkLength);
60 if (result != E_OK)
61 {
62 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_setVerificationResult(
63 PduFeatureHandle, SECOC_MESSAGELINKERFAILURE));
64 USERCODE_DEBUG_PRINT("Verification aborted due to not matching message linker\n");
65 return E_OK;
66 }
67 }
68
69 /* Get whether a time stamp is used to calculate the freshness value.
70 * If the value of the related parameter is not set, set the value to FALSE, i.e., no time stamp is used.
71 * If a logical error occurs (e.g., an invalid handle), return E_NOT_OK and
72 * exit DsBusCustomCode_onPduFeatureExecution. */
73 {
74 boolean useFreshnessTimestamp;
75 returnValue = DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp(securedIPdu_PduHandle,
76 &useFreshnessTimestamp);
77 if (returnValue == E_PARAMETER_NOT_SET)
78 {
79 useFreshnessTimestamp = FALSE;
80 }
81 else if (returnValue != E_OK)
82 {
83 return E_NOT_OK;
84 }
85
86 /* If a time stamp is used, call the related demo user code function to access the received
87 * freshness value and its length, and copy the values to local variables.
88 * Copying the data to local variables with defined data types avoids problems, e.g., if the freshness
89 * value manager specifies different data types for the accessed variables. */
90 uint32 freshnessVerifyValueLength = freshnessValueLength;
91 uint64 freshnessVerifyValue;
92 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_SecOC_GetRxFreshness(((struct UserCode_FeatureData*)
93 featureDataPtr)->TimeBaseHandle, 0, securedIPdu_SduDataPtr + (securedIPduFreshnessValuePosition / 8),
94 freshnessValueTxLength, 0, (uint8*)&freshnessVerifyValue, &freshnessVerifyValueLength,
95 useFreshnessTimestamp));
96 freshnessValue = freshnessVerifyValue;
97 }
98 USERCODE_DEBUG_PRINT("RX Local Freshness Value 0x%llX\n", freshnessValue);
99
100 /* Get whether a part of the payload of the authentic IPDU is included in the freshness value.
101 * If the value of the related parameter is not set, set the value to FALSE, i.e., no payload is included in
the
102 * freshness value.
103 * If a logical error occurs (e.g., an invalid handle), return E_NOT_OK and
104 * exit DsBusCustomCode_onPduFeatureExecution. */
105 returnValue = DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness(securedIPdu_PduHandle,
106 &useAuthDataFreshness);
107 if (returnValue == E_PARAMETER_NOT_SET)
108 {
109 useAuthDataFreshness = FALSE;
110 }
111 else if (returnValue != E_OK)
112 {

54
Bus Custom Code Interface Handling May 2024
 Example of Implementing Secure Onboard Communication (SecOC) via the Bus Custom Code Interface

113 return E_NOT_OK;

114 }
115
116 /* If a part of the payload is included in the freshness value, get the length of the included payload.
117 * If the function is executed without logical errors and a length is specified, get the position of the
118 * start bit.
119 * Call the related demo user code function to access the related payload bits in the received
120 * freshness value */
121 if (useAuthDataFreshness)
122 {
123 uint16 length;
124 uint64 authDataFreshnessBE = 0;
125 uint64 authDataFreshness = 0;
126
127 returnValue = DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength(securedIPdu_PduHandle, &length);
128 if (returnValue == E_OK && length > 0)
129 {
130 authDataFreshnessLength = length;
131 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecuredIPdu_
132 getAuthDataFreshnessStartPosition(securedIPdu_PduHandle, &authDataFreshnessStartPosition));
133 }
134
135 UserCode_SecOCHelper_CopyBits((uint8*) &authDataFreshnessBE, 64 - authDataFreshnessLength,
136 authenticIPdu_SduDataPtr, authDataFreshnessStartPosition, authDataFreshnessLength);
137 authDataFreshness = USER_CODE_INT64_FROM_BE(authDataFreshnessBE);
138 USERCODE_DEBUG_PRINT("RX AuthDataFreshness 0x%llX\n", authDataFreshness);
139 }
140
141 /* Now you can call the user code functions for calculating the expected freshness value.
142 * These functions are not part of the demo user code. */
143
144 /* Set the freshness value that was calculated in the user code and is expected to be received. */
145 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue(
146 PduFeatureHandle, freshnessValue));
147
148 /* Call the demo user code function that collects the received data which is required for verifying
149 * the received authentication information. */
150 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_SecOCHelper_PrepareDataToAuthenticator(dataId,
151 authenticIPdu_SduDataPtr + actualSecuredAreaOffset, actualSecuredAreaLength, freshnessValue,
152 freshnessValueLength, Crypto_Job->PrimitiveInputOutput->inputPtr, &Crypto_Job->PrimitiveInputOutput->
153 inputLength));
154 USERCODE_DEBUG_PRINTDATA("RX Data to Auth", Crypto_Job->PrimitiveInputOutput->inputPtr, Crypto_Job->
155 PrimitiveInputOutput->inputLength);
156
157 authenticatorLength = Crypto_Job->jobPrimitiveInfo->primitiveInfo->resultLength;
158
159 /* According to AUTOSAR, the Crypto Service Manager expects a pre-set outputLengthPtr. Therefore, set the
160 * outputLengthPtr to the expected authenticator length. */
161 *(Crypto_Job->PrimitiveInputOutput->outputLengthPtr) = authenticatorLength;
162
163 /* Call the demo user code function that calculates the expected authenticator. */
164 DSBUSCUSTOMCODE_TRY(featureDescriptor, UserCode_Csm_MacGenerate(csmJobHandle, Crypto_Job->
165 PrimitiveInputOutput->mode, Crypto_Job->PrimitiveInputOutput->inputPtr, Crypto_Job->
166 PrimitiveInputOutput->inputLength, Crypto_Job->PrimitiveInputOutput->outputPtr, Crypto_Job->
167 PrimitiveInputOutput->outputLengthPtr));
168 USERCODE_DEBUG_PRINTDATA("MAC received", securedIPdu_SduDataPtr + (securedIPduAuthenticatorPosition / 8),
169 (authInfoTxLength + 7) / 8);
170
171 /* Call the demo user code function that compares the received authentication information with the
172 * expected authentication information.
173 * Set the related return value, i.e., SECOC_VERIFICATIONFAILURE or SECOC_VERIFICATIONSUCCESS. */
174 Std_ReturnType result = UserCode_SecOCHelper_CompareBits(securedIPdu_SduDataPtr + (
175 securedIPduAuthenticatorPosition / 8), freshnessValueTxLength % 8, Crypto_Job->PrimitiveInputOutput->

55
May 2024 Bus Custom Code Interface Handling
 Examples of Implementing User-Specific Functionalities via the Bus Custom Code Interface

176 outputPtr, 0, authInfoTxLength);

177
178 if (result != E_OK)
179 {
180 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_setVerificationResult(
181 PduFeatureHandle, SECOC_VERIFICATIONFAILURE));
182 USERCODE_DEBUG_PRINT("Verification failure\n");
183 }
184 else
185 {
186 DSBUSCUSTOMCODE_TRY(featureDescriptor, DsBusCustomCodeSecOCRxPduFeature_setVerificationResult(
187 PduFeatureHandle, SECOC_VERIFICATIONSUCCESS));
188 USERCODE_DEBUG_PRINT("Verification success\n");
189 }
190 }
191 /* Return whether DsBusCustomCode_onPduFeatureExecution function is implemented correctly. */
192 return E_OK;
193 }

56
Bus Custom Code Interface Handling May 2024
 API Reference of the Bus Custom Code Interface

API Reference of the Bus Custom Code Interface

Where to go from here Information in this section

Handles of the Bus Custom Code Interface.............................................. 58

Functions of the Bus Custom Code Interface........................................... 74

57
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Handles of the Bus Custom Code Interface

Where to go from here Information in this section

DsBusCustomCodeHandle....................................................................... 58
The handle that represents a DsBusCustomCode element.

DsBusCustomCodeCommunicationClusterHandle.................................... 59
The handle that represents a communication cluster.

DsBusCustomCodeEcuHandle.................................................................. 60
The handle that represents an ECU.

DsBusCustomCodePduHandle................................................................. 60
The handle that represents a PDU.

DsBusCustomCodePduFeatureHandle...................................................... 61
The handle that represents a PDU feature.

DsBusCustomCodeSecOCPduFeatureHandle............................................ 62
The handle that represents a SecOC PDU feature.

DsBusCustomCodeSecOCRxPduFeatureHandle........................................ 64
The handle that represents a SecOC RX PDU feature.

DsBusCustomCodeSecOCTxPduFeatureHandle........................................ 66
The handle that represents a SecOC TX PDU feature.

DsBusCustomCodeSecuredIPduHandle.................................................... 68
The handle that represents a secured IPDU.

DsBusCustomCodeSignalHandle.............................................................. 70
The handle that represents a signal of a PDU.

DsBusCustomCodeUserCodePduFeatureHandle....................................... 71
The handle that represents the PDU User Code feature of a PDU.

DsBusCustomCodeUserPortHandle.......................................................... 72
The handle that represents a user port that is available for the PDU User
Code feature of a PDU.

DsBusCustomCodeHandle

Purpose This handle represents a DsBusCustomCode element.

58
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Inheritance diagram

DsBusCustomCode

DsBusCustomCodeCommunicationCluster DsBusCustomCodeEcu DsBusCustomCodePdu DsBusCustomCodePduFeature DsBusCustomCodeSignal

DsBusCustomCodeSecuredIPdu

DsBusCustomCodeSecOCPduFeature DsBusCustomCodeUserCodePduFeature

DsBusCustomCodeSecOCRxPduFeature DsBusCustomCodeSecOCTxPduFeature

Include file DsBusCustomCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeCommunicationClusterHandle

Purpose This handle represents a communication cluster.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodeCommunicationCluster

Include file DsBusCustomCode.h

Functions of the handle This handle does not provide handle-specific functions.

59
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeEcuHandle

Purpose This handle represents an ECU.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodeEcu

Include file DsBusCustomCode.h

Functions of the handle This handle does not provide handle-specific functions.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodePduHandle

Purpose This handle represents a PDU.

60
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePdu

DsBusCustomCodeSecuredIPdu

Include file DsBusCustomCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodePdu_getCanChannelName on page 81 To get the name of a CAN channel.
DsBusCustomCodePdu_getCanFrameTriggering on page 82 To get the frame triggering of a CAN frame or the CAN
identifier of a J1939‑compliant IPDU.
DsBusCustomCodePdu_getIsTx on page 85 To get the direction of a PDU.
DsBusCustomCodePdu_getLinFrameTriggering on page 86 To get the frame triggering of a LIN frame.
DsBusCustomCodePdu_getSduDataPtr on page 88 To get the SduDataPtr pointer of a PDU.
DsBusCustomCodePdu_getSduLength on page 89 To get the SDU length of a PDU in bytes.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodePduFeatureHandle

Purpose This handle represents a PDU feature.

61
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePduFeature

DsBusCustomCodeSecOCPduFeature DsBusCustomCodeUserCodePduFeature

DsBusCustomCodeSecOCRxPduFeature DsBusCustomCodeSecOCTxPduFeature

Include file DsBusCustomCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90 To get the FeatureDataPtr pointer of a PDU feature
handle.
DsBusCustomCodePduFeature_getPdu on page 91 To get the PDU that is accessed by a PDU feature handle.
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93 To set the FeatureDataPtr pointer of a PDU feature
handle.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeSecOCPduFeatureHandle

Purpose This handle represents a SecOC PDU feature.

62
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePduFeature

DsBusCustomCodeSecOCPduFeature

DsBusCustomCodeSecOCRxPduFeature DsBusCustomCodeSecOCTxPduFeature

Include file DsBusCustomCode_SecOC.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset on To get the offset value of the position
page 94 of the authentication information in a
non-cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyAsString on page 96 To get the SecOC key of a secured IPDU
as a string value.
DsBusCustomCodeSecOCPduFeature_getKeyLength on page 97 To get the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyPtr on page 98 To get the KeyPtr pointer of a SecOC
PDU feature handle.
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset on To set an offset value to the position of
page 100 the authentication information in a non-
cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyLength on page 102 To set the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyPtr on page 103 To set the KeyPtr pointer of a SecOC
PDU feature handle.

Functions inherited from This handle inherits the following functions from
DsBusCustomCodePduFeature DsBusCustomCodePduFeatureHandle on page 61:
Handle

Function Purpose
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90 To get the FeatureDataPtr pointer of a PDU feature
handle.
DsBusCustomCodePduFeature_getPdu on page 91 To get the PDU that is accessed by a PDU feature handle.
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93 To set the FeatureDataPtr pointer of a PDU feature
handle.

63
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeSecOCRxPduFeatureHandle

Purpose This handle represents a SecOC RX PDU feature.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePduFeature

DsBusCustomCodeSecOCPduFeature

DsBusCustomCodeSecOCRxPduFeature

Include file DsBusCustomCode_SecOC.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue on To get the data of the user code that is
page 105 provided to an RX secured IPDU via the
Calculated Freshness Value variable.
DsBusCustomCodeSecOCRxPduFeature_getEnableVerification on page 106 To get the enable state for verifying
the authentication information of an RX
secured IPDU.
DsBusCustomCodeSecOCRxPduFeature_getVerificationResult on page 108 To get data of the user code that is
provided to an RX secured IPDU via the
Verification Result variable.
DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue on To set data of the user code to an
page 109 RX secured IPDU via the Calculated
Freshness Value variable.
DsBusCustomCodeSecOCRxPduFeature_setVerificationResult on page 111 To set data of the user code to an
RX secured IPDU via the Verification
Result variable.

64
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from
DsBusCustomCodeSecOCPduF DsBusCustomCodeSecOCPduFeatureHandle on page 62:
eatureHandle

Function Purpose
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset on To get the offset value of the position
page 94 of the authentication information in a
non-cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyAsString on page 96 To get the SecOC key of a secured IPDU
as a string value.
DsBusCustomCodeSecOCPduFeature_getKeyLength on page 97 To get the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyPtr on page 98 To get the KeyPtr pointer of a SecOC
PDU feature handle.
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset on To set an offset value to the position of
page 100 the authentication information in a non-
cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyLength on page 102 To set the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyPtr on page 103 To set the KeyPtr pointer of a SecOC
PDU feature handle.

Functions inherited from This handle inherits the following functions from
DsBusCustomCodePduFeature DsBusCustomCodePduFeatureHandle on page 61:
Handle

Function Purpose
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90 To get the FeatureDataPtr pointer of a PDU feature
handle.
DsBusCustomCodePduFeature_getPdu on page 91 To get the PDU that is accessed by a PDU feature handle.
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93 To set the FeatureDataPtr pointer of a PDU feature
handle.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

65
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeSecOCTxPduFeatureHandle

Purpose This handle represents a SecOC TX PDU feature.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePduFeature

DsBusCustomCodeSecOCPduFeature

DsBusCustomCodeSecOCTxPduFeature

Include file DsBusCustomCode_SecOC.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType on page 112 To get the enable state of the
authentication type manipulation
that is specified for a TX secured
IPDU.
DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue on page 114 To get the data of the user
code that is provided to a TX
secured IPDU via the Calculated
Freshness Value variable.
DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication on page 115 To get the enable state of the
authentication value calculation that
is specified for a TX secured IPDU.
DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalculation on To get the enable state of the
page 117 freshness value calculation that is
specified for a TX secured IPDU.
DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset on page 119 To get the offset value that is
specified for the freshness value of
a TX secured IPDU.
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr on To get the pointer to the byte
page 120 array that provides the user-defined
authentication value, which is
specified for a TX secured IPDU.
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue on page 121 To get the user-defined freshness
value that is specified for a TX
secured IPDU.
DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue on page 123 To set data of the user code to a TX
secured IPDU via the Calculated
Freshness Value variable.

66
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from
DsBusCustomCodeSecOCPduF DsBusCustomCodeSecOCPduFeatureHandle on page 62:
eatureHandle

Function Purpose
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset on To get the offset value of the position
page 94 of the authentication information in a
non-cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyAsString on page 96 To get the SecOC key of a secured IPDU
as a string value.
DsBusCustomCodeSecOCPduFeature_getKeyLength on page 97 To get the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_getKeyPtr on page 98 To get the KeyPtr pointer of a SecOC
PDU feature handle.
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset on To set an offset value to the position of
page 100 the authentication information in a non-
cryptographic secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyLength on page 102 To set the length of a SecOC key byte
array of a secured IPDU.
DsBusCustomCodeSecOCPduFeature_setKeyPtr on page 103 To set the KeyPtr pointer of a SecOC
PDU feature handle.

Functions inherited from This handle inherits the following functions from
DsBusCustomCodePduFeature DsBusCustomCodePduFeatureHandle on page 61:
Handle

Function Purpose
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90 To get the FeatureDataPtr pointer of a PDU feature
handle.
DsBusCustomCodePduFeature_getPdu on page 91 To get the PDU that is accessed by a PDU feature handle.
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93 To set the FeatureDataPtr pointer of a PDU feature
handle.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

67
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeSecuredIPduHandle

Purpose This handle represents a secured IPDU.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePdu

DsBusCustomCodeSecuredIPdu

Include file DsBusCustomCode_SecOC.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName on page 124 To get the value of the AUTOSAR
AuthAlgorithm attribute of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength on To get the value of the AUTOSAR
page 126 AuthDataFreshnessLength attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPosition To get the value of the AUTOSAR
on page 127 AuthDataFreshnessStartPosition attribute
of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength on page 128 To get the value of the AUTOSAR
AuthInfoTxLength attribute of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength on page 130 To get the value of the AUTOSAR
SecOCAuthPduHeaderLength attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthenticPdu on page 131 To get the authentic IPDU that is secured by a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts on To get the value of the AUTOSAR
page 132 AuthenticationBuildAttempts attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getAuthenticationRetries on page 134 To get the value of the AUTOSAR
AuthenticationRetries attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getDataId on page 135 To get the value of the AUTOSAR DataId
attribute of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttempts on To get the value of the AUTOSAR
page 136 FreshnessCounterSyncAttempts attribute of
a secured IPDU.
DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFactor To get the value of the AUTOSAR
on page 138 FreshnessTimestampTimePeriodFactor
attribute of a secured IPDU.

68
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Function Purpose
DsBusCustomCodeSecuredIPdu_getFreshnessValueId on page 139 To get the value of the AUTOSAR
FreshnessValueId attribute of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getFreshnessValueLength on page 141 To get the value of the AUTOSAR
FreshnessValueLength attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength on To get the value of the AUTOSAR
page 142 FreshnessValueTxLength attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getKeyId on page 143 To get the value of the AUTOSAR KeyID attribute
of a secured IPDU.
DsBusCustomCodeSecuredIPdu_getMessageLinkLength on page 144 To get the value of the AUTOSAR
MessageLinkLength attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getMessageLinkPosition on page 146 To get the value of the AUTOSAR
MessageLinkPosition attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getRxSecurityVerification on To get the value of the AUTOSAR
page 147 RxSecurityVerification attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getSecuredAreaLength on page 149 To get the value of the AUTOSAR
SecuredAreaLength attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset on page 151 To get the value of the AUTOSAR
SecuredAreaOffset attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWindow on To get the value of the AUTOSAR
page 152 TimestampRxAcceptanceWindow attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu on page 153 To get the value of the AUTOSAR
UseAsCryptographicIPdu attribute of a
secured IPDU.
DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness on page 155 To get the value of the AUTOSAR
UseAuthDataFreshness attribute of a secured
IPDU.
DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp on page 156 To get the value of the AUTOSAR
UseFreshnessTimestamp attribute of a secured
IPDU.

Functions inherited from This handle inherits the following functions from DsBusCustomCodePduHandle
DsBusCustomCodePduHandle on page 60:

Function Purpose
DsBusCustomCodePdu_getCanChannelName on page 81 To get the name of a CAN channel.
DsBusCustomCodePdu_getCanFrameTriggering on page 82 To get the frame triggering of a CAN frame or the CAN
identifier of a J1939‑compliant IPDU.
DsBusCustomCodePdu_getIsTx on page 85 To get the direction of a PDU.
DsBusCustomCodePdu_getLinFrameTriggering on page 86 To get the frame triggering of a LIN frame.

69
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Function Purpose
DsBusCustomCodePdu_getSduDataPtr on page 88 To get the SduDataPtr pointer of a PDU.
DsBusCustomCodePdu_getSduLength on page 89 To get the SDU length of a PDU in bytes.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeSignalHandle

Purpose This handle represents a signal of a PDU.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodeSignal

Include file DsBusCustomCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeSignal_getEndianness on page 158 To get the endianness of a signal.
DsBusCustomCodeSignal_getLength on page 159 To get the length of a signal.
DsBusCustomCodeSignal_getStartBitPosition on page 160 To get the start bit position of a signal.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

70
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

DsBusCustomCodeUserCodePduFeatureHandle

Purpose This handle represents the PDU User Code feature of a PDU.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodePduFeature

DsBusCustomCodeUserCodePduFeature

Include file DsBusCustomCode_PduUserCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts on page 162 To get the number of user ports that are
specified for a PDU via the PDU User Code
feature.
DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals on page 163 To get the number of user signals that are
specified for a PDU via the PDU User Code
feature.
DsBusCustomCodeUserCodePduFeature_getResult on page 164 To get the data of the user code that is
provided to an RX PDU via the PDU User
Code feature.
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering on To get the run‑time frame triggering of a
page 166 CAN frame or the run‑time CAN identifier
of a simulated RX J1939‑compliant IPDU
via the PDU User Code feature.
DsBusCustomCodeUserCodePduFeature_getUserPorts on page 168 To get the array of the user ports that are
specified for a PDU via the PDU User Code
feature.
DsBusCustomCodeUserCodePduFeature_getUserSignals on page 170 To get the array of the user signals that
are specified for a PDU via the PDU User
Code feature.
DsBusCustomCodeUserCodePduFeature_setResult on page 171 To set data of the user code to an RX PDU
via the PDU User Code feature.

71
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from
DsBusCustomCodePduFeature DsBusCustomCodePduFeatureHandle on page 61:
Handle

Function Purpose
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90 To get the FeatureDataPtr pointer of a PDU feature
handle.
DsBusCustomCodePduFeature_getPdu on page 91 To get the PDU that is accessed by a PDU feature handle.
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93 To set the FeatureDataPtr pointer of a PDU feature
handle.

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodeUserPortHandle

Purpose This handle represents a user port that is available for the PDU User Code feature
of a PDU.

Inheritance diagram
DsBusCustomCode

DsBusCustomCodeUserPort

Include file DsBusCustomCode_PduUserCode.h

Functions of the handle This handle provides the following functions:

Function Purpose
DsBusCustomCodeUserPort_getDirection on page 173 To get the direction of a user port that is available for the PDU User
Code feature of a PDU.
DsBusCustomCodeUserPort_getPortData on page 174 To get the data of a user port that is available for the PDU User Code
feature of a PDU.
DsBusCustomCodeUserPort_setPortData on page 176 To set data to a user port that is available for the PDU User Code
feature of a PDU.

72
Bus Custom Code Interface Handling May 2024
 Handles of the Bus Custom Code Interface

Functions inherited from This handle inherits the following functions from DsBusCustomCodeHandle on
DsBusCustomCodeHandle page 58:

Function Purpose
DsBusCustomCode_getDescriptor on page 78 To get the descriptor of a DsBusCustomCode handle.
DsBusCustomCode_getName on page 80 To get the name of an element that is addressed by a DsBusCustomCode
handle.

73
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Functions of the Bus Custom Code Interface

Where to go from here Information in this section

DsBusCustomCode_getDescriptor........................................................... 78
To get the descriptor of a DsBusCustomCode handle.

DsBusCustomCode_getName.................................................................. 80
To get the name of an element that is addressed by a DsBusCustomCode
handle.

DsBusCustomCodePdu_getCanChannelName......................................... 81
To get the name of a CAN channel.

DsBusCustomCodePdu_getCanFrameTriggering...................................... 82
To get the frame triggering of a CAN frame or the CAN identifier of a
J1939‑compliant IPDU.

DsBusCustomCodePdu_getIsTx................................................................ 85
To get the direction of a PDU.

DsBusCustomCodePdu_getLinFrameTriggering........................................ 86
To get the frame triggering of a LIN frame.

DsBusCustomCodePdu_getSduDataPtr.................................................... 88
To get the SduDataPtr pointer of a PDU.

DsBusCustomCodePdu_getSduLength..................................................... 89
To get the SDU length of a PDU in bytes.

DsBusCustomCodePduFeature_getFeatureDataPtr................................... 90
To get the FeatureDataPtr pointer of a PDU feature handle.

DsBusCustomCodePduFeature_getPdu.................................................... 91
To get the PDU that is accessed by a PDU feature handle.

DsBusCustomCodePduFeature_setFeatureDataPtr.................................... 93
To set the FeatureDataPtr pointer of a PDU feature handle.

DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOff
set........................................................................................................... 94
To get the offset value of the position of the authentication information
in a non-cryptographic secured IPDU.

DsBusCustomCodeSecOCPduFeature_getKeyAsString............................. 96
To get the SecOC key of a secured IPDU as a string value.

DsBusCustomCodeSecOCPduFeature_getKeyLength............................... 97
To get the length of a SecOC key byte array of a secured IPDU.

DsBusCustomCodeSecOCPduFeature_getKeyPtr...................................... 98
To get the KeyPtr pointer of a SecOC PDU feature handle.

DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOff
set......................................................................................................... 100
To set an offset value to the position of the authentication information in
a non-cryptographic secured IPDU.

74
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecOCPduFeature_setKeyLength.............................. 102
To set the length of a SecOC key byte array of a secured IPDU.

DsBusCustomCodeSecOCPduFeature_setKeyPtr.................................... 103
To set the KeyPtr pointer of a SecOC PDU feature handle.

DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessVa
lue......................................................................................................... 105
To get the data of the user code that is provided to an RX secured IPDU
via the Calculated Freshness Value variable.

DsBusCustomCodeSecOCRxPduFeature_getEnableVerification............... 106
To get the enable state for verifying the authentication information of an
RX secured IPDU.

DsBusCustomCodeSecOCRxPduFeature_getVerificationResult................ 108
To get data of the user code that is provided to an RX secured IPDU via
the Verification Result variable.

DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessVa
lue......................................................................................................... 109
To set data of the user code to an RX secured IPDU via the Calculated
Freshness Value variable.

DsBusCustomCodeSecOCRxPduFeature_setVerificationResult................ 111
To set data of the user code to an RX secured IPDU via the
Verification Result variable.

DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType............. 112
To get the enable state of the authentication type manipulation that is
specified for a TX secured IPDU.

DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessVa
lue......................................................................................................... 114
To get the data of the user code that is provided to a TX secured IPDU via
the Calculated Freshness Value variable.

DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication......... 115
To get the enable state of the authentication value calculation that is
specified for a TX secured IPDU.

DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValue
Calculation............................................................................................ 117
To get the enable state of the freshness value calculation that is specified
for a TX secured IPDU.

DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset.......... 119
To get the offset value that is specified for the freshness value of a TX
secured IPDU.

DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthentic
atorPtr................................................................................................... 120
To get the pointer to the byte array that provides the user-defined
authentication value, which is specified for a TX secured IPDU.

75
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshness
Value..................................................................................................... 121
To get the user-defined freshness value that is specified for a TX secured
IPDU.

DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessVal
ue......................................................................................................... 123
To set data of the user code to a TX secured IPDU via the Calculated
Freshness Value variable.

DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName...................... 124
To get the value of the AUTOSAR AuthAlgorithm attribute of a secured
IPDU.

DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength.............. 126
To get the value of the AUTOSAR AuthDataFreshnessLength attribute
of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPositio
n........................................................................................................... 127
To get the value of the AUTOSAR AuthDataFreshnessStartPosition
attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength........................... 128
To get the value of the AUTOSAR AuthInfoTxLength attribute of a
secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength................... 130
To get the value of the AUTOSAR SecOCAuthPduHeaderLength
attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthenticPdu................................. 131
To get the authentic IPDU that is secured by a secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts.......... 132
To get the value of the AUTOSAR AuthenticationBuildAttempts
attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getAuthenticationRetries..................... 134
To get the value of the AUTOSAR AuthenticationRetries attribute of
a secured IPDU.

DsBusCustomCodeSecuredIPdu_getDataId............................................ 135
To get the value of the AUTOSAR DataId attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttemp
ts........................................................................................................... 136
To get the value of the AUTOSAR FreshnessCounterSyncAttempts
attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFac
tor......................................................................................................... 138
To get the value of the AUTOSAR
FreshnessTimestampTimePeriodFactor attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getFreshnessValueId............................. 139
To get the value of the AUTOSAR FreshnessValueId attribute of a
secured IPDU.

76
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecuredIPdu_getFreshnessValueLength..................... 141
To get the value of the AUTOSAR FreshnessValueLength attribute of
a secured IPDU.

DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength................. 142
To get the value of the AUTOSAR FreshnessValueTxLength attribute
of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getKeyId.............................................. 143
To get the value of the AUTOSAR KeyID attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getMessageLinkLength........................ 144
To get the value of the AUTOSAR MessageLinkLength attribute of a
secured IPDU.

DsBusCustomCodeSecuredIPdu_getMessageLinkPosition....................... 146
To get the value of the AUTOSAR MessageLinkPosition attribute of a
secured IPDU.

DsBusCustomCodeSecuredIPdu_getRxSecurityVerification...................... 147
To get the value of the AUTOSAR RxSecurityVerification attribute
of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getSecuredAreaLength........................ 149
To get the value of the AUTOSAR SecuredAreaLength attribute of a
secured IPDU.

DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset.......................... 151
To get the value of the AUTOSAR SecuredAreaOffset attribute of a
secured IPDU.

DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWin
dow...................................................................................................... 152
To get the value of the AUTOSAR TimestampRxAcceptanceWindow
attribute of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu................. 153
To get the value of the AUTOSAR UseAsCryptographicIPdu attribute
of a secured IPDU.

DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness................... 155
To get the value of the AUTOSAR UseAuthDataFreshness attribute of
a secured IPDU.

DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp................. 156
To get the value of the AUTOSAR UseFreshnessTimestamp attribute of
a secured IPDU.

DsBusCustomCodeSignal_getEndianness............................................... 158
To get the endianness of a signal.

DsBusCustomCodeSignal_getLength..................................................... 159
To get the length of a signal.

DsBusCustomCodeSignal_getStartBitPosition......................................... 160
To get the start bit position of a signal.

77
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts.......... 162
To get the number of user ports that are specified for a PDU via the PDU
User Code feature.

DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignal
s............................................................................................................ 163
To get the number of user signals that are specified for a PDU via the
PDU User Code feature.

DsBusCustomCodeUserCodePduFeature_getResult................................ 164
To get the data of the user code that is provided to an RX PDU via the
PDU User Code feature.

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTri
ggering................................................................................................. 166
To get the run‑time frame triggering of a CAN frame or the run‑time
CAN identifier of a simulated RX J1939‑compliant IPDU via the PDU User
Code feature.

DsBusCustomCodeUserCodePduFeature_getUserPorts.......................... 168
To get the array of the user ports that are specified for a PDU via the PDU
User Code feature.

DsBusCustomCodeUserCodePduFeature_getUserSignals....................... 170
To get the array of the user signals that are specified for a PDU via the
PDU User Code feature.

DsBusCustomCodeUserCodePduFeature_setResult................................ 171
To set data of the user code to an RX PDU via the PDU User Code
feature.

DsBusCustomCodeUserPort_getDirection.............................................. 173
To get the direction of a user port that is available for the PDU User Code
feature of a PDU.

DsBusCustomCodeUserPort_getPortData............................................... 174
To get the data of a user port that is available for the PDU User Code
feature of a PDU.

DsBusCustomCodeUserPort_setPortData............................................... 176
To set data to a user port that is available for the PDU User Code feature
of a PDU.

DsBusCustomCode_getDescriptor

Purpose To get the descriptor of a DsBusCustomCode handle.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the

78
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the descriptor of a DsBusCustomCode handle.

Syntax
Std_ReturnType DsBusCustomCode_getDescriptor(DsBusCustomCodeHandle Handle, char** Descriptor)

Parent handle This function is provided by DsBusCustomCodeHandle on page 58.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
Handle A DsBusCustomCode handle.
Descriptor The descriptor of the handle.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare a pointer for the descriptor
2 char* featureDescriptor;
3 // Let the pointer point to the descriptor

79
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

4 DsBusCustomCode_getDescriptor (PduFeatureHandle, &featureDescriptor);

5

DsBusCustomCode_getName

Purpose To get the name of an element that is addressed by a DsBusCustomCode handle.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the name of an element that is addressed by a

DsBusCustomCode handle.

Syntax
Std_ReturnType DsBusCustomCode_getName(DsBusCustomCodeHandle Handle, char** Name)

Parent handle This function is provided by DsBusCustomCodeHandle on page 58.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
Handle A DsBusCustomCode handle.
Name The name of the element that is addressed by the DsBusCustomCode
handle.

80
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare pointer for name
2 char* name;
3 // Let the pointer point to the name
4 DsBusCustomCode_getName(PduFeatureHandle, &name);

DsBusCustomCodePdu_getCanChannelName

Purpose To get the name of a CAN channel.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the the name of a CAN channel.

Syntax
Std_ReturnType DsBusCustomCodePdu_getCanChannelName(DsBusCustomCodePduHandle PduHandle, char** Name)

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

81
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
Name The name of the CAN channel.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare pointer for CAN channel name
2 char* My_CanChannelName;
3
4 // Let the pointer point to the CAN channel name
5 DsBusCustomCodePdu_getCanChannelName(pduHandle, &My_CanChannelName);

DsBusCustomCodePdu_getCanFrameTriggering

Purpose To get the frame triggering of a CAN frame or the CAN identifier of a
J1939‑compliant IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

82
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description Depending on whether this function accesses a CAN frame or a J1939‑compliant

IPDU, it gets the following information:
§ CAN frame: This function gets the frame triggering, i.e., the following data:
§ CAN frame identifier
§ Identifier format, i.e., standard identifier format (11-bit) or extended
identifier format (29-bit)
§ CAN frame type, i.e., classic CAN frame or CAN FD frame
To get the frame triggering, this function has to access a PDU that is included
in the related frame. However, this function can get the frame triggering only
if the accessed PDU is included in exactly one CAN frame, i.e., there is only
one CAN frame triggering.
§ J1939‑compliant IPDU: This function gets the CAN identifier, i.e., the priority,
parameter group number, and source address.

However, this function gets only the CAN frame identifier or the CAN identifier
that is specified in the communication matrix:
§ If the communication matrix specifies an RX mask for the frame triggering, the
CAN frame identifier that is available on the bus for the accessed PDU might
differ from the CAN frame identifier that is specified in the communication
matrix. In this case, this function does not provide the CAN frame identifier
that is available on the bus.
§ If the CAN identifier of a J1939‑compliant IPDU changes at run time, e.g.,
because the related network node has claimed a new transport protocol
address, this function does not provide the changed identifier.

Tip

To get the data that is actually available on the bus at run time, you can use
the DsBusCustomCodePdu_getRuntimeCanFrameTriggering function
instead. However, this is possible only if you use the Bus Manager. Refer to
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTrigger
ing on page 166.

The data of this function is provided as a struct.

Syntax
Std_ReturnType DsBusCustomCodePdu_getCanFrameTriggering(DsBusCustomCodePduHandle PduHandle,
DsBusCustomCodeCanFrameTriggeringType* DsBusCustomCodeCanFrameTriggering)

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

83
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
DsBusCustomCodeCanFrameTriggering A struct of three elements providing the
following information:
§ (.Identifier): Providing the CAN
frame identifier or the CAN identifier of
J1939‑compliant IPDUs.
§ (.AddresingMode): Providing the
identifier format:
§ Standard = standard identifier format
(11-bit)
§ Extended = extended identifier format
(29-bit)
§ (.FrameBehavior): Providing the CAN
frame type:
§ Can20 = classic CAN frame
§ CanFd = CAN FD frame

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare CAN frame triggering variables (frame identifier, identifier format, frame type)
2 DsBusCustomCodeCanFrameTriggeringType My_CanFrameTriggering;
3 uint32 My_ID;
4 uint8 My_AddressingMode;
5 uint8 My_FrameBehavior;
6 ...
7 // Let the pointer point to the CAN frame triggering structure and extract frame triggering variables
8 DsBusCustomCodePdu_getCanFrameTriggering(pduHandle, &My_CanFrameTriggering);
9 My_ID = (uint32)My_CanFrameTriggering.Identifier;
10 My_AddressingMode = (uint8)My_CanFrameTriggering.AddresingMode;
11 My_FrameBehavior = (uint8)My_CanFrameTriggering.FrameBehavior;

84
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodePdu_getIsTx

Purpose To get the direction of a PDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the direction of a PDU, i.e, whether a PDU is transmitted (TX
PDU) or received (RX PDU).

Syntax
Std_ReturnType DsBusCustomCodePdu_getIsTx(DsBusCustomCodePduHandle PduHandle, boolean* IsTx)

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
IsTx The direction of the PDU:
§ TRUE: TX PDU
§ FALSE: RX PDU

85
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodePdu_getLinFrameTriggering

Purpose To get the frame triggering of a LIN frame.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the following information on the frame triggering of a LIN
frame:
§ LIN frame identifier (ID), which is part of the protected identifier (PID) of the
LIN frame header
§ Checksum type, i.e., classic or enhanced checksum calculation type

The information is provided as a struct.

To get the frame triggering, this function has to access a PDU that is included
in the related frame. However, this function can get the frame triggering only if
the accessed PDU is included in exactly one LIN frame, i.e., there is only one LIN
frame triggering.

Syntax
Std_ReturnType DsBusCustomCodePdu_getLinFrameTriggering(DsBusCustomCodePduHandle PduHandle,
DsBusCustomCodeLinFrameTriggeringType* DsBusCustomCodeLinFrameTriggering)

86
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
DsBusCustomCodeLinFrameTriggering A struct of two elements providing the LIN
frame triggering:
§ (.Identifier): Providing the LIN frame
identifier.
§ (.ChecksumType): Providing the
checksum type:
§ Classic = classic checksum calculation
type
§ Enhanced = enhanced checksum
calculation type

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare LIN frame triggering variables (frame identifier, checksum type)
2 DsBusCustomCodeLinFrameTriggeringType My_LinFrameTriggering;
3 uint32 My_ID;
4 uint8 My_ChecksumType;
5 ...
6 // Let the pointer point to the LIN frame triggering structure and extract frame triggering variables
7 DsBusCustomCodePdu_getLinFrameTriggering(pduHandle, &My_LinFrameTriggering);
8 My_ID = (uint32)My_LinFrameTriggering.Identifier;
9 My_ChecksumType = (uint8)My_LinFrameTriggering.ChecksumType;

87
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodePdu_getSduDataPtr

Purpose To get the SduDataPtr pointer of a PDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the SduDataPtr pointer of a PDU. The pointer points to the
SDU bytes, i.e., the data bytes of the PDU.

Syntax
Std_ReturnType DsBusCustomCodePdu_getSduDataPtr(DsBusCustomCodePduHandle PduHandle, uint8** SduDataPtr)

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
SduDataPtr The pointer to the SDU bytes.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.

88
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Value Description
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodePdu_getSduLength

Purpose To get the SDU length of a PDU in bytes.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the SDU length, i.e., the payload length of a PDU in bytes.

Syntax
Std_ReturnType DsBusCustomCodePdu_getSduLength(DsBusCustomCodePduHandle PduHandle, uint32* SduLength)

Parent handle This function is provided by DsBusCustomCodePduHandle on page 60.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

89
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
SduLength The SDU length in bytes.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodePduFeature_getFeatureDataPtr

Purpose To get the FeatureDataPtr pointer of a PDU feature handle.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the FeatureDataPtr pointer of a PDU feature

handle. To get the pointer, it must be set beforehand by using
the DsBusCustomCodePduFeature_setFeatureDataPtr function. Refer to
DsBusCustomCodePduFeature_setFeatureDataPtr on page 93.

In the user code, you can let the pointer point to an arbitrary, user-defined data
structure, e.g., a struct. By using this function, you can access the data of this
data structure.

For example, you use the data structure to store data that alternates during
subsequent PDU feature execution calls, such as counter values or state

90
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

information. In this case, you can use this function to access the data that was
written to the data structure during the previous PDU feature execution call.

Syntax
Std_ReturnType DsBusCustomCodePduFeature_getFeatureDataPtr(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint8**
FeatureDataPtr)

Parent handle This function is provided by DsBusCustomCodePduFeatureHandle on page 61.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
FeatureDataPtr The FeatureDataPtr pointer of the PDU feature handle. The
data type of the pointer is uint8. However, in the user code you
can cast this data type to the data type of the data structure to
which the pointer points.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodePduFeature_getPdu

Purpose To get the PDU that is accessed by a PDU feature handle.

91
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the PDU that is accessed by a PDU feature handle. The
function gets the PDU via its PDU handle.

Syntax
Std_ReturnType DsBusCustomCodePduFeature_getPdu(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
DsBusCustomCodePduHandle* PduHandle)

Parent handle This function is provided by DsBusCustomCodePduFeatureHandle on page 61.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
PduHandle The PDU handle that addresses the PDU which is accessed by the
PDU feature handle.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

92
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Example -

DsBusCustomCodePduFeature_setFeatureDataPtr

Purpose To set the FeatureDataPtr pointer of a PDU feature handle.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets the FeatureDataPtr pointer of a PDU feature handle.

In the user code, you can let the pointer point to an arbitrary,
user-defined data structure, e.g., a struct. When you set the
FeatureDataPtr pointer by using this function during the initialization
phase of an executable application (i.e., real-time application or
offline simulation application), you can access the data of the data
structure by calling the DsBusCustomCodePduFeature_getFeatureDataPtr
function during PDU feature execution calls. Refer to
DsBusCustomCodePduFeature_getFeatureDataPtr on page 90.

For example, you can use a user-defined data structure to store data that
alternates during different feature execution calls such as counter values and
state information. By using the FeatureDataPtr pointer, you can provide this
alternating data to the user code.

Syntax
Std_ReturnType DsBusCustomCodePduFeature_setFeatureDataPtr(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint8*
FeatureDataPtr)

Parent handle This function is provided by DsBusCustomCodePduFeatureHandle on page 61.

93
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
FeatureDataPtr The FeatureDataPtr pointer of the PDU feature handle. The
data type of the pointer is uint8. However, in the user code you
can cast this data type to the data type of the data structure to
which the pointer points.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset

Purpose To get the offset value of the position of the authentication information in a
non-cryptographic secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

94
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Description This function gets the offset value of the position of the authentication
information (i.e., the freshness value and the authenticator) in a non-
cryptographic secured IPDU. The offset value indicates the deviation in
bits of the current position of the authentication information from
the position that is specified in the communication matrix. If the
offset value is 0, there is no deviation and the current position of
the authentication information is the position that is specified in the
communication matrix. You can specify a user-defined offset value by using the
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset
function. Refer to
DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset
on page 100.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, sint32* AuthenticatorPositionOffset)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
AuthenticatorPositionOffset The deviation in bits of the current position of the
authentication information in the secured IPDU from
the position that is specified in the communication
matrix.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

95
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Example -

DsBusCustomCodeSecOCPduFeature_getKeyAsString

Purpose To get the SecOC key of a secured IPDU as a string value.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function can get the SecOC key of a secured IPDU as a string value. To
get the SecOC key, it must be specified in the communication matrix. The
implementation of the SecOC key in the communication matrix is customer-
specific.

Via a user-defined C-function, you can parse the key value in a

byte array, for example. When you do this, you can use the
DsBusCustomCodeSecOCPduFeature_setKeyLength function to specify the
length of the byte array. If you set the KeyPtr pointer of the SecOC PDU
feature handle by using the DsBusCustomCodeSecOCPduFeature_setKeyPtr
function, you can access the data of the byte array by using the KeyPtr pointer.
Refer to DsBusCustomCodeSecOCPduFeature_setKeyLength on page 102
and DsBusCustomCodeSecOCPduFeature_setKeyPtr on page 103.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_getKeyAsString(DsBusCustomCodePduFeatureHandle PduFeatureHandle, char**
KeyAsString)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

96
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
KeyAsString The SecOC key that is specified in the communication matrix. The
key is provided as a string value.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCPduFeature_getKeyLength

Purpose To get the length of a SecOC key byte array of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

97
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Description This function gets the length of a SecOC key byte array of a
secured IPDU. To get the length, it must be set beforehand by using
the DsBusCustomCodeSecOCPduFeature_setKeyLength function. Refer to
DsBusCustomCodeSecOCPduFeature_setKeyLength on page 102.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_getKeyLength(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint32*
KeyLength)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
KeyLength The length of the SecOC key byte array in bytes.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCPduFeature_getKeyPtr

Purpose To get the KeyPtr pointer of a SecOC PDU feature handle.

98
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the KeyPtr pointer of a SecOC PDU feature
handle. To get the pointer, it must be set beforehand by using
the DsBusCustomCodeSecOCPduFeature_setKeyPtr function. Refer to
DsBusCustomCodeSecOCPduFeature_setKeyPtr on page 103.

For example, you can use the KeyPtr pointer to access the SecOC key of a
secured IPDU: In the user code, you can specify a byte array that contains the
SecOC key of a secured IPDU and let the pointer point to this array. By using this
function, you can access the data of this array during subsequent PDU feature
execution calls.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_getKeyPtr(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint8** KeyPtr)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
KeyPtr The KeyPtr pointer of the SecOC PDU feature handle. The data
type of the pointer is uint8. However, in the user code you can
cast this data type to the data type of the byte array to which the
pointer points.

99
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset

Purpose To set an offset value to the position of the authentication information in a

non-cryptographic secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software (only for internal use)

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets an offset value to the position of the authentication
information in a non-cryptographic secured IPDU, i.e., in a secured IPDU whose
UseAsCryptographicIPdu attribute is unspecified or set to False.

The offset value applies to the position of the authentication information

(i.e., to the freshness value and the authenticator) that is included in the non-
cryptographic secured IPDU. The offset value determines the deviation in bits
of the current position of the authentication information to the position that is
specified in the communication matrix. By default, the offset value is 0, i.e., there
is no deviation and the current position of the authentication information is the
position that is specified in the communication matrix. You can specify a positive
deviation to the originally specified position (i.e., offset value > 0) or a negative
deviation (i.e., offset value < 0).

For example, you can use this function to specify the position of the
authentication information if the secured IPDU has a dynamic payload length.
To get the payload length in the current PDU feature execution call (i.e., the

100
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

current sampling step), you can use the DsBusCustomCodePdu_getSduLength

function. Refer to DsBusCustomCodePdu_getSduLength on page 89.

The bus implementation software internally uses the specified offset value to
determine the start position of the authentication information in the secured
IPDU, e.g., for inspecting the truncated freshness and authenticator values of a
received secured IPDU.

The specified offset value applies only to the current PDU feature execution call:
The bus implementation software resets the offset value to 0 before the next
PDU feature execution call (i.e., before the next sampling step).

At run time, you can access the offset value by using the
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset
function. Refer to
DsBusCustomCodeSecOCPduFeature_getAuthenticatorPositionOffset
on page 94.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_setAuthenticatorPositionOffset(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, sint32 AuthenticatorPositionOffset)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
AuthenticatorPositionOffset The offset value in bits that applies to the position of
the authentication information that it is specified in
the communication matrix for a non-cryptographic
secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

101
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Example -

DsBusCustomCodeSecOCPduFeature_setKeyLength

Purpose To set the length of a SecOC key byte array of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets the length of a SecOC key byte array of a secured IPDU.

In the user code, you can use a byte array to store the SecOC key of the
secured IPDU. The SecOC key can directly be specified in the user code.
The SecOC key can also be specified in the communication matrix but this
requires a customer-specific implementation of the SecOC key. Depending on
the customer-specific implementation, you can get the SecOC key by using
the DsBusCustomCodeSecOCPduFeature_getKeyAsString function. Refer to
DsBusCustomCodeSecOCPduFeature_getKeyAsString on page 96.

At run time, you can access the length of the SecOC key byte array by using
the DsBusCustomCodeSecOCPduFeature_getKeyLength function. Refer to
DsBusCustomCodeSecOCPduFeature_getKeyLength on page 97.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_setKeyLength(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint32
KeyLength)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

102
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
KeyLength The length of the SecOC key byte array in bytes.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCPduFeature_setKeyPtr

Purpose To set the KeyPtr pointer of a SecOC PDU feature handle.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets the KeyPtr pointer of the SecOC PDU feature handle.

For example, you can use the KeyPtr pointer to access the SecOC key
of a secured IPDU: In the user code, you can specify a byte array that

103
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

contains the SecOC key of a secured IPDU and let the pointer point to this
array. When you set the KeyPtr pointer by using this function during the
initialization phase of an executable application (i.e., real-time application or
offline simulation application), you can access the data of the array by calling the
DsBusCustomCodeSecOCPduFeature_getKeyPtr function during PDU feature
execution calls. Refer to DsBusCustomCodeSecOCPduFeature_getKeyPtr on
page 98.

Syntax
Std_ReturnType DsBusCustomCodeSecOCPduFeature_setKeyPtr(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint8* KeyPtr)

Parent handle This function is provided by DsBusCustomCodeSecOCPduFeatureHandle on

page 62.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
KeyPtr The KeyPtr pointer of the SecOC PDU feature handle. The data
type of the pointer is uint8. However, in the user code you can
cast this data type to the data type of the byte array the pointer
points to.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

104
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue

Purpose To get the data of the user code that is provided to an RX secured IPDU via the
Calculated Freshness Value variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the data of the user code that is provided to an RX secured
IPDU via the Calculated Freshness Value variable.

To get the data of the Calculated Freshness Value

variable, it must be set beforehand by using the
DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue
function. Refer to
DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue on
page 109.

Syntax
Std_ReturnType DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint64* CalculatedFreshnessValue)

Parent handle This function is provided by DsBusCustomCodeSecOCRxPduFeatureHandle on

page 64.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

105
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
CalculatedFreshnessValue The data that is provided to the Calculated
Freshness Value variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCRxPduFeature_getEnableVerification

Purpose To get the enable state for verifying the authentication information of an RX
secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the enable state for verifying the authentication information of
an RX secured IPDU.

In the user code, you can use the provided state value to enable or disable
the verification of the authentication information of the RX secured IPDU. The
specifications in the user code determine how the state value is evaluated.

106
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

To ensure full compatibility with all bus implementation software tools, it is

recommended to use the following values:

Value Use For

0x00 Disable verification.
0x01 Enable verification.

Syntax
Std_ReturnType DsBusCustomCodeSecOCRxPduFeature_getEnableVerification(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
uint32* EnableVerification)

Parent handle This function is provided by DsBusCustomCodeSecOCRxPduFeatureHandle on

page 64.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
EnableVerification The enable state of the authentication information verification
that is provided by bus implementation software.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

107
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeSecOCRxPduFeature_getVerificationResult

Purpose To get data of the user code that is provided to an RX secured IPDU via the
Verification Result variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the data of the user code that is provided to an RX secured
IPDU via the Verification Result variable.

To get the data of the Verification Result

variable, it must be set beforehand by using the
DsBusCustomCodeSecOCRxPduFeature_setVerificationResult function.
Refer to DsBusCustomCodeSecOCRxPduFeature_setVerificationResult
on page 111.

Syntax
Std_ReturnType DsBusCustomCodeSecOCRxPduFeature_getVerificationResult(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
uint32* VerificationResult)

Parent handle This function is provided by DsBusCustomCodeSecOCRxPduFeatureHandle on

page 64.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

108
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
VerificationResult The data that is provided to the Verification Result
variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue

Purpose To set data of the user code to an RX secured IPDU via the Calculated
Freshness Value variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software, provides data via TRC and/or
model variable

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets data of the user code to an RX secured IPDU via the
Calculated Freshness Value variable.

The specifications in the user code determine which data is set to the
Calculated Freshness Value variable. For example, you can use this
function to set the freshness value that was calculated for the RX secured IPDU in
the user code by using user-specific algorithms.

109
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

At run time, you can also access the data of

the Calculated Freshness Value variable by using the
DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue
function. Refer to
DsBusCustomCodeSecOCRxPduFeature_getCalculatedFreshnessValue on
page 105.

Syntax
Std_ReturnType DsBusCustomCodeSecOCRxPduFeature_setCalculatedFreshnessValue(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint64 CalculatedFreshnessValue)

Parent handle This function is provided by DsBusCustomCodeSecOCRxPduFeatureHandle on

page 64.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
CalculatedFreshnessValues The data that is provided to the Calculated
Freshness Value variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

110
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecOCRxPduFeature_setVerificationResult

Purpose To set data of the user code to an RX secured IPDU via the Verification
Result variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software, provides data via TRC and/or
model variable

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets data of the user code to an RX secured IPDU via the
Verification Result variable.

The specifications in the user code determine which data is set to the
Verification Result variable. For example, you can use this function to set
the verification result that was calculated for the RX secured IPDU in the user
code by using user-specific algorithms.

If you do this, the specifications in the user code determine which verification
results can be available and by which value they are represented. To ensure full
compatibility with all bus implementation software tools, it is recommended to
use the following mapping of verification results and values:

Value Use For

0x00 SECOC_VERIFICATIONSUCCESS: Verification was successful.
0x01 SECOC_VERIFICATIONFAILURE: Verification failed, e.g., because the related
verification function of the user code indicates an error.
0x02 SECOC_FRESHNESSFAILURE: Verification failed because of an unexpected
freshness value.
0x3E SECOC_MESSAGELINKERFAILURE: Verification failed because of an unexpected
message linker value.
0x3F SECOC_VERIFICATIONNOTEXECUTED: Verification is not executed because it is
disabled.

At run time, you can also access the data

of the Verification Result variable by using the
DsBusCustomCodeSecOCRxPduFeature_getVerificationResult function.
Refer to DsBusCustomCodeSecOCRxPduFeature_getVerificationResult
on page 108.

111
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Syntax
Std_ReturnType DsBusCustomCodeSecOCRxPduFeature_setVerificationResult(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
uint32 VerificationResult)

Parent handle This function is provided by DsBusCustomCodeSecOCRxPduFeatureHandle on

page 64.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
VerificationResult The data that is provided to the Verification Result
variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType

Purpose To get the enable state of the authentication type manipulation that is specified
for a TX secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.

112
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the enable state of the authentication type manipulation that
is specified for a TX secured IPDU.

In the user code, you can use the provided state value to enable or disable
the manipulation of the authentication type of the TX secured IPDU. The
specifications in the user code determine how the state value is evaluated.
To ensure full compatibility with all bus implementation software tools, it is
recommended to use the following values:

Value Use For

0x00 Disable the manipulation of the authentication type, i.e, use the correct
algorithms to calculate the authenticator in the user code.
0x01 Enable the manipulation of the authentication type, i.e., invalidate the calculation
of the authenticator in the user code.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getAuthenticationType(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
uint32* AuthenticationType)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
AuthenticationType The enable state of the authentication type manipulation that is
provided by bus implementation software.

113
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue

Purpose To get the data of the user code that is provided to a TX secured IPDU via the
Calculated Freshness Value variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the data of the user code that is provided to a TX secured
IPDU via the Calculated Freshness Value variable.

To get the data of the Calculated Freshness Value

variable, it must be set beforehand by using the
DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue
function. Refer to
DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue on
page 123.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint64* CalculatedFreshnessValue)

114
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
CalculatedFreshnessValue The data that is provided to the Calculated
Freshness Value variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication

Purpose To get the enable state of the authentication value calculation that is specified
for a TX secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

115
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the enable state of the authentication value calculation that is
specified for a TX secured IPDU.

In the user code, you can use the provided state value to enable or disable the
calculation of the authentication value of the TX secured IPDU. The specifications
in the user code determine how the state value is evaluated. To ensure full
compatibility with all bus implementation software tools, it is recommended to
use the following values:

Value Use For

0x00 Disable the calculation of the authentication value, i.e, the authentication value
is not calculated in the user code. Instead, a user‑defined authentication value
can be used. You can access the user‑defined authentication value by using the
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr
function. Refer to
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr
on page 120.
0x01 Enable the calculation of the authentication value, i.e, the authentication value is
calculated in the user code.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint32* EnableAuthentication)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
EnableAuthentication The enable state of the authentication value calculation that
is provided by bus implementation software.

116
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalculation

Purpose To get the enable state of the freshness value calculation that is specified for a TX
secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the enable state of the freshness value calculation that is
specified for a TX secured IPDU.

In the user code, you can use the provided state value to enable or disable the
calculation of the freshness value of the TX secured IPDU. The specifications
in the user code determine how the state value is evaluated. To ensure full
compatibility with all bus implementation software tools, it is recommended to
use the following values:

Value Use For

0x00 Disable the calculation of the freshness value, i.e, the freshness value is
not calculated in the user code. Instead, a user-defined freshness value can
be used. You can access the user-defined freshness value by using the
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue
function. Refer to
DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue
on page 121.

117
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Value Use For

0x01 Enable the calculation of the freshness value, i.e, the freshness value is calculated
in the user code.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalculation(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint32* EnableFreshnessValueCalculation)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
EnableFreshnessValueCalculation The enable state of the freshness value
calculation that is provided by bus
implementation software.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

118
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset

Purpose To get the offset value that is specified for the freshness value of a TX secured
IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the offset value that is specified for the freshness value of a TX
secured IPDU.

The specified value applies to the freshness value of the TX secured IPDU,
regardless of whether the freshness value is calculated in the user code or a
user-defined freshness value is used. The specified offset can be a positive or
negative value, or 0.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getFreshnessValueOffset(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, sint64* FreshnessValueOffset)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

119
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
FreshnessValueOffset The offset value that applies to the freshness value and which
is provided by bus implementation software.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr

Purpose To get the pointer to the byte array that provides the user-defined authentication
value, which is specified for a TX secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the pointer to the byte array that provides the user-defined
authentication value, which is specified for a TX secured IPDU.

The user-defined authentication value applies to the TX secured IPDU

only if calculating the authentication value in the user code is disabled
via the DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication
function. Refer to

120
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecOCTxPduFeature_getEnableAuthentication on
page 115.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getUserDefinedAuthenticatorPtr(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint8** UserDefinedAuthenticatorPtr)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
UserDefinedAuthenticatorPtr The pointer to the byte array that provides the user-
defined authentication value.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue

Purpose To get the user-defined freshness value that is specified for a TX secured IPDU.

121
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value provided by
bus implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the user-defined freshness value that is specified for a TX
secured IPDU.

The user-defined freshness value applies to the TX secured IPDU only if

calculating the freshness value in the user code is disabled via the
DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalcula
tion function. Refer to
DsBusCustomCodeSecOCTxPduFeature_getEnableFreshnessValueCalcula
tion on page 117.

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_getUserDefinedFreshnessValue(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint64* UserDefinedFreshnessValue)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
UserDefinedFreshnessValue The user-defined freshness value that is provided by
bus implementation software.

122
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue

Purpose To set data of the user code to a TX secured IPDU via the Calculated
Freshness Value variable.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software, provides data via TRC and/or
model variable

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets data of the user code to a TX secured IPDU via the
Calculated Freshness Value variable.

The specifications in the user code determine which data is set to the
Calculated Freshness Value variable. For example, you can use this
function to set the freshness value that was calculated for the TX secured IPDU in
the user code by using user-specific algorithms.

At run time, you can also access the data of

the Calculated Freshness Value variable by using the
DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue
function. Refer to
DsBusCustomCodeSecOCTxPduFeature_getCalculatedFreshnessValue on
page 114.

123
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Syntax
Std_ReturnType DsBusCustomCodeSecOCTxPduFeature_setCalculatedFreshnessValue(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint64 CalculatedFreshnessValue)

Parent handle This function is provided by DsBusCustomCodeSecOCTxPduFeatureHandle on

page 66.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
CalculatedFreshnessValues The data that is provided to the Calculated
Freshness Value variable by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName

Purpose To get the value of the AUTOSAR AuthAlgorithm attribute of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.

124
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data source Communication matrix (via bus implementation software)

Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR AuthAlgorithm attribute of a
secured IPDU.

According to AUTOSAR, the value of the AuthAlgorithm attribute specifies the

name of the authentication algorithm of a secured IPDU.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthAlgorithmName(DsBusCustomCodePduHandle PduHandle, char**
AuthAlgorithmNameAsString)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthAlgorithmNameAsString The name of the authentication algorithm.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

125
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength

Purpose To get the value of the AUTOSAR AuthDataFreshnessLength attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR AuthDataFreshnessLength

attribute of a secured IPDU.

According to AUTOSAR, a part of the payload of an authentic IPDU can be

included in the freshness value. The value of the AuthDataFreshnessLength
attribute determines the length in bits of the authentic IPDU's payload that is
used for this purpose.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessLength(DsBusCustomCodePduHandle PduHandle, uint16*
AuthDataFreshnessLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthDataFreshnessLength The length in bits of the authentic IPDU's payload that is
included in the freshness value.

126
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPosition

Purpose To get the value of the AUTOSAR AuthDataFreshnessStartPosition

attribute of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR

AuthDataFreshnessStartPosition attribute of a secured IPDU.

According to AUTOSAR, a part of the payload of an authentic

IPDU can be included in the freshness value. The value of the
AuthDataFreshnessStartPosition attribute determines the position of the
first bit in the authentic IPDU's payload that is used for this purpose. To
determine the bit position, the counting starts from the most significant bit
(MSB) of the first byte of the payload.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthDataFreshnessStartPosition(DsBusCustomCodePduHandle PduHandle, uint16*
AuthDataFreshnessStartPosition)

127
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthDataFreshnessStartPosition The position of the first bit in the authentic
IPDU's payload that is included in the freshness
value.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength

Purpose To get the value of the AUTOSAR AuthInfoTxLength attribute of a secured

IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

128
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR AuthInfoTxLength attribute of a
secured IPDU.

According to AUTOSAR, the value of the AuthInfoTxLength attribute

determines the length in bits of the calculated authenticator that is included
in the payload of a secured IPDU.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength(DsBusCustomCodePduHandle PduHandle, uint32*
AuthInfoTxLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthInfoTxLength The length in bits of the calculated authenticator that is included
in the payload of the secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

129
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Example
1 // Copy authInfoTxLength number of bits of authenticator to secured IPDU
2 uint32 authInfoTxLength;
3 DsBusCustomCodeSecuredIPdu_getAuthInfoTxLength(securedIPdu_PduHandle, &authInfoTxLength);

DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength

Purpose To get the value of the AUTOSAR SecOCAuthPduHeaderLength attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR SecOCAuthPduHeaderLength

attribute of a secured IPDU.

According to AUTOSAR, the value of the SecOCAuthPduHeaderLength

attribute indicates the length of the secured PDU header that is used in a secured
IPDU. The length is provided in bytes, e.g., 0 indicates that no secured PDU
header is used and 4 indicates a 32-bit secured PDU header.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthPduHeaderLength(DsBusCustomCodePduHandle PduHandle, uint8*
AuthPduHeaderLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

130
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthPduHeaderLength The length in bytes of the secured PDU header that is used in
the secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getAuthenticPdu

Purpose To get the authentic IPDU that is secured by a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the authentic IPDU that is secured by a secured IPDU. The
function gets the authentic IPDU via its handle.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthenticPdu(DsBusCustomCodePduHandle PduHandle, DsBusCustomCodePduHandle*
AuthenticPduHandle)

131
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthenticPduHandle The handle of the authentic IPDU that is secured by the secured
IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // The PduFeatureHandle is typically provided as a parameter of an interface
2 // call, e.g. DsBusCustomCode_onApplicationInit
3 DsBusCustomCodePduHandle securedIPdu_PduHandle, authenticIPdu_PduHandle;
4 DsBusCustomCodePduFeature_getPdu(PduFeatureHandle, &securedIPdu_PduHandle);
5 DsBusCustomCodeSecuredIPdu_getAuthenticPdu(securedIPdu_PduHandle, &authenticIPdu_PduHandle);
6

DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts

Purpose To get the value of the AUTOSAR AuthenticationBuildAttempts attribute of

a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the

132
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR AuthenticationBuildAttempts

attribute of a secured IPDU.

According to AUTOSAR, the value of the AuthenticationBuildAttempts

attribute determines how often the sender of a secured IPDU tries to generate
the authentication information.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthenticationBuildAttempts(DsBusCustomCodePduHandle PduHandle, uint16*
AuthenticationBuildAttempts)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthenticationBuildAttempts The number of the authentication build attempts.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

133
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Example -

DsBusCustomCodeSecuredIPdu_getAuthenticationRetries

Purpose To get the value of the AUTOSAR AuthenticationRetries attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR AuthenticationRetries

attribute of a secured IPDU.

According to AUTOSAR, the value of the AuthenticationRetries attribute

determines how often the receiver of a secured IPDU tries to verify the received
authentication information if the first attempt failed. A value of 0 indicates that
there will be no additional authentication attempts, i.e., the receiver tries to
verify received authentication information only once.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getAuthenticationRetries(DsBusCustomCodePduHandle PduHandle, uint16*
AuthenticationRetries)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

134
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthenticationRetries The number of the additional authentication attempts.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getDataId

Purpose To get the value of the AUTOSAR DataId attribute of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR DataId attribute of a secured
IPDU.

According to AUTOSAR, the data ID is a unique numerical identifier for the

secured IPDU. Typically, the data ID is included in the calculation of the
authenticator.

135
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getDataId(DsBusCustomCodePduHandle PduHandle, uint16* DataId)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
DataId The data ID of the secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 DsBusCustomCodePduHandle securedIPdu_PduHandle;
2 DsBusCustomCodePduFeature_getPdu(PduFeatureHandle, &securedIPdu_PduHandle);
3 DsBusCustomCodeSecuredIPdu_getDataId(securedIPdu_PduHandle, &dataId);
4 // ... prepare authentication data including data ID and generate MAC
5

DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttempts

Purpose To get the value of the AUTOSAR FreshnessCounterSyncAttempts attribute

of a secured IPDU.

136
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR

FreshnessCounterSyncAttempts attribute of a secured IPDU.

According to AUTOSAR, the FreshnessCounterSyncAttempts attribute

applies only if the freshness value is calculated according to a freshness counter,
i.e., the UseFreshnessTimestamp attribute of the secured IPDU is set to FALSE.

According to AUTOSAR, the value of the FreshnessCounterSyncAttempts

attribute determines how often the receiver of a secured IPDU tries to
synchronize the freshness counter if the first verification of the authentication
information failed. A value of 0 indicates that there will be no additional
synchronization attempts, i.e., the receiver tries to synchronize the freshness
counter only once.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getFreshnessCounterSyncAttempts(DsBusCustomCodePduHandle PduHandle, uint32*
FreshnessCounterSyncAttempts)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
FreshnessCounterSyncAttempts The number of the additional synchronization
attempts for the freshness counter.

137
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFactor

Purpose To get the value of the AUTOSAR FreshnessTimestampTimePeriodFactor

attribute of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR

FreshnessTimestampTimePeriodFactor attribute of a secured IPDU.

According to AUTOSAR, the FreshnessTimestampTimePeriodFactor

attribute applies only if the freshness value is calculated according to a freshness
time stamp, i.e., the UseFreshnessTimestamp attribute of the secured IPDU is
set to TRUE.

According to AUTOSAR, the value of the

FreshnessTimestampTimePeriodFactor attribute is the factor of the time
period for the freshness time stamp. The specified factor determines the duration
in microseconds for one increment of the freshness time stamp.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getFreshnessTimestampPeriodFactor(DsBusCustomCodePduHandle PduHandle, uint32*
FreshnessTimestampPeriodFactor)

138
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
FreshnessTimestampPeriodFactor The factor in microseconds of the time period
for the freshness time stamp.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getFreshnessValueId

Purpose To get the value of the AUTOSAR FreshnessValueId attribute of a secured

IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

139
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR FreshnessValueId attribute of a
secured IPDU.

According to AUTOSAR, the FreshnessValueId attribute specifies the identifier

for the freshness value of the secured IPDU.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getFreshnessValueId(DsBusCustomCodePduHandle PduHandle, uint16*
FreshnessValueId)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
FreshnessValueId The freshness value ID of the secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

140
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecuredIPdu_getFreshnessValueLength

Purpose To get the value of the AUTOSAR FreshnessValueLength attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR FreshnessValueLength attribute
of a secured IPDU.

According to AUTOSAR, the value of the FreshnessValueLength attribute

determines the length in bits that is used for the complete freshness value.
Typically, the specified value is larger than the number of bits that are
transmitted.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getFreshnessValueLength(DsBusCustomCodePduHandle PduHandle, uint32*
FreshnessValueLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
FreshnessValueLength The length of the complete freshness value in bits.

141
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength

Purpose To get the value of the AUTOSAR FreshnessValueTxLength attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR FreshnessValueTxLength

attribute of a secured IPDU.

According to AUTOSAR, the value of the FreshnessValueTxLength attribute

determines the length in bits of the freshness value that is included in the
payload of a secured IPDU.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getFreshnessValueTxLength(DsBusCustomCodePduHandle PduHandle, uint32*
FreshnessValueTxLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

142
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
FreshnessValueTxLength The length in bits of the freshness value that is included in
the payload of the secured IPDU.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getKeyId

Purpose To get the value of the AUTOSAR KeyID attribute of a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR KeyID attribute of a secured IPDU.

143
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

According to AUTOSAR, the KeyID attribute identifies the key that is used to
generate and verify the message authentication code (MAC). The specified key ID
value must be unique per ECU.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getKeyId(DsBusCustomCodePduHandle PduHandle, uint32* KeyId)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
KeyId The key ID.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getMessageLinkLength

Purpose To get the value of the AUTOSAR MessageLinkLength attribute of a secured

IPDU.

144
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR MessageLinkLength attribute of a
secured IPDU.

If a secured IPDU is configured as cryptographic IPDU, a part of the payload of

the related authentic IPDU can be included in the cryptographic IPDU. This part is
called the message linker.

According to AUTOSAR, the value of the MessageLinkLength attribute

determines the length in bits of the message linker.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getMessageLinkLength(DsBusCustomCodePduHandle PduHandle, uint16*
MessageLinkLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
MessageLinkLength The length of the message linker in bits.

145
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getMessageLinkPosition

Purpose To get the value of the AUTOSAR MessageLinkPosition attribute of a secured

IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR MessageLinkPosition attribute
of a secured IPDU.

If a secured IPDU is configured as cryptographic IPDU, a part of the payload of

the related authentic IPDU can be included in the cryptographic IPDU. This part is
called the message linker.

According to AUTOSAR, the value of the MessageLinkPosition attribute

determines the position of the first bit in the authentic IPDU's payload that is
used as the message linker.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getMessageLinkPosition(DsBusCustomCodePduHandle PduHandle, uint16*
MessageLinkPos)

146
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended usage During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
MessageLinkPos The position of the first bit in the authentic IPDU's payload that is
used as the message linker.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getRxSecurityVerification

Purpose To get the value of the AUTOSAR RxSecurityVerification attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

147
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR RxSecurityVerification

attribute of a secured IPDU.

According to AUTOSAR, the value of the RxSecurityVerification attribute

determines whether the authentication information of a received secured IPDU
is verified. If the attribute is not specified or set to TRUE, the authentication
information is verified. If set to FALSE, the secured IPDU will be processed by the
receiving ECU without verifying its authentication information.

Note

This function gets the enable state for verifying authentication

information as specified in the communication matrix. To
specify whether the bus implementation software verifies
received authentication information, it is recommended to use
the DsBusCustomCodeSecOCRxPduFeature_getEnableVerification
function instead. Refer to
DsBusCustomCodeSecOCRxPduFeature_getEnableVerification on
page 106.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getRxSecurityVerification(DsBusCustomCodePduHandle PduHandle, boolean*
RxSecurityVerification)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

148
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
RxSecurityVerification The value determining whether the authentication
information of a secured IPDU is verified on the receiver
side:
§ TRUE: The authentication information is verified.
§ FALSE: The authentication information is not verified.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getSecuredAreaLength

Purpose To get the value of the AUTOSAR SecuredAreaLength attribute of a secured

IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR SecuredAreaLength attribute of a
secured IPDU.

149
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

According to AUTOSAR, the value of the SecuredAreaLength attribute

determines the length in bytes of the authentic IPDU's payload that is secured.
For these bytes, authentication information is generated.

If this attribute is specified, the SecuredAreaOffset attribute must also be

specified. If both attributes are not specified, the complete payload of the
authentic IPDU is secured.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getSecuredAreaLength(DsBusCustomCodePduHandle PduHandle, uint32*
SecuredAreaLength)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
SecuredAreaLength The length in bytes of the authentic IPDU's payload that is
secured.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

150
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset

Purpose To get the value of the AUTOSAR SecuredAreaOffset attribute of a secured

IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR SecuredAreaOffset attribute of a
secured IPDU.

According to AUTOSAR, the SecuredAreaOffset attribute determines the

position of the first byte in the authentic IPDU's payload that is secured. Starting
from this byte, authentication information is generated for the number of bytes
that are specified by the SecuredAreaLength attribute.

If this attribute is specified, the SecuredAreaLength attribute must also be

specified. If both attributes are not specified, the complete payload of the
authentic IPDU is secured.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getSecuredAreaOffset(DsBusCustomCodePduHandle PduHandle, uint32*
SecuredAreaOffset)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

151
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
AuthPduHeaderLength The position of the first byte in the authentic IPDU's payload
that is secured.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWindow

Purpose To get the value of the AUTOSAR TimestampRxAcceptanceWindow attribute of

a secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR TimestampRxAcceptanceWindow

attribute of a secured IPDU.

According to AUTOSAR, the value of the TimestampRxAcceptanceWindow

attribute determines the maximum allowed deviation of a received freshness
time stamp from the expected freshness time stamp of a received secured IPDU.

In contrast to AUTOSAR, this function gets the value of the

TimestampRxAcceptanceWindow attribute in milliseconds.

152
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getTimeStampRxAcceptanceWindow(DsBusCustomCodePduHandle PduHandle, uint64*
TimeStampRxAcceptanceWindow)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
TimeStampRxAcceptanceWindow The maximum allowed deviation in milliseconds of
a received freshness time stamp from the expected
freshness time stamp.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu

Purpose To get the value of the AUTOSAR UseAsCryptographicIPdu attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the

153
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR UseAsCryptographicIPdu

attribute of a secured IPDU.

According to AUTOSAR, the value of the UseAsCryptographicIPdu attribute

determines whether a secured IPDU is used as cryptographic IPDU. If the
attribute is set to TRUE, the secured IPDU is used as cryptographic IPDU. In
this case, the secured IPDU contains only the authentication information and the
related authentic IPDU is transmitted separately on the bus. If the attribute is set
to FALSE or not specified, the payload of the authentic IPDU is directly included
in the secured IPDU. In this case, only one PDU is exchanged on the bus.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getUseAsCryptographicPdu(DsBusCustomCodePduHandle PduHandle, boolean*
UseAsCryptographicIPdu)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
UseAsCryptographicIPdu The value determining whether the secured IPDU is used as
cryptographic IPDU:
§ TRUE: The secured IPDU is used as cryptographic IPDU.
§ FALSE: The secured IPDU is not used as cryptographic
IPDU.

154
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness

Purpose To get the value of the AUTOSAR UseAuthDataFreshness attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR UseAuthDataFreshness attribute
of a secured IPDU.

According to AUTOSAR, the value of the UseAuthDataFreshness attribute

determines whether a part of the payload of an authentic IPDU is included
in the freshness value. If the attribute is set to TRUE, a part of the
payload of an authentic IPDU is included in the freshness value. In this case,
the AuthDataFreshnessStartPosition and AuthDataFreshnessLength
attributes are required to specify the related payload part.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getUseAuthDataFreshness(DsBusCustomCodePduHandle PduHandle, boolean*
UseAuthDataFreshness)

155
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
UseAuthDataFreshness The value determining whether a part of the payload of an
authentic IPDU is included in the freshness value:
§ TRUE: A part of the payload of an authentic IPDU is
included in the freshness value.
§ FALSE: No part of the payload of an authentic IPDU is
included in the freshness value.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp

Purpose To get the value of the AUTOSAR UseFreshnessTimestamp attribute of a

secured IPDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.

156
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameter data source Communication matrix (via bus implementation software)

Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the value of the AUTOSAR UseFreshnessTimestamp

attribute of a secured IPDU.

According to AUTOSAR, the value of the UseFreshnessTimestamp attribute

determines whether a freshness time stamp or a freshness counter is used to
generate the freshness value. If the attribute is set to TRUE, a freshness time
stamp is used.

Syntax
Std_ReturnType DsBusCustomCodeSecuredIPdu_getUseFreshnessTimestamp(DsBusCustomCodePduHandle PduHandle, boolean*
UseFreshnessTimestamp)

Parent handle This function is provided by DsBusCustomCodeSecuredIPduHandle on

page 68.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduHandle A DsBusCustomCode PDU handle.
UseFreshnessTimestamp The value determining whether a freshness time stamp or a
freshness counter is used to generate the freshness value:
§ TRUE: A freshness time stamp is used.
§ FALSE: A freshness counter is used.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

157
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Example -

DsBusCustomCodeSignal_getEndianness

Purpose To get the endianness of a signal.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the endianness of a signal in bits.

Syntax
Std_ReturnType DsBusCustomCodeSignal_getEndianness(DsBusCustomCodeSignalHandle Handle, DsBusCustomCode_ByteOrderType*
Data)

Parent handle This function is provided by DsBusCustomCodeSignalHandle on page 70.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

158
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Parameters This function has the following parameters:

Parameter Description
Handle A DsBusCustomCode handle.
Data The endianness of the signal. It can be one of the following enumeration
values:
§ BigEndian: The most significant byte of the signal is stored first and the
most significant bit is the start bit.
§ LittleEndian: The least significant byte of the signal is stored first and
the least significant bit is the start bit.
§ Opaque: The byte order is similar to the little endian format.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSignal_getLength

Purpose To get the length of a signal.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the length of a signal in bits.

159
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Syntax
Std_ReturnType DsBusCustomCodeSignal_getLength(DsBusCustomCodeSignalHandle Handle, uint32* Data)

Parent handle This function is provided by DsBusCustomCodeSignalHandle on page 70.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
Handle A DsBusCustomCode handle.
Data The signal length in bits.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeSignal_getStartBitPosition

Purpose To get the start bit position of a signal.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Communication matrix (via bus implementation software)
Parameter data recipient User code

160
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the start bit position of a signal in bits. The start bit position
determines the first bit in the payload of a PDU that is used by the signal.

Syntax
Std_ReturnType DsBusCustomCodeSignal_getStartBitPosition(DsBusCustomCodeSignalHandle Handle, uint32* Data)

Parent handle This function is provided by DsBusCustomCodeSignalHandle on page 70.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
Handle A DsBusCustomCode handle.
Data The start bit position of the signal in bits.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

161
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts

Purpose To get the number of user ports that are specified for a PDU via the PDU User
Code feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value set by bus
implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the number of user ports that are specified for a PDU via
the PDU User Code feature. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
uint32* Data)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The number of the user ports.

162
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare a uint32 variable for the number of user ports
2 uint32 UserPortCount;
3
4 // Get the number of user ports and provide it to the UserPortCount variable
5 DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts(PduFeatureHandle, &UserPortCount);

DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals

Purpose To get the number of user signals that are specified for a PDU via the PDU User
Code feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value set by bus
implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the number of user signals that are specified for a PDU via
the PDU User Code feature. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, uint32* Data)

163
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The number of user signals.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeUserCodePduFeature_getResult

Purpose To get the data of the user code that is provided to an RX PDU via the PDU User
Code feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient User code

164
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the data of the user code that is provided to an RX PDU
via the PDU User Code feature. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

To get the data, it must be set beforehand by using the

DsBusCustomCodeUserCodePduFeature_setResult function. Refer to
DsBusCustomCodeUserCodePduFeature_setResult on page 171.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getResult(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint32*
Data)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The data that is provided by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

165
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering

Purpose To get the run‑time frame triggering of a CAN frame or the run‑time CAN
identifier of a simulated RX J1939‑compliant IPDU via the PDU User Code
feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source Run‑time data received on the bus (provided by bus
implementation software)
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description Depending on whether this function accesses a CAN frame or a J1939‑compliant

IPDU, it gets the following run‑time information:
§ CAN frame: This function gets the frame triggering that is available on the
bus, i.e., the following data:
§ CAN frame identifier
§ Identifier format, i.e., standard identifier format (11-bit) or extended
identifier format (29-bit)
§ CAN frame type, i.e., classic CAN frame or CAN FD frame
§ Bit rate switch, i.e., whether switching the bit rate for the data phase of the
frame is enabled. The bit rate switch applies only if the frame is a CAN FD
frame.
§ J1939‑compliant IPDU: This function gets the CAN identifier that is available
on the bus, i.e., the priority, parameter group number, and source address.

Note

This function can get the CAN identifier only of RX J1939‑compliant

IPDUs that are simulated by the Bus Manager, i.e., of RX J1939‑compliant
IPDUs that are assigned to the Simulated ECUs part of a bus
configuration.

In most cases, the data that is available on the bus and that is accessed by this
function is the same data as specified in the communication matrix. However, in
some cases, the data might differ. For example:
§ The communication matrix specifies an RX mask for the frame triggering of
a CAN frame. In this case, the CAN frame identifier that is available on the
bus for the accessed PDU might differ from the CAN frame identifier that is
specified in the communication matrix.

166
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

§ The CAN identifier of a J1939‑compliant IPDU changes at run time, e.g.,

because the related network node has claimed a new transport protocol
address.

Note

The requirements for implementing this function in the user code differ
depending on the specific use scenario. Refer to Implementing the
DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
Function in the User Code on page 26.

Tip

To get the frame triggering of a CAN frame or the CAN identifier of a

J1939‑compliant IPDU that is specified in the communication matrix, you
can use the DsBusCustomCodePdu_getCanFrameTriggering function
instead. Refer to DsBusCustomCodePdu_getCanFrameTriggering on
page 82.

The data of this function is provided as a struct.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering(DsBusCustomCodePduFeatureHandle
PduFeatureHandle, DsBusCustomCodeRuntimeCanFrameTriggeringType* DsBusCustomCodeRuntimeCanFrameTriggering)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
DsBusCustomCodeRuntimeCanFrameTriggering A struct of four elements providing the following information:
§ (.Identifier): Providing the CAN frame identifier or the CAN identifier
of J1939‑compliant IPDUs.
§ (.AddressingMode): Providing the identifier format:
§ Standard = standard identifier format (11-bit)
§ Extended = extended identifier format (29-bit)

167
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameter Description
§ (.FrameBehavior): Providing the CAN frame type:
§ Can20 = classic CAN frame
§ CanFd = CAN FD frame
§ (.BitRateSwitch): Providing the bit rate switch:
§ NotSet: The bit rate switch is not specified.
§ Disabled: The bit rate switch is disabled, i.e., the data phase of the
CAN FD frame is transmitted with the same bit rate as the arbitration
phase of the frame.
§ Enabled: The bit rate switch is enabled, i.e., the data phase of the
CAN FD frame can be transmitted with a higher bit rate than the
arbitration phase of the frame.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example For examples, refer to Implementing the

DsBusCustomCodeUserCodePduFeature_getRuntimeCanFrameTriggering
Function in the User Code on page 26.

DsBusCustomCodeUserCodePduFeature_getUserPorts

Purpose To get the array of the user ports that are specified for a PDU via the PDU User
Code feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value set by bus
implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

168
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Description This function gets the array of the user ports that are specified for a PDU via
the PDU User Code feature. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

The array size is determined by the number of user ports that are specified
for the PDU User Code feature. You can get the array size by using the
DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts function.
Refer to DsBusCustomCodeUserCodePduFeature_getNumberOfUserPorts
on page 162.

The array provides access to the configured user ports, i.e., to the
direction and the data of the user ports. You can access the direction
and the data by using the DsBusCustomCodeUserPort_getDirection,
DsBusCustomCodeUserPort_setPortData, and
DsBusCustomCodeUserPort_getPortData functions. Refer to
DsBusCustomCodeUserPort_getDirection on page 173,
DsBusCustomCodeUserPort_setPortData on page 176, and
DsBusCustomCodeUserPort_getPortData on page 174, respectively.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getUserPorts(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
DsBusCustomCodeUserPortHandle** Data)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The pointer to get the array. To get the array, the pointer points to
the user port handle of the first user port of the array.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.

169
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Value Description
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare a pointer for the UserPorts array of handles
2 DsBusCustomCodeUserPortHandle* UserPorts;
3
4 // Let the pointer point to the array of handles
5 DsBusCustomCodeUserCodePduFeature_getUserPorts(PduFeatureHandle, &UserPorts);

DsBusCustomCodeUserCodePduFeature_getUserSignals

Purpose To get the array of the user signals that are specified for a PDU via the PDU User
Code feature.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value set by bus
implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the array of the user signals that are specified for a PDU via
the PDU User Code feature. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

The array size is determined by the number of user signals that are specified
via the PDU User Code feature. You can get the array size by using
the DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals
function. Refer to
DsBusCustomCodeUserCodePduFeature_getNumberOfUserSignals on
page 163.

The array provides access to the configured user signals, i.e., to the ISignals that
are mapped to user signals via the PDU User Code feature. If a user signal is not
mapped to an ISignal, the array entries of this user signal are NULL.

170
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

You can use this function to provide the data of the user signals to the user
code. In the user code, you can use the data to verify received checksum values
or calculate counter values, for example.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_getUserSignals(DsBusCustomCodePduFeatureHandle PduFeatureHandle,
DsBusCustomCodeSignalHandle** Data)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The pointer to get the array. To get the array, the pointer points to
the signal handle of the first user signal of the array.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeUserCodePduFeature_setResult

Purpose To set data of the user code to an RX PDU via the PDU User Code feature.

171
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software, provides data via TRC and/or
model variable

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets data of the user code to an RX PDU via the PDU User Code
feature. The PDU User Code feature is a feature of bus implementation software
tools. For more information on the feature, refer to the documentation of the
related bus implementation software tool.

The specifications in the user code determine which data is set to the RX
PDU. For example, you can use this function to set the verification result of a
checksum value that was received with the PDU and evaluated in the user code.

At run time, you can also access the data by using the
DsBusCustomCodeUserCodePduFeature_getResult function. Refer to
DsBusCustomCodeUserCodePduFeature_getResult on page 164.

Syntax
Std_ReturnType DsBusCustomCodeUserCodePduFeature_setResult(DsBusCustomCodePduFeatureHandle PduFeatureHandle, uint32 Data)

Parent handle This function is provided by DsBusCustomCodeUserCodePduFeatureHandle

on page 71.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During run time
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
PduFeatureHandle A DsBusCustomCode PDU feature handle.
Data The data that is provided by the user code.

172
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example -

DsBusCustomCodeUserPort_getDirection

Purpose To get the direction of a user port that is available for the PDU User Code feature
of a PDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source TRC and/or model variable, or constant value set by bus
implementation software
Parameter data recipient User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the direction of a user port that is available for the PDU
User Code feature of a PDU. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

Syntax
Std_ReturnType DsBusCustomCodeUserPort_getDirection(DsBusCustomCodeUserPortHandle UserPortHandle, boolean* Data)

Parent handle This function is provided by DsBusCustomCodeUserPortHandle on page 72.

173
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
UserPortHandle A DsBusCustomCode user port handle.
Data The direction of the user port that is addressed by user port handle:
§ TRUE: The direction of the user port is Out.
§ FALSE: The direction of the user port is In.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare a boolean variable for the direction of an user port
2 boolean portIsOut;
3
4 // Get the direction of the first user port of the UserPorts array and provide the direction to the portIsOut variable
5 DsBusCustomCodeUserPort_getDirection(UserPorts[0], &portIsOut);

DsBusCustomCodeUserPort_getPortData

Purpose To get the data of a user port that is available for the PDU User Code feature of a
PDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.

174
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

Direction of user port User Inport User Outport

Parameter data source TRC and/or model variable, or constant User code
value set by bus implementation software
Parameter data recipient User code User code

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function gets the data of a user port that is available for the PDU User Code
feature of a PDU. The PDU User Code feature is a feature of bus implementation
software tools. For more information on the feature, refer to the documentation
of the related bus implementation software tool.

You can use this function to get data of user inports or of user outports.
However, in most cases, using this function is useful only to get data of user
inports, for example, to provide data that is received from a behavior model to
the user code.

If you want to use this function to get the data of a user outport, you must set
the data beforehand by using the DsBusCustomCodeUserPort_setPortData
function. Refer to DsBusCustomCodeUserPort_setPortData on page 176.

Syntax
Std_ReturnType DsBusCustomCodeUserPort_getPortData(DsBusCustomCodeUserPortHandle UserPortHandle, float64* Data)

Parent handle This function is provided by DsBusCustomCodeUserPortHandle on page 72.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
UserPortHandle A DsBusCustomCode user port handle.
Data The user port data that is accessed by the user port handle.

175
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_PARAMETER_NOT_SET The requested information is not available.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare a float64 variable for the user port data
2 float64 port3Data;
3
4 // Get the data of the third user port of the UserPorts array and provide the data to the port3Data variable
5 DsBusCustomCodeUserPort_getPortData(UserPorts[2], &port3Data);

DsBusCustomCodeUserPort_setPortData

Purpose To set data to a user port that is available for the PDU User Code feature of a
PDU.

Parameter data The following table provides an overview of the required data source of the
function parameters and the recipients of the parameter data. When the
function is called at run time but the data source does not provide the required
data, the function returns E_PARAMETER_NOT_SET.
Parameter data source User code
Parameter data recipient Bus implementation software, provides data via TRC and/or
model variable

For an overview of the bus implementation software tools with which this
function can be used, refer to Using Bus Custom Code Functions with Bus
Implementation Software on page 23.

Description This function sets data of the user code to a user port that is available for the
PDU User Code feature of a PDU. The PDU User Code feature is a feature of bus
implementation software tools. For more information on the feature, refer to the
documentation of the related bus implementation software tool.

The specifications in the user code determine which data is set to the user port.
For example, you can use this function to write status information to a user
outport. Then, the model variable of the user outport can provide this data to a
behavior model, for example.

176
Bus Custom Code Interface Handling May 2024
 Functions of the Bus Custom Code Interface

You can use this function to set data to user outports or to user inports.
However, in most cases, using this function is useful only to set data to user
outports.

You can also access the data of user ports by using

the DsBusCustomCodeUserPort_getPortData function. Refer to
DsBusCustomCodeUserPort_getPortData on page 174.

Syntax
Std_ReturnType DsBusCustomCodeUserPort_setPortData(DsBusCustomCodeUserPortHandle UserPortHandle, float64 Data)

Parent handle This function is provided by DsBusCustomCodeUserPortHandle on page 72.

Characteristics This function has the following characteristics:

Thread-safe Yes
Intended use During initialization
Execution time Deterministic

Parameters This function has the following parameters:

Parameter Description
UserPortHandle A DsBusCustomCode user port handle.
Data The data that is provided by the user code.

Returns This function returns one of the following values:

Value Description
E_OK The function is correctly executed.
E_NOT_OK The function is not correctly executed.
E_INVALID_HANDLE A handle is invalid, e.g., because of an assigned NULL pointer.

Example
1 // Declare the port4Data variable for the user port data and specify the data of the variable
2 float64 port4Data = 12.04;
3
4 // Write the data of the port4Data variable to the fourth user port of the UserPorts array
5 DsBusCustomCodeUserPort_setPortData(UserPorts[3], port4Data);

177
May 2024 Bus Custom Code Interface Handling
 API Reference of the Bus Custom Code Interface

178
Bus Custom Code Interface Handling May 2024
 Index
Index
B
Bus Custom Code interface 10
functions 20
handles 12, 20
modules 12
return values 13
run-time behavior 15
syntax of functions 13
bus implementation software 10

C
Common Program Data folder 8

D
Documents folder 8
DsBusCustomCode module 12

F
function syntax of the Bus Custom Code
interface 13
functions of the Bus Custom Code interface 20

H
handles of the Bus Custom Code interface 12,
20

L
Local Program Data folder 8

M
modules of the Bus Custom Code interface 12

P
PduUserCode module 12

R
return values of the Bus Custom Code
interface 13
run-time behavior 15

S
SecOC module 12

U
user code 10
run-time behavior 15

179
May 2024 Bus Custom Code Interface Handling
 Index

180
Bus Custom Code Interface Handling May 2024