can_selftest.h

/*
 * The CAN (Controller Area Network) echo self-test: the first check when two
 * nodes are wired together.
 *
 * It answers one question: do frames cross this bus intact?  The initiator
 * sends a frame with a sequence number and a payload, the responder sends it
 * back unchanged, and the initiator compares it byte for byte.  No page map,
 * no registers, no state machine above it.  A passing test with a link that
 * does not work places the fault above the wire.  A wrong bit timing, a
 * missing terminator, a transceiver in the wrong mode and a dispatcher bug
 * all present as a panel that shows no numbers; this test separates the
 * first three from the fourth.
 *
 * The payloads exercise bit stuffing.  CAN stuffs a complementary bit after
 * five bits of the same polarity, so a marginal bus fails on long runs of one
 * level.  The first two payload bytes carry the sequence number; the other
 * six carry one of four patterns selected by it (0x00, 0xFF, 0x55, 0xAA),
 * and the echo is checked against the pattern it was sent with.
 *
 * The test runs at the lowest arbitration priority on a page the map does
 * not use, so it can run beside normal traffic without delaying it.
 *
 * SPDX-License-Identifier: MIT
 */
 
#ifndef RCBENCH_CAN_SELFTEST_H
#define RCBENCH_CAN_SELFTEST_H
 
#include <stdbool.h>
#include <stdint.h>
 
#include "link_can.h"
 
#ifdef __cplusplus
extern "C" {
#endif

#define CAN_SELFTEST_PAGE 0x7Eu

#define CAN_SELFTEST_MIN_PROBES 8u
 
typedef enum {
    CAN_SELFTEST_RUNNING = 0, 
    CAN_SELFTEST_OK,
    CAN_SELFTEST_SILENT,
    CAN_SELFTEST_CORRUPT,
    CAN_SELFTEST_LOSSY,
    CAN_SELFTEST_DROPPED,
} can_selftest_verdict_t;
 
typedef struct {
    uint32_t sent;
    uint32_t echoed;      
    uint32_t timed_out;
    uint32_t corrupt;     
    uint32_t stale;       
 
    uint16_t seq;         
    uint16_t outstanding; 
    bool     waiting;
    uint32_t sent_ms;
    uint32_t timeout_ms;
 
    uint32_t rtt_min_us;
    uint32_t rtt_max_us;

    uint32_t bus_errors;
} can_selftest_t;
 
void can_selftest_init(can_selftest_t *st, uint32_t timeout_ms);

bool can_selftest_probe(can_selftest_t *st, uint32_t now_ms,
                        link_can_frame_t *out);

bool can_selftest_rx(can_selftest_t *st, const link_can_frame_t *f,
                     uint32_t rtt_us);

bool can_selftest_tick(can_selftest_t *st, uint32_t now_ms);
 
can_selftest_verdict_t can_selftest_verdict(const can_selftest_t *st);
const char *can_selftest_text(can_selftest_verdict_t v);
const char *can_selftest_hint(can_selftest_verdict_t v);
 
/* ----------------------------------------------- the far end's own numbers */
 
/*
 * The IOmcu's view of the bus, carried across the bus in one 8-byte
 * frame on the self-test page at the lowest priority, so one console shows
 * both ends of a fault.
 *
 * It is polled: the IOmcu transmits only in answer to a request.
 */
typedef struct {
    bool     up;          
    uint8_t  tx_errors;   
    uint8_t  rx_errors;   
    uint8_t  flags;       
    uint16_t echoes;      
    uint16_t overflows;   
} can_remote_status_t;

bool can_selftest_status_request(link_can_frame_t *out);

bool can_selftest_status_reply(const link_can_frame_t *in,
                               const can_remote_status_t *st,
                               link_can_frame_t *out);

bool can_selftest_status_parse(const link_can_frame_t *in,
                               can_remote_status_t *out);

uint16_t can_selftest_return_loss(uint16_t before, uint16_t after,
                                  uint32_t heard);
 
/* ------------------------------------------------------------- responder */

bool can_selftest_echo(const link_can_frame_t *in, link_can_frame_t *out);
 
#ifdef __cplusplus
}
#endif
 
#endif /* RCBENCH_CAN_SELFTEST_H */