rlnc_simdx/
lib.rs

1//! # rlnc-simdx — Random Linear Network Coding over GF(2⁸)
2//!
3//! High-performance, `no_std`-compatible RLNC implementation with maximum
4//! SIMD acceleration across all major architectures.
5//!
6//! Crate: **`rlnc-simdx`** · use as `use rlnc_simdx::...`.
7//!
8//! ## ⚠️ Security & cryptography warning
9//!
10//! **This is a network-coding acceleration library, not a cryptography library.**
11//!
12//! - **Do not** use it to “encrypt” or obfuscate confidential data.
13//! - Field arithmetic is **not constant-time** — no side-channel resistance.
14//! - Built-in [`SimpleRng`] is a fast LFSR for coding coefficients, **not** a CSPRNG.
15//! - Authenticate and protect coded packets with external crypto (TLS, AEAD, etc.).
16//!
17//! ## Kernel safety (public API)
18//!
19//! - [`kernel::axpy`] / [`kernel::scale`]: equal lengths **and** non-overlapping
20//!   buffers are **asserted in release** (cheap pointer-range check).
21//! - For in-place scale use [`kernel::scale_inplace`].
22//! - Raw SIMD tier functions are **crate-private**; only the safe wrappers above
23//!   are part of the supported public surface.
24//!
25//! ## SIMD Tier Hierarchy
26//!
27//! With `std`, the library selects the best available kernel at runtime and
28//! caches that choice. Without `std`, it selects from compile-time target features.
29//!
30//! | Tier | Feature flags                   | Width   | Throughput |
31//! |------|---------------------------------|---------|------------|
32//! | 1    | GFNI + AVX-512BW                | 512-bit | ~64 B/cy   |
33//! | 2    | GFNI + AVX2                     | 256-bit | ~32 B/cy   |
34//! | 3    | GFNI + SSE4.2                   | 128-bit | ~16 B/cy   |
35//! | 4    | AVX-512BW + SSSE3               | 512-bit | ~11 B/cy   |
36//! | 5    | AVX2 + SSSE3                    | 256-bit | ~5 B/cy    |
37//! | 6    | SSSE3                           | 128-bit | ~3 B/cy    |
38//! | 7    | NEON (`AArch64`)                | 128-bit | ~3 B/cy    |
39//! | 8    | WASM SIMD128                    | 128-bit | ~3 B/cy    |
40//! | 9    | Scalar (all targets)            | 1 byte  | ~0.3 B/cy  |
41//!
42//! SVE is experimental, has no production kernel, and is not selected by dispatch.
43//!
44//! ## Feature Flags
45//!
46//! | Flag              | Default | Effect                                       |
47//! |-------------------|---------|----------------------------------------------|
48//! | `alloc`           | on      | Enables heap-backed RLNC APIs and `GfMatrix` |
49//! | `std`             | on      | Enables runtime CPU dispatch; implies alloc  |
50//! | `bench-internals` | off     | Unstable scalar/direct-tier benchmark APIs   |
51//!
52//! ## Quick Start
53//!
54//! ```rust
55//! use rlnc_simdx::{Encoder, Decoder, SimpleRng};
56//!
57//! let k = 4;   // generation size (number of source symbols)
58//! let n = 128; // symbol size (bytes)
59//!
60//! // Source data
61//! let source: Vec<Vec<u8>> = (0..k).map(|i| vec![i as u8; n]).collect();
62//! let refs: Vec<&[u8]> = source.iter().map(|v| v.as_slice()).collect();
63//!
64//! // Encode
65//! let enc = Encoder::new(k, n).unwrap();
66//! let mut rng = SimpleRng::new(42);
67//! let packets: Vec<_> = (0..k+2)
68//!     .map(|_| enc.encode_random(&refs, &mut rng).unwrap())
69//!     .collect();
70//!
71//! // Decode
72//! let mut dec = Decoder::new(k, n).unwrap();
73//! for pkt in packets {
74//!     dec.receive(pkt).unwrap();
75//!     if dec.is_complete() { break; }
76//! }
77//! let decoded = dec.decode().unwrap().unwrap();
78//! assert_eq!(decoded[0], source[0]);
79//! ```
80
81#![cfg_attr(not(feature = "std"), no_std)]
82#![warn(missing_docs)]
83#![warn(clippy::pedantic)]
84#![allow(clippy::module_name_repetitions)]
85#![allow(clippy::cast_possible_truncation)]
86// The API predates pedantic documentation/must-use coverage. These narrowly
87// scoped compatibility allows keep the strict workspace gate useful without
88// forcing unrelated public-API churn in this remediation pass.
89#![allow(clippy::missing_errors_doc)]
90#![allow(clippy::missing_panics_doc)]
91#![allow(clippy::must_use_candidate)]
92#![allow(clippy::needless_pass_by_value)]
93
94// Pull in alloc crate for no_std + alloc builds.
95#[cfg(all(feature = "alloc", not(feature = "std")))]
96extern crate alloc;
97
98#[cfg(feature = "alloc")]
99pub mod aligned;
100#[cfg(feature = "alloc")]
101pub mod decoder;
102#[cfg(feature = "alloc")]
103pub mod encoder;
104pub mod error;
105pub mod field;
106pub mod kernel;
107#[cfg(feature = "alloc")]
108pub mod matrix;
109#[cfg(feature = "alloc")]
110pub mod recoder;
111
112// Re-export the most commonly used types at crate root.
113pub use error::RlncError;
114pub use field::Gf8;
115
116#[cfg(feature = "alloc")]
117pub use aligned::AlignedBuffer;
118#[cfg(feature = "alloc")]
119pub use decoder::Decoder;
120#[cfg(feature = "alloc")]
121pub use encoder::{CodedPacket, Encoder, SimpleRng};
122#[cfg(feature = "alloc")]
123pub use matrix::GfMatrix;
124#[cfg(feature = "alloc")]
125pub use recoder::Recoder;
126
127/// Returns the name of the SIMD kernel tier active for this build.
128///
129/// Useful for diagnostics and benchmarking.
130///
131/// # Example
132/// ```rust
133/// println!("Active kernel: {}", rlnc_simdx::active_kernel());
134/// ```
135#[must_use]
136pub fn active_kernel() -> &'static str {
137    kernel::active_kernel_name()
138}
rlnc_simdx/lib.rs

rlnc_simdx/
lib.rs
