use crate::{ElementType, Error, Result};
#[allow(dead_code)]
pub(crate) const SCHEME_TAG: u8 = 0x02;
pub(crate) const ENCODED_LEN: usize = 20;
pub(crate) const SUPPORTED_VERSION: u8 = 0x01;
const ZP_SENTINEL: u32 = 0xFFFF_FFFF;
const SCALE_TYPE_TAG_FLOAT32: u8 = 0x03;
pub const FLAG_SYMMETRIC: u16 = 0b1;
pub const RESERVED_MASK: u16 = !FLAG_SYMMETRIC;
const OFFSET_AXIS: usize = 4;
const OFFSET_SCALE_BUF: usize = 8;
const OFFSET_ZP_BUF: usize = 12;
const OFFSET_SCALE_TYPE: usize = 16;
const OFFSET_RESERVED: usize = 17;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct PerChannelAffine {
axis: u32,
scale_buffer_index: u32,
zero_point_buffer_index: Option<u32>,
scale_type: ElementType,
}
impl PerChannelAffine {
pub fn new_asymmetric(
axis: u32,
scale_buffer_index: u32,
zero_point_buffer_index: u32,
) -> Result<Self> {
if scale_buffer_index == ZP_SENTINEL {
return Err(Error::InvalidQuantization(
"scale_buffer_index must not be 0xFFFFFFFF (reserved sentinel)".into(),
));
}
Ok(Self {
axis,
scale_buffer_index,
zero_point_buffer_index: Some(zero_point_buffer_index),
scale_type: ElementType::Float32,
})
}
pub fn new_symmetric(axis: u32, scale_buffer_index: u32) -> Result<Self> {
if scale_buffer_index == ZP_SENTINEL {
return Err(Error::InvalidQuantization(
"scale_buffer_index must not be 0xFFFFFFFF (reserved sentinel)".into(),
));
}
Ok(Self {
axis,
scale_buffer_index,
zero_point_buffer_index: None,
scale_type: ElementType::Float32,
})
}
#[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 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 valid_storage_types() -> &'static [ElementType] {
&[
ElementType::Int8,
ElementType::Uint8,
ElementType::Int16,
ElementType::Uint16,
ElementType::Int32,
ElementType::Uint32,
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 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 scale_buf == ZP_SENTINEL {
return Err(Error::InvalidQuantization(
"scale_buffer_index must not be 0xFFFFFFFF".into(),
));
}
if scale_type_byte != SCALE_TYPE_TAG_FLOAT32 {
return Err(Error::InvalidQuantization(format!(
"per-channel affine scale_type_tag must be 0x03 (float32) in v1, got 0x{scale_type_byte:02X}"
)));
}
if bytes[OFFSET_RESERVED..OFFSET_RESERVED + 3]
.iter()
.any(|&b| b != 0)
{
return Err(Error::InvalidQuantization(
"per-channel affine reserved bytes [17..20] 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 {
if zp_buf_raw == ZP_SENTINEL {
return Err(Error::InvalidQuantization(
"SYMMETRIC flag is not set but zero_point_buffer_index is 0xFFFFFFFF".into(),
));
}
Some(zp_buf_raw)
};
Ok(Self {
axis,
scale_buffer_index: scale_buf,
zero_point_buffer_index,
scale_type: ElementType::Float32,
})
}
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_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] = SCALE_TYPE_TAG_FLOAT32;
out[OFFSET_RESERVED..OFFSET_RESERVED + 3].fill(0);
}
pub(crate) fn flags(&self) -> u16 {
if self.is_symmetric() {
FLAG_SYMMETRIC
} else {
0
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{ElementType, Error};
#[test]
fn new_symmetric_sentinel_scale_buf_is_err() {
assert!(matches!(
PerChannelAffine::new_symmetric(0, 0xFFFF_FFFF),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn new_asymmetric_sentinel_scale_buf_is_err() {
assert!(matches!(
PerChannelAffine::new_asymmetric(0, 0xFFFF_FFFF, 1),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn new_symmetric_is_symmetric() {
let q = PerChannelAffine::new_symmetric(0, 1).unwrap();
assert!(q.is_symmetric());
assert_eq!(q.zero_point_buffer_index(), None);
}
#[test]
fn new_asymmetric_is_not_symmetric() {
let q = PerChannelAffine::new_asymmetric(0, 1, 2).unwrap();
assert!(!q.is_symmetric());
assert_eq!(q.zero_point_buffer_index(), Some(2));
}
#[test]
fn scale_type_is_always_float32() {
let q = PerChannelAffine::new_symmetric(0, 1).unwrap();
assert_eq!(q.scale_type(), ElementType::Float32);
}
fn encode_decode(q: &PerChannelAffine) -> PerChannelAffine {
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);
PerChannelAffine::decode_payload(flags, &buf).unwrap()
}
#[test]
fn round_trip_symmetric() {
let original = PerChannelAffine::new_symmetric(3, 5).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn round_trip_asymmetric() {
let original = PerChannelAffine::new_asymmetric(1, 2, 4).unwrap();
let decoded = encode_decode(&original);
assert_eq!(decoded, original);
}
#[test]
fn decode_payload_too_short_is_err() {
let short = vec![0u8; ENCODED_LEN - 1];
assert!(matches!(
PerChannelAffine::decode_payload(0, &short),
Err(Error::QuantizationDescriptorTooShort { .. })
));
}
#[test]
fn decode_payload_reserved_flag_bits_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&1u32.to_le_bytes());
buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[16] = 0x03; assert!(matches!(
PerChannelAffine::decode_payload(0x0002, &buf),
Err(Error::ReservedQuantizationFlagsBits { .. })
));
}
#[test]
fn decode_payload_sentinel_scale_buf_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[16] = 0x03;
assert!(matches!(
PerChannelAffine::decode_payload(FLAG_SYMMETRIC, &buf),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn decode_payload_wrong_scale_type_tag_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&1u32.to_le_bytes());
buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[16] = 0x01;
assert!(matches!(
PerChannelAffine::decode_payload(FLAG_SYMMETRIC, &buf),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn decode_payload_symmetric_flag_set_but_zp_not_sentinel_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&1u32.to_le_bytes());
buf[12..16].copy_from_slice(&2u32.to_le_bytes());
buf[16] = 0x03;
assert!(matches!(
PerChannelAffine::decode_payload(FLAG_SYMMETRIC, &buf),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn decode_payload_symmetric_flag_not_set_but_zp_sentinel_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&1u32.to_le_bytes());
buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[16] = 0x03;
assert!(matches!(
PerChannelAffine::decode_payload(0, &buf),
Err(Error::InvalidQuantization(_))
));
}
#[test]
fn decode_payload_nonzero_reserved_bytes_is_err() {
let mut buf = vec![0u8; ENCODED_LEN];
buf[0] = SCHEME_TAG;
buf[1] = SUPPORTED_VERSION;
buf[8..12].copy_from_slice(&1u32.to_le_bytes());
buf[12..16].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
buf[16] = 0x03;
buf[17] = 0xAB;
assert!(matches!(
PerChannelAffine::decode_payload(FLAG_SYMMETRIC, &buf),
Err(Error::InvalidQuantization(_))
));
}
}