station_abi.h
http-3.0/station/station_abi.h · 155 line(s) · c
/* ==========================================================================
* station_abi.h -- shared ABI between the SLeeLa HTTP 3.0 Station kernel driver
* (http-3.0/kernel/sleela_station.ko) and userland (http-3.0/station/).
*
* The Station is a Router function that WITNESSES a two-party negotiation over
* TCP/IP control semantics. Clients do not (yet) exchange payload; they signal
* INTENT using TCP control flags (URG/ACK/SYN/...) plus a HOP distance encoding
* (DIST+0 / DIST+1). The Station classifies each signal into a CONDITION,
* advances a three-phase premise (start / intermediary / cancelling), and
* records the negotiation, including the terminal states UNCLEAR, HUNG-UP, and
* DISASTROUS.
*
* This header is the single source of truth for the numbers on the wire and in
* the ioctl interface, so the kernel module and userland agree exactly.
* ========================================================================== */
#ifndef SLEELA_STATION_ABI_H
#define SLEELA_STATION_ABI_H
#ifdef __KERNEL__
#include <linux/types.h>
#include <linux/ioctl.h>
#else
#include <stdint.h>
#include <sys/ioctl.h>
#endif
#define SLEELA_STATION_ABI_VERSION 1u
/* Character device the driver exposes; userland opens /dev/<name>. */
#define SLEELA_STATION_DEVICE "sleela_station"
#define SLEELA_STATION_DEVPATH "/dev/" SLEELA_STATION_DEVICE
/* ----------------------------------------------------------------------------
* TCP control-flag vocabulary (RFC 793 bit positions). The Station reads these
* from the TCP header of signaling segments; combinations carry meaning.
* -------------------------------------------------------------------------- */
#define SL_TCP_FIN 0x01u
#define SL_TCP_SYN 0x02u
#define SL_TCP_RST 0x04u
#define SL_TCP_PSH 0x08u
#define SL_TCP_ACK 0x10u
#define SL_TCP_URG 0x20u
#define SL_TCP_ECE 0x40u
#define SL_TCP_CWR 0x80u
/* The negotiation uses the URGENT pointer count as a small signal integer.
* "8 URG" (SL_STATION_URG_MAX) is the full-scale signal that selects a premise
* bank; fewer URG units select within a bank. */
#define SL_STATION_URG_MAX 8u
/* ----------------------------------------------------------------------------
* HOP distance encoding. DIST is the Station's own hop index on the path.
* A signaling segment carries a hop field; its relation to DIST is the verb:
* DIST + 0 -> HOLD : witness/record at the current station (no advance)
* DIST + 1 -> ADVANCE: move the premise forward one phase
* DIST - 1 -> CANCEL : withdraw/roll back the current premise
* -------------------------------------------------------------------------- */
typedef enum {
SL_HOP_CANCEL = -1, /* DIST-1 */
SL_HOP_HOLD = 0, /* DIST+0 */
SL_HOP_ADVANCE = 1 /* DIST+1 */
} sl_hop_verb_t;
/* ----------------------------------------------------------------------------
* Conditions the Station classifies a signal into (the "Intentional Condition,
* Legal Condition, Warning Condition, etc." of the design).
* -------------------------------------------------------------------------- */
typedef enum {
SL_COND_NONE = 0,
SL_COND_INTENTIONAL = 1, /* a deliberate premise offer/step */
SL_COND_LEGAL = 2, /* a legally-framed assertion (carries dressing)*/
SL_COND_WARNING = 3, /* a caution; proceed only with acknowledgement */
SL_COND_EMERGENCY = 4 /* time-critical; expedited witnessing */
} sl_condition_t;
/* ----------------------------------------------------------------------------
* The three-phase premise of a negotiation turn.
* -------------------------------------------------------------------------- */
typedef enum {
SL_PREMISE_START = 0, /* opening premise (what I propose to send) */
SL_PREMISE_INTERMEDIARY = 1, /* mediated/counter premise */
SL_PREMISE_CANCELLING = 2 /* withdrawal of a premise */
} sl_premise_t;
/* ----------------------------------------------------------------------------
* Negotiation outcome / terminal state as witnessed by the Station.
* -------------------------------------------------------------------------- */
typedef enum {
SL_STATE_IDLE = 0,
SL_STATE_OPEN = 1, /* negotiation in progress */
SL_STATE_CLEAR = 2, /* both parties agreed on what to send */
SL_STATE_UNCLEAR = 3, /* ended without a definite agreement */
SL_STATE_HUNG_UP = 4, /* a party stopped responding */
SL_STATE_DISASTROUS = 5 /* RST/abort or contradictory/illegal premises */
} sl_state_t;
/* Which side of the two-party negotiation a signal came from. */
typedef enum { SL_PARTY_A = 0, SL_PARTY_B = 1 } sl_party_t;
/* ----------------------------------------------------------------------------
* A single signaling event as seen on the wire (what the Netfilter hook feeds
* the classifier). This is the raw evidence before classification.
* -------------------------------------------------------------------------- */
typedef struct {
uint32_t abi_version; /* = SLEELA_STATION_ABI_VERSION */
uint64_t session_id; /* negotiation this signal belongs to */
uint8_t party; /* sl_party_t */
uint8_t tcp_flags; /* OR of SL_TCP_* bits */
uint8_t urg_units; /* URGENT signal magnitude, 0..SL_STATION_URG_MAX*/
int8_t hop_delta; /* hop - DIST, i.e. sl_hop_verb_t */
uint64_t timestamp_ns; /* Station clock at observation */
} sl_signal_t;
/* ----------------------------------------------------------------------------
* The classifier's verdict for one signal (condition + premise + verb), and a
* witnessed record entry the Station stores.
* -------------------------------------------------------------------------- */
typedef struct {
uint64_t session_id;
uint8_t party; /* sl_party_t */
uint8_t condition; /* sl_condition_t */
uint8_t premise; /* sl_premise_t */
int8_t hop_verb; /* sl_hop_verb_t */
uint64_t timestamp_ns;
uint32_t sequence; /* monotonic index within the session */
} sl_record_t;
/* Snapshot of a session's witnessed state, returned by the query ioctl. */
typedef struct {
uint64_t session_id;
uint8_t state; /* sl_state_t */
uint8_t last_premise_a; /* sl_premise_t last seen from A */
uint8_t last_premise_b; /* sl_premise_t last seen from B */
uint8_t reserved;
uint32_t record_count; /* number of witnessed records */
uint64_t opened_ns;
uint64_t updated_ns;
} sl_session_view_t;
/* ----------------------------------------------------------------------------
* ioctl interface (the "known API" for direct calls into the driver).
* -------------------------------------------------------------------------- */
#define SL_IOC_MAGIC 0xB7
/* Open/register a new witnessed session; kernel fills session_id. */
#define SL_IOC_OPEN _IOWR(SL_IOC_MAGIC, 1, sl_session_view_t)
/* Feed one signaling event; kernel returns the classified record. */
#define SL_IOC_SIGNAL _IOWR(SL_IOC_MAGIC, 2, sl_signal_t)
/* Query a session's current witnessed view. */
#define SL_IOC_QUERY _IOWR(SL_IOC_MAGIC, 3, sl_session_view_t)
/* Close a session, sealing its stored record. */
#define SL_IOC_CLOSE _IOW (SL_IOC_MAGIC, 4, uint64_t)
#endif /* SLEELA_STATION_ABI_H */