use crate::{ElementType, Error, Result};
pub(crate) const SCHEME_TAG: u8 = 0x05;
pub(crate) const ENCODED_LEN: usize = 16;
pub(crate) const SUPPORTED_VERSION: u8 = 0x01;
pub const MXFP_MIN_BLOCK_SIZE: u32 = 16;
pub const MXFP_MAX_BLOCK_SIZE: u32 = 2048;
pub const MXFP_CANONICAL_BLOCK_SIZE: u32 = 32;
const RESERVED_FLAGS_MASK: u16 = 0xFFFF;
const INVALID_BUF_SENTINEL: u32 = 0xFFFF_FFFF;
const OFFSET_AXIS: usize = 4;
const OFFSET_BLOCK_SIZE: usize = 8;
const OFFSET_SCALE_BUF: usize = 12;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Mxfp {
axis: u32,
block_size: u32,
scale_buffer_index: u32,
}
impl Mxfp {
pub fn new(axis: u32, block_size: u32, scale_buffer_index: u32) -> Result<Self> {
validate_block_size(block_size)?;
Ok(Self {
axis,
block_size,
scale_buffer_index,
})
}
#[inline]
pub fn axis(&self) -> u32 {
self.axis
}
#[inline]
pub fn block_size(&self) -> u32 {
self.block_size
}
#[inline]
pub fn scale_buffer_index(&self) -> u32 {
self.scale_buffer_index
}
pub fn num_blocks_per_axis(&self, shape_axis: u64) -> Result<u64> {
if shape_axis == 0 || !shape_axis.is_multiple_of(self.block_size as u64) {
return Err(Error::QuantizationShapeMismatch {
axis: self.axis,
shape_axis,
block_size: self.block_size,
reason: "MXFP requires shape[axis] to be a positive multiple of block_size; partial trailing blocks are not permitted",
});
}
Ok(shape_axis / self.block_size as u64)
}
pub fn validate_against_shape_axis(&self, shape_axis: u64) -> Result<()> {
self.num_blocks_per_axis(shape_axis).map(|_| ())
}
pub fn validate_scale_bytes(&self, bytes: &[u8]) -> Result<()> {
for (i, &b) in bytes.iter().enumerate() {
if b == 0x00 || b == 0xFF {
return Err(Error::InvalidQuantization(format!(
"MXFP scale buffer byte at index {i} is 0x{b:02X}, which is a reserved \
float8_e8m0 NaN pattern (OCP MX v1.0 § 5.6); values 0x00 and 0xFF are \
forbidden in the scale buffer"
)));
}
}
Ok(())
}
pub fn valid_storage_types() -> &'static [ElementType] {
&[
ElementType::Float8E4M3, ElementType::Float8E5M2, ElementType::Float4E2M1, ElementType::Float6E2M3, ElementType::Float6E3M2, ElementType::Int8, ElementType::Int4, ]
}
pub(crate) fn decode_payload(flags: u16, bytes: &[u8]) -> Result<Self> {
if bytes.len() < ENCODED_LEN {
return Err(Error::QuantizationDescriptorTooShort {
found: bytes.len(),
needed: ENCODED_LEN,
});
}
if flags & RESERVED_FLAGS_MASK != 0 {
return Err(Error::ReservedQuantizationFlagsBits {
flags,
mask: RESERVED_FLAGS_MASK,
});
}
let axis = u32::from_le_bytes(
bytes[OFFSET_AXIS..OFFSET_AXIS + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("axis slice error".into()))?,
);
let block_size = u32::from_le_bytes(
bytes[OFFSET_BLOCK_SIZE..OFFSET_BLOCK_SIZE + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("block_size slice error".into()))?,
);
let scale_buf = u32::from_le_bytes(
bytes[OFFSET_SCALE_BUF..OFFSET_SCALE_BUF + 4]
.try_into()
.map_err(|_| Error::InvalidQuantization("scale_buffer_index slice error".into()))?,
);
validate_block_size(block_size)?;
if scale_buf == INVALID_BUF_SENTINEL {
return Err(Error::InvalidQuantization(
"MXFP scale_buffer_index must not be 0xFFFFFFFF".into(),
));
}
Ok(Self {
axis,
block_size,
scale_buffer_index: scale_buf,
})
}
pub(crate) fn encode_payload(&self, out: &mut [u8]) {
out[OFFSET_AXIS..OFFSET_AXIS + 4].copy_from_slice(&self.axis.to_le_bytes());
out[OFFSET_BLOCK_SIZE..OFFSET_BLOCK_SIZE + 4]
.copy_from_slice(&self.block_size.to_le_bytes());
out[OFFSET_SCALE_BUF..OFFSET_SCALE_BUF + 4]
.copy_from_slice(&self.scale_buffer_index.to_le_bytes());
}
}
fn validate_block_size(block_size: u32) -> Result<()> {
if !block_size.is_power_of_two()
|| !(MXFP_MIN_BLOCK_SIZE..=MXFP_MAX_BLOCK_SIZE).contains(&block_size)
{
return Err(Error::InvalidBlockSize {
scheme_tag: SCHEME_TAG,
block_size,
min: MXFP_MIN_BLOCK_SIZE,
max: MXFP_MAX_BLOCK_SIZE,
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{ElementType, Error};
#[test]
fn new_block_size_below_min_is_err() {
assert!(matches!(
Mxfp::new(0, 8, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_block_size_above_max_is_err() {
assert!(matches!(
Mxfp::new(0, 4096, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_block_size_not_power_of_two_is_err() {
assert!(matches!(
Mxfp::new(0, 48, 1),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_min_block_size_is_ok() {
assert!(Mxfp::new(0, MXFP_MIN_BLOCK_SIZE, 1).is_ok());
}
#[test]
fn new_canonical_block_size_is_ok() {
assert!(Mxfp::new(0, MXFP_CANONICAL_BLOCK_SIZE, 1).is_ok());
}
#[test]
fn new_max_block_size_is_ok() {
assert!(Mxfp::new(0, MXFP_MAX_BLOCK_SIZE, 1).is_ok());
}
#[test]
fn num_blocks_per_axis_zero_shape_is_err() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(matches!(
q.num_blocks_per_axis(0),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn num_blocks_per_axis_exact_divisibility_is_ok() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert_eq!(q.num_blocks_per_axis(64).unwrap(), 2);
}
#[test]
fn num_blocks_per_axis_not_divisible_is_err() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(matches!(
q.num_blocks_per_axis(65),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn validate_scale_bytes_empty_slice_is_ok() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(q.validate_scale_bytes(&[]).is_ok());
}
#[test]
fn validate_scale_bytes_valid_bytes_is_ok() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(q.validate_scale_bytes(&[0x01, 0x7F, 0x80, 0xFE]).is_ok());
}
#[test]
fn validate_scale_bytes_zero_byte_is_err() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(matches!(
q.validate_scale_bytes(&[0x01, 0x00, 0x7F]),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn validate_scale_bytes_0xff_is_err() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(matches!(
q.validate_scale_bytes(&[0x7F, 0xFF]),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn validate_scale_bytes_mixed_valid_and_invalid_is_err() {
let q = Mxfp::new(0, 32, 1).unwrap();
assert!(matches!(
q.validate_scale_bytes(&[0x7F, 0x00]),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn valid_storage_types_contains_expected_float_and_int_types() {
let types = Mxfp::valid_storage_types();
assert!(types.contains(&ElementType::Float8E4M3));
assert!(types.contains(&ElementType::Float8E5M2));
assert!(types.contains(&ElementType::Float4E2M1));
assert!(types.contains(&ElementType::Float6E2M3));
assert!(types.contains(&ElementType::Float6E3M2));
assert!(types.contains(&ElementType::Int8));
assert!(types.contains(&ElementType::Int4));
}
#[test]
fn valid_storage_types_does_not_contain_float32() {
assert!(!Mxfp::valid_storage_types().contains(&ElementType::Float32));
}
fn encode_decode(q: &Mxfp) -> Mxfp {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = 0;
buf[3] = 0;
q.encode_payload(&mut buf);
Mxfp::decode_payload(0, &buf).unwrap()
}
#[test]
fn round_trip_canonical_block_size() {
let original = Mxfp::new(0, MXFP_CANONICAL_BLOCK_SIZE, 3).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn round_trip_min_block_size() {
let original = Mxfp::new(1, MXFP_MIN_BLOCK_SIZE, 2).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn round_trip_max_block_size() {
let original = Mxfp::new(0, MXFP_MAX_BLOCK_SIZE, 1).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
}