channel_configuration_example.c

Go to the documentation of this file.

 
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <stdio.h>
 
#include "rte/channel_link/rte_channel.h"
#include "rte/voter/rte_voter.h"
#include "rte/status/rte_status.h"
 
/* ============================================================================
 * Channel Configuration Structures (User fills these in)
 * ========================================================================== */

typedef struct {
    const char *name;
    const char *remote_ip;           // e.g., "192.168.1.100"
    uint16_t remote_port;            // e.g., 5000
    size_t message_size;             // e.g., 256
    uint32_t timeout_ms;             // e.g., 1000
    bool server_mode;                // true = listen, false = connect
} tcp_channel_config_t;

typedef struct {
    const char *name;
    const char *local_ip;            // e.g., "192.168.1.50"
    uint16_t local_port;             // e.g., 5001
    const char *remote_ip;           // e.g., "192.168.1.100"
    uint16_t remote_port;            // e.g., 5001
    size_t message_size;             // e.g., 256
    uint32_t timeout_ms;             // e.g., 500
} udp_channel_config_t;

typedef struct {
    const char *name;
    const char *descriptor_path;     // e.g., "/dev/shm/rte_channel"
    size_t message_size;             // e.g., 256
    size_t queue_depth;              // e.g., 10
    uint32_t timeout_ms;             // e.g., 100
} shm_channel_config_t;

typedef struct {
    const char *name;
    const char *fifo_path;           // e.g., "/tmp/rte_channel_fifo"
    size_t message_size;             // e.g., 256
    uint32_t timeout_ms;             // e.g., 500
    bool blocking;                   // true = blocking, false = non-blocking
} fifo_channel_config_t;
 
/* ============================================================================
 * Channel Type Identification (for dispatcher)
 * ========================================================================== */
 
typedef enum {
    CHANNEL_TYPE_TCP,
    CHANNEL_TYPE_UDP,
    CHANNEL_TYPE_SHM,
    CHANNEL_TYPE_FIFO,
} channel_type_t;

typedef struct {
    channel_type_t type;
    void *impl;  // Opaque pointer to actual channel (TCP/UDP/SHM/FIFO)
    uint32_t timeout_ms;
} channel_wrapper_t;
 
/* ============================================================================
 * Dispatcher Callbacks (User implements these)
 * ========================================================================== */

static rte_status_t app_backend_send(void *channel, const void *data, size_t size)
{
    channel_wrapper_t *wrapper = (channel_wrapper_t *)channel;
 
    if (wrapper == NULL) {
        return RTE_STATUS_INVALID_PARAM;
    }
 
    switch (wrapper->type) {
    case CHANNEL_TYPE_TCP:
        // TODO: Call actual TCP send
        // return tcp_send(wrapper->impl, data, size, wrapper->timeout_ms);
        printf("[TCP] Sending %zu bytes\n", size);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_UDP:
        // TODO: Call actual UDP send
        // return udp_send(wrapper->impl, data, size, wrapper->timeout_ms);
        printf("[UDP] Sending %zu bytes\n", size);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_SHM:
        // TODO: Call actual SHM send
        // return shm_send(wrapper->impl, data, size, wrapper->timeout_ms);
        printf("[SHM] Sending %zu bytes\n", size);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_FIFO:
        // TODO: Call actual FIFO send
        // return fifo_send(wrapper->impl, data, size, wrapper->timeout_ms);
        printf("[FIFO] Sending %zu bytes\n", size);
        return RTE_STATUS_OK;
 
    default:
        return RTE_STATUS_INVALID_PARAM;
    }
}

static rte_status_t app_backend_recv(void *channel, void *data, size_t size,
                                      uint32_t timeout_ms)
{
    channel_wrapper_t *wrapper = (channel_wrapper_t *)channel;
 
    if (wrapper == NULL) {
        return RTE_STATUS_INVALID_PARAM;
    }
 
    switch (wrapper->type) {
    case CHANNEL_TYPE_TCP:
        // TODO: Call actual TCP recv
        // return tcp_recv(wrapper->impl, data, size, timeout_ms);
        printf("[TCP] Receiving up to %zu bytes (timeout %ums)\n", size, timeout_ms);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_UDP:
        // TODO: Call actual UDP recv
        // return udp_recv(wrapper->impl, data, size, timeout_ms);
        printf("[UDP] Receiving up to %zu bytes (timeout %ums)\n", size, timeout_ms);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_SHM:
        // TODO: Call actual SHM recv
        // return shm_recv(wrapper->impl, data, size, timeout_ms);
        printf("[SHM] Receiving up to %zu bytes (timeout %ums)\n", size, timeout_ms);
        return RTE_STATUS_OK;
 
    case CHANNEL_TYPE_FIFO:
        // TODO: Call actual FIFO recv
        // return fifo_recv(wrapper->impl, data, size, timeout_ms);
        printf("[FIFO] Receiving up to %zu bytes (timeout %ums)\n", size, timeout_ms);
        return RTE_STATUS_OK;
 
    default:
        return RTE_STATUS_INVALID_PARAM;
    }
}
 
/* ============================================================================
 * Example 1: Online/Standby with TCP/IP (Primary Use Case)
 * ========================================================================== */
 
void example_tcp_based_redundancy(void)
{
    printf("\n=== Example 1: TCP/IP Based Online/Standby ===\n");
 
    /* ========================================================================
     * ONLINE HOST CONFIGURATION
     * ======================================================================== */
 
    printf("\n[ONLINE HOST] Configuration:\n");
 
    // User specifies TCP configuration for online host
    tcp_channel_config_t tcp_config_online = {
        .name = "online_to_standby_tcp",
        .remote_ip = "192.168.1.100",        // User provides standby IP
        .remote_port = 5000,                 // User chooses port
        .message_size = 256,
        .timeout_ms = 1000,
        .server_mode = false,                // Connect to standby (client)
    };
 
    printf("  ✓ TCP Config: %s → %s:%u\n", tcp_config_online.name,
           tcp_config_online.remote_ip, tcp_config_online.remote_port);
    printf("    Timeout: %ums\n", tcp_config_online.timeout_ms);
 
    // Optional: Add UDP for fast heartbeat
    udp_channel_config_t udp_config_online = {
        .name = "online_heartbeat_udp",
        .local_ip = "192.168.1.50",          // Online host IP
        .local_port = 5001,
        .remote_ip = "192.168.1.100",        // Standby host IP
        .remote_port = 5001,
        .message_size = 256,
        .timeout_ms = 500,
    };
 
    printf("  ✓ UDP Config: %s (heartbeat)\n", udp_config_online.name);
    printf("    Local: %s:%u\n", udp_config_online.local_ip, udp_config_online.local_port);
    printf("    Remote: %s:%u\n", udp_config_online.remote_ip, udp_config_online.remote_port);
 
    // Create wrapper channels, one rte_channel_t per transport (ADR-025:
    // a single "vital channel" type used to bundle N transports plus
    // voting; that split into one rte_channel_t per link registered
    // into a separate rte_voter_t for the voting itself).
    static channel_wrapper_t online_ch0 = {
        .type = CHANNEL_TYPE_TCP,
        .impl = (void *)0x1000,  // Placeholder (actual handle from OS OSAdapter)
        .timeout_ms = 1000,
    };
 
    static channel_wrapper_t online_ch1 = {
        .type = CHANNEL_TYPE_UDP,
        .impl = (void *)0x2000,  // Placeholder
        .timeout_ms = 500,
    };
 
    // Configure a voter for 2oo2 voting (both must agree)
    rte_voter_config_t voter_cfg_online = {
        .voting_strategy = RTE_VOTING_2OO2,
        .channel_timeout_ms = 1000,
        .log_disagreements = true,
        .on_disagreement = NULL,
        .disagreement_context = NULL,
    };
 
    static rte_channel_t online_channels[2];
    static rte_voter_t voter_online;
 
    rte_status_t rc = rte_voter_init(&voter_online, &voter_cfg_online);
    if (rc == RTE_STATUS_OK) {
        rte_channel_config_t chan_cfg0 = {
            .channel_handle = &online_ch0,
            .send = app_backend_send,    // User's dispatcher
            .recv = app_backend_recv,
        };
        rte_channel_config_t chan_cfg1 = {
            .channel_handle = &online_ch1,
            .send = app_backend_send,
            .recv = app_backend_recv,
        };
 
        rc = rte_channel_init(&online_channels[0], &chan_cfg0);
        if (rc == RTE_STATUS_OK) {
            rc = rte_voter_register_channel(&voter_online, &online_channels[0]);
        }
        if (rc == RTE_STATUS_OK) {
            rc = rte_channel_init(&online_channels[1], &chan_cfg1);
        }
        if (rc == RTE_STATUS_OK) {
            rc = rte_voter_register_channel(&voter_online, &online_channels[1]);
        }
    }
    if (rc == RTE_STATUS_OK) {
        printf("  ✓ Voter (2oo2) initialized over 2 channels\n");
    } else {
        printf("  ✗ Failed to initialize channels/voter\n");
        return;
    }
 
    /* ========================================================================
     * STANDBY HOST CONFIGURATION
     * ======================================================================== */
 
    printf("\n[STANDBY HOST] Configuration:\n");
 
    // Standby listens for TCP connections
    tcp_channel_config_t tcp_config_standby = {
        .name = "standby_listen_tcp",
        .remote_ip = "0.0.0.0",              // Listen on all interfaces
        .remote_port = 5000,                 // Same port as online's target
        .message_size = 256,
        .timeout_ms = 1000,
        .server_mode = true,                 // Listen (server mode)
    };
 
    printf("  ✓ TCP Config: %s (listening)\n", tcp_config_standby.name);
    printf("    Listen: %s:%u\n", tcp_config_standby.remote_ip, tcp_config_standby.remote_port);
 
    // Standby also receives UDP
    udp_channel_config_t udp_config_standby = {
        .name = "standby_heartbeat_udp",
        .local_ip = "192.168.1.100",         // Standby IP
        .local_port = 5001,
        .remote_ip = "192.168.1.50",         // Online IP (for feedback)
        .remote_port = 5001,
        .message_size = 256,
        .timeout_ms = 500,
    };
 
    printf("  ✓ UDP Config: %s (receiving)\n", udp_config_standby.name);
    printf("    Listen: %s:%u\n", udp_config_standby.local_ip, udp_config_standby.local_port);
 
    // Create channels with same configuration
    static channel_wrapper_t standby_ch0 = {
        .type = CHANNEL_TYPE_TCP,
        .impl = (void *)0x3000,
        .timeout_ms = 1000,
    };
 
    static channel_wrapper_t standby_ch1 = {
        .type = CHANNEL_TYPE_UDP,
        .impl = (void *)0x4000,
        .timeout_ms = 500,
    };
 
    static rte_channel_t standby_channels[2];
    static rte_voter_t voter_standby;
 
    rc = rte_voter_init(&voter_standby, &voter_cfg_online);
    if (rc == RTE_STATUS_OK) {
        rte_channel_config_t chan_cfg0 = {
            .channel_handle = &standby_ch0,
            .send = app_backend_send,
            .recv = app_backend_recv,
        };
        rte_channel_config_t chan_cfg1 = {
            .channel_handle = &standby_ch1,
            .send = app_backend_send,
            .recv = app_backend_recv,
        };
 
        rc = rte_channel_init(&standby_channels[0], &chan_cfg0);
        if (rc == RTE_STATUS_OK) {
            rc = rte_voter_register_channel(&voter_standby, &standby_channels[0]);
        }
        if (rc == RTE_STATUS_OK) {
            rc = rte_channel_init(&standby_channels[1], &chan_cfg1);
        }
        if (rc == RTE_STATUS_OK) {
            rc = rte_voter_register_channel(&voter_standby, &standby_channels[1]);
        }
    }
    if (rc == RTE_STATUS_OK) {
        printf("  ✓ Voter (2oo2) initialized over 2 channels\n");
    }
 
    /* ========================================================================
     * SIMULATION: Voting Communication
     * ======================================================================== */
 
    printf("\n[COMMUNICATION] Simulated voting:\n");
 
    uint8_t command[256] = {0x42};  // Dummy command
 
    printf("  1. Online broadcasts command via the voter...\n");
    rc = rte_voter_send(&voter_online, command, 256);
    printf("     Result: %d (broadcasts via TCP + UDP)\n", rc);
 
    printf("  2. Standby receives and votes...\n");
    uint8_t received[256] = {0};
    rte_voting_result_t vote = RTE_VOTING_AGREED;
    size_t bytes_received = 0;
    rc = rte_voter_receive(&voter_standby, received, 256, &vote, &bytes_received);
    printf("     Result: %d, Voting: %d\n", rc, vote);
 
    printf("  3. Check health...\n");
    rte_channel_health_t health;
    rc = rte_channel_get_health(&online_channels[0], &health);
    printf("     Channel 0 health: sends=%u, errors=%u\n",
           health.send_count, health.send_error_count);
}
 
/* ============================================================================
 * Example 2: Local Shared Memory Channels (Optional)
 * ========================================================================== */
 
void example_local_redundancy(void)
{
    printf("\n=== Example 2: Local Shared Memory (Optional For Same-Board) ===\n");
 
    // For same-board redundancy: Online A and Standby B on same CPU
    shm_channel_config_t shm_config = {
        .name = "vital_ab_shared",
        .descriptor_path = "/dev/shm/rail_vital_ab",  // User specifies path
        .message_size = 256,
        .queue_depth = 10,
        .timeout_ms = 100,  // Much tighter for local
    };
 
    printf("  Shared Memory Config:\n");
    printf("    Path: %s\n", shm_config.descriptor_path);
    printf("    Queue: %zu messages × %zu bytes\n",
           shm_config.queue_depth, shm_config.message_size);
    printf("    Timeout: %ums\n", shm_config.timeout_ms);
 
    static channel_wrapper_t shm_ch = {
        .type = CHANNEL_TYPE_SHM,
        .impl = (void *)0x5000,
        .timeout_ms = 100,
    };
 
    printf("  ✓ Channel created\n");
}
 
/* ============================================================================
 * Example 3: Hybrid Configuration
 * ========================================================================== */
 
void example_hybrid_configuration(void)
{
    printf("\n=== Example 3: Hybrid (TCP Primary, Local SHM Fallback) ===\n");
    printf("  For maximum flexibility: use TCP for remote, SHM for local\n");
    printf("  Dispatcher handles both transparently\n");
 
    // This allows:
    // - Channel 0: TCP to remote standby (50-100ms)
    // - Channel 1: SHM to local standby (< 1µs)
    // - Vital channel votes on both
    // - If TCP times out, still have SHM
    // - If both fail, safe-state triggered
}
 
int main(void)
{
    printf("========================================\n");
    printf("Channel Configuration Examples\n");
    printf("========================================\n");
 
    example_tcp_based_redundancy();
    example_local_redundancy();
    example_hybrid_configuration();
 
    printf("\n========================================\n");
    printf("Configuration Complete\n");
    printf("========================================\n");
    printf("\nKey Points:\n");
    printf("  ✓ User provides configuration values (IPs, ports, paths)\n");
    printf("  ✓ Framework handles voting and health tracking\n");
    printf("  ✓ OS integrator implements actual I/O (send/recv)\n");
    printf("  ✓ Dispatcher routes to correct transport\n");
    printf("  ✓ Same channel/voter code works with ANY transport\n");
 
    return 0;
}