Documentation Index

Feature-Specific Documentation

Documentation is organized by feature, co-located with headers for easy discovery:

IPC Module (include/rte/ipc/)

• IPC_GUIDE.dox - Start here for IPC overview
  • Architecture layers, workflow, design principles
  • Links to all IPC documentation
• IPC_TRANSPORT_SELECTION.dox - Transport options
  • Shared Memory, FIFO, TCP/IP, UDP characteristics
  • POSIX vs RTOS OSAdapter differences
  • Decision tree for choosing transports
  • Real-world scenarios (railway, automotive, web service)
• CHANNEL_CONFIGURATION.dox - Configuration framework
  • Configuration structures for each transport type
  • How users specify IP addresses, ports, paths
  • Dispatcher callback pattern for mixed transports
  • Online/Standby examples
• rte_ipc.h - Base IPC API (code, not documentation)
  • OSAdapter vtable abstraction
  • OS-agnostic interface
• rte_ipc_request_reply.h - Request-Reply pattern (code)
  • RPC-style synchronous communication
  • Deadlock-free with timeouts
• rte_ipc_pubsub.h - Publish-Subscribe pattern (code)
  • One-to-many broadcasting
  • Asynchronous, decoupled

Vital Channel Module (include/rte/vital_channel/)

• ARCHITECTURE.dox - Vital channel design
  • Voting logic (2oo2, 2oo3, NMR)
  • Transport abstraction via callbacks
  • Safe-state trigger on disagreement
  • Integration with IPC transports
• CHANNEL_TOPOLOGIES.dox - Redundancy patterns
  • Pattern 1: Single-system 2oo2 (A ↔ B → C)
  • Pattern 2: Distributed 2oo2 (network)
  • Pattern 3: Hot standby with mirroring
  • Pattern 4: Triple redundancy (2oo3)
  • Decision tree for selecting topology
• rte_channel.h - Public API (code)
  • init(), send(), receive(), get_health()
  • Voting strategies and result codes

System-Wide Documentation (docs/)

• architecture/SYSTEM_OVERVIEW.dox - System layering and common-cause mitigation
  • Layered architecture (app manager, vital channels, IPC, OS)
  • Channel taxonomy (internal, inter-unit, inter-system)
  • Blocking semantics (vital, non-vital, async)
  • App Manager responsibilities
  • POSIX vs RTOS implementation differences
  • Complete railway train control example
• DOCUMENTATION_INDEX.dox - This file
  • Documentation organization
  • Reading paths for different roles

Reading Paths by Role

For System Architects

1. Start: docs/architecture/SYSTEM_OVERVIEW.dox
2. Then: include/rte/vital_channel/ARCHITECTURE.md
3. Then: include/rte/vital_channel/CHANNEL_TOPOLOGIES.md
4. Then: include/rte/ipc/IPC_GUIDE.md

For Integrators (Implementing for Your OS)

1. Start: include/rte/ipc/IPC_GUIDE.md
2. Then: include/rte/ipc/CHANNEL_CONFIGURATION.md
3. Then: include/rte/ipc/IPC_TRANSPORT_SELECTION.md
4. Implement: OS-specific OSAdapters (TCP, FIFO, SHM, UDP send/recv)
5. Example: examples/channel_configuration_example.c

For Application Developers

1. Start: include/rte/vital_channel/CHANNEL_TOPOLOGIES.md
   • Find your topology (2oo2 local, 2oo3 distributed, etc.)
2. Then: include/rte/ipc/CHANNEL_CONFIGURATION.md
   • Configure your channels (IPs, ports, paths)
3. Then: docs/architecture/SYSTEM_OVERVIEW.dox (section on App Manager)
   • Implement your main loop
4. Code: See examples/channel_configuration_example.c

For Safety/Compliance Engineers

1. Start: include/rte/vital_channel/ARCHITECTURE.md
   • Understand voting logic and safe-state
2. Then: include/rte/vital_channel/CHANNEL_TOPOLOGIES.md
   • Review redundancy patterns
3. Then: include/rte/ipc/IPC_TRANSPORT_SELECTION.md
   • Understand transport reliability characteristics
4. Reference: docs/architecture/SYSTEM_OVERVIEW.dox
   • Understand timeout handling and error propagation

Documentation Structure

Each module follows this structure:

include/rte/MODULE/
  ├─ MODULE.h              (API - code + Doxygen comments)
  ├─ ARCHITECTURE.dox       (How it works - technical design)
  ├─ GUIDE.md              (Overview + navigation)
  └─ CONFIG.md             (How to configure)

This co-location ensures:

• ✓ Documentation stays synchronized with code
• ✓ Easy discovery (docs live with headers)
• ✓ Clear relationships between modules
• ✓ Doxygen can link between pages

Quick Reference

Question	Document
How do channels communicate?	IPC_GUIDE.dox
Which transport should I use?	IPC_TRANSPORT_SELECTION.dox
How do I configure a channel?	CHANNEL_CONFIGURATION.dox
How does voting work?	vital_channel/ARCHITECTURE.md
What topology fits my system?	vital_channel/CHANNEL_TOPOLOGIES.md
How do I build the app manager?	architecture/SYSTEM_OVERVIEW.dox
What is POSIX vs RTOS?	architecture/SYSTEM_OVERVIEW.dox + IPC_TRANSPORT_SELECTION.dox
Show me working code	examples/channel_configuration_example.c

Generating HTML Documentation

All documentation uses Doxygen format. Generate HTML:

doxygen Doxyfile
# Output: docs/html/index.html

This creates:

• Full API reference (all .h files)
• Architecture pages (all .md files)
• Cross-linked navigation
• Search functionality

Contributing Documentation

When adding new modules:

1. Create MODULE/ARCHITECTURE.md - Technical design, how it works
2. Create MODULE/GUIDE.md - Navigation and overview
3. Create MODULE/CONFIGURATION.md (if applicable) - Configuration options
4. Add Doxygen comments to MODULE/MODULE.h - API documentation
5. Update this index with links and reading path