transport.h File Reference

Transport abstraction for the Safe Communication Framework. More...

#include <stddef.h>
#include <stdint.h>
#include "safecomm/status.h"

Include dependency graph for transport.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	safecomm_transport_t
	A consumer-supplied bearer the SaF layer runs over. More...
struct	safecomm_transport_channel_ctx_t
	Caller-owned storage for safecomm_transport_from_channel_service. No dynamic memory (MISRA): the caller allocates this, typically embedded in its own per-link state, the same way it allocates an rte_channel_service_t. More...

Typedefs
typedef safecomm_status_t(*)	safecomm_transport_send_fn(void *user, const uint8_t *buf, size_t len)
	Blocking send of exactly len bytes.
typedef safecomm_status_t(*)	safecomm_transport_recv_fn(void *user, uint8_t *buf, size_t cap, size_t *out_len)
	Blocking receive of up to cap bytes.
typedef void(*)	safecomm_transport_close_fn(void *user)
	Release the underlying bearer. Idempotent.

Functions
safecomm_status_t	safecomm_transport_oal_tcp (safecomm_transport_t *out, const char *host, uint16_t port, uint32_t recv_timeout_ms)
	Populate out with an OAL/TCP transport built on safeAPIFreamwork.
safecomm_status_t	safecomm_transport_from_channel_service (safecomm_transport_t *out, safecomm_transport_channel_ctx_t *ctx, void *channel, uint32_t recv_timeout_ms)
	Populate out with a transport that runs over an already-open, caller-owned Platform_RTE named channel (rte_channel_service_t) — e.g. RBC_GP's own train or IL relay channel, opened and closed by the caller for its own reasons independent of this transport's lifetime. Unlike safecomm_transport_oal_tcp, this does not open a bearer itself: it wraps one the caller already has, which is the shape RBC_GP's vital A/B processes need (the relay channel is shared infrastructure, not something the SaF layer should own or close).

Detailed Description

Transport abstraction for the Safe Communication Framework.

The SaF sub-layer never opens a socket. The consumer supplies a safecomm_transport_t with blocking send / recv / close callbacks over an already-established bearer:

• Subset-037: a GSM-R / FRMCS call or packet-switched bearer set up by the CFM (out of scope here — see CLAUDE.md).
• Subset-098: a fixed IP connection between two RBCs.

An OAL-backed default built on safeAPIFreamwork's channel API is provided by safecomm_transport_oal_tcp() for the common case.

REQ-SC-TRANSPORT-001..006 — see docs/requirements/SRS.md.

Definition in file transport.h.

Typedef Documentation

safecomm_transport_send_fn

typedef safecomm_status_t(*) safecomm_transport_send_fn(void *user, const uint8_t *buf, size_t len)

Blocking send of exactly len bytes.

Parameters

user	the safecomm_transport_t::user pointer.
buf	bytes to send. Non-NULL when len > 0.
len	byte count.

Returns

SAFECOMM_STATUS_OK on full send, SAFECOMM_STATUS_TRANSPORT on any error or short write, SAFECOMM_STATUS_PEER_DISCONNECT on EOF.

Definition at line 38 of file transport.h.

safecomm_transport_recv_fn

typedef safecomm_status_t(*) safecomm_transport_recv_fn(void *user, uint8_t *buf, size_t cap, size_t *out_len)

Blocking receive of up to cap bytes.

Parameters

user	the safecomm_transport_t::user pointer.
buf	destination. Non-NULL when cap > 0.
cap	capacity of buf.
out_len	receives the number of bytes read (> 0 on success). Non-NULL.

Returns

SAFECOMM_STATUS_OK, SAFECOMM_STATUS_TIMEOUT, SAFECOMM_STATUS_PEER_DISCONNECT, or SAFECOMM_STATUS_TRANSPORT.

Definition at line 49 of file transport.h.

safecomm_transport_close_fn

typedef void(*) safecomm_transport_close_fn(void *user)

Release the underlying bearer. Idempotent.

Definition at line 52 of file transport.h.

Function Documentation

safecomm_transport_oal_tcp()

safecomm_status_t safecomm_transport_oal_tcp	(	safecomm_transport_t *	out,
		const char *	host,
		uint16_t	port,
		uint32_t	recv_timeout_ms )

Populate out with an OAL/TCP transport built on safeAPIFreamwork.

Parameters

out	receives the transport. Non-NULL.
host	peer host (NUL-terminated). Non-NULL.
port	peer TCP port.
recv_timeout_ms	per-recv supervision timeout, 0 = block forever.

Returns

SAFECOMM_STATUS_OK / _INVALID_PARAM / _TRANSPORT / _NOT_IMPLEMENTED.

Note

REQ-SC-TRANSPORT-004. Only meaningful when the framework dependency is present; a pure SaF/MAC unit test does not need it.

Definition at line 99 of file transport.c.

safecomm_transport_from_channel_service()

safecomm_status_t safecomm_transport_from_channel_service	(	safecomm_transport_t *	out,
		safecomm_transport_channel_ctx_t *	ctx,
		void *	channel,
		uint32_t	recv_timeout_ms )

Populate out with a transport that runs over an already-open, caller-owned Platform_RTE named channel (rte_channel_service_t) — e.g. RBC_GP's own train or IL relay channel, opened and closed by the caller for its own reasons independent of this transport's lifetime. Unlike safecomm_transport_oal_tcp, this does not open a bearer itself: it wraps one the caller already has, which is the shape RBC_GP's vital A/B processes need (the relay channel is shared infrastructure, not something the SaF layer should own or close).

channel must point to an already-set-up rte_channel_service_t (opaque void* here so this public header does not depend on Platform_RTE's own headers — only this function's .c file does, and only when built with the framework present).

This transport's own close() is a deliberate no-op: closing the underlying channel remains the caller's responsibility, since other traffic (or the plain, unauthenticated path during migration, REQ-SC integration plan step 6) may still need it after a SaF session ends.

Parameters

out	receives the transport. Non-NULL.
ctx	caller-owned storage this transport's callbacks close over. Non-NULL, must outlive out.
channel	an already-open rte_channel_service_t*, owned by the caller. Non-NULL.
recv_timeout_ms	per-recv supervision timeout passed straight through to rte_channel_service_read_ex(), 0 = block forever.

Returns

SAFECOMM_STATUS_OK / _INVALID_PARAM, or SAFECOMM_STATUS_NOT_IMPLEMENTED when this library was not built with the framework present (SAFECOMM_USE_INSTALLED_FRAMEWORK).

Note

REQ-SC-TRANSPORT-004.

Definition at line 84 of file transport.c.