pcap.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file pcap.h
 * @brief libpcap file framing - the classic global + per-record headers, link-type agnostic.
 *
 * One owner for the PCAP framing shared by every capture feature (Wi-Fi promiscuous capture,
 * CAN / bus listen-only capture, ...): each writes its frames with the matching DLT link type so
 * the forwarded stream is a valid `.pcap` a wired Wireshark / tcpdump opens directly. Header-only
 * and pure (little-endian byte writes, no heap, no stdlib), host-identical.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_PCAP_H
#define PROTOCORE_PCAP_H
 
#include "endian/endian.h" // parva_extremitas.wr - libpcap headers are little-endian
 
#include "protocore_config.h" // the entry point: protocore_types.h for the widths
 
/** @brief libpcap header sizes. */
#define PROTOCORE_PCAP_GLOBAL_HDR_LEN 24
#define PROTOCORE_PCAP_REC_HDR_LEN 16
 
/** @brief Common libpcap DLT link-layer types. */
#define PROTOCORE_DLT_IEEE802_11 105         ///< raw 802.11 (Wi-Fi promiscuous capture)
#define PROTOCORE_DLT_CAN_SOCKETCAN 227      ///< Linux SocketCAN classic/FD frames
#define PROTOCORE_DLT_ETHERNET 1             ///< IEEE 802.3 Ethernet
#define PROTOCORE_DLT_IEEE802_15_4_NOFCS 230 ///< raw 802.15.4 MAC frame, no FCS
#define PROTOCORE_DLT_IEEE802_15_4_TAP 283   ///< 802.15.4 with a TAP pseudo-header (RSSI / channel TLVs)
#define PROTOCORE_DLT_RAW 101                ///< the record starts at the IP header, with no link layer
 
/** @brief Where a header is written, and the link type the file declares. */
typedef struct
{
    uint8_t *out;      ///< where the header lands
    size_t cap;        ///< how much room it has
    uint32_t linktype; ///< the DLT_* link type of the frames that follow
} PcapArgs;
 
/** @brief What one captured frame's record header states. */
typedef struct
{
    uint32_t ts_sec;  ///< capture time, whole seconds
    uint32_t ts_usec; ///< and microseconds within that second
    uint32_t caplen;  ///< octets actually stored
    uint32_t origlen; ///< octets the frame had on the wire
} PcapRecArgs;
 
/**
 * @brief The two libpcap headers a capture file is built from.
 *
 * @var PcapNs::args           where a header is written, and the link type the file declares
 * @var PcapNs::rec            what one captured frame's record header states
 * @var PcapNs::n              octets written, or 0 when the buffer is too small
 * @var PcapNs::global_header  the 24-byte file header (little-endian, microsecond timestamps)
 * @var PcapNs::record_header  the 16-byte per-frame header
 *
 * No storage member: both headers are written into the caller's buffer.
 */
typedef struct
{
    PcapArgs args;
    PcapRecArgs rec;
    size_t n;
} PcapVars;
 
/** @brief The operands and the outcome. */
extern PcapVars PcapV;
 
/** @brief The entries. */
typedef struct
{
    void (*const global_header)(uint8_t *work);
    void (*const record_header)(uint8_t *work);
} PcapNs;
 
// What the table binds, defined once in the .c and taking one parameter each: everything
// else an entry needs is an operand in PcapV or a region of the borrow at a fixed offset.
void protocore_pcap_global_header(uint8_t *work);
void protocore_pcap_record_header(uint8_t *work);
 
// `static const`, initialised HERE rather than `extern` against a definition in the .c: a
// const object whose initializer every translation unit can see is a COMPILE-TIME FACT, so
// `Pcap.global_header(work)` resolves to a named function and becomes a DIRECT call. An extern table
// leaves the call indirect and the symbol live at every level, -O2 -flto included.
static const PcapNs Pcap __attribute__((unused)) = {
    .global_header = protocore_pcap_global_header,
    .record_header = protocore_pcap_record_header,
};
 
#endif // PROTOCORE_PCAP_H