C Radio APIs

Data Structures
struct	trusted_ue_info_t
struct	tx_pool_id_info_t
struct	v2x_iface_capabilities_t
struct	v2x_tx_bandwidth_reservation_t
struct	v2x_chan_meas_params_t
struct	v2x_chan_measurements_t
struct	v2x_radio_calls_t
struct	v2x_sps_mac_details_t
struct	v2x_per_sps_reservation_calls_t
struct	v2x_tx_flow_info_t
struct	v2x_sock_info_t
struct	v2x_sid_list_t
struct	v2x_tx_sps_flow_info_t
struct	socket_info_t

Macros
#define	V2X_RADIO_HANDLE_BAD   (-1)
#define	V2X_MAX_RADIO_SESSIONS   (10)
#define	V2X_RX_WILDCARD_PORTNUM   (9000)
#define	MAX_POOL_IDS_LIST_LEN   (20)
#define	MAX_MALICIOUS_IDS_LIST_LEN   (50)
#define	MAX_TRUSTED_IDS_LIST_LEN   (50)
#define	MAX_SUBSCRIBE_SIDS_LIST_LEN   (10)

Typedefs
typedef int	v2x_radio_handle_t
typedef traffic_ip_type_t	traffic_ip_type

Enumerations
enum	v2x_concurrency_sel_t { V2X_WWAN_NONCONCURRENT = 0, V2X_WWAN_CONCURRENT = 1 }
enum	v2x_event_t {   V2X_INACTIVE = 0, V2X_ACTIVE, V2X_TX_SUSPENDED, V2X_RX_SUSPENDED,   V2X_TXRX_SUSPENDED }
enum	v2x_priority_et {   V2X_PRIO_MOST_URGENT = 0, V2X_PRIO_1 = 1, V2X_PRIO_2 = 2, V2X_PRIO_3 = 3,   V2X_PRIO_4 = 4, V2X_PRIO_5 = 5, V2X_PRIO_6 = 6, V2X_PRIO_BACKGROUND = 7 }
enum	v2x_service_status_t { SERVICE_UNAVAILABLE = 0, SERVICE_AVAILABLE = 1 }
enum	v2x_auto_retransmit_policy_t { V2X_AUTO_RETRANSMIT_DISABLED = 0, V2X_AUTO_RETRANSMIT_ENABLED = 1, V2X_AUTO_RETRANSMIT_DONT_CARE = 2 }
enum	traffic_ip_type_t { TRAFFIC_IP = 0, TRAFFIC_NON_IP = 1 }

Functions
uint16_t	v2x_convert_priority_to_traffic_class (v2x_priority_et priority)
v2x_priority_et	v2x_convert_traffic_class_to_priority (uint16_t traffic_class)
v2x_api_ver_t	v2x_radio_api_version ()
v2x_status_enum_type	v2x_radio_query_parameters (const char *iface_name, v2x_iface_capabilities_t *caps)
v2x_status_enum_type	v2x_radio_deinit (v2x_radio_handle_t handle)
int	v2x_radio_rx_sock_create_and_bind (v2x_radio_handle_t handle, int *sock, struct sockaddr_in6 *rx_sockaddr)
int	v2x_radio_rx_sock_create_and_bind_v2 (v2x_radio_handle_t handle, int id_ist_len, uint32_t *id_list, int *sock, struct sockaddr_in6 *rx_sockaddr)
int	v2x_radio_rx_sock_create_and_bind_v3 (v2x_radio_handle_t handle, uint16_t port_num, int id_ist_len, uint32_t *id_list, int *sock, struct sockaddr_in6 *rx_sockaddr)
int	v2x_radio_sock_create_and_bind (v2x_radio_handle_t handle, v2x_tx_sps_flow_info_t *tx_flow_info, v2x_per_sps_reservation_calls_t *calls, int tx_sps_portnum, int tx_event_portnum, int rx_portnum, v2x_sid_list_t *rx_id_list, v2x_sock_info_t *tx_sps_sock, v2x_sock_info_t *tx_event_sock, v2x_sock_info_t *rx_sock)
int	v2x_radio_tx_sps_sock_create_and_bind (v2x_radio_handle_t handle, v2x_tx_bandwidth_reservation_t *res, v2x_per_sps_reservation_calls_t *calls, int sps_portnum, int event_portnum, int *sps_sock, struct sockaddr_in6 *sps_sockaddr, int *event_sock, struct sockaddr_in6 *event_sockaddr)
int	v2x_radio_tx_sps_only_create (v2x_radio_handle_t handle, v2x_tx_bandwidth_reservation_t *res, v2x_per_sps_reservation_calls_t *calls, int sps_portnum, int *sps_sock, struct sockaddr_in6 *sps_sockaddr)
v2x_status_enum_type	v2x_radio_tx_reservation_change (int *sps_sock, v2x_tx_bandwidth_reservation_t *updated_reservation)
int	v2x_radio_tx_event_sock_create_and_bind (const char *interface, int v2x_id, int event_portnum, struct sockaddr_in6 *event_sock_addr, int *sock)
v2x_status_enum_type	v2x_radio_start_measurements (v2x_radio_handle_t handle, v2x_chan_meas_params_t *measure_this_way)
v2x_status_enum_type	v2x_radio_stop_measurements (v2x_radio_handle_t handle)
int	v2x_radio_sock_close (int *sock_fd)
void	v2x_radio_set_log_level (int new_level, int use_syslog)
v2x_event_t	cv2x_status_poll (uint64_t *status_age_useconds)
int	v2x_radio_trigger_l2_update (v2x_radio_handle_t handle)
int	v2x_radio_update_trusted_ue_list (unsigned int malicious_list_len, unsigned int malicious_list[MAX_MALICIOUS_IDS_LIST_LEN], unsigned int trusted_list_len, trusted_ue_info_t trusted_list[MAX_TRUSTED_IDS_LIST_LEN])
int	v2x_radio_tx_sps_sock_create_and_bind_v2 (v2x_radio_handle_t handle, v2x_tx_sps_flow_info_t *sps_flow_info, v2x_per_sps_reservation_calls_t *calls, int sps_portnum, int event_portnum, int *sps_sock, struct sockaddr_in6 *sps_sockaddr, int *event_sock, struct sockaddr_in6 *event_sockaddr)
int	v2x_radio_tx_sps_only_create_v2 (v2x_radio_handle_t handle, v2x_tx_sps_flow_info_t *sps_flow_info, v2x_per_sps_reservation_calls_t *calls, int sps_portnum, int *sps_sock, struct sockaddr_in6 *sps_sockaddr)
v2x_status_enum_type	v2x_radio_tx_reservation_change_v2 (int *sps_sock, v2x_tx_sps_flow_info_t *updated_flow_info)
v2x_status_enum_type	v2x_radio_tx_event_flow_info_change (int *sock, v2x_tx_flow_info_t *updated_flow_info)
v2x_status_enum_type	start_v2x_mode ()
v2x_status_enum_type	stop_v2x_mode ()
v2x_radio_handle_t	v2x_radio_init_v2 (traffic_ip_type_t ip_type, v2x_concurrency_sel_t mode, v2x_radio_calls_t *callbacks_p, void *ctx_p)
int	v2x_radio_tx_event_sock_create_and_bind_v3 (traffic_ip_type_t ip_type, int v2x_id, int event_portnum, v2x_tx_flow_info_t *event_flow_info, struct sockaddr_in6 *event_sockaddr, int *sock)
v2x_status_enum_type	get_iface_name (traffic_ip_type_t ip_type, char *iface_name, size_t buffer_len)
int	v2x_radio_tcp_sock_create_and_bind (v2x_radio_handle_t handle, const v2x_tx_flow_info_t *event_info, const socket_info_t *sock_info, int *sock_fd, struct sockaddr_in6 *sockaddr)

Detailed Description

This section contains C Radio APIs related to Cellular-V2X operation. For any new CV2x development, it is recommended to use the C++ telux::cv2x::* APIs

Abstraction of the radio driver parameters for a V2X broadcast socket interface, including 3GPP CV2X QoS bandwidth contracts.

---

Data Structure Documentation

struct trusted_ue_info_t

Contains time confidence, position confidence, and propagation delay for a trusted UE.

Data Fields
uint32_t	source_l2_id	L2 ID of the trusted source
float	time_uncertainty	Time uncertainty in milliseconds.
uint16_t	time_confidence_level	Deprecated. Use time_uncertainty instead. Confidence level of the time period. Supported values: 0 through 127, where 0 is invalid or unavailable and 127 is the most confident
uint16_t	position_confidence_level	Confidence level of the position. Supported values: 0 through 127, where 0 is invalid or unavailable and 127 is the most confident
uint32_t	propagation_delay	Propagation delay in microseconds.

struct tx_pool_id_info_t

Contains minimum and maximum frequencies for a Tx pool ID. This struct is used in v2x_iface_capabilities_t.

Data Fields
uint8_t	pool_id	ID of the Tx pool.
uint16_t	min_freq	Minimum frequency in MHz.
uint16_t	max_freq	Maximum frequency in MHz.

struct v2x_iface_capabilities_t

Contains information on the capabilities of a Radio interface.

Data Fields
int	link_ip_MTU_bytes	Maximum data payload length (in bytes) of a packet supported by the IP Radio interface.
int	link_non_ip_MTU_bytes	Maximum data payload length (in bytes) of a packet supported by the non-IP Radio interface.
v2x_concurrency_sel_t	max_supported_concurrency	Indicates whether this interface supports concurrent WWAN with V2X (PC5).
uint16_t	non_ip_tx_payload_offset_bytes	Byte offset in a non-IP Tx packet before the actual payload begins. In 3GPP CV2X, the first byte after the offset is the 1-byte V2X Family ID. This offset is to the left for a per-packet Tx header that includes Tx information that might be inserted in front of the packet payload (in subsequent releases). An example of Tx information is MAC/Phy parameters (power, rate, retransmissions policy, and so on). Currently, this value is expected to be 0. But it is reserved to support possible per-packet Tx/Rx headers that might be added in future releases of this API.
uint16_t	non_ip_rx_payload_offset_bytes	Byte offset in a non-IP Rx packet before the actual payload begins. Initially, this value is zero. But it allows for later insertion of per-packet Rx information (sometimes called metadata) to be added to the front of the data payload. An example of Rx information is MAC/Phy measurements (receive signal strength, timestamps, and so on). The V2X Family ID is considered as part of the payload in the 3GPP CV2X. Higher layers (applications that are clients to this API) must remove or advance past that 1 byte to get to the more familiar actual WSMP/Geonetworking payload.
uint16_t	int_min_periodicity_multiplier_ms	Lowest number of milliseconds requested for a bandwidth. This value is also the basis for all possible bandwidth reservation periods. For example, if this multiplier=100 ms, applications can only reserve bandwidths of 100 ms, 200 ms, up to 1000 ms.
uint16_t	int_maximum_periodicity_ms	Least frequent bandwidth periodicity that is supported. Above this value, use event-driven periodic messages of a period larger than this value.
unsigned	supports_10ms_periodicity: 1	Indicates whether n*10 ms periodicities are supported. Supported values: 0 – Not supported 1 – Supported
unsigned	supports_20ms_periodicity: 1	Indicates whether an n*20 ms bandwidth reservation is supported. Supported values: 0 – Not supported 1 – Supported
unsigned	supports_50ms_periodicity: 1	Indicates whether 50 ms periodicity is supported. Supported values: 0 – Not supported 1 – Supported
unsigned	supports_100ms_periodicity: 1	Indicates whether the basic minimum periodicity of 100 ms is supported. Supported values: 0 – Not supported 1 – Supported
unsigned	max_quantity_of_auto_retrans: 4	Maximum number automatic retransmissions. Supported values: 0 through 15
unsigned	size_of_layer2_mac_address: 4	Size of the L2 MAC address. Different Radio Access Technologies have different-sized L2 MAC addresses: 802.11 has 6 bytes, whereas 3GPP PC5 has only 3 bytes. Because a randomized MAC address comes from an HSM with good pseudo random entropy, higher layers must know how many bytes of the MAC address to generate.
uint16_t	v2x_number_of_priority_levels	Number of different priority levels supported. For example, 8 is the current 3GPP standard (where a lower number means a higher priority).
uint16_t	highest_priority_value	Least urgent priority number supported by this radio. Higher numbers are lower priority, so if the full range is supported, this value is V2X_PRIO_BACKGROUND.
uint16_t	lowest_priority_value	Highest priority value (most urgent traffic). Lower numbers are higher priority, so if the highest level supported this value is V2X_PRIO_MOST_URGENT.
uint16_t	max_qty_SPS_flows	Maximum number of supported SPS reservations.
uint16_t	max_qty_non_SPS_flows	Maximum number of supported event flows (non-SPS ports).
int32_t	max_tx_pwr	Maximum supported transmission power in dBm.
int32_t	min_tx_pwr	Minimum supported transmission power in dBm.
uint32_t	tx_pool_ids_supported_len	Length of the tx_pool_ids_supported array.
tx_pool_id_info_t	tx_pool_ids_supported[MAX_POOL_IDS_LIST_LEN]	Array of Tx pool IDs and their associated minimum and maximum frequencies.

struct v2x_tx_bandwidth_reservation_t

Used when requesting a QoS bandwidth contract, which is implemented in PC5 3GPP V2-X radio as a Semi Persistent Flow (SPS).

The underlying radio providing the interface might support periodicities of various granularity in 100 ms integer multiples (such as 200 ms, 300 ms, and 400 ms).

The reservation is also used internally as a handle.

Data Fields
int	v2xid	Variable length 4-byte PSID or ITS_AID, or another application ID.
v2x_priority_et	priority	Specifies one of the 3GPP levels of priority for the traffic that is pre-reserved on the SPS flow. Use v2x_radio_query_parameters() to get the exact number of supported priority levels.
int	period_interval_ms	Bandwidth-reserved periodicity interval in milliseconds. There are limits on which intervals the underlying radio supports. Use the capabilities query method to discover the int_min_periodicity_multiplier_ms and int_maximum_periodicity_ms supported intervals.
int	tx_reservation_size_bytes	Number of Tx bandwidth bytes that are sent every periodicity interval.

struct v2x_chan_meas_params_t

Contains the measurement parameters for configuring the MAC/Phy radio channel measurements (such as CBR utilization).

The radio chip contains requests on radio measurement parameters that API clients can use to specify the following:

• How their higher-level application requires the CBR/CBP to be measured
• Over which time window
• When to send a report

Data Fields
int	channel_measurement_interval_us	Duration in microseconds of the sliding window size.
int	rs_threshold_decidbm	Parameter to the radio CBR measurement that is used for determining how busy the channel is. Signals weaker than the specified receive strength (RSRP, or RSSI) are not considered to be in use (busy).

struct v2x_chan_measurements_t

Periodically returned by the radio with all measurements about the radio channel, such as the amount of noise and bandwidth saturation (channel_busy_percentage, or CBR).

Data Fields
float	channel_busy_percentage	No measurement parameters are supplied.
float	noise_floor	Measurement of the background noise for a quiet channel.
float	time_uncertainty	V2X time uncertainty in milliseconds.

struct v2x_radio_calls_t

Contains callback functions used in a v2x_radio_init() and v2x_radio_init_v2 call.

The radio interface uses these callback functions for events such as completion of initialization, a Layer-02 MAC address change, or a status event (loss of sufficient GPS time precision to transmit).

These callbacks are related to a specific radio interface, and its MAC/Phy parameters, such as transmit power, bandwidth utilization, and changes in radio status.

Data Fields
void(*	v2x_radio_init_complete )(v2x_status_enum_type status, void *context)
void(*	v2x_radio_status_listener )(v2x_event_t event, void *context)
void(*	v2x_radio_chan_meas_listener )(v2x_chan_measurements_t *measurements, void *context)
void(*	v2x_radio_l2_addr_changed_listener )(int new_l2_address, void *context)
void(*	v2x_radio_macphy_change_complete_cb )(void *context)
void(*	v2x_radio_capabilities_listener )(v2x_iface_capabilities_t *caps, void *context)
void(*	v2x_service_status_listener )(v2x_service_status_t status, void *context)

Field Documentation

void(* v2x_radio_calls_t::v2x_radio_init_complete) (v2x_status_enum_type status, void *context)

Callback that indicates initialization is complete.

Associated data types

v2x_status_enum_type

Parameters

[in]	status	Updated current radio status that indicates whether transmit and receive are ready.
[in]	context	Pointer to the context that was supplied during initial registration.

void(* v2x_radio_calls_t::v2x_radio_status_listener) (v2x_event_t event, void *context)

Callback made when the status in the radio changes. For example, in response to a fault when there is a loss of GPS timing accuracy.

Associated data types

v2x_event_t

Parameters

[in]	event	Delivery of the event that just occurred, such losing the ability to transmit.
[in]	context	Pointer to the context of the caller who originally registered for this callback.

void(* v2x_radio_calls_t::v2x_radio_chan_meas_listener) (v2x_chan_measurements_t *measurements, void *context)

Callback made from lower layers when periodic radio measurements are prepared.

Associated data types

v2x_chan_measurements_t

Parameters

[in]	measurements	Pointer to the periodic measurements.
[in]	context	Pointer to the context of the caller who originally registered for this callback.

void(* v2x_radio_calls_t::v2x_radio_l2_addr_changed_listener) (int new_l2_address, void *context)

Callback made by the platform SDK when the MAC address (L2 SRC address) changes.

Parameters

[in]	new_l2_address	New L2 source address as an integer (because the L2 address is 3 bytes).
[in]	context	Pointer to the context of the caller who originally registered for this callback.

void(* v2x_radio_calls_t::v2x_radio_macphy_change_complete_cb) (void *context)

Callback made to indicate that the requested radio MAC/Phy change (such as channel/frequency and power) has completed.

Parameters

[in]

context

Pointer to the context of the caller who originally registered for this callback.

void(* v2x_radio_calls_t::v2x_radio_capabilities_listener) (v2x_iface_capabilities_t *caps, void *context)

Callback made when V2X capabilities change.

Associated data types

v2x_iface_capabilities_t

Parameters

[in]	caps	Pointer to the capabilities of this interface.
[in]	context	Pointer to the context of the caller who originally registered for this callback.

void(* v2x_radio_calls_t::v2x_service_status_listener) (v2x_service_status_t status, void *context)

Callback made when the service status changes.

Associated data types

v2x_service_status_t

Parameters

[in]	status	Service status.
[in]	context	Pointer to the context of the caller who originally registered for this callback.

struct v2x_sps_mac_details_t

Contains MAC information that is reported from the actual MAC SPS in the radio. The offsets can periodically change on any given transmission report.

Data Fields
uint32_t	periodicity_in_use_ns	Actual transmission interval period (in nanoseconds) scheduled relative to 1PP 0:00.00 time.
uint16_t	currently_reserved_periodic_bytes	Actual number of bytes currently reserved at the MAC layer. This number can be slightly larger than original request.
uint32_t	tx_reservation_offset_ns	Actual offset, from a 1PPS pulse and Tx flow periodicity, that the MAC selected and is using for the transmit reservation. If data goes to the radio with enough time, it can be transmitted on the medium in the next immediately scheduled slot.
uint64_t	utc_time_ns	Absolute UTC start time of next selected grant, in nanoseconds.

struct v2x_per_sps_reservation_calls_t

Callback functions used in v2x_radio_tx_sps_sock_create_and_bind() calls.

Data Fields
void(*	v2x_radio_l2_reservation_change_complete_cb )(void *context, v2x_sps_mac_details_t *details)
void(*	v2x_radio_sps_offset_changed )(void *context, v2x_sps_mac_details_t *details)

Field Documentation

void(* v2x_per_sps_reservation_calls_t::v2x_radio_l2_reservation_change_complete_cb) (void *context, v2x_sps_mac_details_t *details)

Callback made upon completion of a reservation change that a v2x_radio_tx_reservation_change() call initiated for a MAC/Phy contention.

The current SPS offset and reservation parameter are passed in the details structure returned by the pointer details.

Associated data types

v2x_sps_mac_details_t

Parameters

[in]	context	Pointer to the application context.
[in]	details	Pointer to the MAC information.

void(* v2x_per_sps_reservation_calls_t::v2x_radio_sps_offset_changed) (void *context, v2x_sps_mac_details_t *details)

Callback periodically made when the MAC SPS timeslot changes. The new reservation offset is in the details structure returned by pointer details.

Associated data types

v2x_sps_mac_details_t

Parameters

[in]	measurements	Pointer to the channel measurements.
[in]	context	Pointer to the context.

Detailed description

This callback can occur when a MAC contention triggers a new reservation time slot to be selected. It is relevant only to connections opened with v2x_radio_tx_sps_sock_create_and_bind().

struct v2x_tx_flow_info_t

Advanced parameters that can be specified for Tx SPS and event-driven flows.

Data Fields
v2x_auto_retransmit_policy_t	retransmit_policy	V2X retransmit policy.
uint8_t	default_tx_power_valid	Indicates whether the default Tx power is specified. Supported values: 0 – Default power is not specified 1 – Default power is specified and is valid
int32_t	default_tx_power	Default power used for transmission.
uint8_t	mcs_index_valid	Indicates whether the MCS index is specified. Supported values: 0 – Index is not specified 1 – Index is specified and is valid
uint8_t	mcs_index	MCS index number
uint8_t	tx_pool_id_valid	Indicates whether the Tx pool ID is valid. Supported values: 0 – ID is not specified 1 – ID is specified and is valid
uint8_t	tx_pool_id	ID of the Tx pool.

struct v2x_sock_info_t

Parameters to identify a Tx or Rx socket.

Data Fields
int	sock	Pointer to the file descriptor for the socket.
struct sockaddr_in6	sockaddr	IPv6 socket address. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function.

struct v2x_sid_list_t

Parameters to identify a service ID list.

Data Fields
int	length	number of services IDs included in the array of sid.
uint32_t	sid[MAX_SUBSCRIBE_SIDS_LIST_LEN]	array of service IDs.

struct v2x_tx_sps_flow_info_t

Advanced parameters that can be specified for Tx SPS flows.

Data Fields
v2x_tx_bandwidth_reservation_t	reservation	Transmit reservation information.
v2x_tx_flow_info_t	flow_info	Transmit resource information about the SPS Tx flow.

struct socket_info_t

Parameters that can be specified for the creation of CV2X socket.

Data Fields
uint32_t	service_id	V2X service ID bound to the CV2X socket.
uint16_t	local_port	Local port number of the CV2X socket used for binding.

Macro Definition Documentation

#define V2X_RADIO_HANDLE_BAD   (-1)

Invalid handle returned by v2x_radio_init() and v2x_radio_init_v2() upon an error.

#define V2X_MAX_RADIO_SESSIONS   (10)

Limit on the number of simultaneous RmNet Radio interfaces this library can have open at once.

Typically, there are only a few actual radios. On the same radio however, one interface can be for IP traffic, and another interface can be for non-IP traffic.

#define V2X_RX_WILDCARD_PORTNUM   (9000)

Wildcard value for a port number. When the wildcard is used, all V2X received traffic is routed.

#define MAX_POOL_IDS_LIST_LEN   (20)

Maximum length of the pool ID list that is returned in v2x_iface_capabilities_t.

#define MAX_MALICIOUS_IDS_LIST_LEN   (50)

Maximum length of the malicious ID list that can be passed in v2x_radio_update_trusted_ue_list().

#define MAX_TRUSTED_IDS_LIST_LEN   (50)

Maximum length of the trusted ID list that can be passed in v2x_radio_update_trusted_ue_list().

#define MAX_SUBSCRIBE_SIDS_LIST_LEN   (10)

Maximum length for the subscribed service ID list that can be passed in v2x_radio_rx_sock_create_and_bind_v2().

Typedef Documentation

typedef int v2x_radio_handle_t

Radio data handle to the interface.

typedef traffic_ip_type_t traffic_ip_type

Enumeration Type Documentation

enum v2x_concurrency_sel_t

Describes whether the radio chip modem should attempt or support concurrent 3GPP CV2X operation with a WWAN 4G/5G data call.

Some chips are only capable of operating on CV2X. In this case:

• The callers can only request V2X_WWAN_NONCONCURRENT.
• The interface parameters that are returned list v2x_concurrency_sel_t as the value for V2X_WAN_NONCONCURRENT.

Enumerator
V2X_WWAN_NONCONCURRENT	No simultaneous WWAN + CV2X on this interface.
V2X_WWAN_CONCURRENT	Interface allows requests for concurrent support of WWAN + CV2X connections.

enum v2x_event_t

Event indications sent asynchronously from the radio via callbacks that indicate the state of the radio. The state can change in response to the loss of timing precision or a geofencing change.

Enumerator
V2X_INACTIVE	V2X communication is disabled.
V2X_ACTIVE	V2X communication is enabled. Transmit and receive are possible.
V2X_TX_SUSPENDED	Small loss of timing precision occurred. Transmit is no longer supported.
V2X_RX_SUSPENDED	Radio can no longer receive any messages.
V2X_TXRX_SUSPENDED	Radio can no longer transmit or receive for some reason.

enum v2x_priority_et

Range of supported priority levels, where a lower number means a higher priority. For example, 8 is the current 3GPP standard.

Enumerator
V2X_PRIO_MOST_URGENT	Highest priority.
V2X_PRIO_1
V2X_PRIO_2
V2X_PRIO_3
V2X_PRIO_4
V2X_PRIO_5
V2X_PRIO_6
V2X_PRIO_BACKGROUND	Lowest priority.

enum v2x_service_status_t

Valid service availability states.

Enumerator
SERVICE_UNAVAILABLE
SERVICE_AVAILABLE

enum v2x_auto_retransmit_policy_t

V2X Tx retransmission policies supported by the modem.

Enumerator
V2X_AUTO_RETRANSMIT_DISABLED	Retransmit mode is disabled.
V2X_AUTO_RETRANSMIT_ENABLED	Retransmit mode is enabled.
V2X_AUTO_RETRANSMIT_DONT_CARE	Modem falls back to its default behavior.

enum traffic_ip_type_t

V2X Ip Types

Enumerator
TRAFFIC_IP	Use Ip type traffic.
TRAFFIC_NON_IP	Use Non-Ip type traffic.

Function Documentation

uint16_t v2x_convert_priority_to_traffic_class

(

v2x_priority_et

priority

)

Converts a traffic priority to one of the 255 IPv6 traffic class bytes that are used in the data plane to indicate per-packet priority on non-SPS (event driven) data ports.

Associated data types

v2x_priority_et

Parameters

[in]

priority

Packet priority that is to be converted to an IPv6 traffic class. This priority is between the lowest and highest priority values returned in v2x_iface_capabilities_t.

Detailed description

This function is symmetric and is a reverse operation.

The traffic priority is one of the values between min_priority_value and max_priority_value returned in the v2x_iface_capabilities_t query.

Returns

IPv6 traffic class for achieving the calling input parameter priority level.

v2x_priority_et v2x_convert_traffic_class_to_priority

(

uint16_t

traffic_class

)

Maps an IPv6 traffic class to a V2X priority value.

Parameters

[in]

traffic_class

IPv6 traffic classification that came in a packet from the radio.

Detailed description

This function is the inverse of the v2x_convert_priority_to_traffic_class() function. It is symmetric and is a reverse operation.

Returns

Priority level (between highest and lowest priority values) equivalent to the input IPv6 traffic class parameter.

v2x_api_ver_t v2x_radio_api_version

(

)

Method used to query the platform SDK for its version number, build information, and build date.

Returns

v2x_api_ver_t – Contains the build date and API version number.

v2x_status_enum_type v2x_radio_query_parameters	(	const char *	iface_name,
		v2x_iface_capabilities_t *	caps
	)

Gets the capabilities of a specific Radio interface attached to the system.

Associated data types

v2x_iface_capabilities_t

Parameters

[in]	iface_name	Pointer to the Radio interface name. The Radio interface is one of the following: An RmNet interface (HLOS) The interface supplied for IP communication The interface for non-IP communication (such as WSMP and Geonetworking).
[out]	caps	Pointer to the v2x_iface_capabilities_t structure, which contains the capabilities of this specific interface.

Returns

V2X_STATUS_SUCCESS – The radio is ready for data-plane sockets to be created and bound.

Error code – If there is a problem (see v2x_status_enum_type).

v2x_status_enum_type v2x_radio_deinit

(

v2x_radio_handle_t

handle

)

De-initializes a specific Radio interface.

Associated data types

v2x_radio_handle_t

Parameters

[in]

handle

Handle to the Radio that was initialized.

Returns

Indication of success or failure (see v2x_status_enum_type).

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

int v2x_radio_rx_sock_create_and_bind	(	v2x_radio_handle_t	handle,
		int *	sock,
		struct sockaddr_in6 *	rx_sockaddr
	)

Opens a new V2X radio receive socket, and initializes the given sockaddr buffer. The socket is also bound as an AF_INET6 UDP type socket.

Associated data types

v2x_radio_handle_t

Parameters

[in]	handle	Identifies the initialized Radio interface.
[out]	sock	Pointer to the socket that, on success, returns the socket descriptor. The caller must release this socket with v2x_radio_sock_close().
[out]	rx_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind.

Detailed description

You can execute any sockopts that are appropriate for this type of socket (AF_INET6).

The port number for the receive path is not exposed, but it is in the sockaddr_ll structure (if the caller is interested).

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

int v2x_radio_rx_sock_create_and_bind_v2	(	v2x_radio_handle_t	handle,
		int	id_ist_len,
		uint32_t *	id_list,
		int *	sock,
		struct sockaddr_in6 *	rx_sockaddr
	)

Opens a new V2X radio receive socket with specific service IDs for subscription, and initializes the given sockaddr buffer. The socket is also bound as an AF_INET6 UDP type socket.

Associated data types

v2x_radio_handle_t

Parameters

[in]	handle	Identifies the initialized Radio interface.
[in]	id_ist_len	Identifies the length of service ID list.
[in]	id_list	Pointer to the service ID list for subscription, subscribe wildcard if input nullptr.
[out]	sock	Pointer to the socket that, on success, returns the socket descriptor. The caller must release this socket with v2x_radio_sock_close().
[out]	rx_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind.

Detailed description

You can execute any sockopts that are appropriate for this type of socket (AF_INET6).

This API can be used to subscribe wildcard, catchall port, or specifc service IDs. The Rx port should be set with v2x_set_rx_port() before any subscription via this API, otherwise a default port number will be used.

Wildcard is used to receive all traffic. Only one port can be registered as wildcard port. Once wildcard is registered successfully, all received packets will be directed to wildcard port, and any subscription for specific service IDs or catchall port at other ports will be invalid. The parameter id_list of this API should be set to a null list for wildcard subscription.

Catchall port is used to receive packets with non-registered service IDs (via specific service IDs subscription). Only one port can be registered as catchall port. If catchall port is registered successfully, received packets with non-registered service ID will be directed to catchall port. All specific service IDs subscription (if any) should be performed before catchall port subscription. The parameter id_list of this API should include all non-registered service IDs for catchall port subscription.

Any port different from catchall port can be used to receive packets with specific service IDs. Only one port can be registered for a single service ID, a list of service IDs can be registered at a single port. To subscribe specific service IDs at a given Rx port, a Tx flow must be pre-setup with the Tx service ID set to any service ID included in the list of specific service IDs and the Tx source port set to the same port number as Rx port. The parameter id_list of this API should include all interested service IDs for the given Rx port.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init(). The handle from that function must be used as the parameter in this function. The Rx port must be pre-set with v2x_set_rx_port(), otherwise a default port number will be used. For any specific service ID subscription, a Tx flow must be pre-setup using one of the following methods:

• v2x_radio_tx_sps_sock_create_and_bind()
• v2x_radio_tx_sps_sock_create_and_bind_v2()
• v2x_radio_tx_sps_only_create()
• v2x_radio_tx_sps_only_create_v2()
• v2x_radio_tx_event_sock_create_and_bind()
• v2x_radio_tx_event_sock_create_and_bind_v2()
• v2x_radio_tx_event_sock_create_and_bind_v3()

int v2x_radio_rx_sock_create_and_bind_v3	(	v2x_radio_handle_t	handle,
		uint16_t	port_num,
		int	id_ist_len,
		uint32_t *	id_list,
		int *	sock,
		struct sockaddr_in6 *	rx_sockaddr
	)

Opens a new V2X radio receive socket with specific service IDs for subscription and specifc port number for the receive path, and initializes the given sockaddr buffer. The socket is also bound as an AF_INET6 UDP type socket.

This v2x_radio_rx_sock_create_and_bind_v3() method differs from v2x_radio_rx_sock_create_and_bind_v2() in that you can use the port_num parameter to specify the port number for the receive path.

Associated data types

v2x_radio_handle_t

Parameters

[in]	handle	Identifies the initialized Radio interface.
[in]	port_num	Identifies the port number for the receive path.
[in]	id_ist_len	Identifies the length of service ID list.
[in]	id_list	Pointer to the service ID list for subscription, subscribe wildcard if input nullptr.
[out]	sock	Pointer to the socket that, on success, returns the socket descriptor. The caller must release this socket with v2x_radio_sock_close().
[out]	rx_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind.

Detailed description

You can execute any sockopts that are appropriate for this type of socket (AF_INET6).

This API can be used to subscribe wildcard, catchall port, or specifc service IDs.

Wildcard is used to receive all traffic. Only one port can be registered as wildcard port. Once wildcard is registered successfully, all received packets will be directed to wildcard port, and any subscription for specific service IDs or catchall port at other ports will be invalid. The parameter id_list of this API should be set to a null list for wildcard subscription.

Catchall port is used to receive packets with non-registered service IDs (via specific service IDs subscription). Only one port can be registered as catchall port. If catchall port is registered successfully, received packets with non-registered service ID will be directed to catchall port. All specific service IDs subscription (if any) should be performed before catchall port subscription. The parameter id_list of this API should include all non-registered service IDs for catchall port subscription.

Any port different from catchall port can be used to receive packets with specific service IDs. Only one port can be registered for a single service ID, a list of service IDs can be registered at a single port. To subscribe specific service IDs at a given Rx port, a Tx flow must be pre-setup with the Tx service ID set to any service ID included in the list of specific service IDs and the Tx source port set to the same port number as Rx port. The parameter id_list of this API should include all interested service IDs for the given Rx port.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init(). The handle from that function must be used as the parameter in this function. For any specific service ID subscription, a Tx flow must be pre-setup using one of the following methods:

• v2x_radio_tx_sps_sock_create_and_bind()
• v2x_radio_tx_sps_sock_create_and_bind_v2()
• v2x_radio_tx_sps_only_create()
• v2x_radio_tx_sps_only_create_v2()
• v2x_radio_tx_event_sock_create_and_bind()
• v2x_radio_tx_event_sock_create_and_bind_v2()
• v2x_radio_tx_event_sock_create_and_bind_v3()

int v2x_radio_sock_create_and_bind	(	v2x_radio_handle_t	handle,
		v2x_tx_sps_flow_info_t *	tx_flow_info,
		v2x_per_sps_reservation_calls_t *	calls,
		int	tx_sps_portnum,
		int	tx_event_portnum,
		int	rx_portnum,
		v2x_sid_list_t *	rx_id_list,
		v2x_sock_info_t *	tx_sps_sock,
		v2x_sock_info_t *	tx_event_sock,
		v2x_sock_info_t *	rx_sock
	)

Creates Tx SPS socket, Tx Event socket and Rx socket with specified parameters. The socket is also bound as an AF_INET6 UDP type socket.

This v2x_radio_sock_create_and_bind() method is the combination of function v2x_radio_tx_sps_sock_create_and_bind_v2()/v2x_radio_tx_event_sock_create_and_bind_v2 in the transmit direction and function v2x_radio_rx_sock_create_and_bind_v3() in the receiving direction.

Associated data types

v2x_radio_handle_t

Parameters

[in]	handle	Identifies the initialized Radio interface.
[in]	tx_flow_info	Pointer to the Tx SPS or event flow information. To create event flow, set reservation.v2xid and flow_info in this structure.
[in]	calls	Pointer to reservation callbacks or listeners. This parameter is called when underlying radio MAC parameters change related to the SPS bandwidth contract. For example, the callback after a reservation change, or if the timing offset of the SPS adjusts itself in response to traffic. This parameter passes NULL if no callbacks are required.
[in]	tx_sps_portnum	Requested Tx source port number for SPS transmissions, or -1 for no Tx sps flow.
[in]	tx_event_portnum	Requested Tx source port number for event transmissions, or -1 for no Tx event flow.
[in]	rx_portnum	Requested Rx destination port number, or -1 for no Rx subscription.
[in]	rx_id_list	Pointer to the Rx service ID list for subscription, subscribe wildcard if input nullptr.
[out]	tx_sps_sock	Pointer to the Tx sps socket that, on success, returns the socket descriptor and the IPv6 socket address. The caller must release this socket with v2x_radio_sock_close().
[out]	tx_event_sock	Pointer to the Tx event socket that, on success, returns the socket descriptor and the IPv6 socket address. The caller must release this socket with v2x_radio_sock_close().
[out]	rx_sock	Pointer to the Rx socket that, on success, returns the socket descriptor and the IPv6 socket address. The caller must release this socket with v2x_radio_sock_close().

Detailed description

You can execute any sockopts that are appropriate for this type of socket (AF_INET6).

This API can be used for the registeration of both Tx and Rx. It sets up sockets on the requested port numbers. A negative port number corresponds to no actions for Tx or Rx.

Wildcard is used to receive all traffic. Only one port can be registered as wildcard port. Once wildcard is registered successfully, all received packets will be directed to wildcard port, and any subscription for specific service IDs or catchall port at other ports will be invalid. The parameter rx_id_list of this API should be set to a null list for wildcard subscription.

Catchall port is used to receive packets with non-registered service IDs (via specific service IDs subscription). Only one port can be registered as catchall port. If catchall port is registered successfully, received packets with non-registered service ID will be directed to catchall port. All specific service IDs subscription (if any) should be performed before catchall port subscription. The parameter rx_id_list of this API should include all non-registered service IDs for catchall port subscription.

Any port different from catchall port can be used to receive packets with specific service IDs. Only one port can be registered for a single service ID, a list of service IDs can be registered at a single port. To subscribe specific service IDs at a given Rx port, a Tx flow should also be set up using this API. The parameter rx_id_list should include all interested service IDs for the given Rx port, the parameter tx_flow_info.reservation.v2xid should be set to one of the service ID included in rx_id_list, the parmenter tx_sps_portnum or tx_event_portnum should be set to the same port number as rx_portnum.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init(). The handle from that function must be used as the parameter in this function.

int v2x_radio_tx_sps_sock_create_and_bind	(	v2x_radio_handle_t	handle,
		v2x_tx_bandwidth_reservation_t *	res,
		v2x_per_sps_reservation_calls_t *	calls,
		int	sps_portnum,
		int	event_portnum,
		int *	sps_sock,
		struct sockaddr_in6 *	sps_sockaddr,
		int *	event_sock,
		struct sockaddr_in6 *	event_sockaddr
	)

Creates and binds a socket with a bandwidth-reserved (SPS) Tx flow with the requested ID, priority, periodicity, and size on a specified source port number. The socket is created as an IPv6 UDP socket.

Associated data types

v2x_radio_handle_t
v2x_tx_bandwidth_reservation_t
v2x_per_sps_reservation_calls_t

Parameters

[in]	handle	Identifies the initialized Radio interface on which this data connection is made.
[in]	res	Pointer to the parameter structure (how often the structure is sent, how many bytes are reserved, and so on).
[in]	calls	Pointer to reservation callbacks or listeners. This parameter is called when underlying radio MAC parameters change related to the SPS bandwidth contract. For example, the callback after a reservation change, or if the timing offset of the SPS adjusts itself in response to traffic. This parameter passes NULL if no callbacks are required.
[in]	sps_portnum	Requested source port number for the bandwidth reserved SPS transmissions.
[in]	event_portnum	Requested source port number for the bandwidth reserved event transmissions, or -1 for no event port.
[out]	sps_sock	Pointer to the socket that is bound to the requested port for Tx with reserved bandwidth.
[out]	sps_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.
[out]	event_sock	Pointer to the socket that is bound to the event-driven transmission port.
[out]	event_sockaddr	Pointer to the IPV6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.

Detailed description

The radio attempts to reserve the flow with the specified size and rate passed in the request parameters.

This function is used only for Tx. It sets up two UDP sockets on the requested two HLOS port numbers.

For only a single SPS flow, indicate the event port number by using a negative number or NULL for the event_sockaddr. For a single event-driven port, use v2x_radio_tx_event_sock_create_and_bind() instead.

Because the modem endpoint requires a specific global address, all data sent on these sockets must have a configurable IPv6 destination address for the non-IP traffic.

The Priority parameter of the SPS reservation is used only for the reserved Tx bandwidth (SPS) flow. The non-SPS/event-driven data sent to the event_portnum parameter is prioritized on the air, based on the IPv67 Traffic Class of the packet.

The caller is expected to identify two unused local port numbers to use for binding: one for the event-driven flow and one for the SPS flow.

This call is a blocking call. When it returns, the sockets are ready to use, assuming there is no error.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

int v2x_radio_tx_sps_only_create	(	v2x_radio_handle_t	handle,
		v2x_tx_bandwidth_reservation_t *	res,
		v2x_per_sps_reservation_calls_t *	calls,
		int	sps_portnum,
		int *	sps_sock,
		struct sockaddr_in6 *	sps_sockaddr
	)

Creates a socket with a bandwidth-reserved (SPS) Tx flow.

Only SPS transmissions are to be implemented for the socket, which is created as an IPv6 UDP socket.

Associated data types

v2x_radio_handle_t
v2x_tx_bandwidth_reservation_t
v2x_per_sps_reservation_calls_t

Parameters

[in]	handle	Identifies the initialized Radio interface on which this data connection is made.
[in]	res	Pointer to the parameter structure (how often the structure is sent, how many bytes are reserved, and so on).
[in]	calls	Pointer to reservation callbacks or listeners. This parameter is called when underlying radio MAC parameters change related to the SPS bandwidth contract. For example, the callback after a reservation change, or if the timing offset of the SPS adjusts itself in response to traffic. This parameter passes NULL if no callbacks are required.
[in]	sps_portnum	Requested source port number for the bandwidth reserved SPS transmissions.
[out]	sps_sock	Pointer to the socket that is bound to the requested port for Tx with reserved bandwidth.
[out]	sps_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.

Detailed description

The radio attempts to reserve the flow with the specified size and rate passed in the request parameters.

This function is used only for Tx. It sets up a UDP socket on the requested HLOS port number. Because the modem endpoint requires a specific global address, all data sent on the socket must have a configurable IPv6 destination address for the non-IP traffic.

The Priority parameter of the SPS reservation is used only for the reserved Tx bandwidth (SPS) flow.

The caller is expected to identify an unused local port number for the SPS flow.

This call is a blocking call. When it returns, the socket is ready to use, assuming there is no error.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EINVAL – On failure to find the interface or get bad parameters.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

v2x_status_enum_type v2x_radio_tx_reservation_change	(	int *	sps_sock,
		v2x_tx_bandwidth_reservation_t *	updated_reservation
	)

Adjusts the reservation for transmit bandwidth.

Associated data types

v2x_tx_bandwidth_reservation_t

Parameters

[out]	sps_sock	Pointer to the socket bound to the requested port.
[in]	updated_reservation	Pointer to a bandwidth reservation with new reservation information.

Detailed description

This function will not update reservation priority. Can be used as follows:

• When the bandwidth requirement changes in periodicity (for example, due to an application layer DCC algorithm)
• Because the packet size is increasing (for example, due to a growing path history size in a BSM).

When the reservation change is complete, a callback to the structure is passed in a v2x_radio_init() or v2x_radio_init_v2() call.

Returns

V2X_STATUS_SUCCESS.

Error code – If there is a problem (see v2x_status_enum_type).

Dependencies

An SPS flow must have been successfully initialized with the v2x_radio_tx_sps_sock_create_and_bind().

int v2x_radio_tx_event_sock_create_and_bind	(	const char *	interface,
		int	v2x_id,
		int	event_portnum,
		struct sockaddr_in6 *	event_sock_addr,
		int *	sock
	)

Opens and binds an event-driven socket (one with no bandwidth reservation). The socket is bound as an AF_INET6 UDP type socket.

Parameters

[in]	interface	Pointer to the operating system name to use. This interface is an RmNet interface (HLOS).
[in]	v2x_id	Used for transmissions that are ultimately mapped to an L2 destination address.
[in]	event_portnum	Local port number to which the socket is bound. Used for transmissions of this ID.
[out]	event_sock_addr	Pointer to the sockaddr_ll structure buffer to be initialized.
[out]	sock	Pointer to the file descriptor. Loaded when the function is successful.

Detailed description

This function is used only for Tx when no periodicity is available for the application type. If you know your transmit data periodicity, use v2x_radio_tx_sps_sock_create_and_bind() instead.

These event-driven sockets pay attention to QoS parameters in the IP socket.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

v2x_status_enum_type v2x_radio_start_measurements	(	v2x_radio_handle_t	handle,
		v2x_chan_meas_params_t *	measure_this_way
	)

Requests a channel utilization (CBP/CBR) measurement result on a channel.

Associated data types

v2x_radio_handle_t
v2x_chan_meas_params_t

Parameters

[in]	handle	Handle to the port.
[in]	measure_this_way	Indicates how and what to measure, and how often to send results. Some higher-level standards (like J2945/1 and ETSI TS102687 DCC) have specific time windows and items to measure.

Detailed description

This function uses the callbacks passed in during initialization to deliver the measurements. Measurement callbacks continue until the Radio interface is closed.

Returns

V2X_STATUS_SUCCESS – The radio is now ready for data-plane sockets to be created and bound.

V2X_STATUS_FAIL – CBR measurement is not supported yet.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

v2x_status_enum_type v2x_radio_stop_measurements

(

v2x_radio_handle_t

handle

)

Discontinues any periodic MAC/Phy channel measurements and the reporting of them via listener calls.

Associated data types

v2x_radio_handle_t

Parameters

[in]

handle

Handle to the radio measurements to be stopped.

Returns

V2X_STATUS_SUCCESS.

Dependencies

The measurements must have been started with v2x_radio_start_measurements().

int v2x_radio_sock_close

(

int *

sock_fd

)

Closes a specified socket file descriptor and deregisters any modem resources associated with it (such as reserved SPS bandwidth contracts).

Parameters

[in]

sock_fd

Socket file descriptor.

Detailed description

This function works on receive, SPS, or event-driven sockets.

The socket file descriptor must be closed when the client exits. We recommend using a trap to catch controlled shutdowns.

Returns

Integer value of the close(sock) operation.

Dependencies

The socket must have been opened with one of the following methods:

• v2x_radio_rx_sock_create_and_bind()
• v2x_radio_tx_sps_sock_create_and_bind()
• v2x_radio_tx_sps_sock_create_and_bind_v2()
• v2x_radio_tx_sps_only_create()
• v2x_radio_tx_sps_only_create_v2()
• v2x_radio_tx_event_sock_create_and_bind()
• v2x_radio_tx_event_sock_create_and_bind_v2()
• v2x_radio_tx_event_sock_create_and_bind_v3()

void v2x_radio_set_log_level	(	int	new_level,
		int	use_syslog
	)

Configures the V2X log level and destination for SDK and lower layers.

Parameters

[in]	new_level	Log level to set to one of the standard syslog levels (LOG_ERR, LOG_INFO, and so on).
[in]	use_syslog	Destination: send to stdout (0) or syslog (otherwise).

Returns

None.

v2x_event_t cv2x_status_poll

(

uint64_t *

status_age_useconds

)

Polls for the recent V2X status.

Parameters

[out]

status_age_useconds

Pointer to the age in microseconds of the last event (radio status) that is being reported.

Detailed description

This function does not generate any modem control traffic. For efficiency, it simply returns the most recently cached value that was reported from the modem (often reported at a high rate or frequent rate from the modem).

Returns

Indication of success or failure (see v2x_status_enum_type).

int v2x_radio_trigger_l2_update

(

v2x_radio_handle_t

handle

)

Triggers the modem to change its source L2 address by randomly generating a new address.

Associated data types

v2x_radio_handle_t

Parameters

[in]

handle

Initialized Radio interface on which this data connection is made.

Detailed description

When the change is complete, clients are notified of the new L2 address via the v2x_radio_calls_t::v2x_radio_l2_addr_changed_listener() callback function.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

int v2x_radio_update_trusted_ue_list	(	unsigned int	malicious_list_len,
		unsigned int	malicious_list[MAX_MALICIOUS_IDS_LIST_LEN],
		unsigned int	trusted_list_len,
		trusted_ue_info_t	trusted_list[MAX_TRUSTED_IDS_LIST_LEN]
	)

Updates the list of malicious and trusted IDs tracked by the modem.

Associated data types

trusted_ue_info_t

Parameters

[in]	malicious_list_len	Number of malicious IDs in malicious_list.
[in]	malicious_list	List of malicious IDs.
[in]	trusted_list_len	Number of trusted IDs in trusted_list.
[in]	trusted_list	List of trusted IDs.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

int v2x_radio_tx_sps_sock_create_and_bind_v2	(	v2x_radio_handle_t	handle,
		v2x_tx_sps_flow_info_t *	sps_flow_info,
		v2x_per_sps_reservation_calls_t *	calls,
		int	sps_portnum,
		int	event_portnum,
		int *	sps_sock,
		struct sockaddr_in6 *	sps_sockaddr,
		int *	event_sock,
		struct sockaddr_in6 *	event_sockaddr
	)

Creates and binds a socket with a bandwidth-reserved (SPS) Tx flow with the requested ID, priority, periodicity, and size on a specified source port number. The socket is created as an IPv6 UDP socket.

This v2x_radio_tx_sps_sock_create_and_bind_v2() method differs from v2x_radio_tx_sps_sock_create_and_bind() in that you can use the sps_flow_info parameter to specify transmission resource information about the Tx flow.

Associated data types

v2x_radio_handle_t
v2x_tx_sps_flow_info_t
v2x_per_sps_reservation_calls_t

Parameters

[in]	handle	Identifies the initialized Radio interface on which this data connection is made.
[in]	sps_flow_info	Pointer to the flow information in the v2x_tx_sps_flow_info_t structure.
[in]	calls	Pointer to reservation callbacks or listeners. This parameter is called when underlying radio MAC parameters change related to the SPS bandwidth contract. For example, the callback after a reservation change, or if the timing offset of the SPS adjusts itself in response to traffic. This parameter passes NULL if no callbacks are required.
[in]	sps_portnum	Requested source port number for the bandwidth reserved SPS transmissions.
[in]	event_portnum	Requested source port number for the bandwidth reserved event transmissions, or -1 for no event port.
[out]	sps_sock	Pointer to the socket that is bound to the requested port for Tx with reserved bandwidth.
[out]	sps_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.
[out]	event_sock	Pointer to the socket that is bound to the event-driven transmission port.
[out]	event_sockaddr	Pointer to the IPV6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.

Detailed description

The radio attempts to reserve the flow with the specified size and rate passed in the request parameters.

This function is used only for Tx. It sets up two UDP sockets on the requested two HLOS port numbers.

For only a single SPS flow, indicate the event port number by using a negative number or NULL for the event_sockaddr. For a single event-driven port, use v2x_radio_tx_event_sock_create_and_bind() or v2x_radio_tx_event_sock_create_and_bind_v2() or v2x_radio_tx_event_sock_create_and_bind_v3() instead.

Because the modem endpoint requires a specific global address, all data sent on these sockets must have a configurable IPv6 destination address for the non-IP traffic.

The Priority parameter of the SPS reservation is used only for the reserved Tx bandwidth (SPS) flow. The non-SPS/event-driven data sent to the event_portnum parameter is prioritized on the air, based on the IPv67 Traffic Class of the packet.

The caller is expected to identify two unused local port numbers to use for binding: one for the event-driven flow and one for the SPS flow.

This call is a blocking call. When it returns, the sockets are ready to use, assuming there is no error.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

int v2x_radio_tx_sps_only_create_v2	(	v2x_radio_handle_t	handle,
		v2x_tx_sps_flow_info_t *	sps_flow_info,
		v2x_per_sps_reservation_calls_t *	calls,
		int	sps_portnum,
		int *	sps_sock,
		struct sockaddr_in6 *	sps_sockaddr
	)

Creates a socket with a bandwidth-reserved (SPS) Tx flow.

Only SPS transmissions are to be implemented for the socket, which is created as an IPv6 UDP socket.

This v2x_radio_tx_sps_only_create_v2() method differs from v2x_radio_tx_sps_only_create() in that you can use the sps_flow_info parameter to specify transmission resource information about the Tx flow.

Associated data types

v2x_radio_handle_t
v2x_tx_sps_flow_info_t
v2x_per_sps_reservation_calls_t

Parameters

[in]	handle	Identifies the initialized Radio interface on which this data connection is made.
[in]	sps_flow_info	Pointer to the flow information in the v2x_tx_sps_flow_info_t structure.
[in]	calls	Pointer to reservation callbacks or listeners. This parameter is called when underlying radio MAC parameters change related to the SPS bandwidth contract. For example, the callback after a reservation change, or if the timing offset of the SPS adjusts itself in response to traffic. This parameter passes NULL if no callbacks are required.
[in]	sps_portnum	Requested source port number for the bandwidth reserved SPS transmissions.
[out]	sps_sock	Pointer to the socket that is bound to the requested port for Tx with reserved bandwidth.
[out]	sps_sockaddr	Pointer to the IPv6 UDP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind() function. The caller can then use the buffer for subsequent sendto() function calls.

Detailed description

The radio attempts to reserve the flow with the specified size and rate passed in the request parameters.

This function is used only for Tx. It sets up a UDP socket on the requested HLOS port number. Because the modem endpoint requires a specific global address, all data sent on the socket must have a configurable IPv6 destination address for the non-IP traffic.

The caller is expected to identify an unused local port number to use for binding the SPS flow.

This call is a blocking call. When it returns, the socket is ready to use, assuming there is no error.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EINVAL – On failure to find the interface or get bad parameters.

Dependencies

The interface must be pre-initialized with v2x_radio_init() or v2x_radio_init_v2(). The handle from that function must be used as the parameter in this function.

v2x_status_enum_type v2x_radio_tx_reservation_change_v2	(	int *	sps_sock,
		v2x_tx_sps_flow_info_t *	updated_flow_info
	)

Adjusts the reservation for transmit bandwidth.

This v2x_radio_tx_reservation_change_v2() method differs from v2x_radio_tx_reservation_change() in that you can use the updated_flow_info parameter to specify transmission resource information about the Tx flow.

Associated data types

v2x_tx_sps_flow_info_t

Parameters

[out]	sps_sock	Pointer to the socket bound to the requested port.
[in]	updated_flow_info	Pointer to the new reservation information.

Detailed description

This function will not update reservation priority. Can be used as follows:

• When the bandwidth requirement changes in periodicity (for example, due to an application layer DCC algorithm)
• Because the packet size is increasing (for example, due to a growing path history size in a BSM).

When the reservation change is complete, a callback to the structure is passed in a v2x_radio_init() or v2x_radio_init_v2() call.

Returns

V2X_STATUS_SUCCESS.

Error code – On failure (see v2x_status_enum_type).

Dependencies

An SPS flow must have been successfully initialized with v2x_radio_tx_sps_sock_create_and_bind() or v2x_radio_tx_sps_sock_create_and_bind_v2().

v2x_status_enum_type v2x_radio_tx_event_flow_info_change	(	int *	sock,
		v2x_tx_flow_info_t *	updated_flow_info
	)

Adjusts the flow parameters for an existing Tx event socket.

Associated data types

v2x_tx_flow_info_t

Parameters

[out]	sock	Pointer to the socket bound to the requested port.
[in]	updated_flow_info	Pointer to the new flow parameters.

Detailed description

When the reservation change is complete, a callback to the structure is passed in a v2x_radio_init() or v2x_radio_init_v2() call.

This call is a blocking call. When it returns, the socket is ready to be use, assuming there is no error.

Returns

V2X_STATUS_SUCCESS.

Error code – On failure (see v2x_status_enum_type).

Dependencies

An event flow must have been successfully initialized with v2x_radio_tx_event_sock_create_and_bind() or v2x_radio_tx_event_sock_create_and_bind_v2() v2x_radio_tx_event_sock_create_and_bind_v3().

v2x_status_enum_type start_v2x_mode

(

)

Starts V2X mode.

The V2X radio status must be INACTIVE. If the status is ACTIVE or SUSPENDED (see v2x_event_t), call stop_v2x_mode() first.

This call is a blocking call. When it returns, V2X mode has been started, assuming there is no error.

Returns

V2X_STATUS_SUCCESS.

Otherwise:

• V2X_STATUS_EALREADY – Failure because V2X mode is already started.
• V2X_STATUS_FAIL – Other failure.

Dependencies

V2X radio status must be V2X_INACTIVE (v2x_event_t).

v2x_status_enum_type stop_v2x_mode

(

)

Stops V2X mode.

The V2X radio status must be ACTIVE or SUSPENDED (see v2x_event_t). If the status is INACTIVE, call start_v2x_mode() first.

This call is a blocking call. When it returns, V2X mode has been stopped, assuming there is no error.

Returns

V2X_STATUS_SUCCESS.

Otherwise:

• V2X_STATUS_EALREADY – Failure because V2X mode is already stopped.
• V2X_STATUS_FAIL – Other failure.

Dependencies

V2X radio status must be V2X_ACTIVE, V2X_TX_SUSPENDED, V2X_RX_SUSPENDED, or V2X_TXRX_SUSPENDED.

v2x_radio_handle_t v2x_radio_init_v2	(	traffic_ip_type_t	ip_type,
		v2x_concurrency_sel_t	mode,
		v2x_radio_calls_t *	callbacks_p,
		void *	ctx_p
	)

Initializes the Radio interface and sets the callback that will be used when events in the radio change (including when radio initialization is complete).

Associated data types

traffic_ip_type_t
v2x_concurrency_sel_t
v2x_radio_calls_t

Parameters

[in]	ip_type	The Ip or non-Ip interface.
[in]	mode	WAN concurrency mode, although the radio might not support concurrency. Errors can be generated.
[in]	callbacks	Pointer to the v2x_radio_calls_t structure that is prepopulated with function pointers used during radio events (such as loss of time synchronization or accuracy) for subscribers. This parameter also points to a callback for this initialization function.
[in]	context	Voluntary pointer to the first parameter on the callback.

Detailed description

This function call is a nonblocking, and it is a control plane action.

Use v2x_radio_deinit() when radio operations are complete.

Currently, the channel and transmit power are not specified. They are specified with a subsequent call to v2x_radio_calls_t::v2x_radio_init_complete() when initialization is complete.

Returns

Handle to the specified initialized radio. The handle is used for reconfiguring, opening or changing, and closing reservations.

V2X_RADIO_HANDLE_BAD – If there is an error. No initialization callback is made.

int v2x_radio_tx_event_sock_create_and_bind_v3	(	traffic_ip_type_t	ip_type,
		int	v2x_id,
		int	event_portnum,
		v2x_tx_flow_info_t *	event_flow_info,
		struct sockaddr_in6 *	event_sockaddr,
		int *	sock
	)

Opens and binds an event-driven socket (one with no bandwidth reservation). The socket is bound as an AF_INET6 UDP type socket.

This v2x_radio_tx_event_sock_create_and_bind_v3() method differs from v2x_radio_tx_event_sock_create_and_bind_v2() in that you can use the traffic_ip_type_t parameter to specify traffic ip type instead of requiring the interface name.

Associated data types

v2x_tx_flow_info_t traffic_ip_type_t

Parameters

[in]	ip_type	traffice_ip_type.
[in]	v2x_id	Used for transmissions that are ultimately mapped to an L2 destination address.
[in]	event_portnum	Local port number to which the socket is bound. Used for transmissions of this ID.
[in]	event_flow_info	Pointer to the event flow parameters.
[out]	event_sock_addr	Pointer to the sockaddr_ll structure buffer to be initialized.
[out]	sock	Pointer to the file descriptor. Loaded when the function is successful.

Detailed description

This function is used only for Tx when no periodicity is available for the application type. If you know your transmit data periodicity, use v2x_radio_tx_sps_sock_create_and_bind() or v2x_radio_tx_sps_sock_create_and_bind_v2() instead.

These event-driven sockets pay attention to QoS parameters in the IP socket.

Returns

0 – On success.

Otherwise:

• EPERM – Socket creation failed; for more details, check errno.h.
• EAFNOSUPPORT – On failure to find the interface.
• EACCES – On failure to get the MAC address of the device.

v2x_status_enum_type get_iface_name	(	traffic_ip_type_t	ip_type,
		char *	iface_name,
		size_t	buffer_len
	)

Returns interface name set during radio initialization.

Associated data types

traffic_ip_type_t

Parameters

[in]	ip_type	traffic_ip_type_t
[out]	iface_name	pointer to buffer for interface name
[in]	buffer_len	length of the buffer passed for interface name. Must be at least the max buffer size for an interface name (IFNAMSIZE).

Detailed description

This function should only be called after successfully initializing a radio.

Returns

V2X_STATUS_SUCCESS.

V2X_STATUS_FAIL – If there is an error. Interface name will be an empty string.

int v2x_radio_tcp_sock_create_and_bind	(	v2x_radio_handle_t	handle,
		const v2x_tx_flow_info_t *	event_info,
		const socket_info_t *	sock_info,
		int *	sock_fd,
		struct sockaddr_in6 *	sockaddr
	)

Creates a TCP socket for event Tx and Rx. The socket is bound as an AF_INET6 TCP type socket.

This v2x_radio_tcp_sock_create_and_bind() API creates a new TCP socket and binds the socket to the IPv6 address of local IP interface with specified source port. Additionally, this API also registers a Tx event flow and subscribes Rx with specified service ID to enable TCP control and data packets in both transmitting and receiving directions.

If the created socket is expected to work as TCP client mode, the caller must establish a connection to the address specifed using function connect(), and then use the socket for send() and recv() on successful connection. The caller must release the created socket and associated resources with v2x_radio_sock_close().

If the created socket is expected to work as TCP server mode, the caller must mark the created socket as a listening socket with function listen(), that is, as a socket that will be used to accept incoming connection requests using accept(). The caller can then use the connected socket returned by accept() for send() and recv(). The caller must close all connected sockets returned by accept() with function close() first, and then release the listening socket and associated resources with v2x_radio_sock_close().

This call is a blocking call. When it returns, the created TCP socket is ready to use, assuming there is no error.

Associated data types

v2x_radio_handle_t

Parameters

[in]	handle	Identifies the initialized Radio interface. The caller must specify IP interface for raido initilization.
[in]	event_info	Pointer to the Tx event flow information.
[in]	sock_info	Pointer to the TCP socket information.
[out]	sock_fd	Pointer to the socket that, on success, returns the TCP socket descriptor. The caller must release this socket with v2x_radio_sock_close().
[out]	sockaddr	Pointer to the address of TCP socket. The sockaddr_in6 buffer is initialized with the IPv6 source address and source port that are used for the bind.

Detailed description

You can execute any sockopts that are appropriate for this type of socket (AF_INET6).

Returns

0 – On success.

Otherwise:

• EINVAL – On failure to find the interface or get bad parameters.
• EPERM – Socket operation failed; for more details, check errno.h.

Dependencies

The interface used for IP communication must be pre-initialized with v2x_radio_init(). The handle from that function must be used as the parameter in this function.