ihash 0.1.2

World's fastest high-quality non-cryptographic hash, deterministic cross-platform XOF, and seekable stream cipher
Documentation
use crate::{
  backend::mode::AesMode,
  state::{BLOCK_LEN, State, rd32_ptr, rd64_ptr, read_1_3},
};

/// Orthogonal 128-bit AES state operations mapped cleanly to native or software instructions.
///
/// Trait methods must omit `#[target_feature]` so LLVM inlines them directly into caller kernels.
pub(crate) trait Aes128: Copy {
  type V: Copy;
  type Mode: AesMode<Self>;
  /// Whether `prefetch_l1` emits an active hardware prefetch hint (disabled on Apple/ARM64 L1/L2 streamers).
  const HAS_PREFETCH: bool = false;

  unsafe fn zero(self) -> Self::V;
  unsafe fn ld(self, ptr: *const u8) -> Self::V;
  unsafe fn st(self, ptr: *mut u8, v: Self::V);
  unsafe fn to_state(self, v: Self::V) -> State;

  #[inline(always)]
  unsafe fn to_u32(self, v: Self::V) -> u32 {
    // SAFETY: forwarded from caller contract.
    unsafe { self.to_u128(v) as u32 }
  }

  #[inline(always)]
  unsafe fn to_u64(self, v: Self::V) -> u64 {
    // SAFETY: forwarded from caller contract.
    unsafe { self.to_u128(v) as u64 }
  }

  #[inline(always)]
  unsafe fn to_u128(self, v: Self::V) -> u128 {
    // SAFETY: forwarded from caller contract.
    u128::from_le_bytes(unsafe { self.to_state(v) })
  }

  unsafe fn seed_v(self, seed: u64) -> Self::V;
  unsafe fn pair_v(self, lo: u64, hi: u64) -> Self::V;
  /// Broadcasts a 32-bit word across all four AES columns (`[x, x, x, x]`).
  unsafe fn dup_u32(self, x: u32) -> Self::V;

  unsafe fn xor(self, a: Self::V, b: Self::V) -> Self::V;
  /// Vector `u64x2` wrapping addition.
  unsafe fn add_u64(self, a: Self::V, b: Self::V) -> Self::V;

  /// Loads two possibly overlapping 64-bit halves `(p0[..8], p1[..8])` into one 128-bit lane.
  #[inline(always)]
  unsafe fn load_pair_u64(self, p0: *const u8, p1: *const u8) -> Self::V {
    // SAFETY: caller guarantees >= 8 readable bytes at p0 and p1.
    unsafe { self.pair_v(rd64_ptr(p0, 0), rd64_ptr(p1, 0)) }
  }

  /// Loads two possibly overlapping 32-bit words `(p0[..4], p1[..4])` into the low 64 bits.
  #[inline(always)]
  unsafe fn load_pair_u32(self, p0: *const u8, p1: *const u8) -> Self::V {
    // SAFETY: caller guarantees >= 4 readable bytes at p0 and p1.
    unsafe {
      let lo = rd32_ptr(p0, 0) as u64;
      let hi = rd32_ptr(p1, 0) as u64;
      self.pair_v(lo | (hi << 32), 0)
    }
  }

  /// Zero-extends a 32-bit word into lane 0 of a 128-bit vector.
  #[inline(always)]
  unsafe fn u32_v(self, x: u32) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { self.pair_v(x as u64, 0) }
  }

  /// Loads `0..=16` bytes cleanly into a 128-bit lane without out-of-bounds access.
  #[inline(always)]
  unsafe fn load_short(self, ptr: *const u8, len: usize) -> Self::V {
    // SAFETY: caller guarantees len readable bytes at ptr and len <= BLOCK_LEN.
    unsafe {
      if len >= 8 {
        if len == BLOCK_LEN {
          return self.ld(ptr);
        }
        self.load_pair_u64(ptr, ptr.add(len - 8))
      } else if len >= 4 {
        self.load_pair_u32(ptr, ptr.add(len - 4))
      } else if len > 0 {
        self.u32_v(read_1_3(ptr, len))
      } else {
        self.zero()
      }
    }
  }

  /// Hints the CPU to prefetch the cache line containing `ptr` into L1 data cache.
  #[inline(always)]
  unsafe fn prefetch_l1(self, _ptr: *const u8) {}

  /// Interleaves the low and high 64-bit halves bytewise (`[b0, b8, b1, b9, ..., b7, b15]`).
  unsafe fn zip_u8(self, v: Self::V) -> Self::V;

  /// Computes `MC(SR(SB(a ^ b)))` with implicit zero post-key.
  #[inline(always)]
  unsafe fn r1_zero(self, a: Self::V, b: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::r1_zero(self, a, b) }
  }

  /// Executes `N + 1` chained AES rounds starting with `x0 ^ x1` and ending keyless.
  #[inline(always)]
  unsafe fn chain_x01<const N: usize>(
    self,
    x0: Self::V,
    x1: Self::V,
    rk_li: [Self::V; N],
  ) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::chain_x01(self, x0, x1, rk_li) }
  }

  /// Computes 3 chained AES rounds ending keyless: `F(F(F(x0 ^ x1) ^ x2) ^ x3)`.
  #[inline(always)]
  unsafe fn r3_zero(self, x0: Self::V, x1: Self::V, x2: Self::V, x3: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { self.chain_x01(x0, x1, [x2, x3]) }
  }

  /// Executes `N + 2` chained AES rounds starting with `x0 ^ x1`, terminating keyless with
  /// arithmetic Davies-Meyer feed-forward `F(u) +_{u64} u` where `u` is the penultimate state.
  #[inline(always)]
  unsafe fn chain_x01_ff<const N: usize>(
    self,
    x0: Self::V,
    x1: Self::V,
    mid_li: [Self::V; N],
  ) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe {
      let u = self.chain_x01(x0, x1, mid_li);
      self.add_u64(Self::Mode::f_zero(self, u), u)
    }
  }

  /// Computes 3 chained AES rounds (`F(u) +_{u64} u`, `u = F(F(x0 ^ x1) ^ k2)`).
  #[inline(always)]
  unsafe fn r3_ff(self, x0: Self::V, x1: Self::V, k2: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { self.chain_x01_ff(x0, x1, [k2]) }
  }

  #[inline(always)]
  unsafe fn acc_init_1(self, key: Self::V, data: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::acc_init_1(self, key, data) }
  }

  #[inline(always)]
  unsafe fn acc_absorb_1(self, acc: Self::V, data: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::acc_absorb_1(self, acc, data) }
  }

  #[inline(always)]
  unsafe fn ctr_prep_1(self, ctr: Self::V, rk0: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::ctr_prep_1(self, ctr, rk0) }
  }

  #[inline(always)]
  unsafe fn ctr_mid_1(self, s: Self::V, rk: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::ctr_mid_1(self, s, rk) }
  }

  #[inline(always)]
  unsafe fn ctr_fin_1(self, s: Self::V, rk3: Self::V, rk0: Self::V) -> Self::V {
    // SAFETY: forwarded from caller contract.
    unsafe { Self::Mode::ctr_fin_1(self, s, rk3, rk0) }
  }
}