IPC (Inter-Process Communication) Guide

Overview

• The IPC module provides transport-agnostic inter-process/inter-task communication
• with support for multiple backend implementations (Shared Memory, FIFO, TCP/IP, UDP).
• Documents in this directory:
• - IPC Transport Selection Guide - Complete transport selection guide
• - Shared Memory, FIFO, TCP/IP, UDP characteristics
• - POSIX vs RTOS backends
• - Decision tree for choosing transports
• - Channel Configuration Guide - Configuration framework for users
• - Configuration structures for each transport type
• - How to specify IP addresses, ports, paths
• - Dispatcher callback pattern for mixed transports
• - Online/Standby examples with TCP/IP
• - sapi_ipc_request_reply.h - Request-Reply pattern (RPC-style)
• - Client sends request, server replies
• - Deadlock-free with timeouts
• - Typical: Train controller queries signal database
• - sapi_ipc_pubsub.h - Publish-Subscribe pattern (broadcast)
• - One publisher sends to multiple subscribers
• - Asynchronous, decoupled communication
• - Typical: Track database broadcasts state changes
• - sapi_ipc.h - Base IPC API
• - Backend vtable abstraction
• - OS-agnostic interface
• - Users can register custom backends

IPC Architecture Layers

• Application Layer (vital_channel, app manager)
• │
• v
• Inter-Process Communication Pattern Layer (Request-Reply, Pub-Sub)
• │
• v
• Inter-Process Communication Transport Abstraction (vtable)
• │
• v
• OS-Specific Implementations
• ├─ POSIX: mmap(), mkfifo(), sockets
• ├─ QNX: MsgPass, shared memory
• ├─ RTOS: Native messaging, memory mapping
• └─ Custom: User-provided backends

Typical Workflow for Online/Standby Setup

• Step 1: Choose Transports (See IPC Transport Selection Guide)
• For online/standby over network:
• → TCP/IP (reliable, ordered) + UDP (fast, best-effort)
• For same-board redundancy:
• → Shared Memory (ultra-low latency) + FIFO (fallback)
• Step 2: Configure Channels (See Channel Configuration Guide)
• c
• sapi_ipc_config_tcp_t tcp_cfg = {
• .remote_ip = "192.168.1.100", // User provides standby IP
• .remote_port = 5000, // User chooses port
• .timeout_ms = 1000,
• };
• sapi_ipc_handle_t tcp_channel;
• sapi_ipc_create_tcp(&tcp_channel, &tcp_cfg); // OS backend implements
• Step 3: Wrap in Vital Channel (See Vital Channel Communication Architecture)
• c
• sapi_channel_config_t vital_cfg = {
• .voting_strategy = SAPI_VOTING_2OO2,
• .backend_send = your_dispatcher_send,
• .backend_recv = your_dispatcher_recv,
• };
• void *channels[2] = { &tcp_channel, &udp_channel };
• sapi_channel_init(&vital, &vital_cfg, channels, 2);
• Step 4: Use in App Manager (See System Architecture Overview)
• c
• // Main loop: read vital, process, send vital
• while (running) {
• vital_channel_recv(&vital, &cmd, timeout=100ms);
• process_command(&cmd);
• vital_channel_send(&vital, &output);
• }

Design Principles

• 1. Transport Independence
• - Framework doesn't care what transport you use (SHM, TCP, UDP, FIFO)
• - User chooses and configures transports
• - OS integrator implements actual I/O
• - Application code unchanged regardless of transport
• 2. Configuration, Not Coupling
• - Framework provides configuration structures
• - User fills in IP addresses, ports, paths
• - No hardcoding of transport mechanisms
• - Easy to switch transports at runtime (if needed)
• 3. Extensibility
• - Backend vtable pattern allows new transport types
• - Just add new configuration structure
• - Dispatcher routes to correct backend
• - Existing code unaffected
• 4. Safety-Critical
• - Vital channels require 2oo2/2oo3 voting
• - Disagreement triggers safe-state automatically
• - Health tracking per channel
• - Deterministic timeouts (no indefinite waits)

Quick Examples

• Example 1: TCP/IP Online → Standby
• c
• // See CHANNEL_CONFIGURATION.md for complete example
• tcp_config.remote_ip = "192.168.1.100";
• tcp_config.remote_port = 5000;
• Example 2: Local Shared Memory
• c
• // See CHANNEL_CONFIGURATION.md
• shm_config.descriptor_path = "/dev/shm/rail_vital_ab";
• Example 3: Mixed Transports (Dispatcher)
• c
• // See examples/channel_configuration_example.c
• if (is_tcp_channel) return tcp_send(...);
• if (is_udp_channel) return udp_send(...);
• if (is_shm_channel) return shm_send(...);

Next Steps

• 1. Read IPC Transport Selection Guide to understand transport options
• 2. Read Channel Configuration Guide to learn configuration
• 3. Check examples/channel_configuration_example.c for working code
• 4. Implement OS-specific backends (sapi_ipc_create_tcp, etc.)
• 5. Integrate with vital_channel for voting/redundancy
• 6. Review System Architecture Overview for complete system design

• See also

  vital_channel_architecture for voting and redundancy

• See also

  system_architecture for overall system design

• */