Skip to main content

rusty_esp_dsp_esp/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![deny(unsafe_code)]
3//! `rusty_esp_dsp-esp` — the chip half of the kernel home: the PIE twins.
4//!
5//! [`PieS3`] (feature `pie-s3`) and [`PieP4`] (feature `pie-p4`) implement
6//! the seam's three traits. A kernel with a twin runs the chip's SIMD; a
7//! kernel without one runs the scalar oracle under the same name, so a
8//! firmware selects its type in one place and nothing else changes as
9//! twins arrive. Every twin is gated byte-identical against
10//! [`rusty_esp_dsp::seam::Scalar`] over the corpus
11//! [`rusty_esp_dsp::seam::twin_matches_scalar`] generates — on the host with
12//! the intrinsics stubbed to scalar, and on the board with them live (D2's
13//! board row).
14//!
15//! **Nine of the seam's thirteen kernels now run real `ee.*` twins on an
16//! ESP32-S3** -- `yuyv_to_gray8`, `downscale2x_gray8`, `dot_i16`,
17//! `sum_sq_i16`, `peak_abs_i16`, `sad_8x8`, `sad_16x16`, `yuyv_to_rgb565`
18//! and `downscale2x_rgb565`. The rest
19//! delegate to the oracle, either because no twin exists yet or because one
20//! was built and MEASURED WORSE (`satd_4x4_sum`; see the ledger's P4 and P6
21//! entries) or is impossible on this unit (`rgb565_to_rgb888` and
22//! `rgb888_to_rgb565` need a 3-way byte deinterleave the ISA does not have).
23//!
24//! The twins are `cfg(target_arch = "xtensa")`. Off-chip -- a host build, a
25//! host test, a RISC-V target -- every method is the scalar oracle, so this
26//! crate builds everywhere and needs nightly only for the Xtensa build.
27//!
28//! `PieP4` still delegates everything: D4 has no board yet.
29
30// `ee.*` reaches Rust only through inline asm, and Xtensa asm is still
31// experimental; the `esp` toolchain is nightly, so this is available. Gated
32// on the target so the host build of this crate (where the twins are the
33// scalar oracle) needs no nightly at all.
34#![cfg_attr(
35    all(feature = "pie-s3", target_arch = "xtensa"),
36    feature(asm_experimental_arch)
37)]
38
39/// The ESP32-S3 twins.
40#[cfg(all(feature = "pie-s3", target_arch = "xtensa"))]
41pub mod pie_s3;
42
43#[cfg(any(feature = "pie-s3", feature = "pie-p4"))]
44use rusty_esp_core::error::Result;
45#[cfg(any(feature = "pie-s3", feature = "pie-p4"))]
46use rusty_esp_core::frame::Geometry;
47use rusty_esp_dsp::seam::Scalar;
48#[cfg(any(feature = "pie-s3", feature = "pie-p4"))]
49use rusty_esp_dsp::seam::{BlockKernels, PixelKernels, SampleKernels};
50
51// Only `PieP4` is generated now; `PieS3` writes its impls out so that
52// which kernels are accelerated is readable rather than inferred.
53#[cfg(feature = "pie-p4")]
54macro_rules! delegate_to_scalar {
55    ($ty:ident) => {
56        impl PixelKernels for $ty {
57            fn yuyv_to_rgb888(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
58                Scalar.yuyv_to_rgb888(src, dst)
59            }
60
61            fn yuyv_to_rgb565(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
62                Scalar.yuyv_to_rgb565(src, dst)
63            }
64
65            fn yuyv_to_gray8(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
66                Scalar.yuyv_to_gray8(src, dst)
67            }
68
69            fn rgb565_to_rgb888(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
70                Scalar.rgb565_to_rgb888(src, dst)
71            }
72
73            fn rgb888_to_rgb565(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
74                Scalar.rgb888_to_rgb565(src, dst)
75            }
76
77            fn downscale2x_gray8(
78                &self,
79                src: &[u8],
80                width: u32,
81                height: u32,
82                dst: &mut [u8],
83            ) -> Result<Geometry> {
84                Scalar.downscale2x_gray8(src, width, height, dst)
85            }
86
87            fn downscale2x_rgb565(
88                &self,
89                src: &[u8],
90                width: u32,
91                height: u32,
92                dst: &mut [u8],
93            ) -> Result<Geometry> {
94                Scalar.downscale2x_rgb565(src, width, height, dst)
95            }
96        }
97
98        impl SampleKernels for $ty {
99            fn dot_i16(&self, a: &[i16], b: &[i16]) -> i64 {
100                Scalar.dot_i16(a, b)
101            }
102
103            fn sum_sq_i16(&self, a: &[i16]) -> i64 {
104                Scalar.sum_sq_i16(a)
105            }
106
107            fn peak_abs_i16(&self, a: &[i16]) -> u16 {
108                Scalar.peak_abs_i16(a)
109            }
110        }
111
112        impl BlockKernels for $ty {
113            fn sad_8x8(&self, a: &[u8], sa: usize, b: &[u8], sb: usize) -> Result<u32> {
114                Scalar.sad_8x8(a, sa, b, sb)
115            }
116
117            fn sad_16x16(&self, a: &[u8], sa: usize, b: &[u8], sb: usize) -> Result<u32> {
118                Scalar.sad_16x16(a, sa, b, sb)
119            }
120
121            fn satd_4x4_sum(&self, blocks: &[[i32; 16]]) -> i64 {
122                Scalar.satd_4x4_sum(blocks)
123            }
124        }
125    };
126}
127
128/// The ESP32-S3 kernel set (`ee.*`, 128-bit PIE). Seven of the thirteen
129/// seam kernels run a real twin on an S3; the impls below say which, and
130/// why each of the rest does not.
131#[cfg(feature = "pie-s3")]
132#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
133pub struct PieS3;
134
135/// `PieS3` does NOT use `delegate_to_scalar!`: each method either calls its
136/// twin or states that it is deliberately the oracle. Written out rather
137/// than generated so that "which kernels are actually accelerated" is
138/// readable in one place -- the defect this crate previously had was a
139/// fully-delegating seam sitting in front of a module full of working
140/// twins, where every gate passed and no caller ever reached one.
141#[cfg(feature = "pie-s3")]
142impl PixelKernels for PieS3 {
143    /// Oracle: no twin. 3 bytes a pixel needs a 3-way deinterleave and the
144    /// PIE unit has only 2-way `zip`/`unzip` with no general byte permute.
145    fn yuyv_to_rgb888(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
146        Scalar.yuyv_to_rgb888(src, dst)
147    }
148
149    /// TWIN (backlog B2, -63.2%).
150    fn yuyv_to_rgb565(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
151        #[cfg(target_arch = "xtensa")]
152        {
153            pie_s3::yuyv_to_rgb565(src, dst)
154        }
155        #[cfg(not(target_arch = "xtensa"))]
156        {
157            Scalar.yuyv_to_rgb565(src, dst)
158        }
159    }
160
161    /// TWIN.
162    fn yuyv_to_gray8(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
163        #[cfg(target_arch = "xtensa")]
164        {
165            pie_s3::yuyv_to_gray8(src, dst)
166        }
167        #[cfg(not(target_arch = "xtensa"))]
168        {
169            Scalar.yuyv_to_gray8(src, dst)
170        }
171    }
172
173    /// Oracle: impossible on this unit, as for `yuyv_to_rgb888`.
174    fn rgb565_to_rgb888(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
175        Scalar.rgb565_to_rgb888(src, dst)
176    }
177
178    /// Oracle: impossible on this unit, as for `yuyv_to_rgb888`.
179    fn rgb888_to_rgb565(&self, src: &[u8], dst: &mut [u8]) -> Result<usize> {
180        Scalar.rgb888_to_rgb565(src, dst)
181    }
182
183    /// TWIN. The twin reports only success or a length failure, so the
184    /// geometry the seam owes its caller is built here; a length failure
185    /// goes to the oracle, which produces the exact error.
186    fn downscale2x_gray8(
187        &self,
188        src: &[u8],
189        width: u32,
190        height: u32,
191        dst: &mut [u8],
192    ) -> Result<Geometry> {
193        #[cfg(target_arch = "xtensa")]
194        {
195            match pie_s3::downscale2x_gray8(src, width, height, dst) {
196                Ok(()) => Geometry::new(
197                    width / 2,
198                    height / 2,
199                    rusty_esp_core::frame::PixelFormat::Gray8,
200                ),
201                Err(()) => Scalar.downscale2x_gray8(src, width, height, dst),
202            }
203        }
204        #[cfg(not(target_arch = "xtensa"))]
205        {
206            Scalar.downscale2x_gray8(src, width, height, dst)
207        }
208    }
209
210    /// TWIN (backlog B1, -65.5%). As for `downscale2x_gray8`, the twin
211    /// reports only success or a length failure, so the geometry the seam
212    /// owes its caller is built here.
213    fn downscale2x_rgb565(
214        &self,
215        src: &[u8],
216        width: u32,
217        height: u32,
218        dst: &mut [u8],
219    ) -> Result<Geometry> {
220        #[cfg(target_arch = "xtensa")]
221        {
222            match pie_s3::downscale2x_rgb565(src, width, height, dst) {
223                Ok(()) => Geometry::new(
224                    width / 2,
225                    height / 2,
226                    rusty_esp_core::frame::PixelFormat::Rgb565,
227                ),
228                Err(()) => Scalar.downscale2x_rgb565(src, width, height, dst),
229            }
230        }
231        #[cfg(not(target_arch = "xtensa"))]
232        {
233            Scalar.downscale2x_rgb565(src, width, height, dst)
234        }
235    }
236}
237
238#[cfg(feature = "pie-s3")]
239impl SampleKernels for PieS3 {
240    /// TWIN.
241    fn dot_i16(&self, a: &[i16], b: &[i16]) -> i64 {
242        #[cfg(target_arch = "xtensa")]
243        {
244            pie_s3::dot_i16(a, b)
245        }
246        #[cfg(not(target_arch = "xtensa"))]
247        {
248            Scalar.dot_i16(a, b)
249        }
250    }
251
252    /// TWIN.
253    fn sum_sq_i16(&self, a: &[i16]) -> i64 {
254        #[cfg(target_arch = "xtensa")]
255        {
256            pie_s3::sum_sq_i16(a)
257        }
258        #[cfg(not(target_arch = "xtensa"))]
259        {
260            Scalar.sum_sq_i16(a)
261        }
262    }
263
264    /// TWIN.
265    fn peak_abs_i16(&self, a: &[i16]) -> u16 {
266        #[cfg(target_arch = "xtensa")]
267        {
268            pie_s3::peak_abs_i16(a)
269        }
270        #[cfg(not(target_arch = "xtensa"))]
271        {
272            Scalar.peak_abs_i16(a)
273        }
274    }
275}
276
277#[cfg(feature = "pie-s3")]
278impl BlockKernels for PieS3 {
279    /// TWIN.
280    fn sad_8x8(&self, a: &[u8], sa: usize, b: &[u8], sb: usize) -> Result<u32> {
281        #[cfg(target_arch = "xtensa")]
282        {
283            pie_s3::sad_8x8(a, sa, b, sb)
284        }
285        #[cfg(not(target_arch = "xtensa"))]
286        {
287            Scalar.sad_8x8(a, sa, b, sb)
288        }
289    }
290
291    /// TWIN.
292    fn sad_16x16(&self, a: &[u8], sa: usize, b: &[u8], sb: usize) -> Result<u32> {
293        #[cfg(target_arch = "xtensa")]
294        {
295            pie_s3::sad_16x16(a, sa, b, sb)
296        }
297        #[cfg(not(target_arch = "xtensa"))]
298        {
299            Scalar.sad_16x16(a, sa, b, sb)
300        }
301    }
302
303    /// ORACLE BY MEASUREMENT, not by omission. A twin was built twice --
304    /// once with the 4x4 transpose going through memory (+25.4%) and once
305    /// with it entirely in registers (+7.6%) -- and lost both times. Ledger
306    /// P4 and P6.
307    fn satd_4x4_sum(&self, blocks: &[[i32; 16]]) -> i64 {
308        Scalar.satd_4x4_sum(blocks)
309    }
310}
311
312/// The ESP32-P4 kernel set (`esp.*`, 128-bit). Every kernel is the scalar
313/// oracle until D4.
314#[cfg(feature = "pie-p4")]
315#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
316pub struct PieP4;
317
318#[cfg(feature = "pie-p4")]
319delegate_to_scalar!(PieP4);
320
321/// The kernel set a firmware for `chip` should hold: the chip's twins when
322/// the feature is on, the scalar oracle otherwise. Written as a function so
323/// the choice is one line in a firmware and nowhere else.
324#[must_use]
325pub fn default_kernels() -> Kernels {
326    Kernels::default()
327}
328
329/// What [`default_kernels`] returns under the crate's features.
330#[cfg(feature = "pie-s3")]
331pub type Kernels = PieS3;
332/// What [`default_kernels`] returns under the crate's features.
333#[cfg(all(feature = "pie-p4", not(feature = "pie-s3")))]
334pub type Kernels = PieP4;
335/// What [`default_kernels`] returns under the crate's features.
336#[cfg(not(any(feature = "pie-s3", feature = "pie-p4")))]
337pub type Kernels = Scalar;
338
339#[cfg(all(test, feature = "std"))]
340mod tests {
341    use super::*;
342    use rusty_esp_dsp::seam::twin_matches_scalar;
343
344    #[test]
345    fn the_chip_kernel_set_matches_the_oracle() {
346        // trivially, today: the gate that will hold the real twins to it
347        assert_eq!(
348            twin_matches_scalar(&default_kernels(), 0x5EA3_0002, 32),
349            32 * 13
350        );
351    }
352
353    #[cfg(feature = "pie-s3")]
354    #[test]
355    fn pie_s3_is_selected_and_matches() {
356        assert_eq!(twin_matches_scalar(&PieS3, 0x5EA3_0003, 32), 32 * 13);
357    }
358}