DoIP (ISO13400) Server Stack

Overview

RAPIDSEA supports DoIP protocol as explained in the ISO13400 - DoIP Protocol page. This page explains the server architecture and details how the user should interface the stack with their custom logic and realize the ECU implementation quickly. It also provides guidelines on adopting the stack for different systems.

The below diagram captures the block level diagram of the DoIP server and how it interfaces with other modules.

DOIP Server Block Diagram

Application Interface

While the RAPIDSEA DoIP server stack can handle most of the functionality such as message validation, vehicle identification request, routing activation request, diagnostic request message handling etc, the business logic has to implement the application functionality. the RAPIDSEA DoIP server clearly defines API and callback functions that are essential for the user to use/implement.

The below table captures the function that are to be called from the application logic.

API Functions

Function

Description

rs_iso13400_server_open

To initialize the DoIP server instance structure for both UDP and TCP process

rs_iso13400_server_timer_init

To initialize the DoIP server timer

rs_iso13400_server_run

To be called to set the run state for state machine for both UDP and TCP process.

rs_iso13400_server_udp_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP server UDP communication

rs_iso13400_server_udp_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP server UDP communication.

rs_iso13400_server_tcp_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP server TCP communication

rs_iso13400_server_tcp_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP server TCP communication.

rs_iso13400_server_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP server and UDS communication.

rs_iso13400_server_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP server and UDS communication.

rs_iso13400_server_comm_process

To be called periodically to process the incoming/outgoing messages of both UDP and TCP process.

rs_iso13400_server_process

To be called periodically to get the response from the UDS stack and frame doip layer on top of UDS response and sent to client.

rs_iso13400_server_close

To be called to release the DoIP client handle

These functions are documented in detail in the below sections. It is important for the server to implement these functions correct for proper operation of the system.

Implementation Guide

This section explains how the DoIP server can be implemented using the RAPIDSEA stack. Whether the stack is available in source form or in binary form, the steps to be followed are

  • Implement the Callback functions mentioned above

  • Initialize the buffers necessary for the operation

  • Initialize the DoIP stack function.

  • Periodically call the communication process and server process functions so that internal timeouts are handled.

High level flow chart is depicted below:

DoIP Server Flow Diagram

The below diagram captures the high level sequence of operations associated with the DoIP stack.

DoIP High level Sequence Diagram

This can be implemented in a bare-metal system or over RTOS or over full fledged OS such as Linux etc.

Dependency

This stack depends on the below RAPIDSEA interfaces that can be obtained or custom implemented.

Example demo

An example implementation is available along with the release and is described in DoIP UDS Server Demo.

DoIP Server Header Details

Documentation from the relevant header as follows:

ISO13400 DoIP server Module.

This file contains the APIs for using ISO13400 defined DOIP server Module

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Typedefs

typedef struct tag_rs_iso13400_server_config rs_iso13400_server_config_t

Contains information about ISO13400 server configuration.

typedef struct tag_rs_iso13400_udp_server_info rs_iso13400_udp_server_info_t

Contains information about ISO13400 UDP server information.

typedef struct tag_rs_iso13400_tcp_server_info rs_iso13400_tcp_server_info_t

Contains information about ISO13400 TCP server information.

typedef struct tag_rs_iso13400_server_instance rs_iso13400_server_instance_t

Contains information about ISO13400 server instance.

Functions

rs_handle_t rs_iso13400_server_open(rs_iso13400_server_instance_t *ptr_instance, rs_iso13400_server_config_t *ptr_config)

Initialize the DoIP instance structure with initial values.

This function initialize the DoIP instance structure with initial values.

Parameters:

  • ptr_instance – [in] - pointer to the DoIP instance information

  • ptr_config – [in] - pointer to the DoIP configuration information

Returns:

Handle of the DoIP instance information which include configuration information also

rs_ret_val_t rs_iso13400_server_timer_init(rs_handle_t doip_handle, rs_doip_timer_config_t *ptr_timer_cfg)

Initialize the DoIP server timer.

Initialize the DoIP server timer configuration

Parameters:

  • doip_handle – [in] - handle of the DoIP server instance

  • ptr_timer_cfg – [in] - Pointer to the timer configuration

Returns:

0 on success or error code on failure

rs_ret_val_t rs_iso13400_server_run(rs_handle_t doip_handle, uint32_t u32_run)

Assign the initial state of the state machine for both UDP and TCP.

This function assigns the initial state of the state machine for both UDP and TCP.

Parameters:

  • doip_handle – [in] - Handle of the DoIP server instance information

  • u32_run – [in] - state will be set according to this value.

Returns:

Zero on success or negative error code on failure.

rs_ret_val_t rs_iso13400_server_comm_process(rs_handle_t doip_handle)

Called to call the UDP and TCP’s state machine and process respectively and server timer process.

This function called to call the UDP and TCP’s state machine and process respectively and server timer process..

Parameters:

doip_handle – [in] - Handle of the DoIP server instance information

Returns:

Return 0 if success or negative value if failure.

rs_ret_val_t rs_iso13400_server_udp_set_tx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP server UDP communication.

This function sets up the transmit buffers to be used for DoIP server UDP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP server instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_udp_set_rx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_rx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the receive buffers to be used for the DoIP server UDP communication.

This function sets up the receive buffers to be used for DoIP server UDP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP instance information

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_tcp_set_tx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP server TCP communication.

This function sets up the transmit buffers to be used for DoIP server TCP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP server instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_tcp_set_rx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_rx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the receive buffers to be used for the DoIP server TCP communication.

This function sets up the receive buffers to be used for DoIP server TCP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP instance information

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_set_tx_msg_buf(rs_handle_t doip_handle, rs_an_tp_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP server and UDS communication.

This function sets up the transmit buffers to be used for DoIP server and UDS communication.

Parameters:

  • doip_handle – [in] - handle of DoIP server instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_set_rx_msg_buf(rs_handle_t doip_handle, rs_an_tp_msg_t *ptr_rx_msgs, uint32_t u32_num_msg)

Set up the receive buffers to be used for the DoIP server and UDS communication.

This function sets up the receive buffers to be used for the DoIP server and UDS communication

Parameters:

  • doip_handle – [in] - handle of DoIP server instance information.

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_server_process(rs_handle_t doip_handle)

Frame and sent response messages to appropriate request from DoIP client.

This function frame and sent response messages to appropriate request from DoIP client.

Parameters:

doip_handle – [in] - handle of DoIP server instance information.

Returns:

0 on success and negative on failure

rs_ret_val_t rs_iso13400_server_close(rs_handle_t doip_handle)

Called to free the DoIP server handle.

This function Called to free the DoIP server handle..

Parameters:

doip_handle – [in] - handle of DoIP server instance information.

Returns:

0 on success and negative on failure

struct tag_rs_iso13400_server_config
#include <rs_iso13400_server.h>

Contains information about ISO13400 server configuration.

Public Members

uint16_t port_num

Port number of server.

uint8_t ip_addr[RS_13400_MAX_BUFFER_LENGTH]

IP address of server.

uint8_t broadcast_addr[RS_13400_MAX_BUFFER_LENGTH]

IP address for broadcast.

uint16_t broadcast_port_num

Port number for broadcast.

uint8_t multicast_addr[RS_13400_MAX_BUFFER_LENGTH]

IP address for multicast.

uint16_t num_conn_accept

Number of connections to accept for TCP.

uint16_t client_max_addr

Client’s maximum source address.

uint16_t client_min_addr

Client’s maximum source address.

uint8_t vin[RS_ISO13400_VIN_LEN]

Vehicle identification number.

uint16_t logical_addr

Logical Address.

uint64_t eid

Entity identification number (6bytes only)

uint64_t gid

Group identification number (6bytes only)

uint8_t far_val

further action required

uint16_t *ptr_target_addr

Pointer to the server’s available addresses.

uint8_t num_target_addr

Number of addresses available on server side.

uint8_t diag_pow_mode_state

diagnostics power mode state

struct tag_rs_iso13400_udp_server_info
#include <rs_iso13400_server.h>

Contains information about ISO13400 UDP server information.

Public Members

rs_socket_config_t udp_socket_config

UDP socket configuration.

rs_udp_instance_t udp_socket_instance

UDP socket instance(information)

uint32_t data_len

Data length of RX/TX packet.

uint8_t state

UDP process state.

uint8_t data_buff[RS_13400_BUF_SIZE]

Buffer for RX/TX.

rs_buffer_mgr_t tx_buf_mgr

Transmit buffer manager.

rs_buffer_mgr_t rx_buf_mgr

Receive buffer manager.

rs_buffer_mgr_t rx_msg_queue_mgr

RX message FIFO.

rs_buffer_mgr_t tx_msg_queue_mgr

TX message FIFO.

struct tag_rs_iso13400_tcp_server_info
#include <rs_iso13400_server.h>

Contains information about ISO13400 TCP server information.

Public Members

rs_socket_config_t tcp_socket_config

TCP socket configuration.

rs_tcp_server_instance_t tcp_socket_instance

TCP socket instance(information)

uint32_t data_len

Data length of RX/TX packet.

uint8_t state

TCP process state.

uint8_t data_buff[RS_13400_BUF_SIZE]

Buffer for RX/TX.

rs_buffer_mgr_t tx_buf_mgr

Transmit buffer manager.

rs_buffer_mgr_t rx_buf_mgr

Receive buffer manager.

rs_buffer_mgr_t rx_msg_queue_mgr

RX message FIFO.

rs_buffer_mgr_t tx_msg_queue_mgr

TX message FIFO.

struct tag_rs_iso13400_server_instance
#include <rs_iso13400_server.h>

Contains information about ISO13400 server instance.

Public Members

rs_an_tp_instance_t an_tp_instance

Common instance DoCAN/DoIP(Information)

rs_iso13400_server_config_t *ptr_doip_server_config

Pointer to the DoIP server configuration.

rs_iso13400_udp_server_info_t iso13400_udp_server_info

DoIP UDP server information.

rs_iso13400_tcp_server_info_t iso13400_tcp_server_info

DoIP TCP server information.

rs_handle_t udp_comm_handle

Transport interface handle for UDP.

rs_handle_t tcp_comm_handle

Transport interface handle for TCP.

uint8_t run_state

DoIP server run state.

rs_doip_timer_config_t *ptr_doip_timer

pointer to the DoIP timer configuration

rs_handle_t conn_handle

DoIP socket accept handle.

rs_doip_data_t *ptr_cur_tx_data

DoIP Data being transmitted.

uint16_t client_src_addr

DoIP client’s source address or server’s target address.