SOME/IP Server Stack

Overview

RAPIDSEA supports SOME/IP protocol as explained in the SOME/IP 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 SOME/IP server and how it interfaces with other modules.

Application Interface

While the RAPIDSEA SOME/IP server 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 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_some_server_open	To initialize the SOME/IP server instance structure for both discovery and notification process.
rs_some_server_run	To be called to set the run state for state machine for both discovery and notification process.
rs_some_server_set_tx_msg_buf	To set up the transmit buffers to be used for the SOME/IP server communication.
rs_some_server_set_rx_msg_buf	To set up the receive buffers to be used for the SOME/IP server communication.
rs_some_server_req_stop_offer_service	To frame and sent the stop offer service from server
rs_some_server_process	To be called to call the discovery and notification’s state machine and process respectively and notification event send function.
rs_some_server_subscribe_init	To initialize the SOME/IP subscription details structure associated with the server
rs_some_server_set_reboot_flag	To be called to set the reboot flag in SOME/IP server instance.
rs_some_server_send_notify_event	To be called to send notification events from server
rs_some_server_close	To freed the SOME/IP server handle

There are many functions through which the SOME/IP server 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_server_rx_req_handler	called to handle the request received from client and prepare the response
rcb_some_server_update_response_status_info	Called to send the update value as notification message to client.
rcb_some_server_get_serialized_config_option	called to check service available or not and registered if available.
rcb_some_server_get_load_balancing_option_info	Called to get the data of load balancing option
rcb_some_server_set_deserialize_config_option	Called to set the deserialized data of configuration option
rcb_some_server_get_mem	Called to get memory

SOME/IP Server Configuration Parameter:

Server Configuration
Function	Description
server_addr	SOME/IP Server IP address
sd_multicast_addr	SOME/IP SD Multicast IP address
sd_port	SOME/IP SD Port number
protocol_ver	SOME/IP protocol version
interface_ver	SOME/IP interface version
initial_delay	SOME/IP SD initial wait time
repetitions_base_delay	SOME/IP SD repetition base delay
repetitions_max	SOME/IP SD repetition max
sd_ip_version	SOME/IP SD IP Version (IPv4/IPv6)
log_level	SOME/IP Client log level

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 SOME/IP server can be implemented using the RAPIDSEA stack. The stack is available in source form, the steps to be followed are

Initialize the server 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_server_process functions so that internal timeouts are handled.

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 Server Stack Memory Usage

ROM/RAM Consumption (Stack only)
Platform	Memory	Size
Linux	ROM	68KB
Linux	RAM	27KB
Micro controller (iMXRT)	ROM	65KB
Micro controller (iMXRT)	RAM	25KB

ROM/RAM Consumption (Stack + Application)
Platform	Memory	Size
Linux	ROM	80KB
Linux	RAM	170KB
Micro controller (iMXRT)	ROM	135KB
Micro controller (iMXRT)	RAM	175KB

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 interfaces 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 Server Demo.

SOME/IP Server Header Details

Documentation from the relevant header as follows:

SOME/IP server based APIs.

This file have declaration of SOME/IP server based functions

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

Defines

RS_SOMEIP_SERVER_MAX_NOTIFY_UDP_SOCKET: SOME/IP Server Maximum Number of Notification UDP Sockets.

RS_SOMEIP_SERVER_MAX_NOTIFY_TCP_SOCKET: SOME/IP Server Maximum Number of Notification TCP Sockets.

RS_SOMEIP_SERVER_MAX_NUM_OF_TCP_CLIENT_CONN: SOME/IP Server Maximum Number of TCP Client connections.

Typedefs

typedef struct tag_rs_someip_server_service_info rs_someip_server_service_info_t: Contains information about SOME/IP Server service details.

typedef struct tag_rs_someip_server_subscribe_info rs_someip_server_subscribe_info_t: Contains information about SOME/IP subscribe details.

typedef struct tag_rs_someip_tcp_conn_instance rs_someip_tcp_conn_instance_t: Contains information about SOME/IP TCP Client connection details.

typedef struct tag_rs_someip_server_tcp_info rs_someip_server_tcp_info_t: Contains information about SOME/IP TCP Server Socket details.

typedef struct tag_rs_someip_server_notify_info rs_someip_server_notify_info_t: Contains information about SOME/IP Server notification process.

typedef struct tag_rs_someip_server_config rs_someip_server_config_t: Contains information about SOME/IP server configuration.

typedef struct tag_rs_someip_server_instance rs_someip_server_instance_t: Contains information about SOME/IP server instance.

Functions

rs_handle_t rs_some_server_open(rs_someip_server_instance_t *ptr_instance, rs_someip_server_config_t *ptr_config)

Function Declarations.

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 server instance
ptr_config – [in] - Pointer to the SOME/IP server configuration

Returns:

Handle of the SOME/IP instance information

rs_ret_val_t rs_some_server_run(rs_handle_t handle, uint32_t u32_run)

Assign the initial state of the state machine for SOME/IP Server.

This function assigns the initial state of the state machine for SOME/IP Server.

Parameters:

handle – [in] - Handle of the SOME/IP server instance.
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_server_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 server stack.

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

Parameters:

handle – [in] - Handle of SOME/IP server instance
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 on success or negative error code on failure.

rs_ret_val_t rs_some_server_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 server instance
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 on success or negative error code on failure.

rs_ret_val_t rs_some_server_req_stop_offer_service(rs_handle_t handle)

Frame and send stop offer service.

This function frame and send the stop offer service.

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

rs_ret_val_t rs_some_server_subscribe_init(rs_handle_t handle, rs_someip_server_subscribe_info_t *ptr_subscribe_info, uint32_t u32_num_subscription)

Initialize the subscription structure.

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

Parameters:

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

Returns:

Return 0 if success or negative if failure.

rs_ret_val_t rs_some_server_process(rs_handle_t someip_server_handle)

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

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

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

rs_ret_val_t rs_some_server_send_notify_event(rs_handle_t someip_server_handle, rs_someip_notify_event_info_t *ptr_notify_event_info)

Called to send notification events from server.

This function called to send notification events from server.

Parameters:

someip_server_handle – [in] - Handle of the SOME/IP server instance.
ptr_notify_event_info – [in] - Pointer to the notification event information

Returns:

Return 0 if success or negative if failure.

rs_ret_val_t rs_some_server_set_reboot_flag(rs_handle_t someip_server_handle, uint8_t u8_reboot_val)

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

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

Parameters:

someip_server_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_server_close(rs_handle_t someip_server_handle)

Called to free the SOME/IP server handle.

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

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

rs_ret_val_t rcb_some_server_rx_req_handler(rs_handle_t handle, rs_someip_req_resp_info_t *ptr_req_info)

Called to handling the request from client and prepare the response.

This function called to handle the request received from client and prepare the response

Parameters:

handle – [in] - Handle of the SOME/IP server instance.
ptr_req_info – [in] - Pointer to the subscribe information.

Returns:

Return 0 on success or error code on failure.

uint8_t *rcb_some_server_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_server_update_response_status_info(rs_handle_t handle, rs_someip_server_subscribe_info_t *ptr_sub_info, rs_someip_req_resp_info_t *ptr_req_info, uint8_t u8_err_code)

Called to send the update value as notification message to client.

This function called to send the update value as notification message to client.

Parameters:

handle – [in] - Handle of the SOME/IP instance information.
ptr_sub_info – [in] - Pointer to the subscribe information.
ptr_req_info – [in] - Pointer to the request information.
u8_err_code – [in] - Error code.

Returns:

Return 0 if success.

rs_ret_val_t rcb_some_server_get_serialized_config_option(rs_handle_t handle, rs_someip_config_opt_info_t *ptr_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 server instance
ptr_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_server_get_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 get the data of load balancing option.

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

Parameters:

handle – [in] - Handle of the SOME/IP server instance
ptr_load_opt_info – [out] - Pointer to the load balance option information
u8_serv_type – [in] - Service type

Returns:

Return length of the payload data

rs_ret_val_t rcb_some_server_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 configuration option.

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

Parameters:

handle – [in] - Handle of the SOME/IP server 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_server_send_notification_event(rs_handle_t handle, rs_someip_req_resp_info_t *ptr_req_info)

Called to send the notification event.

This callback function is called to send the notification event.

Parameters:

handle – [in] - Handle of the SOME/IP server instance information.
ptr_req_info – [in] - Pointer to the SOME/IP request resposne information.

Returns:

Return 1 on success or 0 on failure

struct tag_rs_someip_server_service_info

#include <rs_someip_server.h>

Contains information about SOME/IP Server service details.

Public Members

rs_someip_service_details_t serv_details: Server service details.

uint16_t port: Port Number.

uint8_t ip_version: IP Version (IPv4/IPV6)

uint8_t proto_type: Protocol communication type (UDP/TCP)

uint16_t num_of_eventgrp_list: Number of eventgroup.

rs_someip_eventgrp_list_t *ptr_eventgrp_list: Pointer to the eventgroup list information.

struct tag_rs_someip_server_subscribe_info

#include <rs_someip_server.h>

Contains information about SOME/IP subscribe details.

Public Members

rs_someip_service_details_t serv_details: Service details of subscription.

uint16_t eventgrp_id: Subscribe Eventgroup ID.

uint16_t client_id: Subscribe Client ID.

rs_sock_addr_t socket_info: Subscription unicast socket IP and port information.

rs_sock_addr_t multi_socket_info: Subscription multicast socket IP and port information.

uint8_t comm_type: Communication type.

uint8_t ip_version: IP Version (IPv4/IPv6)

rs_handle_t transport_handle: Transport handle.

uint32_t last_sub_time: Last subscribe time in ms.

struct tag_rs_someip_tcp_conn_instance

#include <rs_someip_server.h>

Contains information about SOME/IP TCP Client connection details.

Public Members

uint8_t state: SOME/IP Notification TCP Connection process state.

uint8_t run_state: SOME/IP Notification TCP Connection run state.

rs_handle_t client_handle: SOME/IP Notification TCP Connection handle.

uint16_t sn_tcp_session_id: SOME/IP Notification TCP Session ID.

struct tag_rs_someip_server_tcp_info

#include <rs_someip_server.h>

Contains information about SOME/IP TCP Server Socket details.

Public Members

rs_tcp_server_instance_t tcp_socket_instance: SOME/IP TCP Server socket instance(Information)

rs_socket_config_t tcp_socket_config: SOME/IP TCP Server socket configuration.

rs_handle_t comm_tcp_handle: SOME/IP TCP Server socket handle.

uint32_t num_of_clients: Number of client connections.

uint8_t state: SOME/IP TCP Server socket state.

uint8_t run_state: SOME/IP TCP Server socket run state.

rs_someip_tcp_conn_instance_t client_inst[RS_SOMEIP_SERVER_MAX_NUM_OF_TCP_CLIENT_CONN]: SOME/IP TCP Server socket connection instance.

struct tag_rs_someip_server_notify_info

#include <rs_someip_server.h>

Contains information about SOME/IP Server notification process.

Public Members

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

rs_someip_udp_proto_info_t notify_udp_info[RS_SOMEIP_SERVER_MAX_NOTIFY_UDP_SOCKET]: SOME/IP Server notification UDP Socket info.

rs_someip_server_tcp_info_t server_tcp_info[RS_SOMEIP_SERVER_MAX_NOTIFY_TCP_SOCKET]: SOME/IP Server notification TCP Socket info.

struct tag_rs_someip_server_config

#include <rs_someip_server.h>

Contains information about SOME/IP server configuration.

Public Members

uint8_t server_addr[RS_SOMEIP_IP_ADDR_LEN]: SOME/IP Server IP address.

uint8_t sd_multicast_addr[RS_SOMEIP_IP_ADDR_LEN]: SOME/IP SD Multicast IP address.

uint16_t sd_port: SOME/IP SD Port number.

uint8_t protocol_ver: SOME/IP protocol version.

uint8_t interface_ver: SOME/IP interface version.

uint32_t cyclic_offer_delay: SOME/IP SD cyclic offer delay.

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 sd_ip_version: SOME/IP SD IP Version (IPv4/IPv6)

uint8_t log_level: SOME/IP Client log level.

struct tag_rs_someip_server_instance

#include <rs_someip_server.h>

Contains information about SOME/IP server instance.

Public Members

rs_someip_server_config_t *ptr_config: Pointer to containing server configuration.

rs_someip_discov_process_info_t discov_process_info: SOME/IP server discovery process information.

rs_someip_server_notify_info_t notify_process_info: SOME/IP server notification process information.

rs_someip_server_subscribe_info_t *ptr_subscribe_details: Pointer to subscribe structure information.

uint32_t number_of_subscribe: Number of subscribers.

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

uint32_t number_of_services: Number of services.

uint32_t last_offer_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 Server notification tx mode (unicast or multicast)

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