#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum KvRole {
Key,
Value,
Fused,
}
impl KvRole {
#[inline]
pub fn wire_byte(self) -> u8 {
match self {
Self::Key => 0x00,
Self::Value => 0x01,
Self::Fused => 0x02,
}
}
#[inline]
pub fn from_wire(byte: u8) -> Option<Self> {
match byte {
0x00 => Some(Self::Key),
0x01 => Some(Self::Value),
0x02 => Some(Self::Fused),
_ => None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum BlockTableIndexType {
U32,
U64,
}
impl BlockTableIndexType {
#[inline]
pub fn wire_byte(self) -> u8 {
match self {
Self::U32 => 0x00,
Self::U64 => 0x01,
}
}
#[inline]
pub fn from_wire(byte: u8) -> Option<Self> {
match byte {
0x00 => Some(Self::U32),
0x01 => Some(Self::U64),
_ => None,
}
}
#[inline]
pub fn element_bytes(self) -> usize {
match self {
Self::U32 => 4,
Self::U64 => 8,
}
}
}
pub(crate) const LAYER_INDEX_NONE: u32 = 0xFFFF_FFFF;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct BlockPagedLayout {
pub page_size: u32,
pub num_pages: u64,
pub paged_axis: u32,
pub num_seqs: u32,
pub kv_role: KvRole,
pub layer_index: Option<u32>,
pub block_table_index_type: BlockTableIndexType,
}
impl BlockPagedLayout {
#[allow(clippy::too_many_arguments)]
pub fn new(
page_size: u32,
num_pages: u64,
paged_axis: u32,
num_seqs: u32,
kv_role: KvRole,
layer_index: Option<u32>,
block_table_index_type: BlockTableIndexType,
) -> Self {
Self {
page_size,
num_pages,
paged_axis,
num_seqs,
kv_role,
layer_index,
block_table_index_type,
}
}
pub fn validate_quantization_compatibility(
&self,
scheme_tag: u8,
quant_axis: u32,
quant_block_size: u32,
) -> crate::Result<()> {
const SCHEME_PER_CHANNEL: u8 = 0x02;
const SCHEME_PER_BLOCK_AFFINE: u8 = 0x03;
match scheme_tag {
SCHEME_PER_CHANNEL => {
if quant_axis == 0 {
return Err(crate::Error::InvalidQuantization(
"block-paged: per-channel quantization (scheme 0x02) MUST NOT be applied \
to the paged axis (axis 0); use axis 1 (num_heads) or axis 2 (head_dim)"
.to_string(),
));
}
}
SCHEME_PER_BLOCK_AFFINE => {
if quant_axis != 0 {
return Err(crate::Error::InvalidQuantization(format!(
"block-paged: per-block-affine quantization (scheme 0x03) requires \
axis = 0, got axis = {quant_axis}"
)));
}
if quant_block_size != self.page_size {
return Err(crate::Error::InvalidQuantization(format!(
"block-paged: per-block-affine quantization (scheme 0x03) requires \
block_size == page_size ({}), got block_size = {}",
self.page_size, quant_block_size
)));
}
}
_ => {}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::layout::LayoutDescriptor;
use std::num::NonZeroU8;
#[test]
fn kv_role_wire_byte_key_is_0x00() {
assert_eq!(KvRole::Key.wire_byte(), 0x00);
}
#[test]
fn kv_role_wire_byte_value_is_0x01() {
assert_eq!(KvRole::Value.wire_byte(), 0x01);
}
#[test]
fn kv_role_wire_byte_fused_is_0x02() {
assert_eq!(KvRole::Fused.wire_byte(), 0x02);
}
#[test]
fn kv_role_from_wire_round_trips_all_variants() {
for variant in [KvRole::Key, KvRole::Value, KvRole::Fused] {
let byte = variant.wire_byte();
let decoded = KvRole::from_wire(byte);
assert_eq!(
decoded,
Some(variant),
"KvRole::from_wire(0x{byte:02X}) should return {variant:?}"
);
}
}
#[test]
fn kv_role_from_wire_rejects_0x03() {
assert_eq!(KvRole::from_wire(0x03), None);
}
#[test]
fn kv_role_from_wire_rejects_0xff() {
assert_eq!(KvRole::from_wire(0xFF), None);
}
#[test]
fn block_table_index_type_wire_byte_u32_is_0x00() {
assert_eq!(BlockTableIndexType::U32.wire_byte(), 0x00);
}
#[test]
fn block_table_index_type_wire_byte_u64_is_0x01() {
assert_eq!(BlockTableIndexType::U64.wire_byte(), 0x01);
}
#[test]
fn block_table_index_type_from_wire_round_trips_all_variants() {
for variant in [BlockTableIndexType::U32, BlockTableIndexType::U64] {
let byte = variant.wire_byte();
let decoded = BlockTableIndexType::from_wire(byte);
assert_eq!(
decoded,
Some(variant),
"BlockTableIndexType::from_wire(0x{byte:02X}) should return {variant:?}"
);
}
}
#[test]
fn block_table_index_type_from_wire_rejects_0x02() {
assert_eq!(BlockTableIndexType::from_wire(0x02), None);
}
#[test]
fn block_table_index_type_from_wire_rejects_0xff() {
assert_eq!(BlockTableIndexType::from_wire(0xFF), None);
}
#[test]
fn block_table_index_type_element_bytes_u32_is_4() {
assert_eq!(BlockTableIndexType::U32.element_bytes(), 4);
}
#[test]
fn block_table_index_type_element_bytes_u64_is_8() {
assert_eq!(BlockTableIndexType::U64.element_bytes(), 8);
}
#[test]
fn layer_index_none_sentinel_value_is_0xffffffff() {
assert_eq!(LAYER_INDEX_NONE, 0xFFFF_FFFF);
}
#[test]
fn layer_index_some_zero_is_distinct_from_none() {
let layout_none =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, None, BlockTableIndexType::U32);
let layout_some_zero =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert_ne!(layout_none, layout_some_zero);
assert_eq!(layout_none.layer_index, None);
assert_eq!(layout_some_zero.layer_index, Some(0));
}
#[test]
fn layer_index_some_large_value_stored_correctly() {
let n = 0xFFFF_FFFE_u32; let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(n), BlockTableIndexType::U32);
assert_eq!(layout.layer_index, Some(n));
}
#[test]
fn block_paged_layout_tag_is_0x0a() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
let desc = LayoutDescriptor::BlockPaged(layout);
assert_eq!(desc.tag(), 0x0A);
}
#[test]
fn block_paged_buffer_count_is_3() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
let desc = LayoutDescriptor::BlockPaged(layout);
assert_eq!(desc.buffer_count(), NonZeroU8::new(3));
}
#[test]
fn quant_compat_per_tensor_always_accepted() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert!(layout
.validate_quantization_compatibility(0x01, 0, 0)
.is_ok());
assert!(layout
.validate_quantization_compatibility(0x01, 99, 999)
.is_ok());
}
#[test]
fn quant_compat_per_channel_on_axis_0_rejected() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
let result = layout.validate_quantization_compatibility(0x02, 0, 0);
assert!(result.is_err(), "per-channel on axis 0 must be rejected");
assert!(matches!(result, Err(crate::Error::InvalidQuantization(_))));
}
#[test]
fn quant_compat_per_channel_on_axis_1_accepted() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert!(layout
.validate_quantization_compatibility(0x02, 1, 0)
.is_ok());
}
#[test]
fn quant_compat_per_channel_on_axis_2_accepted() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert!(layout
.validate_quantization_compatibility(0x02, 2, 0)
.is_ok());
}
#[test]
fn quant_compat_per_block_affine_axis_0_block_size_eq_page_size_accepted() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert!(layout
.validate_quantization_compatibility(0x03, 0, 16)
.is_ok());
}
#[test]
fn quant_compat_per_block_affine_axis_nonzero_rejected() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
let result = layout.validate_quantization_compatibility(0x03, 1, 16);
assert!(
result.is_err(),
"per-block-affine with axis=1 must be rejected"
);
assert!(matches!(result, Err(crate::Error::InvalidQuantization(_))));
}
#[test]
fn quant_compat_per_block_affine_block_size_mismatch_rejected() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
let result = layout.validate_quantization_compatibility(0x03, 0, 32);
assert!(
result.is_err(),
"per-block-affine with block_size=32 != page_size=16 must be rejected"
);
assert!(matches!(result, Err(crate::Error::InvalidQuantization(_))));
}
#[test]
fn quant_compat_unknown_scheme_tag_passes() {
let layout =
BlockPagedLayout::new(16, 64, 0, 2, KvRole::Key, Some(0), BlockTableIndexType::U32);
assert!(layout
.validate_quantization_compatibility(0x04, 0, 0)
.is_ok());
assert!(layout
.validate_quantization_compatibility(0xFF, 0, 0)
.is_ok());
}
}