use crate::{ElementType, Error, Result};
pub(crate) const SCHEME_TAG: u8 = 0x03;
pub(crate) const ENCODED_LEN: usize = 24;
pub(crate) const SUPPORTED_VERSION: u8 = 0x01;
const ZP_SENTINEL: u32 = 0xFFFF_FFFF;
pub const PER_BLOCK_AFFINE_MIN_BLOCK_SIZE: u32 = 2;
const MAX_BLOCK_SIZE: u32 = u32::MAX;
pub const FLAG_SYMMETRIC: u16 = 0b1;
pub const RESERVED_MASK: u16 = !FLAG_SYMMETRIC;
const VALID_SCALE_TYPE_TAGS: [u8; 3] = [0x01, 0x02, 0x03];
const OFFSET_AXIS: usize = 4;
const OFFSET_BLOCK_SIZE: usize = 8;
const OFFSET_SCALE_BUF: usize = 12;
const OFFSET_ZP_BUF: usize = 16;
const OFFSET_SCALE_TYPE: usize = 20;
const OFFSET_RESERVED: usize = 21;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct PerBlockAffine {
axis: u32,
block_size: u32,
scale_buffer_index: u32,
zero_point_buffer_index: Option<u32>,
scale_type: ElementType,
}
impl PerBlockAffine {
pub fn new_asymmetric(
axis: u32,
block_size: u32,
scale_buffer_index: u32,
zero_point_buffer_index: u32,
scale_type: ElementType,
) -> Result<Self> {
validate_block_size(block_size)?;
validate_scale_type(scale_type)?;
Ok(Self {
axis,
block_size,
scale_buffer_index,
zero_point_buffer_index: Some(zero_point_buffer_index),
scale_type,
})
}
pub fn new_symmetric(
axis: u32,
block_size: u32,
scale_buffer_index: u32,
scale_type: ElementType,
) -> Result<Self> {
validate_block_size(block_size)?;
validate_scale_type(scale_type)?;
Ok(Self {
axis,
block_size,
scale_buffer_index,
zero_point_buffer_index: None,
scale_type,
})
}
#[inline]
pub fn is_symmetric(&self) -> bool {
self.zero_point_buffer_index.is_none()
}
#[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
}
#[inline]
pub fn zero_point_buffer_index(&self) -> Option<u32> {
self.zero_point_buffer_index
}
#[inline]
pub fn scale_type(&self) -> ElementType {
self.scale_type
}
pub fn num_blocks_per_axis(&self, shape_axis: u64) -> u64 {
if shape_axis == 0 {
return 0;
}
shape_axis.div_ceil(self.block_size as u64)
}
pub fn validate_against_shape_axis(&self, shape_axis: u64) -> Result<()> {
if shape_axis == crate::shape::DYNAMIC {
return Err(Error::QuantizationShapeMismatch {
axis: self.axis,
shape_axis,
block_size: self.block_size,
reason: "shape[axis] must not be the DYNAMIC sentinel (0xFFFFFFFFFFFFFFFF)",
});
}
if shape_axis > 0 && self.block_size as u64 > shape_axis {
return Err(Error::QuantizationShapeMismatch {
axis: self.axis,
shape_axis,
block_size: self.block_size,
reason: "block_size must not exceed shape[axis] when shape[axis] > 0",
});
}
Ok(())
}
pub fn valid_storage_types() -> &'static [ElementType] {
&[
ElementType::Int8,
ElementType::Uint8,
ElementType::Int4,
ElementType::Uint4,
ElementType::Int2,
ElementType::Uint2,
]
}
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_MASK != 0 {
return Err(Error::ReservedQuantizationFlagsBits {
flags,
mask: RESERVED_MASK,
});
}
let symmetric = flags & FLAG_SYMMETRIC != 0;
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()))?,
);
let zp_buf_raw =
u32::from_le_bytes(bytes[OFFSET_ZP_BUF..OFFSET_ZP_BUF + 4].try_into().map_err(
|_| Error::InvalidQuantization("zero_point_buffer_index slice error".into()),
)?);
let scale_type_byte = bytes[OFFSET_SCALE_TYPE];
if !block_size.is_power_of_two() || block_size < PER_BLOCK_AFFINE_MIN_BLOCK_SIZE {
return Err(Error::InvalidBlockSize {
scheme_tag: SCHEME_TAG,
block_size,
min: PER_BLOCK_AFFINE_MIN_BLOCK_SIZE,
max: MAX_BLOCK_SIZE,
});
}
if !VALID_SCALE_TYPE_TAGS.contains(&scale_type_byte) {
return Err(Error::InvalidQuantization(format!(
"per-block affine scale_type_tag must be 0x01, 0x02, or 0x03, got 0x{scale_type_byte:02X}"
)));
}
let scale_type = ElementType::from_tag(scale_type_byte)?;
if bytes[OFFSET_RESERVED..OFFSET_RESERVED + 3]
.iter()
.any(|&b| b != 0)
{
return Err(Error::InvalidQuantization(
"per-block affine reserved bytes [21..24] must be 0x00".into(),
));
}
let zero_point_buffer_index = if symmetric {
if zp_buf_raw != ZP_SENTINEL {
return Err(Error::InvalidQuantization(
"SYMMETRIC flag is set but zero_point_buffer_index is not 0xFFFFFFFF".into(),
));
}
None
} else {
Some(zp_buf_raw)
};
Ok(Self {
axis,
block_size,
scale_buffer_index: scale_buf,
zero_point_buffer_index,
scale_type,
})
}
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());
let zp_wire = self.zero_point_buffer_index.unwrap_or(ZP_SENTINEL);
out[OFFSET_ZP_BUF..OFFSET_ZP_BUF + 4].copy_from_slice(&zp_wire.to_le_bytes());
out[OFFSET_SCALE_TYPE] = self.scale_type.tag();
out[OFFSET_RESERVED..OFFSET_RESERVED + 3].fill(0);
}
pub(crate) fn flags(&self) -> u16 {
if self.is_symmetric() {
FLAG_SYMMETRIC
} else {
0
}
}
}
fn validate_block_size(block_size: u32) -> Result<()> {
if !block_size.is_power_of_two() || block_size < PER_BLOCK_AFFINE_MIN_BLOCK_SIZE {
return Err(Error::InvalidBlockSize {
scheme_tag: SCHEME_TAG,
block_size,
min: PER_BLOCK_AFFINE_MIN_BLOCK_SIZE,
max: MAX_BLOCK_SIZE,
});
}
Ok(())
}
fn validate_scale_type(scale_type: ElementType) -> Result<()> {
if !VALID_SCALE_TYPE_TAGS.contains(&scale_type.tag()) {
return Err(Error::InvalidQuantization(format!(
"per-block affine scale_type must be Float16, BFloat16, or Float32, got {:?}",
scale_type
)));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{ElementType, Error};
#[test]
fn new_symmetric_block_size_not_power_of_two_is_err() {
assert!(matches!(
PerBlockAffine::new_symmetric(0, 3, 1, ElementType::Float32),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_symmetric_block_size_zero_is_err() {
assert!(matches!(
PerBlockAffine::new_symmetric(0, 0, 1, ElementType::Float32),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_symmetric_block_size_one_is_err() {
assert!(matches!(
PerBlockAffine::new_symmetric(0, 1, 1, ElementType::Float32),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_symmetric_sentinel_scale_buf_is_accepted() {
assert!(PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).is_ok());
}
#[test]
fn new_asymmetric_block_size_not_power_of_two_is_err() {
assert!(matches!(
PerBlockAffine::new_asymmetric(0, 6, 1, 2, ElementType::Float32),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_asymmetric_block_size_zero_is_err() {
assert!(matches!(
PerBlockAffine::new_asymmetric(0, 0, 1, 2, ElementType::Float32),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn new_symmetric_invalid_scale_type_is_err() {
assert!(matches!(
PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Int8),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn new_asymmetric_invalid_scale_type_is_err() {
assert!(matches!(
PerBlockAffine::new_asymmetric(0, 32, 1, 2, ElementType::Uint8),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn valid_scale_types_are_float16_bfloat16_float32() {
assert!(PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float16).is_ok());
assert!(PerBlockAffine::new_symmetric(0, 32, 1, ElementType::BFloat16).is_ok());
assert!(PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).is_ok());
}
#[test]
fn num_blocks_per_axis_zero_shape_returns_zero() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert_eq!(q.num_blocks_per_axis(0), 0);
}
#[test]
fn num_blocks_per_axis_exact_divisibility() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert_eq!(q.num_blocks_per_axis(64), 2);
}
#[test]
fn num_blocks_per_axis_partial_trailing_block_uses_div_ceil() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert_eq!(q.num_blocks_per_axis(65), 3);
}
#[test]
fn valid_storage_types_contains_integer_sub_byte_and_byte_types() {
let types = PerBlockAffine::valid_storage_types();
assert!(types.contains(&ElementType::Int8));
assert!(types.contains(&ElementType::Uint8));
assert!(types.contains(&ElementType::Int4));
assert!(types.contains(&ElementType::Uint4));
assert!(types.contains(&ElementType::Int2));
assert!(types.contains(&ElementType::Uint2));
}
#[test]
fn valid_storage_types_does_not_contain_float32() {
assert!(!PerBlockAffine::valid_storage_types().contains(&ElementType::Float32));
}
fn encode_decode(q: &PerBlockAffine) -> PerBlockAffine {
let mut buf = vec![0u8; ENCODED_LEN];
let flags = q.flags();
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = (flags & 0xFF) as u8;
buf[3] = (flags >> 8) as u8;
q.encode_payload(&mut buf);
PerBlockAffine::decode_payload(flags, &buf).unwrap()
}
#[test]
fn round_trip_symmetric() {
let original = PerBlockAffine::new_symmetric(1, 64, 2, ElementType::BFloat16).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn round_trip_asymmetric() {
let original = PerBlockAffine::new_asymmetric(0, 32, 1, 3, ElementType::Float16).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn validate_against_shape_axis_ok_when_block_size_le_shape() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert!(q.validate_against_shape_axis(32).is_ok());
assert!(q.validate_against_shape_axis(64).is_ok());
}
#[test]
fn validate_against_shape_axis_ok_when_shape_is_zero_adr007() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert!(q.validate_against_shape_axis(0).is_ok());
}
#[test]
fn validate_against_shape_axis_err_when_block_size_exceeds_shape() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert!(matches!(
q.validate_against_shape_axis(16),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn validate_against_shape_axis_err_for_dynamic_sentinel() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
assert!(matches!(
q.validate_against_shape_axis(u64::MAX),
Err(Error::QuantizationShapeMismatch { .. })
));
}
#[test]
fn decode_payload_too_short_is_err() {
let short = vec![0u8; ENCODED_LEN - 1];
assert!(matches!(
PerBlockAffine::decode_payload(0, &short),
Err(Error::QuantizationDescriptorTooShort { .. })
));
}
#[test]
fn decode_payload_nonzero_reserved_flags_is_err() {
let q = PerBlockAffine::new_symmetric(0, 32, 1, ElementType::Float32).unwrap();
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
let nonzero_flags: u16 = 0xFF00;
buf[2] = (nonzero_flags & 0xFF) as u8;
buf[3] = (nonzero_flags >> 8) as u8;
q.encode_payload(&mut buf);
assert!(matches!(
PerBlockAffine::decode_payload(nonzero_flags, &buf),
Err(Error::ReservedQuantizationFlagsBits { .. })
));
}
#[test]
fn decode_payload_invalid_block_size_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[2] = 0;
buf[3] = 0;
buf[4..8].copy_from_slice(&0u32.to_le_bytes());
buf[8..12].copy_from_slice(&33u32.to_le_bytes());
buf[12..16].copy_from_slice(&1u32.to_le_bytes());
buf[16..20].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[20] = 0x03;
assert!(matches!(
PerBlockAffine::decode_payload(0b1, &buf),
Err(Error::InvalidBlockSize { .. })
));
}
#[test]
fn decode_payload_invalid_scale_type_tag_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
let flags: u16 = 0b1;
buf[2] = (flags & 0xFF) as u8;
buf[3] = (flags >> 8) as u8;
buf[4..8].copy_from_slice(&0u32.to_le_bytes()); buf[8..12].copy_from_slice(&32u32.to_le_bytes()); buf[12..16].copy_from_slice(&1u32.to_le_bytes()); buf[16..20].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes()); buf[20] = 0x10; assert!(matches!(
PerBlockAffine::decode_payload(flags, &buf),
Err(Error::InvalidQuantization(_))
));
}
}