fix(jpeg): JPEG can encode and decode in encryption situation

docs/en/api-reference/peripherals/jpeg.rst

@@ -17,15 +17,18 @@ Functional Overview
 
 This document covers the following sections:
 
--  `Resource Allocation <#resource-allocation>`__ - covers how to allocate JPEG resources with properly set of configurations. It also covers how to recycle the resources when they finished working.
--  `Finite State Machine <#finite-state-machine>`__ - covers JPEG workflow. Introduce how jpeg driver uses internal resources and its software process.
--  `JPEG Decoder Engine <#jpeg-decoder-engine>`__ - covers behavior of JPEG decoder engine. Introduce how to use decoder engine functions to decode an image (from jpg format to raw format).
--  `JPEG Encoder Engine <#jpeg-encoder-engine>`__ - covers behavior of JPEG encoder engine. Introduce how to use encoder engine functions to encode an image (from raw format to jpg format).
--  `Performance Overview <#performance-overview>`__ - covers encoder and decoder performance.
--  `Pixel Storage Layout for Different Color Formats <#pixel-storage-layout-for-different-color-formats>`__ - covers color space order overview required in this JPEG decoder and encoder.
--  `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver.
--  `Power Management <#power-management>`__ - describes how JPEG driver would be affected by power consumption.
--  `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can bring different effects to the driver.
+-  :ref:`jpeg-resource-allocation` - covers how to allocate JPEG resources with properly set of configurations. It also covers how to recycle the resources when they finished working.
+-  :ref:`jpeg-finite-state-machine` - covers JPEG workflow. Introduce how jpeg driver uses internal resources and its software process.
+-  :ref:`jpeg-decoder-engine` - covers behavior of JPEG decoder engine. Introduce how to use decoder engine functions to decode an image (from jpg format to raw format).
+-  :ref:`jpeg-encoder-engine` - covers behavior of JPEG encoder engine. Introduce how to use encoder engine functions to encode an image (from raw format to jpg format).
+-  :ref:`jpeg-performance-overview` - covers encoder and decoder performance.
+-  :ref:`jpeg-pixel-storage-layout` - covers color space order overview required in this JPEG decoder and encoder.
+-  :ref:`jpeg-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
+-  :ref:`jpeg-power-management` - describes how JPEG driver would be affected by power consumption.
+-  :ref:`jpeg-flash-encryption` - describes how to use the JPEG codec correctly when flash/PSRAM encryption is enabled.
+-  :ref:`jpeg-kconfig-options` - lists the supported Kconfig options that can bring different effects to the driver.
+
+.. _jpeg-resource-allocation:
 
 Resource Allocation
 ^^^^^^^^^^^^^^^^^^^
@@ -85,6 +88,8 @@ If a previously installed JPEG engine is no longer needed, it's recommended to r
 
     ESP_ERROR_CHECK(jpeg_del_encoder_engine(encoder_engine));
 
+.. _jpeg-finite-state-machine:
+
 Finite State Machine
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -96,6 +101,8 @@ The JPEG driver usage of hardware resources and its process workflow are shown i
 
     JPEG finite state machine
 
+.. _jpeg-decoder-engine:
+
 JPEG Decoder Engine
 ^^^^^^^^^^^^^^^^^^^
 
@@ -153,6 +160,8 @@ There are some tips that can help you use this driver more accurately:
 
 3. If the source JPEG uses YUV420 or YUV422 sampling, the decoded output dimensions can be padded up to 16-pixel boundaries. For example, if the visible image size is 1080*1920, the decoder may require an output buffer sized for 1088*1920 pixels. This comes from the JPEG block layout, so please provide enough output buffer memory for the padded image, not only for the visible width and height.
 
+.. _jpeg-encoder-engine:
+
 JPEG Encoder Engine
 ^^^^^^^^^^^^^^^^^^^
 
@@ -212,6 +221,8 @@ There are some tips that can help you use this driver more accurately:
 
 4. The compression ratio depends on the chosen `image_quality` and the content of the image itself. Generally, a higher `image_quality` value obviously results in better image quality but a smaller compression ratio. As for the image content, it is hard to give any specific guidelines, so this question is out of the scope of this document. Generally, the baseline JPEG compression ratio can vary from 40:1 to 10:1. Please take the actual situation into account.
 
+.. _jpeg-performance-overview:
+
 Performance Overview
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -343,6 +354,8 @@ JPEG encoder performance
 .. [#] Format of Original Image
 .. [#] Down sampling method
 
+.. _jpeg-pixel-storage-layout:
+
 Pixel Storage Layout for Different Color Formats
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -419,11 +432,15 @@ In the following picture, each small block means one byte.
 
     YUV420 pixel order
 
+.. _jpeg-thread-safety:
+
 Thread Safety
 ^^^^^^^^^^^^^
 
 The factory function :cpp:func:`jpeg_new_decoder_engine`, :cpp:func:`jpeg_decoder_get_info`, :cpp:func:`jpeg_decoder_process`, and :cpp:func:`jpeg_del_decoder_engine` are guaranteed to be thread safe by the driver, which means, user can call them from different RTOS tasks without protection by extra locks.
 
+.. _jpeg-power-management:
+
 Power Management
 ^^^^^^^^^^^^^^^^
 
@@ -431,6 +448,26 @@ When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is set), the sys
 
 Whenever the user is decoding or encoding via JPEG (i.e., calling :cpp:func:`jpeg_encoder_process` or :cpp:func:`jpeg_decoder_process`), the driver guarantees that the power management lock is acquired by setting it to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_CPU_FREQ_MAX`. Once the encoding or decoding is finished, the driver releases the lock and the system can enter Light-sleep.
 
+.. _jpeg-flash-encryption:
+
+Usage Under Encryption
+^^^^^^^^^^^^^^^^^^^^^^
+
+The JPEG codec moves data via the 2D-DMA, and the JPEG codec **cannot process encrypted data**. Therefore, when PSRAM encryption is enabled, the JPEG input/output buffers must reside in an unencrypted memory region, otherwise encoding/decoding fails.
+
+To support the encrypted scenario, the driver does the following:
+
+- When ``CONFIG_SPIRAM_ENC_EXEMPT`` is enabled, :cpp:func:`jpeg_alloc_decoder_mem` and :cpp:func:`jpeg_alloc_encoder_mem` allocate buffers from the unencrypted PSRAM region (``MALLOC_CAP_SPIRAM_NO_ENC``) automatically.
+- The allocated buffers satisfy both the cache line alignment and the byte alignment required by the 2D-DMA.
+
+Please note the following when using it:
+
+1. It is recommended to always allocate buffers via :cpp:func:`jpeg_alloc_encoder_mem` / :cpp:func:`jpeg_alloc_decoder_mem` to ensure correct alignment and memory region.
+
+2. The size of the unencrypted region is determined by ``CONFIG_SPIRAM_ENC_EXEMPT_SIZE``. Since the JPEG buffer size depends on the image resolution and cannot be predicted automatically, configure it according to the largest image you actually process. If the region is insufficient, the allocation fails and an error log is printed, suggesting to enlarge ``CONFIG_SPIRAM_ENC_EXEMPT_SIZE``. Also note that this value must not be greater than or equal to the actual PSRAM size, otherwise the unencrypted region is disabled.
+
+.. _jpeg-kconfig-options:
+
 Kconfig Options
 ^^^^^^^^^^^^^^^