Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions .github/workflows/hevc-inverse-reference.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
name: hevc-inverse-reference
run-name: HEVC inverse reference ${{ inputs.candidate }}
# workflow-check: not required

on:
workflow_call:
inputs:
baseline:
required: true
type: string
candidate:
required: true
type: string
only:
required: true
type: string
workflow_dispatch:
inputs:
baseline:
description: Exact baseline decoder commit
required: true
type: string
candidate:
description: Exact candidate decoder commit
required: true
type: string
only:
description: Comma-separated reference input IDs
required: true
type: string

permissions:
contents: read

jobs:
inverse-reference:
runs-on: ubuntu-24.04
timeout-minutes: 60
env:
BASELINE: ${{ inputs.baseline }}
CANDIDATE: ${{ inputs.candidate }}
ONLY: ${{ inputs.only }}
Comment thread
capy-ai[bot] marked this conversation as resolved.
Resolved
steps:
- name: Validate dispatch inputs
run: |
set -euo pipefail
[[ "$BASELINE" =~ ^[0-9a-f]{40}$ ]]
[[ "$CANDIDATE" =~ ^[0-9a-f]{40}$ ]]
input='(c0[0-3]|d(0[0-9]|1[0-9]|2[0-5]))'
pattern="^${input}(,${input})*$"
[[ "$ONLY" =~ $pattern ]]
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
with:
persist-credentials: false
path: driver
- name: Check reference boundaries
run: |
python3 -m unittest discover -s driver/scripts/tests -p test_reference_hevc.py
python3 -m unittest discover -s driver/scripts/tests -p test_hevc_inverse_reference.py
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
with:
persist-credentials: false
ref: ${{ env.BASELINE }}
path: baseline
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
with:
persist-credentials: false
ref: ${{ env.CANDIDATE }}
path: candidate
- name: Admit exact repository commits before builds and credentials
run: |
set -euo pipefail
for arm in baseline candidate; do
sha="$BASELINE"
if [ "$arm" = candidate ]; then sha="$CANDIDATE"; fi
test "$(git -C "$arm" rev-parse HEAD)" = "$sha"
git -C "$arm" fetch --quiet --unshallow --no-tags origin '+refs/heads/*:refs/remotes/origin/*'
test -n "$(git -C "$arm" branch -r --contains "$sha")"
done
- uses: dtolnay/rust-toolchain@686976e191b89faba57d3206551f0f330d8cb249
with:
toolchain: stable
- name: Build and test explicit decoder arms
run: |
set -euo pipefail
for arm in baseline candidate; do
cp driver/bench/hevc-reference/decode.rs "$arm/crates/coreav-hevc/examples/reference.rs"
(cd "$arm" && CARGO_PROFILE_RELEASE_DEBUG=1 cargo build --locked --release -p coreav-hevc --features native-hevc --example reference)
done
cd candidate
cargo test --locked -p coreav-kernels-hevc --features native-hevc
cargo test --locked -p coreav-kernels-hevc --features native-hevc,scalar
cargo clippy --locked -p coreav-kernels-hevc --all-targets --features native-hevc -- -D warnings
rustc -Vv > "$RUNNER_TEMP/compiler.txt"
- name: Install profiling tools
run: sudo apt-get update -qq && sudo apt-get install -y valgrind
- name: Install the qualified pinned oracle
env:
R2_ENDPOINT: ${{ secrets.COREAV_CORPUS_R2_ENDPOINT }}
R2_ACCESS_KEY_ID: ${{ secrets.COREAV_CORPUS_R2_ACCESS_KEY_ID }}
R2_SECRET_ACCESS_KEY: ${{ secrets.COREAV_CORPUS_R2_SECRET_ACCESS_KEY }}
R2_BUCKET: ${{ vars.COREAV_CORPUS_R2_BUCKET }}
run: driver/scripts/install-oracle-ffmpeg.sh "$RUNNER_TEMP/oracle"
- name: Verify pixels before rotated same-host reference calls
env:
R2_ENDPOINT: ${{ secrets.COREAV_CORPUS_R2_ENDPOINT }}
R2_ACCESS_KEY_ID: ${{ secrets.COREAV_CORPUS_R2_ACCESS_KEY_ID }}
R2_SECRET_ACCESS_KEY: ${{ secrets.COREAV_CORPUS_R2_SECRET_ACCESS_KEY }}
R2_BUCKET: ${{ vars.COREAV_CORPUS_R2_BUCKET }}
run: |
python3 -I driver/scripts/hevc_inverse_reference.py \
--baseline "$PWD/baseline/target/release/examples/reference" --baseline-sha "$BASELINE" \
--candidate "$PWD/candidate/target/release/examples/reference" --candidate-sha "$CANDIDATE" \
--oracle-bin "$RUNNER_TEMP/oracle" --out "$RUNNER_TEMP/reference" --only "$ONLY"
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
if: always()
with:
name: hevc-inverse-reference-${{ env.CANDIDATE }}
path: |
${{ runner.temp }}/reference/results.json
${{ runner.temp }}/compiler.txt
if-no-files-found: error
retention-days: 30
20 changes: 17 additions & 3 deletions .github/workflows/hevc-reference.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,17 @@ run-name: HEVC reference ${{ inputs.candidate }} (${{ inputs.only || 'all' }}, c
on:
workflow_dispatch:
inputs:
inverse:
description: Run the same-host inverse reconstruction comparison
required: false
default: false
type: boolean
candidate:
description: Exact decoder commit
required: true
type: string
baseline:
description: Optional full main SHA for the threading comparison
description: Optional full baseline SHA for a comparison
required: false
default: ''
type: string
Expand Down Expand Up @@ -39,8 +44,17 @@ permissions:
contents: read

jobs:
inverse-comparison:
if: inputs.inverse
uses: ./.github/workflows/hevc-inverse-reference.yml
with:
baseline: ${{ inputs.baseline }}
candidate: ${{ inputs.candidate }}
only: ${{ inputs.only }}
secrets: inherit

reference:
if: inputs.baseline == '' && !inputs.sanitizer_only
if: ${{ !inputs.inverse && inputs.baseline == '' && !inputs.sanitizer_only }}
runs-on: ubuntu-24.04
timeout-minutes: 150
env:
Expand Down Expand Up @@ -114,7 +128,7 @@ jobs:
retention-days: 30

threading:
if: inputs.baseline != '' || inputs.sanitizer_only
if: ${{ !inputs.inverse && (inputs.baseline != '' || inputs.sanitizer_only) }}
uses: ./.github/workflows/hevc-threading.yml
with:
candidate: ${{ inputs.candidate }}
Expand Down
49 changes: 49 additions & 0 deletions crates/coreav-kernels-hevc/src/inverse.rs
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,14 @@ pub fn add_residual(
return Err(Error::BlockSize);
}
let n = prediction.size.side();
if depth.bits() == 8 {
return match n {
4 => add_eight::<4>(prediction, residual, output),
8 => add_eight::<8>(prediction, residual, output),
16 => add_eight::<16>(prediction, residual, output),
_ => add_eight::<32>(prediction, residual, output),
};
}
for y in 0..n {
for x in 0..n {
if prediction.at(x, y)? > depth.max_sample() {
Expand All @@ -244,3 +252,44 @@ pub fn add_residual(
}
Ok(())
}

fn add_eight<const N: usize>(
prediction: Block<'_, u16>,
residual: Block<'_, i32>,
output: BlockMut<'_, u16>,
) -> Result<(), Error> {
for y in 0..N {
let row = prediction
.data
.get(y * prediction.stride..)
.and_then(<[u16]>::first_chunk::<N>)
.ok_or(Error::Buffer)?;
if row.iter().any(|&sample| sample > 255) {
return Err(Error::Sample);
}
}
for y in 0..N {
let prediction = prediction
.data
.get(y * prediction.stride..)
.and_then(<[u16]>::first_chunk::<N>)
.ok_or(Error::Buffer)?;
let residual = residual
.data
.get(y * residual.stride..)
.and_then(<[i32]>::first_chunk::<N>)
.ok_or(Error::Buffer)?;
let output = output
.data
.get_mut(y * output.stride..)
.and_then(<[u16]>::first_chunk_mut::<N>)
.ok_or(Error::Buffer)?;
for ((&prediction, &residual), sample) in prediction.iter().zip(residual).zip(output) {
*sample = residual.saturating_add(i32::from(prediction)).clamp(0, 255) as u16;
}
}
Ok(())
}

#[cfg(test)]
mod tests;
83 changes: 83 additions & 0 deletions crates/coreav-kernels-hevc/src/inverse/tests.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
#![allow(clippy::indexing_slicing, clippy::unwrap_used)]

use super::*;
use crate::BlockSize;

#[test]
fn eight_bit_add_preserves_the_full_residual_domain_and_short_last_rows() {
let residuals = [
i32::MIN,
i32::MIN + 255,
-32768,
-256,
-255,
-1,
0,
1,
254,
255,
256,
32767,
i32::MAX - 255,
i32::MAX,
];
for n in [4, 8, 16, 32] {
let size = BlockSize::new(n).unwrap();
for p in 0..=255u16 {
let mut prediction = std::vec![u16::MAX; (n - 1) * (n + 1) + n];
let mut residual = std::vec![i32::MIN; (n - 1) * (n + 2) + n];
let mut output = std::vec![u16::MAX; (n - 1) * (n + 3) + n];
for offset in 0..residuals.len() {
for y in 0..n {
for x in 0..n {
prediction[y * (n + 1) + x] = p;
residual[y * (n + 2) + x] =
residuals[(y * n + x + offset) % residuals.len()];
}
}
add_residual(
BitDepth::new(8).unwrap(),
Block::new(&prediction, n + 1, size).unwrap(),
Block::new(&residual, n + 2, size).unwrap(),
BlockMut::new(&mut output, n + 3, size).unwrap(),
)
.unwrap();
for y in 0..n {
for x in 0..n {
assert_eq!(
output[y * (n + 3) + x],
(i64::from(p) + i64::from(residual[y * (n + 2) + x])).clamp(0, 255)
as u16
);
}
if y + 1 < n {
assert_eq!(&output[y * (n + 3) + n..(y + 1) * (n + 3)], &[u16::MAX; 3]);
}
}
}
}
}
}

#[test]
fn every_invalid_eight_bit_prediction_position_preserves_the_whole_output() {
for n in [4, 8, 16, 32] {
let size = BlockSize::new(n).unwrap();
let residual = std::vec![0; n * n];
for invalid in 0..n * n {
let mut prediction = std::vec![255; n * n];
prediction[invalid] = 256;
let mut output = std::vec![1234; n * n];
assert_eq!(
add_residual(
BitDepth::new(8).unwrap(),
Block::new(&prediction, n, size).unwrap(),
Block::new(&residual, n, size).unwrap(),
BlockMut::new(&mut output, n, size).unwrap(),
),
Err(Error::Sample)
);
assert!(output.iter().all(|&sample| sample == 1234));
}
}
}
1 change: 1 addition & 0 deletions docs/agents/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,4 @@ List development caches with `docker volume ls --filter name=coreav-dev-`. After
| A change of an oracle platform's pin or installer starts every workflow that runs that installer | `scripts/workflow_check.py` (`deny.yml`) checks the platform-specific input lists, including the macOS verifier and its frozen Linux imports. `test_macos_installers_track_only_their_own_required_inputs` checks each macOS input and nested shell calls. A job-level filter (`changed-paths`) is review judgment |
| Fixture cache identities and fixture-consuming workflow triggers include every shared qualification support input, not only the directly called script | The existing `test_oracle.SUPPORT` owner supplies both cache keys; `test_both_fixture_cache_keys_bind_every_owner_support_file` executes both key blocks, changes every support file and rejects missing inputs. `test_all_fixture_support_changes_start_both_wasm_events` and `test_release_and_avi_triggers_cover_qualification_and_fixture_inputs` check the WASM, release and AVI filters against that owner and the generators they run. Workflow path filters cannot consume a Python owner at parse time, so checks prevent drift |
| The pinned comparator archive comes from an Actions cache keyed by its registered digest on every branch, only digest-verified bytes enter that cache, and the generator's own digest check still judges what it is served | `test_comparator_archive_is_cached_by_its_registered_digest_on_every_branch` checks both cache steps' key and path against the registration and that neither save is limited to main; `test_fetch_keeps_only_a_digest_verified_archive_and_installs_the_stand_in_beside_it`, `test_stand_in_serves_only_the_generators_request_for_the_registered_archive` and `test_audio_conformance_builds_the_comparator_from_the_cached_archive` execute the shell blocks and the stand-in with a stand-in curl (`deny.yml`). A YAML type cannot govern what a cache step saves |
| The inverse HEVC comparison rejects malformed commit identities and an empty or unknown input selection before checkout, build or credential use, while ordinary reference and threading routes keep their defaults | `test_dispatch_rejects_invalid_inputs_before_checkout_or_build` executes the workflow's actual shell validation for invalid values and all admitted IDs; `test_existing_dispatch_preserves_reference_and_threading_unless_inverse_is_selected` preserves existing routes behind an explicit inverse selector. Validation precedes checkout, where the Python owner is not available; workflow inputs are external strings, so Rust types cannot admit them |
11 changes: 11 additions & 0 deletions docs/design/hevc-inverse-reconstruction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Eight-bit HEVC residual reconstruction

This change stays inside the opt-in HEVC kernel crate. The first target is prediction-plus-residual clipping, defined by ITU-T H.265 V11 (01/2026), equation 8-325. It leaves dequantization, inverse DCT/DST, transform skip, parsing, filtering and ten-bit reconstruction unchanged.

The checked `Block` types already prove every active row's extent, including a short final row without trailing padding. The eight-bit path borrows each row as a fixed array for sizes 4, 8, 16 and 32 instead of repeating checked coordinate arithmetic for every sample. A complete prediction-domain validation pass still precedes every output write. Invalid sizes and prediction samples retain the same errors, and padding is neither read nor written.

For prediction `p` in 0 through 255 and any signed 32-bit residual `r`, `clip(p + r, 0, 255)` equals `clip(saturating_add(p, r), 0, 255)`. Negative overflow cannot occur because `p` is nonnegative. Positive overflow already implies an output of 255, so saturation cannot change the clipped result. This allows safe signed 32-bit arithmetic without narrowing the residual domain or adding an unsafe exception.

Fixed-size rows and safe arithmetic come before explicit SIMD. The existing ten-bit implementation remains the reference for a separate follow-up; no ten-bit vector path is added here. Scratch allocation and its accounting do not change.

Verification compares every prediction value with extreme and boundary residuals using independent 64-bit addition, covers independent strides and a minimally sized last row, and retains the existing all-size reconstruction and no-partial-write tests. Conformance outputs must remain bit-exact. Reference comparisons build explicit baseline and candidate commits in one Actions job, verify pixels before timing, rotate repeated calls, and retain complete function-level instruction profiles. These are reference figures without a judged speed threshold.
Loading
Loading