Repository navigation
perf(hevc): streamline eight-bit reconstruction #502
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
6f1522e
chore(hevc): retain complete function profiles
gunwooterry 46f9b0c
chore(hevc): include the full profile tail
gunwooterry 59f32d1
docs(hevc): plan eight-bit residual reconstruction
gunwooterry 1c922a4
perf(hevc): simplify eight-bit residual clipping
gunwooterry d770356
ci(hevc): route inverse comparisons through dispatch
gunwooterry 2983e12
ci(hevc): reject invalid comparison inputs early
gunwooterry 89dc192
Merge remote-tracking branch 'origin/main' into perf/hevc-inverse8
gunwooterry File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 }} | ||
| 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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)); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.