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_stop_subscribe_req	To be called to stop the eventgroup subscription for given eventgroup ID.
rs_some_client_process	To be called to call the discovery and notification’s state machine and process respectively.
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	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	Called when response for a service discovery request is received
rcb_some_client_get_service_instance_id_for_eventgrp	Called to get service ID and Instance ID for given eventgroup ID.
rcb_some_client_get_eventgrps	Called to get eventgroup ID for given service ID and Instance ID.
rcb_some_client_get_instance_evengrp_id	Called to get service ID,Instance ID,eventgroup ID for given event ID.
rcb_some_client_get_event_group_for_subscription	Called to get eventgroup ID for subscription from user.
rcb_some_client_get_event_info	Called to get event information for given event ID.

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. 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 SOME/IP stack function.
Periodically call the discovery and notification 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_req call
When the response from server is received, rcb_some_client_notification_resp 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.

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.

Typedefs

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, uint16_t *ptr_service_id, uint16_t *ptr_instance_id, uint8_t 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_service_id – [in] - Pointer to service ID array.
ptr_instance_id – [in] - Pointer to instance ID array.
num_entry – [in] - Number of elements in array.

Returns:

Return Number of bytes sent.

rs_ret_val_t rs_some_client_stop_subscribe_req(rs_handle_t handle, uint16_t u16_service_id, uint16_t u16_instance_id, uint16_t u16_eventgrp_id)

Frame and send stop subscribe eventgroup request for subscribed eventgroups.

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

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
u16_service_id – [in] - Service ID of eventgroup to unsubscribe.
u16_instance_id – [in] - Instance ID of eventgroup to unsubscribe.
u16_eventgrp_id – [in] - Eventgroup ID to unsubscribe.

Returns:

Return 0 if success or negative value if failure

rs_ret_val_t rs_some_client_send_req(rs_handle_t handle, uint16_t u16_service_id, uint16_t u16_method_id, uint16_t u16_event_id, uint8_t *ptr_data, uint32_t data_len)

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.
u16_service_id – [in] - Service ID of event ID or Method ID to request.
u16_method_id – [in] - Method ID of function or call to request.
u16_event_id – [in] - Event ID to request.
ptr_data – [in] - Pointer to payload data.
data_len – [in] - Data length.

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_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 client instance structure.
ptr_subscribe_info – [in] - Pointer to subscription structure.
u32_num_subscription – [in] - Max number of subscription.

Returns:

Return 0 if success or -1 if failure.

rs_ret_val_t rcb_some_client_notification_resp_err_handler(rs_handle_t handle, uint16_t u16_srv_id, uint16_t u16_id, uint8_t u8_err_code, uint8_t u8_proc_type)

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.
u16_srv_id – [in] - Service ID of events or response received.
u16_id – [in] - Method ID or Event ID of response.
u8_err_code – [in] - Error code received on response.
u8_proc_type – [in] - Process type (Discovery or Notification)

Returns:

Return 0 on success.

rs_ret_val_t rcb_some_client_notification_resp(rs_handle_t handle, uint16_t u16_srv_id, uint16_t u16_id, uint8_t *ptr_payload_data, uint32_t payload_len, uint8_t u8_proc_type)

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.
u16_srv_id – [in] - Service ID of events or response received.
u16_id – [in] - Method ID or Event ID of response.
ptr_payload_data – [in] - Pointer to response payload data.
payload_len – [in] - Payload length.
u8_proc_type – [in] - Process type (Discovery or Notification)

Returns:

Return 0 on success or negative number on failure.

rs_ret_val_t rcb_some_client_subscription_resp(rs_handle_t handle, uint16_t u16_service_id, uint16_t u16_instance_id, uint16_t u16_eventgrp_id, uint8_t u8_msg_type, uint8_t u8_proc_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.
u16_service_id – [in] - Service ID of eventgroup.
u16_instance_id – [in] - Instance ID of eventgroup.
u16_eventgrp_id – [in] - Eventgroup ID.
u8_msg_type – [in] - Received message type.
u8_proc_type – [in] - Process type (Discovery or Notification)

Returns:

Return 0 on success.

rs_ret_val_t rcb_some_client_get_service_instance_id_for_eventgrp(rs_handle_t handle, uint16_t *ptr_eventgrp_id, uint16_t *ptr_srv_id, uint16_t *ptr_insta_id, uint32_t num_eventgrp)

Called to get service ID and Instance ID for given eventgroup ID.

This function called to get service ID and Instance ID for given eventgroup ID.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_eventgrp_id – [in] - Pointer to the eventgroup ID array.
ptr_srv_id – [out] - Pointer to the service ID array.
ptr_insta_id – [out] - Pointer to the instance ID array.
num_eventgrp – [in] - Number of element in eventgroup array.

Returns:

Return Number of element in service and instance ID array.

rs_ret_val_t rcb_some_client_get_eventgrps(rs_handle_t handle, uint16_t *ptr_data, uint16_t *ptr_srv_id, uint16_t *ptr_insta_id, uint32_t u32_num_entry)

Called to get eventgroup ID for given service ID and Instance ID.

This function called to get eventgroup ID for given service ID and Instance ID.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_data – [out] - Pointer to the eventgroup ID array.
ptr_srv_id – [in] - Pointer to the service ID array.
ptr_insta_id – [in] - Pointer to the instance ID array.
u32_num_entry – [in] - Number of element in service ID and instance ID array.

Returns:

Return Number of element in Eventgroup ID array.

rs_ret_val_t rcb_some_client_get_instance_evengrp_id(rs_handle_t handle, uint16_t u16_event_id, uint16_t *ptr_srv_id, uint16_t *ptr_insta_id, uint16_t *ptr_eventgrp_id)

rs_ret_val_t rcb_some_client_get_event_group_for_subscription(rs_handle_t handle, uint16_t *ptr_resp_data, uint16_t *ptr_srv_id, uint16_t *ptr_insta_id, uint32_t u32_num_entry)

Called to get eventgroup ID for subscription from user.

This function called to get eventgroup ID for subscription from user.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information.
ptr_resp_data – [out] - Pointer to the Eventgroup ID array.
ptr_srv_id – [in] - Pointer to the service ID array.
ptr_insta_id – [in] - Pointer to the instance ID array.
u32_num_entry – [in] - Number of elements in array.

Returns:

Return number of elements in eventgroup array.

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_someip_events_t *rcb_some_client_get_event_info(rs_handle_t handle, uint16_t u16_event_id)

Called to get the event ID information.

This function called to get the event ID information.

Parameters:

handle – [in] - Handle of the SOME/IP client instance information
u16_event_id – [in] - Event ID.

Returns:

return pointer to a SOME/IP events buffer if available or NULL

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.

struct tag_rs_someip_client_config

#include <rs_someip_client.h>

Contains information about SOME/IP client configuration.

Public Members

uint8_t sd_addr[RS_IP_ADDR_LEN]: Initial IP Address for SOME/IP discovery process.

uint16_t sd_port: SD Port number for UDP IP.

uint8_t sn_addr[RS_IP_ADDR_LEN]: Initial IP Address for SOME/IP notification process.

uint16_t sn_cli_port: SN client’s Port number for UDP IP.

uint16_t sn_srv_port: SN server’s Port number for UDP IP.

uint8_t protocol_ver: SOME/IP protocol version.

uint8_t interface_ver: SOME/IP interface version.

uint16_t client_id: SOME/IP Client ID.

uint8_t major_ver: SOME/IP major version.

uint8_t minor_ver: SOME/IP minor version.

uint8_t broadcast_addr[RS_IP_ADDR_LEN]: Broadcast IP address.

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

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_process_info_t notify_process_info: SOME/IP client notification process information.

rs_someip_process_info_t discov_process_info: SOME/IP client discovery process information.

uint32_t number_of_subscribe: number of service subscribed

rs_someip_subscribe_info_t *ptr_subscribe_details: Pointer to subscribe structure information.

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

uint32_t number_of_services: Number of services.