From 4c83d349c0ec6b2854ca892c3f36b7d7cdd65300 Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sun, 8 Nov 2026 13:19:42 +0900 Subject: [PATCH 1/2] docs(hevc): plan sparse coefficient iteration Signed-off-by: Gunwoo Kim --- docs/design/hevc-entropy.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/design/hevc-entropy.md b/docs/design/hevc-entropy.md index 7ce7d5a67..c1d91f494 100644 --- a/docs/design/hevc-entropy.md +++ b/docs/design/hevc-entropy.md @@ -21,3 +21,18 @@ CABAC arithmetic and level decoding remain unchanged in the first candidate. Consider further restructuring or assembly only after measuring this safe candidate. Any later unsafe site must retain a safe reference, document its memory preconditions and compare both implementations on arbitrary bytes. + +## Sparse coefficient-level iteration + +Level decoding visits a 16-position group once to read greater-than-one +flags. Retain that pass and collect the significant positions in a `u16` +mask. The sign and remaining-level passes then visit only the set bits, +from the highest scan position to the lowest. Coefficient storage, +context transitions, sign hiding and Rice adaptation remain unchanged. + +Keep the original three-pass implementation as a test-only reference. +Compare output, coefficient flags, contexts, carried group state and the +complete CABAC state on arbitrary masks and byte sources, including +truncation and exhausted bin budgets. Exhaust the position-mask domain in +unit tests and run the differential target on Actions before measuring. +This candidate uses checked access only and introduces no assembly. From 4d4976c85d75b4a4d63d0e0bf99b7a7fc959129a Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sun, 8 Nov 2026 13:25:31 +0900 Subject: [PATCH 2/2] perf(hevc): visit only significant coefficient levels Signed-off-by: Gunwoo Kim --- crates/coreav-hevc/Cargo.toml | 1 + crates/coreav-hevc/fuzz/Cargo.toml | 9 +- .../coreav-hevc/fuzz/fuzz_targets/levels.rs | 7 + crates/coreav-hevc/src/cabac.rs | 12 ++ crates/coreav-hevc/src/lib.rs | 3 + crates/coreav-hevc/src/residual.rs | 154 ++++++++++++++++-- crates/coreav-hevc/src/residual/reference.rs | 95 +++++++++++ 7 files changed, 268 insertions(+), 13 deletions(-) create mode 100644 crates/coreav-hevc/fuzz/fuzz_targets/levels.rs create mode 100644 crates/coreav-hevc/src/residual/reference.rs diff --git a/crates/coreav-hevc/Cargo.toml b/crates/coreav-hevc/Cargo.toml index 8215040e4..621122471 100644 --- a/crates/coreav-hevc/Cargo.toml +++ b/crates/coreav-hevc/Cargo.toml @@ -13,6 +13,7 @@ publish = false default = [] native-hevc = ["dep:sha2", "dep:md-5", "dep:coreav-kernels-hevc", "coreav-kernels-hevc/native-hevc"] scalar = ["coreav-kernels-hevc?/scalar"] +test-support = [] [dependencies] sha2 = { version = "0.10", optional = true } diff --git a/crates/coreav-hevc/fuzz/Cargo.toml b/crates/coreav-hevc/fuzz/Cargo.toml index aea64f99a..1cd32aaa8 100644 --- a/crates/coreav-hevc/fuzz/Cargo.toml +++ b/crates/coreav-hevc/fuzz/Cargo.toml @@ -12,7 +12,7 @@ cargo-fuzz = true [dependencies] libfuzzer-sys = "0.4" -coreav-hevc = { path = "..", features = ["native-hevc"] } +coreav-hevc = { path = "..", features = ["native-hevc", "test-support"] } [[bin]] name = "intra" @@ -35,5 +35,12 @@ test = false doc = false bench = false +[[bin]] +name = "levels" +path = "fuzz_targets/levels.rs" +test = false +doc = false +bench = false + [lints.rust] unsafe_code = "forbid" diff --git a/crates/coreav-hevc/fuzz/fuzz_targets/levels.rs b/crates/coreav-hevc/fuzz/fuzz_targets/levels.rs new file mode 100644 index 000000000..5fca6d68a --- /dev/null +++ b/crates/coreav-hevc/fuzz/fuzz_targets/levels.rs @@ -0,0 +1,7 @@ +#![no_main] + +libfuzzer_sys::fuzz_target!(|data: &[u8]| { + if data.len() <= 4099 { + assert!(coreav_hevc::coefficient_levels_match_reference(data)); + } +}); diff --git a/crates/coreav-hevc/src/cabac.rs b/crates/coreav-hevc/src/cabac.rs index d0137f859..24ebe99dc 100644 --- a/crates/coreav-hevc/src/cabac.rs +++ b/crates/coreav-hevc/src/cabac.rs @@ -62,6 +62,18 @@ pub(crate) struct Cabac<'a, 'b> { } impl<'a, 'b> Cabac<'a, 'b> { + #[cfg(any(test, feature = "test-support"))] + pub(crate) fn snapshot(&self) -> (usize, u16, u16, bool, u8, u64) { + ( + self.position(), + self.range, + self.offset, + self.last_bit, + self.phase as u8, + *self.remaining_bin_budget, + ) + } + pub(crate) fn new(bytes: &'a [u8], remaining_bin_budget: &'b mut u64) -> Result { let mut decoder = Self { input: Bits::new(bytes), diff --git a/crates/coreav-hevc/src/lib.rs b/crates/coreav-hevc/src/lib.rs index 4e9ecaaf7..ea7f53e2d 100644 --- a/crates/coreav-hevc/src/lib.rs +++ b/crates/coreav-hevc/src/lib.rs @@ -35,6 +35,9 @@ pub use intra::{IntraLimits, IntraPicture, IntraPictureDecoder, IntraPlane, Intr pub use nal::{AnnexB, LengthPrefixed, NalHeader, packet_nal}; pub use parser::{HeaderParser, NalInfo, PictureInfo, Summary}; pub use reconstruction::InterStats; +#[cfg(feature = "test-support")] +#[doc(hidden)] +pub use residual::coefficient_levels_match_reference; pub use rps::Rps; pub use sei::{PictureHash, SeiInfo}; pub use slice::{LongTermRef, SliceHeader}; diff --git a/crates/coreav-hevc/src/residual.rs b/crates/coreav-hevc/src/residual.rs index b13b72f51..072fa1d3e 100644 --- a/crates/coreav-hevc/src/residual.rs +++ b/crates/coreav-hevc/src/residual.rs @@ -1,6 +1,8 @@ use crate::cabac::{Cabac, Context, Initialization}; use crate::{Error, Result}; +#[cfg(any(test, feature = "test-support"))] +mod reference; mod scan; const LAST_INIT: [u8; 18] = [ @@ -46,7 +48,7 @@ const GREATER2_P_INIT: [u8; 6] = [107, 167, 91, 122, 107, 167]; const GREATER2_B_INIT: [u8; 6] = [107, 167, 91, 107, 107, 167]; const SIGNIFICANCE_4X4: [usize; 15] = [0, 1, 4, 5, 2, 3, 4, 5, 6, 6, 8, 8, 7, 7, 8]; -#[derive(Clone, Copy)] +#[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct Contexts { transform_skip: [Context; 2], last_x: [Context; 18], @@ -148,6 +150,7 @@ pub(crate) struct Decoded { pub sign_hidden_groups: u64, } +#[derive(Clone, Copy, Debug, PartialEq, Eq)] struct LevelState { greater1: u8, hidden_groups: u64, @@ -421,7 +424,7 @@ fn significance_context(block: Block, x: usize, y: usize, neighbours: u8) -> Res } } -#[derive(Clone, Copy, Default)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] struct Coefficient { significant: bool, greater1: bool, @@ -441,6 +444,17 @@ fn advance_greater_context(context: u8, flag: bool) -> u8 { } } +fn significant_positions(mut mask: u16) -> impl Iterator { + core::iter::from_fn(move || { + if mask == 0 { + return None; + } + let position = 15 - mask.leading_zeros() as usize; + mask ^= 1 << position; + Some(position) + }) +} + fn decode_levels( bins: &mut impl Bins, contexts: &mut Contexts, @@ -456,10 +470,12 @@ fn decode_levels( let mut first = 16; let mut last = 0; let mut first_greater1 = None; + let mut significance = 0u16; for (position, coefficient) in coefficients.iter_mut().enumerate().rev() { if !coefficient.significant { continue; } + significance |= 1 << position; if count == 0 { last = position; } @@ -489,22 +505,25 @@ fn decode_levels( } let hidden = sign_data_hiding && last - first > 3; state.hidden_groups += u64::from(hidden); - for (position, coefficient) in coefficients.iter_mut().enumerate().rev() { - if coefficient.significant && !(hidden && position == first) { + for position in significant_positions(significance) { + let coefficient = coefficients + .get_mut(position) + .ok_or(Error::InvalidData("residual_coefficient"))?; + if !(hidden && position == first) { coefficient.negative = bins.bypass()?; } } let mut levels = [0; 16]; - let mut significant_count = 0; let mut sum = 0; let mut rice = 0; let mut previous_abs = 0; - for (position, (coefficient, level)) in - coefficients.iter().zip(levels.iter_mut()).enumerate().rev() - { - if !coefficient.significant { - continue; - } + for (significant_count, position) in significant_positions(significance).enumerate() { + let coefficient = coefficients + .get(position) + .ok_or(Error::InvalidData("residual_coefficient"))?; + let level = levels + .get_mut(position) + .ok_or(Error::InvalidData("residual_coefficient"))?; let base = 1 + u32::from(coefficient.greater1) + u32::from(coefficient.greater2); let threshold = if significant_count < 8 { if Some(position) == first_greater1 { @@ -530,7 +549,6 @@ fn decode_levels( sum += magnitude; let negative = coefficient.negative || (hidden && position == first && sum & 1 != 0); *level = signed_level(magnitude, negative)?; - significant_count += 1; } Ok(levels) } @@ -542,6 +560,73 @@ fn signed_level(magnitude: u32, negative: bool) -> Result { .map_err(|_| Error::InvalidData("coefficient_level")) } +#[cfg(any(test, feature = "test-support"))] +#[doc = "Compares sparse and serial coefficient-level parsing on bounded input."] +pub fn coefficient_levels_match_reference(data: &[u8]) -> bool { + let Some(header) = data.get(..3) else { + return true; + }; + let Some(source) = data.get(3..data.len().min(4099)) else { + return true; + }; + let mut header = header.iter().copied(); + let mask = u16::from(header.next().unwrap_or(0)) | (u16::from(header.next().unwrap_or(0)) << 8); + let choice = header.next().unwrap_or(0); + let mut sparse_coefficients = [Coefficient::default(); 16]; + for (position, coefficient) in sparse_coefficients.iter_mut().enumerate() { + coefficient.significant = mask & (1 << position) != 0; + } + let mut serial_coefficients = sparse_coefficients; + let initialization = match choice % 3 { + 0 => Initialization::I, + 1 => Initialization::P, + _ => Initialization::B, + }; + let mut sparse_contexts = Contexts::new(i32::from(choice >> 2), initialization); + let mut serial_contexts = sparse_contexts; + let component = if choice & 1 == 0 { + Component::Luma + } else { + Component::Chroma + }; + let group = usize::from(choice & 63); + let mut sparse_state = LevelState::new((choice >> 4) & 3); + let mut serial_state = sparse_state; + let mut sparse_budget = u64::from(choice & 15) * 32; + let mut serial_budget = sparse_budget; + let (mut sparse, mut serial) = match ( + Cabac::new(source, &mut sparse_budget), + Cabac::new(source, &mut serial_budget), + ) { + (Ok(sparse), Ok(serial)) => (sparse, serial), + (Err(a), Err(b)) => return a == b, + _ => return false, + }; + let a = decode_levels( + &mut sparse, + &mut sparse_contexts, + &mut sparse_coefficients, + component, + group, + choice & 2 != 0, + &mut sparse_state, + ); + let b = reference::decode_levels( + &mut serial, + &mut serial_contexts, + &mut serial_coefficients, + component, + group, + choice & 2 != 0, + &mut serial_state, + ); + a == b + && sparse_coefficients == serial_coefficients + && sparse_contexts == serial_contexts + && sparse_state == serial_state + && sparse.snapshot() == serial.snapshot() +} + fn next_rice(previous_rice: u8, previous_abs: u32) -> u8 { (previous_rice + u8::from(previous_abs > (3 << previous_rice))).min(4) } @@ -573,6 +658,51 @@ fn remaining_level(bins: &mut impl Bins, rice: u8) -> Result { mod tests { use super::*; + #[test] + fn significant_positions_cover_every_mask_in_reverse_scan_order() { + for mask in 0..=u16::MAX { + let expected: Vec = (0..16) + .rev() + .filter(|position| mask & (1 << position) != 0) + .collect(); + assert_eq!(significant_positions(mask).collect::>(), expected); + } + } + + #[test] + fn sparse_levels_match_serial_for_every_significance_mask() { + for mask in 0..=u16::MAX { + for choice in 0x3c..=0x3f { + for payload in [0, 0xaa] { + let mut data = [payload; 35]; + data[0] = mask as u8; + data[1] = (mask >> 8) as u8; + data[2] = choice; + data[3] = 0; + assert!(coefficient_levels_match_reference(&data)); + } + } + } + } + + #[test] + fn sparse_levels_preserve_prefix_failures_and_bin_budgets() { + for mask in [0u16, 1, 0x80, 0x8000, 0x8101, 0x5555, 0xaaaa, 0xffff] { + for choice in [0, 1, 2, 3, 0x3c, 0x3d, 0x3e, 0x3f, 0xff] { + for payload in [0, 0x55, 0xaa, 0xff] { + let mut data = [payload; 35]; + data[0] = mask as u8; + data[1] = (mask >> 8) as u8; + data[2] = choice; + data[3] = 0; + for len in 0..=data.len() { + assert!(coefficient_levels_match_reference(&data[..len])); + } + } + } + } + } + #[derive(Debug)] enum Bin { Decision(bool), diff --git a/crates/coreav-hevc/src/residual/reference.rs b/crates/coreav-hevc/src/residual/reference.rs new file mode 100644 index 000000000..bdc7fab1c --- /dev/null +++ b/crates/coreav-hevc/src/residual/reference.rs @@ -0,0 +1,95 @@ +use super::*; + +pub(super) fn decode_levels( + bins: &mut impl Bins, + contexts: &mut Contexts, + coefficients: &mut [Coefficient; 16], + component: Component, + group: usize, + sign_data_hiding: bool, + state: &mut LevelState, +) -> Result<[i16; 16]> { + let set = greater_context_set(component, group, state.greater1); + let mut greater_context = 1; + let mut count = 0; + let mut first = 16; + let mut last = 0; + let mut first_greater1 = None; + for (position, coefficient) in coefficients.iter_mut().enumerate().rev() { + if !coefficient.significant { + continue; + } + if count == 0 { + last = position; + } + first = position; + if count < 8 { + coefficient.greater1 = decision( + bins, + &mut contexts.greater1, + component.chroma() * 16 + set * 4 + usize::from(greater_context), + )?; + greater_context = advance_greater_context(greater_context, coefficient.greater1); + if coefficient.greater1 && first_greater1.is_none() { + first_greater1 = Some(position); + } + } + count += 1; + } + if count == 0 { + return Ok([0; 16]); + } + state.greater1 = greater_context; + if let Some(position) = first_greater1 { + coefficients + .get_mut(position) + .ok_or(Error::InvalidData("residual_greater2"))? + .greater2 = decision(bins, &mut contexts.greater2, component.chroma() * 4 + set)?; + } + let hidden = sign_data_hiding && last - first > 3; + state.hidden_groups += u64::from(hidden); + for (position, coefficient) in coefficients.iter_mut().enumerate().rev() { + if coefficient.significant && !(hidden && position == first) { + coefficient.negative = bins.bypass()?; + } + } + let mut levels = [0; 16]; + let mut significant_count = 0; + let mut sum = 0; + let mut rice = 0; + let mut previous_abs = 0; + for (position, (coefficient, level)) in + coefficients.iter().zip(levels.iter_mut()).enumerate().rev() + { + if !coefficient.significant { + continue; + } + let base = 1 + u32::from(coefficient.greater1) + u32::from(coefficient.greater2); + let threshold = if significant_count < 8 { + if Some(position) == first_greater1 { + 3 + } else { + 2 + } + } else { + 1 + }; + let remaining = if base == threshold { + rice = next_rice(rice, previous_abs); + let value = remaining_level(bins, rice)?; + previous_abs = base + value; + value + } else { + 0 + }; + let magnitude = base + remaining; + if magnitude > 32768 { + return Err(Error::InvalidData("coefficient_level")); + } + sum += magnitude; + let negative = coefficient.negative || (hidden && position == first && sum & 1 != 0); + *level = signed_level(magnitude, negative)?; + significant_count += 1; + } + Ok(levels) +}