Gateway IPC Binding Architecture#
Overview#
The Gateway IPC Binding (Gateway IPC Binding (comp__gateway_ipc_binding)) connects gatewayd and someipd over
mw::com (LoLa). It maps bridged SOME/IP services directly onto mw::com service discovery,
subscription management, event transport, and shared-memory sample management:
Transports
socomevent updates betweengatewaydandsomeipdovermw::comshared memory.Reserves an 8-byte binding prefix at the front of each shared-memory sample slot and exposes the remaining bytes as a contiguous span so
gatewaydandsomeipdkeep the 16-byte SOME/IP header and payload contiguous for E2E protection without copying.Reports daemon connectivity through
is_connected()and registersgatewaydservice configurations at runtime viaSomeipdService(see SomeipdService and daemon connectivity).
Description#
Rationale Behind Architecture Decomposition#
The binding separates daemon-level lifecycle and control signaling from per-service event transport:
Transport-independent daemon API (
Gateway_ipc_binding_clientandGateway_ipc_binding_server):Client_adapterandServer_adapterexpose onlyis_connected()andstart(), keepinggatewaydandsomeipdindependent ofmw::comtypes outside thecreate_client()andcreate_server()setup calls.Typed control service vs generic service bindings (
SomeipdServicevsService_binding): Bridged SOME/IP services use type-erasedGenericSkeletonandGenericProxyinstances, which do not support methods and are only offered while a service is active. A dedicated typedSomeipdService(Someipd_service_providerandSomeipd_service_consumer) therefore handles daemon liveness and runtime configuration registration (AddServiceConfiguration), while both daemons reuseProvider_service_binding,Consumer_service_binding, andsample_layoutviamake_service_bindings()for event transport.Configuration schema isolation (
score/bridged_services): Translatingmw_someip_configintoService_configslives inscore/bridged_servicesoutsidecomp__gateway_ipc_binding, keeping the IPC binding independent of the FlatBuffers gateway configuration schema.All-or-nothing registration: If any entry of
Service_configsfails setup,create_client()returnsnullptrandAddServiceConfigurationrolls back and returnsfalse(see Registering gatewayd services with someipd), so partial service configurations never go live.
Mapping SOME/IP services to mw::com features#
Service mapping#
Gateway concept |
|
|---|---|
Bridged service instance |
one |
Service interface identity and version |
|
Event identity |
named |
Service becomes available |
|
Service goes away |
|
Event subscription propagation |
|
Payload buffer allocation |
|
Event transmission |
|
Event reception |
|
Payload lifetime |
|
Slot count and slot size |
|
Daemon connectivity |
dedicated typed |
Method calls |
not supported on bridged services (see Limitations) |
Role assignment#
A bridged service always has a data source and a data sink. The binding peer on the source side
(Role::provider) acts as a SOCom Client_connector and pushes events into a GenericSkeleton; the
binding peer on the sink side (Role::consumer) owns the GenericProxy and publishes received events
through a SOCom Server_connector.
Service kind |
Data direction |
|
|
Binding SOCom role on the provider side |
|---|---|---|---|---|
local service instance (application provides, network consumes) |
application to network |
provider, |
consumer, |
|
remote service instance (network provides, application consumes) |
network to application |
consumer, |
provider, |
|
Fig. 1 Role assignment for both data directions#
SomeipdService and daemon connectivity#
The bridged services alone cannot tell gatewayd whether someipd is running. A remote service instance
only becomes available once the SOME/IP service behind it is available on the network, so its absence is
ambiguous: it means either “someipd is down” or “someipd is up but the network service is not there”.
The binding resolves this ambiguity with SomeipdService, a dedicated mw::com service representing the
someipd daemon itself:
Offering order and registration:
someipdoffers itsSomeipdServiceinstance first (Gateway_ipc_binding_server::start()), before any bridged services exist.gatewayddiscovers it withStartFindService, creates aSomeipd_service_proxy, and callsAddServiceConfigurationon every new proxy (see Registering gatewayd services with someipd).Connection state and recovery:
Gateway_ipc_binding_client::is_connected()becomestrueoncesomeipdacceptsAddServiceConfiguration, allowinggatewayd’s startup wait loop to proceed while bridged services arrive asynchronously afterwards through normal SOCom availability. When the find-service handler reports the instance gone,is_connected()returns tofalse; ifsomeipdrestarts, the handler fires again with a new handle andgatewaydre-registers its configuration automatically.Unique instance specifier per daemon: The
SomeipdServiceinstance specifier must be unique persomeipdon a host, and it is the one piece of configurationsomeipdand all itsgatewaydinstances must agree on.Distinct application identity per client: Every
gatewaydconnected to asomeipdMUST have its ownmw::comapplicationID, or its own UID if it configures none, because LoLa treats a secondgatewaydwith the same identity as a restart of the first.
Event sample layout#
A mw::com event sample is a fixed-size, type-erased buffer described by DataTypeMetaInfo{size, alignment}.
SOME/IP messages are variable length and travel whole (header and payload contiguous). The binding therefore
defines the following layout for every event sample it exchanges:
+----------------------+-----------------------------+
| binding prefix (8 B) | payload bytes |
| u32 payload_length | up to max_payload_size, |
| u32 reserved | e.g. a SOME/IP message |
+----------------------+-----------------------------+
^ ^
sample base Payload::data()
Size and alignment:
sizeof theDataTypeMetaInfois8 + max_payload_sizerounded up to a multiple of 8, andalignmentis 8. The 8-byte prefix keeps the payload 8-byte aligned; the rounding is required becausemw::comrejects a size that is not an integer multiple of its alignment. The padding at the end is never addressed, soWritable_payload::wdata()starts atmax_payload_sizebytes andPayload::data()spanspayload_lengthbytes (up tomax_payload_size).Zero-copy payload views: The binding builds
socom::Payloadandsocom::Writable_payloadover the bytes after the prefix, so the producing and consuming applications see the whole SOME/IP message indata()and E2E protection can run over it in place.Length framing:
payload_lengthis the only piece of binding metadata on the link. It is required because LoLa samples are fixed size while SOME/IP payloads are not. The producer shrinks itsWritable_payload; the binding writespayload.data().size()into the prefix just beforeSend(); the consumer side reads it back and sizes thesocom::Payloadaccordingly.
Event sizes#
Only gatewayd knows the event sizes (serialized payload plus SOME/IP header), from its generated
serializers. someipd is type-agnostic and configures max_payload_size as 0. In mw::com, the
Role::provider side allocates the shared-memory sample slots when it creates the GenericSkeleton, so
the provider needs the size up front. How someipd gets the size depends on which daemon provides the
bridged service:
gatewayd provides, someipd consumes:
gatewaydcreates theGenericSkeletonwith its configured size. Whensomeipd’sConsumer_service_bindingattaches to the peer, it reads the sample size fromGenericProxyEvent::GetDataTypeSizeInfo().Size()and subtractskSample_prefix_size. On any consumer, if the peer’s sample size is smaller than the configuredmax_payload_size, the binding logs an error and leaves the service unavailable.someipd provides, gatewayd consumes:
someipdmust size itsGenericSkeletonbeforegatewaydattaches to it.gatewaydtherefore sends{service_id, event_id, max_payload_size}for every event of itsRole::consumerservices inAddServiceConfiguration(at most 1024 events, in any order). Those services areRole::providerservices insomeipd. The call MUST supply one size for every provider event it adds tosomeipd, with no missing, unknown, or duplicate events. Otherwisesomeipdrejects the call and logs an error.
Registering gatewayd services with someipd#
Each gatewayd registers its bridged services with someipd at runtime via AddServiceConfiguration:
Payload:
gatewaydsends the raw FlatBuffers bytes of itsmw_someip_config(up to 64 KiB) together with its consumer event sizes in a single fixed-size, trivially copyableAddServiceConfigurationcall.gatewaydfails at startup if its configuration exceeds 64 KiB.Setup in someipd: the IPC binding treats the configuration bytes as opaque and passes them to
someipd’s handler.someipdvalidates the buffer with the FlatBuffersVerifier, builds the IPC bridged services viabridged_service_configs(), and creates its SOME/IP network services from the same buffer, keeping the buffer alive for as long as the services exist.All-or-nothing rollback: if any step fails,
someipddestroys the service bindings created during the call and returnsfalse.gatewaydlogs the failure and stays disconnected. Anymw::comdeployment already registered withruntime::AddConfigurationstays insomeipduntilsomeipdrestarts, becausemw::comcannot remove a configuration.Restarts and ownership:
someipdkeeps agatewayd’s services alive when thatgatewaydstops. When a restartedgatewaydreconnects and sends the exact same configuration bytes and event sizes,someipdaccepts the call immediately without recreating the services. Any different call that reuses aservice_idfrom an already-accepted call is rejected: each service belongs to onegatewaydand cannot change whilesomeipdruns.Starting service discovery for consumer services: every
Role::consumerservice startsGenericProxydiscovery to detect when the peer daemon offers itsGenericSkeleton. Ingatewayd, consumer discovery starts duringcreate_client(), while insomeipdServer_adapterdispatchesstart()onto itsipc_discoveryworker thread after acceptingAddServiceConfigurationbecauseStartFindServicemust not be called from anmw::commessage-passing callback thread.
Availability propagation#
Provider_service_binding creates its GenericSkeleton eagerly at startup and calls OfferService() or
StopOfferService() on Client_connector::on_service_state_change, while Consumer_service_binding
creates or destroys its GenericProxy and enables or disables its SOCom server connector from its
StartFindService callback. When the local SOCom service becomes unavailable and no peer holds a
subscription, Provider_service_binding also destroys the GenericSkeleton and recreates it on the next
offer; if a peer still holds a subscription, the GenericSkeleton is kept alive so the shared-memory
subscription state remains valid (see Limitations).
Subscription propagation#
On the consumer side, on_event_subscription_change subscribes or unsubscribes the GenericProxyEvent
(with max_sample_count) and registers or removes its receive handler. On the provider side,
GenericSkeletonEvent::SetReceiveHandlerRegistrationChangedHandler tracks whether a remote receive handler
is registered. Because the remote receive handler may be registered before the local SOCom service becomes
available, Provider_service_binding keeps a per-event desired-subscription flag and reconciles
Client_connector::subscribe_event (in Event_mode::update) and unsubscribe_event whenever either
input changes, rather than calling SOCom directly from the mw::com callback.
Payload lifetime and flow control#
LoLa owns the shared-memory sample slots:
provider side:
Provider_service_binding::on_event_payload_allocate()allocates a LoLa sample slot and stores theSampleAllocateePtr<void>as inline user data in theWritable_payloaduntilon_event_update()writes the payload-length prefix and sends it, or releases the slot back to LoLa if theWritable_payloadis dropped unsent. If all sample slots of an event are in use (kNumber_of_sample_slots = 20, shared between allocated samples awaitingSend()on the provider and received samples up tomax_sample_countheld by the consumer),GenericSkeletonEvent::Allocate()fails andon_event_payload_allocate()logs a warning and returnsruntime_error_sample_allocation_failed.consumer side:
GetNewSamplesyields aSamplePtr<void>per sample. The binding moves it into the user data of thesocom::Payloadit builds. When the consuming application destroys the payload, theSamplePtr<void>is destroyed and the slot is returned to LoLa.
Configuration#
Both daemons need a mw_com_config.json and must call InitializeRuntime. The configuration for the
gatewayd / someipd link contains only the entry for SomeipdService and daemon connectivity; both files must spell it
identically:
{
"serviceTypes": [
{
"serviceTypeName": "/score/someip/SomeipdService",
"version": { "major": 1, "minor": 0 },
"bindings": [ {
"binding": "SHM",
"serviceId": 6400,
"methods": [ { "methodName": "AddServiceConfiguration", "methodId": 1 } ]
} ]
}
],
"serviceInstances": [
{
"instanceSpecifier": "someipd/daemon",
"serviceTypeName": "/score/someip/SomeipdService",
"version": { "major": 1, "minor": 0 },
"instances": [ {
"instanceId": 1,
"asil-level": "QM",
"binding": "SHM",
"methods": [ { "methodName": "AddServiceConfiguration", "queueSize": 1 } ]
} ]
}
]
}
Bridged deployment#
Each daemon builds its Service_configs from mw_someip_config using bridged_service_configs() in
score/bridged_services: gatewayd builds them from its own configuration file, and someipd builds
them from the configuration bytes received in AddServiceConfiguration (see Registering gatewayd services with someipd).
add_to_mw_com_runtime() then synthesizes the mw::com SHM serviceTypes and serviceInstances
deployment JSON in memory for any service instance not already present in mw_com_config.json and
registers it via mw::com::runtime::AddConfiguration:
Naming: both
serviceTypeNameandinstanceSpecifierarebridged_ipc/<service_type_name>(with version1.0), keeping bridged instances distinct fromgatewayd-to-application instances.IDs:
serviceIdandeventIdare taken directly from the SOME/IPservice_idandevent_idinmw_someip_config.Instance ID:
instanceIdisipc_instance_idfrommw_someip_config, which defaults to0xFFFF(the SOME/IP “any instance” ID) to avoid colliding with local application instance IDs. Allgatewaydinstances of the samesomeipdMUST use the sameipc_instance_id; a host running more than onesomeipdneeds a distinct value persomeipd.Sample slots and subscribers:
numberOfSampleSlotsiskNumber_of_sample_slots(20) andmaxSubscribersis1for the single peer daemon.ASIL level:
asil-levelis"QM", becausesomeipdis a QM process andmw::comrequires both ends of a shared-memory instance to use"QM"when either peer is QM.
Limitations#
Method calls: Bridged services support events only (
mw::com::GenericProxyandGenericSkeletondo not support methods).SomeipdServiceis a typedmw::comservice and supports theAddServiceConfigurationmethod (see SomeipdService and daemon connectivity).Requested event updates: On-demand event update requests (
socomon_event_update_request) are logged and ignored because the IPC bridge uses push-onlymw::comevent notifications.Re-offering a provider service: If a local SOCom service stops and is re-offered while no peer holds an event subscription,
Provider_service_bindingdestroys and recreates theGenericSkeleton. However, restarting a provider while a peer actively holds an event subscription is not currently supported due to an upstreammw::comlimitation when re-offering an existing shared-memory skeleton with active subscribers.Changing an event size: Modifying a registered service configuration or event payload size requires restarting both
gatewaydandsomeipd, becausesomeipdrejects modified configurations for an already-registeredservice_idandmw::comshared-memory segments have a fixed slot size once created.
Static Architecture#
Gateway IPC Binding Static Architecture
|
status: valid
security: NO
safety: ASIL_B
|
||||
Component structure of
Fig. 2 Gateway IPC Binding on mw::com, component view# |
|||||
Dynamic Architecture#
Gateway IPC Binding Startup and Event Flow
|
status: valid
security: NO
safety: ASIL_B
|
||||
Runtime sequences for
Fig. 3
Fig. 4 Availability for one bridged service#
Fig. 5 Subscription lifecycle for one bridged service#
Fig. 6 Event delivery for one bridged service# |
|||||
Teardown#
On destruction, each service binding tears down its endpoints in order so no callback or shared-memory sample outlives its owner:
Provider_service_binding: UnsetsGenericSkeletonEventreceive-handler registration callbacks, resets thesocom::Client_connector, and stops and destroys theGenericSkeleton.Consumer_service_binding: CallsGenericProxy::StopFindService, disables thesocomserver connector, unsets receive handlers and unsubscribes activeGenericProxyEventinstances, and destroys theGenericProxyand disabled connector.
Threading and concurrency#
SOCom callbacks and
mw::comreceive handlers run on different threads. EveryService_bindingguards its state with a mutex, plus one outer mutex per blocking transition it has to serialize.Both stacks call the binding back while holding an internal lock of their own, and both take that same internal lock from the API the binding calls into. A binding mutex that a callback takes may therefore never be held across such a call, or the two lock orders form a cycle and the daemon deadlocks against a stack-owned thread. Concretely:
mw::comholds its service discovery lock across the find-service handler, and creating or destroying aGenericProxytakes that same lock. Proxies are therefore constructed before, and destroyed after, every binding mutex is released.mw::comholds its event notification registry lock across the receive-handler-registration handler, andOfferService()/StopOfferService()take that same lock. The provider offers underm_offer_mutex, which that handler does not take.SOCom holds connector locks across the subscription callbacks, and
enable()/disable()take those same locks. The consumer enables and disables underm_lifecycle_mutex, which no callback takes.
The outer mutexes exist purely to keep those transitions serialized against each other while the inner ones are released.
Neither a SOCom callback nor a
mw::comhandler may block. The binding does no I/O. TheAddServiceConfigurationhandler is the exception: it sets up services, but never waits for a reply, see Registering gatewayd services with someipd.GetNewSamplesmust not run concurrently for the sameGenericProxyEvent. Because the only caller is the receive handler registered for that event, andmw::comserialises those, this holds without extra locking; the mutex is still taken for the SOCom-visible state.The SOCom deadlock detector terminates the process if a connector is destroyed from inside one of its own callbacks. Teardown therefore never runs from a callback; the
mw::comfind-service handler schedules the disable and destroys the connector outside the handler.
Interfaces#
The public Gateway_ipc_binding_client and Gateway_ipc_binding_server interfaces are declared in
gateway_ipc_binding_client.hpp and gateway_ipc_binding_server.hpp. They expose only
implementation-independent lifecycle operations. The gateway_ipc_binding_mw_com.hpp header adds the
mw::com configuration types and the mw::com-specific free factory functions.
Gateway IPC Binding Client Interface
|
status: valid
security: NO
safety: ASIL_B
|
||||
Client-side lifecycle and configuration interface used by |
|||||
mw_com::create_client
|
status: valid
security: NO
safety: ASIL_B
|
||||
Creates the client-side IPC binding for |
|||||
Gateway_ipc_binding_client::is_connected
|
status: valid
security: NO
safety: ASIL_B
|
||||
Returns |
|||||
Gateway IPC Binding Server Interface
|
status: valid
security: NO
safety: ASIL_B
|
||||
Server-side lifecycle and configuration handler interface used by |
|||||
mw_com::create_server
|
status: valid
security: NO
safety: ASIL_B
|
||||
Creates the server-side IPC binding for |
|||||
Gateway_ipc_binding_server::start
|
status: valid
security: NO
safety: ASIL_B
|
||||
Offers |
|||||
SomeipdService Control Interface
|
status: valid
security: NO
safety: ASIL_B
|
||||
Typed |
|||||
AddServiceConfiguration
|
status: valid
security: NO
safety: ASIL_B
|
||||
Transfers |
|||||