SOME/IP Client Stack

SOME/IP Client Overview

RAPIDSEA supports SOME/IP protocol as explained in the SOME/IP Protocol page. This page explains the client architecture and details how the user should interface the stack with their custom logic and realize the Tester implementation quickly. It also provides guidelines on adopting the stack for different systems.

The below diagram captures the block level diagram of the SOME/IP client and how it interfaces with other modules.

Application Interface

While the RAPIDSEA SOME/IP client stack can handle most of the functionality such as message validation, service discovery management, subscription handling, Notification process etc, the business logic has to implement the application functionality. The RAPIDSEA SOME/IP client 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_some_client_open	To initialize the SOME/IP client instance structure for both discovery and notification process.
rs_some_client_subscribe_init	To initialize the SOME/IP subscription details structure associated with the client.
rs_some_client_run	To be called to set the run state for state machine for both discovery and notification process.
rs_some_client_set_rx_msg_buf	To set up the receive buffers to be used for the SOME/IP client communication.
rs_some_client_set_tx_msg_buf	To set up the transmit buffers to be used for the SOME/IP client communication.
rs_some_client_send_req	To be called to frame and send request message for given method ID and their related parameters.
rs_some_client_req_find_service	To be called to find the service of given service ID and instance ID.
rs_some_client_send_stop_subscribe_req	To be called to stop the eventgroup subscription for given eventgroup ID.
rs_some_client_send_notify_req	To be called to send the request for subscribed eventgroups (read/write/method)
rs_some_client_set_reboot_flag	To be called to set the reboot flag in SOME/IP client instance.
rs_some_client_process	To be called to call the discovery and notification’s state machine and process respectively.
rs_some_client_all_subscribe_reset	Called to reset all subscription details on client.
rs_some_client_close	To freed the SOME/IP client handle.

There are many functions through which the SOME/IP client stack retrieves information from the application logic or indicate actions to be performed. These functions are captured in the below table.

Callback Functions
Function	Description
rcb_some_client_notification_resp_handler	Called when response for a read/write/method request is received and also notification events received
rcb_some_client_notification_resp_err_handler	Called to indicate reception of error response for any request
rcb_some_client_subscription_resp_handler	Called when response for a service discovery request is received
rcb_some_client_get_serialized_config_option	Called when function get the serialized data of configuration option
rcb_some_client_set_deserialize_config_option	Called when function set the deserialized data of load balancing option
rcb_some_client_set_load_balancing_option_info	called when function set the data of load balancing option
rcb_some_client_get_mem	Called to get memory

SOME/IP Client Configuration Parameter:

Client Configuration
Function	Description
sd_multicast_addr	Multicast IP address
client_addr	SOME/IP client IP address
sd_port	SD Port number for UDP IP
sn_port	SN Port number
ip_version	SOME/IP SD repetition max
protocol_ver	SOME/IP protocol version
interface_ver	SOME/IP interface version
client_id	SOME/IP Client ID
initial_delay	SOME/IP SD initial wait time
repetitions_base_delay	SOME/IP SD repetition base delay
repetitions_max	SOME/IP SD repetition max
log_level	SOME/IP Client log level

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

Implementation Guide

This section explains how the SOME/IP client can be implemented using the RAPIDSEA stack. The stack is available in source form, the steps to be followed are

Initialize the client configuration
Implement the Callback functions mentioned above
Initialize the buffers necessary for the operation
Initialize the SOME/IP stack function.
Periodically call the rs_some_client_process functions so that internal timeouts are handled.
If there is a need to send a request to ECU/server, send via rs_some_client_send_notify_req call
When the response from server is received, rcb_some_client_notification_resp_handler function called.
On reception of negative response from server, rcb_some_client_notification_resp_err_handler function is called.

High level flow chart is depicted below:

The below diagram captures the high level sequence of operations associated with the SOME/IP stack.

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

SOME/IP Client Stack Memory Usage

ROM/RAM Consumption (Stack only)
Platform	Memory	Size
Linux	ROM	72KB
Linux	RAM	33KB
Micro controller (iMXRT)	ROM	70KB
Micro controller (iMXRT)	RAM	30KB

ROM/RAM Consumption (Stack + Application)
Platform	Memory	Size
Linux	ROM	85KB
Linux	RAM	178KB
Micro controller (iMXRT)	ROM	145KB
Micro controller (iMXRT)	RAM	180KB

Note:

The above table captures the memory usage for five services. Each service has three event groups, and across these three groups, a total of nine events are mapped (5, 2, and 2 respectively). If you add or remove services, the memory usage will increase or decrease accordingly.

Dependency

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

Socket Interface

Example demo

An example implementation is available along with the release and is described in SOME/IP Client Demo.

SOME/IP Client Header

Documentation from the relevant header as follows:

SOME/IP Client based APIs.

This file contains the declaration and details of SOME/IP client based APIs

Author: Embien RAPIDSEA Team
Copyright: Embien Technologies India Pvt. Ltd.

Defines

RS_SOMEIP_CLIENT_MAX_TCP_CONN: SOME/IP Client maximum number of TCP socket connection.

RS_SOMEIP_CLIENT_MAX_UDP_SOCKET: SOME/IP Client maximum number of UDP socket connection.

RS_SOMEIP_CLIENT_MAX_SUB_EVTGRP_LIST: SOME/IP Client maximum number of subscribe eventgroup list.

Typedefs

typedef struct tag_rs_someip_client_service_info rs_someip_client_service_info_t: Contains information about SOME/IP service details.

typedef struct tag_rs_someip_client_subscribe_list rs_someip_client_subs_eventgrp_list_t: Contains information about SOME/IP subscribe eventgroup list details.

typedef struct tag_rs_someip_client_subscribe_info rs_someip_client_subscribe_info_t: Contains information about SOME/IP subscribe list details per socket information.

typedef struct tag_rs_someip_client_tcp_info rs_someip_client_tcp_info_t: Contains information about SOME/IP client notification TCP protocol communication.

typedef struct tag_rs_someip_client_notify_info rs_someip_client_notify_info_t: Contains information about SOME/IP client notification process.

typedef struct tag_rs_someip_client_config rs_someip_client_config_t: Contains information about SOME/IP client configuration.

typedef struct tag_rs_someip_client_instance rs_someip_client_instance_t: Contains information about SOME/IP client instance.

Functions

rs_handle_t rs_some_client_open(rs_someip_client_instance_t *ptr_instance, rs_someip_client_config_t *ptr_config)

Initialize the SOME/IP instance structure with initial values.

This function initialize the SOME/IP instance structure with initial values.

Parameters:

ptr_instance – [in] - Pointer to the SOME/IP client instance
ptr_config – [in] - Pointer to the SOME/IP client configuration

Returns:

Handle of the SOME/IP instance information

rs_ret_val_t rs_some_client_run(rs_handle_t handle, uint32_t u32_run)

Assign the initial state of the state machine for both discovery and notification.

This function assigns the initial state of the state machine for both discovery and notification.

Parameters:

handle – [in] - Handle of the SOME/IP client 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_some_client_set_rx_msg_buf(rs_handle_t handle, rs_someip_msg_t *ptr_rx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf, uint8_t u8_proc_type)

Set up the receive buffers to be used for the SOME/IP stack.

This function sets up the receive buffers to be used for SOME/IP stack

Parameters:

handle – [in] - handle of SOME/IP client instance information
ptr_rx_msgs – [in] - Pointer to the array of SOME/IP receive messages
u32_num_msg – [in] - Number of receive messages that the SOME/IP stack can use from the above array
ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer
u8_proc_type – [in] - Process type (Discovery or Notification)

Returns:

Zero or negative error code

rs_ret_val_t rs_some_client_set_tx_msg_buf(rs_handle_t handle, rs_someip_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf, uint8_t u8_proc_type)

Set up the transmit buffers to be used for the SOME/IP client stack.

This function sets up the transmit buffers to be used for SOME/IP client stack

Parameters:

handle – [in] - Handle of SOME/IP client instance information
ptr_tx_msgs – [in] - Pointer to the array of SOME/IP transmit messages
u32_num_msg – [in] - Number of transmit messages that the SOME/IP stack can use from the above array
ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer
u8_proc_type – [in] - Process type (Discovery or Notification)

Returns:

Zero or negative error code

rs_ret_val_t rs_some_client_req_find_service(rs_handle_t handle, rs_someip_service_details_t *ptr_srv_details, uint32_t u32_num_entry)

Frame and send find service request.

This function frame and send the find service request for the given service ID and instance ID.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_srv_details – [in] - Pointer to SOME/IP client service details.
u32_num_entry – [in] - Number of elements in array.

Returns:

Return Number of bytes sent.

rs_ret_val_t rs_some_client_send_stop_subscribe_req(rs_handle_t handle)

Frame and send stop subscribe eventgroup request.

This function frame and send the stop subscribe eventgroup request for all eventgroups and reset the subscription in client side.

Parameters:: handle – [in] - Handle of the SOME/IP client instance information.
Returns:: Return 0 if success or negative value if failure

rs_ret_val_t rs_some_client_send_notify_req(rs_handle_t handle, rs_someip_req_resp_info_t *ptr_req_resp_info, rs_someip_client_subscribe_info_t *ptr_subscribe_details)

Frame and send request for subscribed eventgroups.

This function frame and send the request for subscribed eventgroups (read/write/method).

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_req_resp_info – [in] - Pointer to the request response information structure.
ptr_subscribe_details – [in] - Pointer to the subscribe structure.

Returns:

Return 0 if success or negative value if failure.

rs_ret_val_t rs_some_client_set_reboot_flag(rs_handle_t someip_client_handle, uint8_t u8_reboot_val)

Called to set the reboot flag in SOME/IP client instance.

This function called to set the reboot flag in SOME/IP client instance.

Parameters:

someip_client_handle – [in] - Handle of the SOME/IP instance information
u8_reboot_val – [in] - Reboot value.

Returns:

Return 0 if success or negative value if failure.

rs_ret_val_t rs_some_client_subscribe_init(rs_handle_t handle, rs_someip_client_subscribe_info_t *ptr_subscribe_info, uint32_t u32_num_subscription, uint32_t u32_sub_list_num)

Initialize the subscription structure.

This function initialize the subscription structure in given instance structure to store subscribe information on socket bases.

Parameters:

handle – [in] - Handle of the SOME/IP client instance structure.
ptr_subscribe_info – [in] - Pointer to subscription information structure.
u32_num_subscription – [in] - Max number of subscription.
u32_sub_list_num – [in] - Max number of subscription list.

Returns:

Return 0 if success or -1 if failure.

rs_ret_val_t rs_some_client_process(rs_handle_t someip_client_handle)

Called to call the discovery and notification’s state machine and process respectively.

This function called to call the discovery and notification’s state machine and process respectively

Parameters:: someip_client_handle – [in] - Handle of the SOME/IP client instance information
Returns:: Return 0 if success or negative value if failure.

rs_ret_val_t rs_some_client_all_subscribe_reset(rs_handle_t someip_client_handle)

Called to reset all subscription details on client.

This function called to reset all subscription details on client.

Parameters:: someip_client_handle – [in] - Handle of the SOME/IP instance information
Returns:: Return 0 if success.

rs_ret_val_t rs_some_client_close(rs_handle_t someip_client_handle)

Called to free the SOME/IP client handle.

This function called to free the SOME/IP client handle.

Parameters:: someip_client_handle – [in] - Handle of the SOME/IP instance information
Returns:: Return 0 if success or negative value if failure.

uint8_t *rcb_some_client_get_mem(uint32_t u32_size)

Called to get memory.

This function called to get memory.

Parameters:: u32_size – [in] - Needed size
Returns:: Return pointer to a SOME/IP buffer if available or NULL

rs_ret_val_t rcb_some_client_notification_resp_err_handler(rs_handle_t handle, rs_someip_notify_event_info_t *ptr_notify_evt_info, uint8_t u8_err_code)

Called when error response received from server.

This function prints an error line for received error code.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_notify_evt_info – [in] - Pointer to the notification event information.
u8_err_code – [in] - Error code received on response.

Returns:

Return 0 on success.

rs_ret_val_t rcb_some_client_notification_resp_handler(rs_handle_t handle, rs_someip_notify_event_info_t *ptr_notify_evt_info)

Called when notification events or response for request received from server.

This function called for the notification events and response for a given request received form server.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_notify_evt_info – [in] - Pointer to the notification event information.

Returns:

Return 0 on success or negative number on failure.

rs_ret_val_t rcb_some_client_subscription_resp_handler(rs_handle_t handle, rs_someip_service_details_t *ptr_serv_details, uint16_t u16_eventgrp_id, uint8_t u8_msg_type)

Called when response received for eventgroup subscription request.

This function to print ACK or NACK received for eventgroup subscribe request.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_serv_details – [in] - Pointer to the service details.
u16_eventgrp_id – [in] - Eventgroup ID.
u8_msg_type – [in] - Received message type (ACK/NACK).

Returns:

Return 0 on success.

rs_ret_val_t rcb_some_client_get_serialized_config_option(rs_handle_t handle, rs_someip_config_opt_info_t *ptr_config_opt_info, uint8_t u8_serv_type)

Callback function to get the serialized data of configuration option.

This is a callback function to get the serialized data of configuration option

Parameters:

handle – [in] - Handle of the SOME/IP client instance
ptr_config_opt_info – [out] - Pointer to the configuration option information
u8_serv_type – [in] - Service type

Returns:

Return length of the payload data

rs_ret_val_t rcb_some_client_set_deserialize_config_option(rs_handle_t handle, rs_someip_config_opt_info_t *ptr_config_opt_info, uint8_t u8_serv_type)

Callback function to set the deserialized data of load balancing option.

This is a callback function to set the deserialized data of load balancing option

Parameters:

handle – [in] - Handle of the SOME/IP client instance
ptr_config_opt_info – [in] - Pointer to the configuration option data information

Returns:

Return length of the payload data

rs_ret_val_t rcb_some_client_set_load_balancing_option_info(rs_handle_t handle, rs_someip_load_opt_info_t *ptr_load_opt_info, uint8_t u8_serv_type)

Callback function to set the data of load balancing option.

This is a callback function to set the data of load balancing option

Parameters:

handle – [in] - Handle of the SOME/IP client instance
ptr_load_opt_info – [in] - Pointer to the load balancing option data information
u8_serv_type – [in] - Service type

Returns:

Returns 0 on success

struct tag_rs_someip_client_service_info

#include <rs_someip_client.h>

Contains information about SOME/IP service details.

Public Members

rs_someip_service_details_t serv_details: SOME/IP Client service information.

uint16_t num_of_eventgrp: Number of eventgroup.

rs_someip_eventgrp_list_t *ptr_eventgrp: Pointer to the eventgroup information.

struct tag_rs_someip_client_subscribe_list

#include <rs_someip_client.h>

Contains information about SOME/IP subscribe eventgroup list details.

Public Members

uint16_t eventgrp_id: Subscription eventgroup ID.

rs_sock_addr_t multi_socket_info: Subscription eventgroup multicast information.

struct tag_rs_someip_client_subscribe_info

#include <rs_someip_client.h>

Contains information about SOME/IP subscribe list details per socket information.

Public Members

rs_someip_service_details_t serv_details: Subscription service details.

rs_sock_addr_t socket_info: Subscription socket information.

uint8_t comm_type: Subscription communication type.

uint8_t ip_version: Subscription IP version (IPv4 or IPv6)

int32_t transport_handle: Subscription transport handle.

uint32_t last_rx_offer_srv_time: last RX offer service time

uint32_t num_of_eventgrp_list: Maximum number of subscribe eventgroup list.

rs_someip_client_subs_eventgrp_list_t sub_evtgrp_list[RS_SOMEIP_CLIENT_MAX_SUB_EVTGRP_LIST]: Subscribe eventgroup list information.

struct tag_rs_someip_client_tcp_info

#include <rs_someip_client.h>

Contains information about SOME/IP client notification TCP protocol communication.

Public Members

rs_socket_config_t tcp_socket_config: TCP socket configuration.

rs_tcp_conn_instance_t tcp_socket_instance: TCP connection instance.

uint8_t state: TCP Connection communication process state.

uint8_t run_state: TCP connection run state.

rs_handle_t conn_handle: Connection Handle.

uint16_t sn_tcp_session_id: Session ID for Notification.

struct tag_rs_someip_client_notify_info

#include <rs_someip_client.h>

Contains information about SOME/IP client notification process.

Public Members

rs_someip_tx_rx_msg_mgr_info_t notify_comm_msg_mgr_info: SOME/IP Client notification process TX/RX Message manager.

rs_someip_udp_proto_info_t notify_udp_info[RS_SOMEIP_CLIENT_MAX_UDP_SOCKET]: Service Notification UDP socket information.

uint32_t num_of_conn: Number of client connection available.

rs_someip_client_tcp_info_t conn_inst[RS_SOMEIP_CLIENT_MAX_TCP_CONN]: TCP connection instance.

struct tag_rs_someip_client_config

#include <rs_someip_client.h>

Contains information about SOME/IP client configuration.

Public Members

uint8_t client_addr[RS_SOMEIP_IP_ADDR_LEN]: SOME/IP client IP address.

uint8_t sd_multicast_addr[RS_SOMEIP_IP_ADDR_LEN]: Multicast IP address.

uint16_t sd_port: SD Port number for UDP IP.

uint16_t sn_port: SN Port number.

uint8_t ip_version: SOME/IP SD repetition max.

uint8_t protocol_ver: SOME/IP protocol version.

uint8_t interface_ver: SOME/IP interface version.

uint16_t client_id: SOME/IP Client ID.

uint32_t initial_delay: SOME/IP SD initial wait time.

uint32_t repetitions_base_delay: SOME/IP SD repetition base delay.

uint8_t repetitions_max: SOME/IP SD repetition max.

uint8_t log_level: SOME/IP Client log level.

struct tag_rs_someip_client_instance

#include <rs_someip_client.h>

Contains information about SOME/IP client instance.

Public Members

rs_someip_client_config_t *ptr_config: Pointer to containing server configuration.

rs_someip_client_notify_info_t notify_process_info: SOME/IP client service notification process information.

rs_someip_discov_process_info_t discov_process_info: SOME/IP client service discovery process information.

rs_someip_client_subscribe_info_t *ptr_subscribe_details: Pointer to subscribe structure information.

rs_someip_client_service_info_t *ptr_service_info: Pointer to the SOME/IP service information.

uint32_t number_of_subscribe: number of service subscribed

uint32_t number_of_services: Number of services.

uint32_t last_send_find_srv_time: last offer service sent time

uint8_t enable_main_phase: SOME/IP main phase.

uint8_t repetitions_count: SOME/IP repetition count.

uint8_t reboot_flag: SOME/IP Client reboot flag.

uint8_t sn_udp_tx_mode: SOME/IP client notification tx mode (unicast or multicast)

uint8_t sd_udp_tx_mode: SOME/IP client discovery tx mode (unicast or multicast)