[mikeysklar]

What

jpegio now uses the chip's JPEG hardware on ESP32-P4 and ESP32-S31.

Why

Software decode is too slow for video on these chips.

Needs adafruit/esp-idf#18 (adds yuv_range) and #19 (S31 ROM fix).

The esp-idf submodule points at #19, which includes both.

Setting	Effect
MICROPY_BYTES_PER_GC_BLOCK	64 on P4 and S31, so every GC allocation starts on a cache line. Same port_malloc change as #11614.
Cost	Free heap at boot about 576 B lower.
CIRCUITPY_JPEGIO_HW	On for P4 and S31, 0 elsewhere. Set to 0 to opt out.

1280x720, median of 10, hardware / TJpgDec	4:2:0	4:2:2	4:4:4
Adafruit P4 GPIO	9.2 / 302 ms	12.2 / 328 ms	18.2 / 385 ms
ESP32-S31-Korvo-1	16.0 / 375 ms	20.9 / 409 ms	31.0 / 477 ms

TJpgDec is timed from io.BytesIO; the hardware from bytes.

720p on P4	Hardware	TJpgDec
Whole image at 0,0 into a same-size Bitmap (direct)	9.8 ms	312 ms
With an offset or clip (temporary buffer)	31 to 72 ms	142 to 403 ms

Used when	Otherwise
open() got bytes, scale=0, 16-bit Bitmap, baseline color JPEG	TJpgDec, as before
Bitmap is the image size, decoded at 0,0	Temporary buffer, freed before decode() returns
Skip index set, or JPEG not in DMA-reachable memory (e.g. flash)	TJpgDec, as before

Memory	P4	S31	Held
Flash	+15.4 KB	+15.6 KB	Always
JPEG engine	684 B internal SRAM, 3.9 KB PSRAM	744 B internal SRAM, 4.0 KB PSRAM	From the first hardware decode until the JpegDecoder is freed (finaliser)
Temporary buffer	One padded frame in PSRAM	Same	During decode() only
Other chips	None		Flag defaults to 0

Tested on Adafruit P4 GPIO and ESP32-S31-Korvo-1, this branch rebased on main	Result
tests/circuitpython-manual/jpegio/hw_decode.py	Within 4 of 63 levels per channel of TJpgDec; grayscale, odd sizes and scale=1 fall back and match exactly; progressive raises as before
Offsets, clipping and skip indexes, 17 cases	Exactly a full hardware decode blitted with the same arguments; skip indexes take TJpgDec
Create and drop decoders 10 times, and reload with a decoder held	Engine freed each time; IDF heap back to the same level
Three runs plus reload	GC heap free identical to a fresh boot. IDF heap 200 B lower after the first decode, then flat; likely IDF's interrupt allocator keeping a vector entry
Not tested	Flash encryption

AI assistance: written with Claude Code. I ran the tests above on hardware.

[tannewt]

Do we want to be explicit about whether the user wants hardware acceleration? Or do you think it is ok to do through speed testing?

I had a couple comments about structure.

[mikeysklar]

Good point. Timing alone is not enough, since a decode can quietly fall back to software.

Added a read-only JpegDecoder.used_hardware property that says whether the last decode() used the JPEG engine. Other ports always report False. Tested on the S31 with hw_decode.py.

Thanks! Changes:

• Engine freed in __del__
• Removed the reset hook
• Bitmap.c back to main
• 64-byte GC blocks for alignment
• Same port_malloc change as Add initial video pipeline support #11614

I'd keep hardware decode on by default. It costs under 1% of flash and RAM on P4 and S31, and 720p decodes in 9 to 16 ms instead of 300 to 375 ms. Builds can opt out with CIRCUITPY_JPEGIO_HW=0.

Re-ran the hardware tests after these changes, rebased on main. All pass on P4 and S31.

[mikeysklar]

Two merge notes:

• Waiting on adafruit/esp-idf first steps to add sd card support #18 and I2C (seemingly) doesn't work #19.
• Will rebase onto Add initial video pipeline support #11614, keeping only the S31 part.

[tannewt]

Don't wait to rebase on the video pipeline stuff because this is close. The allocation changes here are fine.

[mikeysklar]

(me, not LLM):

Do we want to be explicit about whether the user wants hardware acceleration? Or do you think it is ok to do through speed testing?

Sorry I misread this the first time.

As we settled on Discord:

JpegDecoder(software_ok=False) now raises ValueError when the hardware can't decode the image, including on chips without it.

The default stays True, so existing code is unchanged.

Not waiting on #11614 anymore.

Tested on three ESPs to verify changes worked:

Board	Result
P4	720p in 9 to 18 ms. Unsupported cases raise with software_ok=False
S31	720p in 16 to 31 ms. Same cases raise
Metro ESP32-S3	Decodes in software by default. Raises with software_ok=False

Still waiting on adafruit/esp-idf #19 to point the submodule at it.