SOME/IP Service Discovery

Overview

RAPIDSEA supports SOME/IP service discovery module as explained in the SOME/IP Protocol page. This module is a standalone communication middleware component responsible for handling Service Discovery messages as defined by the SOME/IP-SD protocol. The SOME/IP SD module operates independently of SOME/IP Server and SOME/IP Client application logic and provides a unified mechanism for receiving, parsing, classifying, and dispatching SD messages. This module is used by both SOME/IP Clients and SOME/IP Servers.The SOME/IP SD module is located between the UDP transport layer and the SOME/IP Server and Client functional entities. It acts as a dispatcher that routes SD messages to the appropriate consumer based on the Call-back registeration. Supporting both multicast and unicast message reception in accordance with the SOME/IP-SD specification.This module provides APIs that abstract SOME/IP Service Discovery operations, enabling upper layers to perform service offering, service discovery, and event group subscription without handling low-level communication details.

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

Application Interface

The SD module ensures proper reception, validation, classification, and routing of SOME/IP-SD messages by providing mechanisms for:

• Receiving all SOME/IP-SD messages via a dedicated UDP socket bound to the configured SD port.

• Parsing incoming SD messages, including the SOME/IP-SD header, entry array, and option array.

• Validating message integrity, including:

  • Message length consistency

  • Entry array boundaries

  • Protocol version and interface version

  • SD flags and reserved fields

• Discarding invalid SD messages without further processing if any validation checks fail.

• Providing a registration interface for callback functions corresponding to SOME/IP server and SOME/IP client.

• Supporting multiple independent consumers, such as SOME/IP Server and SOME/IP Client modules.

• Invoking the callback with parsed message data and associated metadata

• Silently discarding messages for which no callback has been registered.

• Sending the transmit message from SOME/IP server or SOME/IP client module

The RAPIDSEA SOME/IP Service Discovery module clearly defines API functions that are essential for users to implement and integrate service discovery, message handling, and callback-based routing mechanisms effectively.

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

API Functions

Function	Description
rs_someip_sd_get_version_info	To retrieves the major, minor and build version numbers of the SOME/IP SD module.
rs_someip_sd_open	To initialize the SOME/IP SD instance structure with initial values and configuration.
rs_some_sd_run	To assign the initial state of the state machine for SOME/IP SD.
rs_someip_sd_register_server_callback	To set the server callback functions that is to be called from the SD Module.
rs_someip_sd_register_client_callback	To set the client callback functions that is to be called from the SD Module.
rs_someip_sd_register_server_handle	To register the server handle to the Service discovery module.
rs_someip_sd_register_client_handle	To register the client handle to the Service discovery module.
rs_someip_sd_deregister_server_handle	To deregister the server handle to the Service discovery module.
rs_someip_sd_deregister_client_handle	To deregister the client handle to the Service discovery module.
rs_someip_sd_transmit_msg	To Transmit the SD message
rs_someip_sd_process	To call the SOME/IP SD TX and RX process
rs_someip_sd_close	To free the instance from handle

SOME/IP SD Configuration Parameter:

SD Configuration

Function	Description
ip_addr	IP address of the Device where SD module running
sd_multicast_ip	SOME/IP SD Multicast IP address
sd_ip_version	SOME/IP SD IP Version (IPv4/IPv6)
sd_port	SOME/IP SD Port number

Implementation Guide

1. Initialize instance using rs_someip_sd_open.

2. Set the initial state of SD state machine using rs_some_sd_run

3. Register the handle using rs_someip_sd_register_server_handle or rs_someip_sd_register_client_handle

4. Register the call-back register rs_someip_sd_register_server_callback or rs_someip_sd_register_client_callback

5. Periodically call rs_someip_sd_process for internal state handling.

6. Routing the incoming SD messages to registered call-back functions.

7. Transmit the SD messages via rs_someip_sd_transmit_msg

8. Release message buffers after transmission or reception using appropriate release APIs.

9. Close the instance using rs_someip_sd_close during shutdown.

High level flow chart is depicted below:

The below diagram captures the Initialization of SOME/IP SD associated with the application layer.

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

Note

***** represents server or client in the above diagrams.

SOME/IP SD Stack Memory Usage

ROM/RAM Consumption (Stack only)

Platform	Memory	Size
Micro controller (iMXRT)	ROM	TODO
Micro controller (iMXRT)	RAM	TODO

Dependency

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

1. SOME/IP Client Stack

2. SOME/IP Server Stack

3. Socket Interface

SOME/IP SD Header Details

Documentation from the relevant header as follows:

SOME/IP Service discovery Module.

This file contains the APIs for using defined Service discovery Module

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_SOMEIP_SD_COMM_COUNT_PER_PROCESS

SOME/IP-SD Communication RX/TX count per process.

RS_SOMEIP_SD_RX_BUF_MAX_LEN

SOME/IP-SD RX Buffer length.

RS_NUM_SOMEIP_SERVER

Number of SOME/IP Server available.

RS_NUM_SOMEIP_CLIENT

Number of SOME/IP Client available.

RS_SOMEIP_SD_STATE_IDLE

SOME/IP Service Discovery state machine macros SOME/IP SD Idle state

RS_SOMEIP_SD_STATE_OPEN

SOME/IP SD Open state.

RS_SOMEIP_SD_STATE_COMM

SOME/IP SD Communication state.

RS_SOMEIP_SD_STATE_ERROR

SOME/IP SD Error state.

RS_SOMEIP_SD_STATE_CLOSE

SOME/IP SD Close state.

Typedefs

typedef rs_ret_val_t (*rs_someip_sd_cb)(rs_handle_t handle, rs_someip_msg_t *ptr_rx_msg)

SD Callback template.

typedef struct tag_rs_someip_sd_config rs_someip_sd_config_t

Contains information about SOME/IP SD configuration.

typedef struct tag_rs_someip_sd_instance rs_someip_sd_instance_t

Contains information about SOME/IP SD instance.

Functions

rs_ret_val_t rs_someip_sd_get_version_info(uint8_t *ptr_maj_ver, uint8_t *ptr_min_ver, uint8_t *ptr_build_ver)

Get the version information of the SOME/IP SD module.

This function retrieves the major, minor, and build version numbers of the SOME/IP SD module.

Parameters:

• ptr_maj_ver – [out] - Pointer to store the major version number

• ptr_min_ver – [out] - Pointer to store the minor version number

• ptr_build_ver – [out] - Pointer to store the build version number

Returns:

Zero on success or negative error code on failure

rs_handle_t rs_someip_sd_open(rs_someip_sd_instance_t *ptr_instance, rs_someip_sd_config_t *ptr_config)

Initialize the SOME/IP SD instance structure with initial values.

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

Parameters:

• ptr_instance – [in] - Pointer to the SOME/IP SD instance

• ptr_config – [in] - Pointer to the SOME/IP SD configuration

Returns:

Handle of the SOME/IP SD instance information

rs_ret_val_t rs_some_sd_run(rs_handle_t handle, uint32_t u32_run)

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

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

Parameters:

• handle – [in] - Handle of the SOME/IP SD instance.

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

Returns:

Zero for success or negative error code on failure.

rs_ret_val_t rs_someip_sd_register_server_callback(rs_handle_t handle, void *ptr_server_cb)

Set the server callback functions that is to be called from the SD Module.

This function sets the callback functions that is to be called from the SD Module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• ptr_server_cb – [in] - Pointer to the Server callback function

Returns:

0 on success

rs_ret_val_t rs_someip_sd_register_client_callback(rs_handle_t handle, void *ptr_client_cb)

Set the callback functions that is to be called from the SD Module.

This function sets the callback functions that is to be called from the SD Module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• ptr_client_cb – [in] - Pointer to the Client callback function

Returns:

0 on success

rs_ret_val_t rs_someip_sd_register_server_handle(rs_handle_t handle, rs_handle_t server_handle)

Register the server handle to the Service discovery module.

This function register the server handle to the Service discovery module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• server_handle – [in] - Handle to the SOME/IP Server instance information

Returns:

0 on success

rs_ret_val_t rs_someip_sd_register_client_handle(rs_handle_t handle, rs_handle_t client_handle)

Register the client handle to the Service discovery module.

This function register the client handle to the Service discovery module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• client_handle – [in] - Handle to the SOME/IP client instance information

Returns:

0 on success

rs_ret_val_t rs_someip_sd_deregister_server_handle(rs_handle_t handle, rs_handle_t server_handle)

Deregister the server handle to the Service discovery module.

This function deregister the server handle to the Service discovery module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• server_handle – [in] - Handle to the SOME/IP Server instance information

Returns:

0 on success

rs_ret_val_t rs_someip_sd_deregister_client_handle(rs_handle_t handle, rs_handle_t client_handle)

Deregister the client handle to the Service discovery module.

This function deregister the client handle to the Service discovery module

Parameters:

• handle – [in] - Handle to the SOME/IP SD instance information

• client_handle – [in] - Handle to the SOME/IP client instance information

Returns:

0 on success

rs_ret_val_t rs_someip_sd_transmit_msg(rs_handle_t handle, rs_someip_msg_t *ptr_tx_msg)

Called to Transmit the SD message.

This function is called to Transmit the SD message

Parameters:

• sd_handle – [in] - Handle to the SOME/IP SD instance

• ptr_rx_msg – [in] - Pointer to the SD TX message

Returns:

Transmit data length in bytes or Negative value for failure.

rs_ret_val_t rs_someip_sd_process(rs_handle_t handle)

Function to call the SD TX and RX process.

This function called to initiate the SD TX and RX process

Parameters:

handle – [in] - Handle to the SOME/IP SD instance

Returns:

0 for success.

rs_ret_val_t rs_someip_sd_close(rs_handle_t handle)

Called to free the instance from handle.

This function is called to free the SOME/IP SD instance from handle

Parameters:

handle – [in] - Handle to the SOME/IP SD instance

Returns:

0 for success.

struct tag_rs_someip_sd_config

#include <rs_someip_sd.h>

Contains information about SOME/IP SD configuration.

Public Members

uint8_t ip_addr[RS_SOMEIP_IP_ADDR_LEN]

Device IP address.

uint8_t sd_multicast_ip[RS_SOMEIP_IP_ADDR_LEN]

SOME/IP SD Multicast IP address.

uint8_t sd_ip_version

SOME/IP SD IP Version (IPv4/IPv6)

uint16_t sd_port

SOME/IP SD Port number.

struct tag_rs_someip_sd_instance

#include <rs_someip_sd.h>

Contains information about SOME/IP SD instance.

Public Members

rs_someip_sd_config_t *ptr_config

Pointer to containing SD configuration.

rs_udp_instance_t udp_socket_instance

UDP socket instance(Information)

rs_socket_config_t udp_socket_config

UDP socket configuration.

rs_handle_t comm_handle

Handle for communication.

uint8_t state

SOME/IP SD process state.

uint8_t run_state

SOME/IP SD run state.

uint8_t rx_buff[RS_SOMEIP_SD_RX_BUF_MAX_LEN]

Data buffer of RX.

rs_someip_msg_t rx_msg

SOME/IP SD RX Message.

rs_handle_t server_handle[RS_NUM_SOMEIP_SERVER]

SOME/IP Server Handle.

rs_handle_t client_handle[RS_NUM_SOMEIP_CLIENT]

SOME/IP Client Handle.

rs_someip_sd_cb ptr_server_cb

SOME/IP SD handler Server Callback function.

rs_someip_sd_cb ptr_client_cb

SOME/IP SD handler Client Callback function.