IPC (Inter-Process Communication) Guide

Overview

The IPC module provides transport-agnostic inter-process/inter-task communication with support for multiple OSAdapter 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 OSAdapters
  • 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
• rte_ipc_request_reply.h - Request-Reply pattern (RPC-style)
  • Client sends request, server replies
  • Deadlock-free with timeouts
  • Typical: Train controller queries signal database
• rte_ipc_pubsub.h - Publish-Subscribe pattern (broadcast)
  • One publisher sends to multiple subscribers
  • Asynchronous, decoupled communication
  • Typical: Track database broadcasts state changes
• rte_ipc.h - Base IPC API
  • OSAdapter vtable abstraction
  • OS-agnostic interface
  • Users can register custom OSAdapters

IPC Architecture Layers

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

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)

rte_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,
};
 
rte_ipc_handle_t tcp_channel;
rte_ipc_create_tcp(&tcp_channel, &tcp_cfg);  // OS OSAdapter implements

Step 3: Wrap in Vital Channel** (See Vital Channel Communication Architecture)

rte_channel_config_t vital_cfg = {
    .voting_strategy = RTE_VOTING_2OO2,
    .backend_send = your_dispatcher_send,
    .backend_recv = your_dispatcher_recv,
};
 
void *channels[2] = { &tcp_channel, &udp_channel };
rte_channel_init(&vital, &vital_cfg, channels, 2);

Step 4: Use in App Manager** (See System Architecture Overview)

// 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
  1. 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)
  1. Extensibility**
• OSAdapter vtable pattern allows new transport types
• Just add new configuration structure
• Dispatcher routes to correct OSAdapter
• Existing code unaffected
  1. 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**

// See CHANNEL_CONFIGURATION.dox for complete example
tcp_config.remote_ip = "192.168.1.100";
tcp_config.remote_port = 5000;

Example 2: Local Shared Memory**

// See CHANNEL_CONFIGURATION.dox
shm_config.descriptor_path = "/dev/shm/rail_vital_ab";

Example 3: Mixed Transports (Dispatcher)**

// 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 OSAdapters (rte_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

system_architecture for overall system design