wireforge 0.1.0__py3-none-any.whl

wireforge/_data/runtime/include/wireforge/byte_io.hpp

@@ -0,0 +1,387 @@
+/**
+ * @file byte_io.hpp
+ * @brief Host-independent reading and writing of integers, floats and bit groups.
+ */
+#ifndef WIREFORGE_BYTE_IO_HPP
+#define WIREFORGE_BYTE_IO_HPP
+
+#include "wireforge/bit_utils.hpp"
+#include "wireforge/span.hpp"
+#include "wireforge/status.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <limits>
+
+namespace wireforge {
+
+/// @brief Byte order of multi-byte values on the wire.
+enum class Endian : std::uint8_t {
+    Big,    ///< Most significant byte first.
+    Little, ///< Least significant byte first.
+};
+
+static_assert(std::numeric_limits<float>::is_iec559 && sizeof(float) == 4U,
+              "f32 requires IEEE-754 binary32");
+static_assert(std::numeric_limits<double>::is_iec559 && sizeof(double) == 8U,
+              "f64 requires IEEE-754 binary64");
+
+/// @brief Largest integer width in bytes.
+inline constexpr std::size_t kMaxWidth = 8U;
+
+/**
+ * @brief Stores the low @p width bytes of @p value at the start of @p out.
+ *
+ * Uses shifts only, so the result never depends on the host byte order.
+ * @param out Destination; must hold at least @p width bytes.
+ * @param value Value to store.
+ * @param width Number of bytes, 1..8.
+ * @param endian Byte order.
+ */
+constexpr void store_unsigned(Span<std::uint8_t> out, std::uint64_t value, std::size_t width,
+                              Endian endian) noexcept {
+    for (std::size_t index = 0U; index < width; ++index) {
+        const std::size_t byte_index = endian == Endian::Big ? width - 1U - index : index;
+        out[byte_index] = static_cast<std::uint8_t>((value >> (8U * index)) & 0xFFU);
+    }
+}
+
+/**
+ * @brief Loads an unsigned integer of @p width bytes from the start of @p input.
+ * @param input Source; must hold at least @p width bytes.
+ * @param width Number of bytes, 1..8.
+ * @param endian Byte order.
+ * @return The value, zero-extended to 64 bits.
+ */
+[[nodiscard]] constexpr std::uint64_t load_unsigned(Span<const std::uint8_t> input,
+                                                    std::size_t width, Endian endian) noexcept {
+    std::uint64_t value = 0U;
+    for (std::size_t index = 0U; index < width; ++index) {
+        const std::size_t byte_index = endian == Endian::Big ? index : width - 1U - index;
+        value = (value << 8U) | input[byte_index];
+    }
+    return value;
+}
+
+/// @brief true when @p width is a supported integer width (1..8 bytes).
+[[nodiscard]] constexpr bool valid_width(std::size_t width) noexcept {
+    return width >= 1U && width <= kMaxWidth;
+}
+
+/// @brief Number of bits in @p width bytes.
+[[nodiscard]] constexpr unsigned width_bits(std::size_t width) noexcept {
+    return narrow_to<unsigned>(width * 8U);
+}
+
+/**
+ * @brief Sequential writer over a caller-provided buffer.
+ *
+ * Every write returns a Status; a failing write changes neither the position nor the buffer.
+ * All functions except the float writers are constexpr.
+ */
+class ByteWriter {
+public:
+    /// @brief Writes into @p buffer starting at its first byte.
+    explicit constexpr ByteWriter(Span<std::uint8_t> buffer) noexcept : buffer_(buffer) {}
+
+    /// @brief Number of bytes written so far.
+    [[nodiscard]] constexpr std::size_t position() const noexcept { return position_; }
+    /// @brief Size of the buffer.
+    [[nodiscard]] constexpr std::size_t capacity() const noexcept { return buffer_.size(); }
+    /// @brief Bytes still free.
+    [[nodiscard]] constexpr std::size_t remaining() const noexcept {
+        return buffer_.size() - position_;
+    }
+    /// @brief The bytes written so far.
+    [[nodiscard]] constexpr Span<const std::uint8_t> written() const noexcept {
+        return Span<const std::uint8_t>(buffer_.first(position_));
+    }
+
+    /**
+     * @brief Writes an unsigned integer.
+     * @param value Value; must fit @p width bytes.
+     * @param width Number of bytes, 1..8.
+     * @param endian Byte order.
+     * @return Status::OutOfRange when @p value does not fit, Status::BufferTooSmall when the
+     *         buffer is full, Status::InvalidState for an unsupported @p width.
+     */
+    constexpr Status write_unsigned(std::uint64_t value, std::size_t width,
+                                    Endian endian) noexcept {
+        if (!valid_width(width)) {
+            return Status::InvalidState;
+        }
+        if (!fits_unsigned(value, width_bits(width))) {
+            return Status::OutOfRange;
+        }
+        if (remaining() < width) {
+            return Status::BufferTooSmall;
+        }
+        store_unsigned(buffer_.subspan(position_), value, width, endian);
+        position_ += width;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Writes a two's complement integer.
+     * @param value Value; must fit @p width bytes as a signed integer.
+     * @param width Number of bytes, 1..8.
+     * @param endian Byte order.
+     * @return As write_unsigned().
+     */
+    constexpr Status write_signed(std::int64_t value, std::size_t width, Endian endian) noexcept {
+        if (!valid_width(width)) {
+            return Status::InvalidState;
+        }
+        if (!fits_signed(value, width_bits(width))) {
+            return Status::OutOfRange;
+        }
+        return write_unsigned(to_twos_complement(value, width_bits(width)), width, endian);
+    }
+
+    /**
+     * @brief Overwrites @p width bytes at @p offset inside the already written region.
+     *
+     * Used to fill in length or checksum fields after the rest of a frame has been written.
+     * @return Status::InvalidLength when [offset, offset + width) is not fully written yet;
+     *         otherwise as write_unsigned().
+     */
+    constexpr Status write_unsigned_at(std::size_t offset, std::uint64_t value, std::size_t width,
+                                       Endian endian) const noexcept {
+        if (!valid_width(width)) {
+            return Status::InvalidState;
+        }
+        if (!fits_unsigned(value, width_bits(width))) {
+            return Status::OutOfRange;
+        }
+        if (offset > position_ || position_ - offset < width) {
+            return Status::InvalidLength;
+        }
+        store_unsigned(buffer_.subspan(offset), value, width, endian);
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Writes an IEEE-754 binary32 value through its bit pattern.
+     * @return Status::BufferTooSmall when fewer than 4 bytes are free.
+     */
+    Status write_f32(float value, Endian endian) noexcept {
+        std::uint32_t bits = 0U;
+        std::memcpy(&bits, &value, sizeof(bits));
+        return write_unsigned(bits, sizeof(bits), endian);
+    }
+
+    /**
+     * @brief Writes an IEEE-754 binary64 value through its bit pattern.
+     * @return Status::BufferTooSmall when fewer than 8 bytes are free.
+     */
+    Status write_f64(double value, Endian endian) noexcept {
+        std::uint64_t bits = 0U;
+        std::memcpy(&bits, &value, sizeof(bits));
+        return write_unsigned(bits, sizeof(bits), endian);
+    }
+
+    /**
+     * @brief Copies @p bytes.
+     * @return Status::BufferTooSmall when they do not fit.
+     */
+    constexpr Status write_bytes(Span<const std::uint8_t> bytes) noexcept {
+        if (remaining() < bytes.size()) {
+            return Status::BufferTooSmall;
+        }
+        for (std::size_t index = 0U; index < bytes.size(); ++index) {
+            buffer_[position_ + index] = bytes[index];
+        }
+        position_ += bytes.size();
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Writes @p count copies of @p value.
+     * @return Status::BufferTooSmall when they do not fit.
+     */
+    constexpr Status write_fill(std::uint8_t value, std::size_t count) noexcept {
+        if (remaining() < count) {
+            return Status::BufferTooSmall;
+        }
+        for (std::size_t index = 0U; index < count; ++index) {
+            buffer_[position_ + index] = value;
+        }
+        position_ += count;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Writes the container of a complete bit group.
+     * @return Status::InvalidState when @p packer is not complete; otherwise as write_unsigned().
+     */
+    constexpr Status write_bits(const BitPacker& packer, Endian endian) noexcept {
+        if (!packer.complete()) {
+            return Status::InvalidState;
+        }
+        return write_unsigned(packer.container(), packer.total_bits() / 8U, endian);
+    }
+
+private:
+    Span<std::uint8_t> buffer_;
+    std::size_t position_ = 0U;
+};
+
+/**
+ * @brief Sequential reader over a caller-provided buffer.
+ *
+ * A failing read changes neither the position nor its output argument. All functions except the
+ * float readers are constexpr.
+ */
+class ByteReader {
+public:
+    /// @brief Reads from @p buffer starting at its first byte.
+    explicit constexpr ByteReader(Span<const std::uint8_t> buffer) noexcept : buffer_(buffer) {}
+
+    /// @brief Number of bytes consumed so far.
+    [[nodiscard]] constexpr std::size_t position() const noexcept { return position_; }
+    /// @brief Size of the buffer.
+    [[nodiscard]] constexpr std::size_t size() const noexcept { return buffer_.size(); }
+    /// @brief Bytes not consumed yet.
+    [[nodiscard]] constexpr std::size_t remaining() const noexcept {
+        return buffer_.size() - position_;
+    }
+    /// @brief The bytes not consumed yet.
+    [[nodiscard]] constexpr Span<const std::uint8_t> rest() const noexcept {
+        return buffer_.subspan(position_);
+    }
+
+    /**
+     * @brief Reads an unsigned integer.
+     * @param[out] value Result, zero-extended.
+     * @param width Number of bytes, 1..8.
+     * @param endian Byte order.
+     * @return Status::Truncated when fewer than @p width bytes remain, Status::InvalidState for an
+     *         unsupported @p width.
+     */
+    constexpr Status read_unsigned(std::uint64_t& value, std::size_t width,
+                                   Endian endian) noexcept {
+        if (!valid_width(width)) {
+            return Status::InvalidState;
+        }
+        if (remaining() < width) {
+            return Status::Truncated;
+        }
+        value = load_unsigned(buffer_.subspan(position_), width, endian);
+        position_ += width;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Reads a two's complement integer and sign-extends it.
+     * @return As read_unsigned().
+     */
+    constexpr Status read_signed(std::int64_t& value, std::size_t width, Endian endian) noexcept {
+        std::uint64_t raw = 0U;
+        const Status status = read_unsigned(raw, width, endian);
+        if (status == Status::Ok) {
+            value = sign_extend(raw, width_bits(width));
+        }
+        return status;
+    }
+
+    /**
+     * @brief Reads @p width bytes at absolute @p offset without moving the position.
+     * @return Status::Truncated when the range is outside the buffer; otherwise as
+     *         read_unsigned().
+     */
+    constexpr Status peek_unsigned_at(std::size_t offset, std::uint64_t& value, std::size_t width,
+                                      Endian endian) const noexcept {
+        if (!valid_width(width)) {
+            return Status::InvalidState;
+        }
+        if (offset > buffer_.size() || buffer_.size() - offset < width) {
+            return Status::Truncated;
+        }
+        value = load_unsigned(buffer_.subspan(offset), width, endian);
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Reads an IEEE-754 binary32 value from its bit pattern.
+     * @return Status::Truncated when fewer than 4 bytes remain.
+     */
+    Status read_f32(float& value, Endian endian) noexcept {
+        std::uint64_t raw = 0U;
+        const Status status = read_unsigned(raw, sizeof(float), endian);
+        if (status == Status::Ok) {
+            const auto bits = static_cast<std::uint32_t>(raw);
+            std::memcpy(&value, &bits, sizeof(value));
+        }
+        return status;
+    }
+
+    /**
+     * @brief Reads an IEEE-754 binary64 value from its bit pattern.
+     * @return Status::Truncated when fewer than 8 bytes remain.
+     */
+    Status read_f64(double& value, Endian endian) noexcept {
+        std::uint64_t bits = 0U;
+        const Status status = read_unsigned(bits, sizeof(double), endian);
+        if (status == Status::Ok) {
+            std::memcpy(&value, &bits, sizeof(value));
+        }
+        return status;
+    }
+
+    /**
+     * @brief Copies out.size() bytes into @p out.
+     * @return Status::Truncated when not enough bytes remain.
+     */
+    constexpr Status read_bytes(Span<std::uint8_t> out) noexcept {
+        if (remaining() < out.size()) {
+            return Status::Truncated;
+        }
+        for (std::size_t index = 0U; index < out.size(); ++index) {
+            out[index] = buffer_[position_ + index];
+        }
+        position_ += out.size();
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Skips @p count bytes.
+     * @return Status::Truncated when not enough bytes remain.
+     */
+    constexpr Status skip(std::size_t count) noexcept {
+        if (remaining() < count) {
+            return Status::Truncated;
+        }
+        position_ += count;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Reads the container of a bit group and prepares an unpacker for its fields.
+     * @param[out] unpacker Replaced by an unpacker over the container on success.
+     * @param total_bits Width of the group: 8, 16, ..., 64.
+     * @param order Placement of the first field.
+     * @param endian Byte order of the container.
+     * @return Status::InvalidState for an invalid group width; otherwise as read_unsigned().
+     */
+    constexpr Status read_bits(BitUnpacker& unpacker, unsigned total_bits, BitOrder order,
+                               Endian endian) noexcept {
+        if (!BitUnpacker(0U, total_bits, order).valid()) {
+            return Status::InvalidState;
+        }
+        std::uint64_t container = 0U;
+        const Status status = read_unsigned(container, total_bits / 8U, endian);
+        if (status == Status::Ok) {
+            unpacker = BitUnpacker(container, total_bits, order);
+        }
+        return status;
+    }
+
+private:
+    Span<const std::uint8_t> buffer_;
+    std::size_t position_ = 0U;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_BYTE_IO_HPP

wireforge/_data/runtime/include/wireforge/checksum.hpp

@@ -0,0 +1,201 @@
+/**
+ * @file checksum.hpp
+ * @brief Checksum algorithm requirements and a parametric CRC engine.
+ *
+ * A checksum algorithm is a type @c C with only static members:
+ * @code
+ * struct MyChecksum {
+ *     static constexpr std::size_t kSize = 2;   // bytes of the value on the wire, 1..8
+ *     struct State { ... };                     // copyable running state
+ *     static State init() noexcept;
+ *     static void update(State&, wireforge::Span<const std::uint8_t>) noexcept; // any chunking
+ *     static std::uint64_t finalize(const State&) noexcept;
+ * };
+ * static_assert(wireforge::is_checksum_v<MyChecksum>);
+ * @endcode
+ * The finalized value is written with the byte order of the message that carries it.
+ */
+#ifndef WIREFORGE_CHECKSUM_HPP
+#define WIREFORGE_CHECKSUM_HPP
+
+#include "wireforge/array_access.hpp"
+#include "wireforge/bit_utils.hpp"
+#include "wireforge/config.hpp"
+#include "wireforge/span.hpp"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+
+namespace wireforge {
+
+/// @cond INTERNAL
+namespace detail {
+
+template <typename C>
+using ChecksumUpdate = decltype(C::update(std::declval<typename C::State&>(),
+                                          std::declval<Span<const std::uint8_t>>()));
+template <typename C>
+using ChecksumFinalize = decltype(C::finalize(std::declval<const typename C::State&>()));
+
+template <typename C>
+inline constexpr bool kChecksumSignatures =
+    std::is_same_v<decltype(C::init()), typename C::State> &&
+    std::is_same_v<ChecksumFinalize<C>, std::uint64_t> &&
+    std::is_convertible_v<decltype(C::kSize), std::size_t>;
+
+template <typename C> inline constexpr bool kChecksumSize = C::kSize >= 1U && C::kSize <= 8U;
+
+template <typename C>
+inline constexpr bool kChecksumNoexcept =
+    noexcept(C::init()) &&
+    noexcept(
+        C::update(std::declval<typename C::State&>(), std::declval<Span<const std::uint8_t>>())) &&
+    noexcept(C::finalize(std::declval<const typename C::State&>()));
+
+} // namespace detail
+/// @endcond
+
+/// @brief Detects whether @p C satisfies the checksum requirements (see the file description).
+template <typename C, typename = void> struct is_checksum : std::false_type {};
+
+/// @cond INTERNAL
+template <typename C>
+struct is_checksum<C, std::void_t<typename C::State, decltype(C::kSize), decltype(C::init()),
+                                  detail::ChecksumUpdate<C>, detail::ChecksumFinalize<C>>>
+    : std::bool_constant<detail::kChecksumSignatures<C> && detail::kChecksumSize<C> &&
+                         detail::kChecksumNoexcept<C>> {};
+/// @endcond
+
+/// @brief true when @p C is a checksum algorithm.
+template <typename C> inline constexpr bool is_checksum_v = is_checksum<C>::value;
+
+/**
+ * @brief Computes a checksum over one contiguous range.
+ * @tparam C Checksum algorithm.
+ * @param bytes Input data.
+ * @return The finalized checksum value.
+ */
+template <typename C>
+[[nodiscard]] std::uint64_t compute_checksum(Span<const std::uint8_t> bytes) noexcept {
+    static_assert(is_checksum_v<C>, "C must satisfy the checksum contract");
+    typename C::State state = C::init();
+    C::update(state, bytes);
+    return C::finalize(state);
+}
+
+/// @cond INTERNAL
+namespace detail {
+
+inline constexpr std::uint64_t kCrcTopBit = std::uint64_t{1U} << 63U;
+
+// Eight shift/xor steps of a left-aligned (bit 63 = top) CRC register.
+[[nodiscard]] constexpr std::uint64_t crc_step_byte(std::uint64_t reg,
+                                                    std::uint64_t aligned_poly) noexcept {
+    for (unsigned bit = 0U; bit < 8U; ++bit) {
+        reg = (reg & kCrcTopBit) != 0U ? (reg << 1U) ^ aligned_poly : reg << 1U;
+    }
+    return reg;
+}
+
+[[nodiscard]] constexpr std::array<std::uint64_t, 256>
+make_crc_table(std::uint64_t aligned_poly) noexcept {
+    std::array<std::uint64_t, 256> table{};
+    std::uint64_t index = 0U;
+    for (std::uint64_t& entry : table) {
+        entry = crc_step_byte(index << 56U, aligned_poly);
+        ++index;
+    }
+    return table;
+}
+
+// One read-only table per left-aligned polynomial, shared by every CRC that uses it.
+template <std::uint64_t AlignedPoly>
+inline constexpr std::array<std::uint64_t, 256> kCrcTable = make_crc_table(AlignedPoly);
+
+} // namespace detail
+/// @endcond
+
+/**
+ * @brief Parametric CRC in the Rocksoft model; satisfies the checksum requirements.
+ *
+ * The parameters are the ones listed in CRC catalogues ("width", "poly", "init", "refin",
+ * "refout", "xorout"). The table mode uses a shared 2 KiB constant table per polynomial; the
+ * table-less mode is slower and needs no table.
+ * @tparam Width CRC width in bits, 1..64.
+ * @tparam Poly Generator polynomial, normal (non-reflected) form.
+ * @tparam Init Initial register value.
+ * @tparam RefIn Reflect each input byte.
+ * @tparam RefOut Reflect the final register.
+ * @tparam XorOut Value XOR-ed into the result.
+ * @tparam UseTable Use the lookup table (default from config::kCrcUseTable).
+ */
+template <unsigned Width, std::uint64_t Poly, std::uint64_t Init, bool RefIn, bool RefOut,
+          std::uint64_t XorOut, bool UseTable = config::kCrcUseTable>
+class Crc {
+    static_assert(Width >= 1U && Width <= kMaxBits, "CRC width must be 1..64");
+    static_assert(fits_unsigned(Poly, Width) && fits_unsigned(Init, Width) &&
+                      fits_unsigned(XorOut, Width),
+                  "CRC parameters must fit the width");
+
+    static constexpr unsigned kShift = kMaxBits - Width;
+    static constexpr std::uint64_t kAlignedPoly = std::uint64_t{Poly} << kShift;
+
+public:
+    /// @brief Bytes of the CRC value on the wire.
+    static constexpr std::size_t kSize = (Width + 7U) / 8U;
+    /// @brief CRC width in bits.
+    static constexpr unsigned kWidth = Width;
+
+    /// @brief Running state of an incremental computation.
+    struct State {
+        std::uint64_t reg; ///< Register, left-aligned and non-reflected.
+    };
+
+    /// @brief Starts a computation.
+    [[nodiscard]] static constexpr State init() noexcept {
+        return State{std::uint64_t{Init} << kShift};
+    }
+
+    /**
+     * @brief Feeds @p bytes into @p state; may be called any number of times.
+     */
+    static constexpr void update(State& state, Span<const std::uint8_t> bytes) noexcept {
+        for (const std::uint8_t byte : bytes) {
+            const std::uint8_t input = RefIn ? static_cast<std::uint8_t>(reflect(byte, 8U)) : byte;
+            if constexpr (UseTable) {
+                const auto index = static_cast<std::uint8_t>((state.reg >> 56U) ^ input);
+                state.reg = (state.reg << 8U) ^ array_at(detail::kCrcTable<kAlignedPoly>, index);
+            } else {
+                state.reg =
+                    detail::crc_step_byte(state.reg ^ (std::uint64_t{input} << 56U), kAlignedPoly);
+            }
+        }
+    }
+
+    /// @brief Returns the CRC of all bytes fed into @p state.
+    [[nodiscard]] static constexpr std::uint64_t finalize(const State& state) noexcept {
+        const std::uint64_t value = state.reg >> kShift;
+        return (RefOut ? reflect(value, Width) : value) ^ XorOut;
+    }
+
+    /// @brief Computes the CRC of @p bytes in one call.
+    [[nodiscard]] static constexpr std::uint64_t compute(Span<const std::uint8_t> bytes) noexcept {
+        State state = init();
+        update(state, bytes);
+        return finalize(state);
+    }
+};
+
+/// @brief CRC-32/ISO-HDLC (the common "CRC-32"); check value 0xCBF43926.
+using Crc32 = Crc<32U, 0x04C11DB7U, 0xFFFFFFFFU, true, true, 0xFFFFFFFFU>;
+/// @brief CRC-16/CCITT-FALSE (CRC-16/IBM-3740); check value 0x29B1.
+using Crc16CcittFalse = Crc<16U, 0x1021U, 0xFFFFU, false, false, 0x0000U>;
+
+static_assert(is_checksum_v<Crc32>, "Crc32 must satisfy the checksum contract");
+
+} // namespace wireforge
+
+#endif // WIREFORGE_CHECKSUM_HPP