diff --git a/.github/workflows/hevc-inverse-reference.yml b/.github/workflows/hevc-inverse-reference.yml new file mode 100644 index 000000000..c2169d541 --- /dev/null +++ b/.github/workflows/hevc-inverse-reference.yml @@ -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 }} + 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 diff --git a/.github/workflows/hevc-reference.yml b/.github/workflows/hevc-reference.yml index 13f18b74d..57fe1f049 100644 --- a/.github/workflows/hevc-reference.yml +++ b/.github/workflows/hevc-reference.yml @@ -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 @@ -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: @@ -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 }} diff --git a/crates/coreav-kernels-hevc/src/inverse.rs b/crates/coreav-kernels-hevc/src/inverse.rs index cb303c3d6..c0aa79ec6 100644 --- a/crates/coreav-kernels-hevc/src/inverse.rs +++ b/crates/coreav-kernels-hevc/src/inverse.rs @@ -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() { @@ -244,3 +252,44 @@ pub fn add_residual( } Ok(()) } + +fn add_eight( + 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::) + .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::) + .ok_or(Error::Buffer)?; + let residual = residual + .data + .get(y * residual.stride..) + .and_then(<[i32]>::first_chunk::) + .ok_or(Error::Buffer)?; + let output = output + .data + .get_mut(y * output.stride..) + .and_then(<[u16]>::first_chunk_mut::) + .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; diff --git a/crates/coreav-kernels-hevc/src/inverse/tests.rs b/crates/coreav-kernels-hevc/src/inverse/tests.rs new file mode 100644 index 000000000..64c1a7286 --- /dev/null +++ b/crates/coreav-kernels-hevc/src/inverse/tests.rs @@ -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)); + } + } +} diff --git a/docs/agents/ci.md b/docs/agents/ci.md index b73ee8a98..abf32c46f 100644 --- a/docs/agents/ci.md +++ b/docs/agents/ci.md @@ -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 | diff --git a/docs/design/hevc-inverse-reconstruction.md b/docs/design/hevc-inverse-reconstruction.md new file mode 100644 index 000000000..b47417113 --- /dev/null +++ b/docs/design/hevc-inverse-reconstruction.md @@ -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. diff --git a/scripts/hevc_inverse_reference.py b/scripts/hevc_inverse_reference.py new file mode 100644 index 000000000..33d34673e --- /dev/null +++ b/scripts/hevc_inverse_reference.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 +"""Compare explicit HEVC reconstruction commits on one reference host.""" + +import argparse +import json +import pathlib +import platform +import re +import sys +import tempfile + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) +import hevc_reference as reference +import test_oracle + + +def compare(baseline, candidate, oracle, source, repeats): + expected = reference.verify(baseline, oracle, source) + if reference.verify(candidate, oracle, source) != expected: + raise ValueError('candidate_output_identity') + commands = { + 'baseline': [baseline, source, 'decode'], + 'candidate': [candidate, source, 'decode'], + 'ffmpeg_one': reference.ffmpeg_command(oracle.ffmpeg, source, True, + ['-progress', 'pipe:1', '-f', 'null', '-']), + } + arms = tuple(commands) + for arm in arms: + stdout, _ = reference.command(commands[arm]) + reference.check_work('coreav' if arm != 'ffmpeg_one' else arm, stdout, expected['frames']) + calls = [] + for repeat in range(repeats): + offset = repeat % len(arms) + for arm in arms[offset:] + arms[:offset]: + stdout, receipt = reference.command(commands[arm]) + reference.check_work('coreav' if arm != 'ffmpeg_one' else arm, stdout, expected['frames']) + calls.append(dict(arm=arm, repeat=repeat, **receipt)) + return dict(**expected, calls=calls) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + for arm in ('baseline', 'candidate'): + parser.add_argument('--' + arm, type=pathlib.Path, required=True) + parser.add_argument('--' + arm + '-sha', required=True) + parser.add_argument('--oracle-bin', type=pathlib.Path, required=True) + parser.add_argument('--out', type=pathlib.Path, required=True) + parser.add_argument('--only', required=True) + parser.add_argument('--frames', type=int, default=32, choices=range(1, 65)) + parser.add_argument('--repeats', type=int, default=5, choices=range(5, 10)) + args = parser.parse_args() + for sha in (args.baseline_sha, args.candidate_sha): + if re.fullmatch('[0-9a-f]{40}', sha) is None: + parser.error('full_commit_sha_required') + args.only = set(args.only.split(',')) + if not args.only or args.only - {f'd{i:02}' for i in range(26)} - {f'c{i:02}' for i in range(4)}: + parser.error('unknown_reference_input') + oracle = test_oracle.require(args.oracle_bin / 'ffmpeg', args.oracle_bin / 'ffprobe') + args.out.mkdir(parents=True, exist_ok=True) + report = dict(complete=False, baseline=args.baseline_sha, candidate=args.candidate_sha, + baseline_binary_sha256=reference.conformance.digest(args.baseline), + candidate_binary_sha256=reference.conformance.digest(args.candidate), + oracle=reference.oracle_pin.load()['BUILD'], selected_ids=sorted(args.only), + frames_cap=args.frames, repeats=args.repeats, files=[], + host=dict(cpu=next(line.split(':', 1)[1].strip() + for line in pathlib.Path('/proc/cpuinfo').read_text().splitlines() + if line.startswith('model name')), kernel=platform.release())) + pool = reference.round_files.pool() + pool.limits.max_requests = 4000 + pool.limits.max_bytes = 32 << 30 + try: + with tempfile.TemporaryDirectory(prefix='hevc-inverse-') as temp: + directory = pathlib.Path(temp) + for identity, source, original_sha in reference.inputs(args, oracle, directory, pool): + row = dict(id=identity, source_sha256=original_sha, + input_sha256=reference.conformance.digest(source), + **compare(args.baseline, args.candidate, oracle, source, args.repeats)) + report['files'].append(row) + if identity == 'c00': + small = directory / 'profile.hevc' + reference.command([oracle.ffmpeg, '-hide_banner', '-loglevel', 'error', '-nostdin', + '-i', source, '-frames:v', '2', '-c:v', 'copy', '-f', 'hevc', '-y', small]) + for arm in ('baseline', 'candidate'): + binary = getattr(args, arm) + profile = dict(id=arm, **reference.verify(binary, oracle, small)) + reference.profile(argparse.Namespace(native=binary), small, profile, directory) + row[arm + '_profile'] = profile + report['r2_requests'] = pool.limits.requests + (args.out / 'results.json').write_text(json.dumps(report, indent=2) + '\n') + if {row['id'] for row in report['files']} != args.only: + raise ValueError('incomplete_input_selection') + report['complete'] = True + finally: + report['r2_requests'] = pool.limits.requests + pool.close() + (args.out / 'results.json').write_text(json.dumps(report, indent=2) + '\n') + + +if __name__ == '__main__': + main() diff --git a/scripts/hevc_reference.py b/scripts/hevc_reference.py index dd2f8d6dc..49233c0ff 100644 --- a/scripts/hevc_reference.py +++ b/scripts/hevc_reference.py @@ -182,7 +182,7 @@ def profile(args, source, record, directory): totals = re.search(r'^summary: (.+)$', text, re.M)[1].split() record['instructions'] = int(totals[events.index('Ir')]) annotation, _ = command(['callgrind_annotate', '--auto=no', '--inclusive=no', '--show=Ir', - '--threshold=95', output]) + '--threshold=100', output]) hot = [] for line in annotation.decode().splitlines(): match = re.match(r'^\s*([\d,]+)\s+\(\s*([\d.]+)%\)\s+.*?:((?:coreav_|