Merge branch 'fix/refactor_source_code_and_comments' into 'master'

fix(hal): updated API description and added comments

Closes IDF-12618

See merge request espressif/esp-idf!38415

components/hal/esp32c3/include/hal/aes_ll.h

@@ -151,7 +151,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32c3/include/hal/ds_ll.h

@@ -104,6 +104,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_BASE, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -131,6 +132,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
         asm volatile ("fence");
+        // Fence ensures all memory operations are completed before proceeding further
         from += frags[i].len;
     }
 }
@@ -177,6 +179,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_BASE, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32c5/include/hal/aes_ll.h

@@ -143,7 +143,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32c5/include/hal/ds_ll.h

@@ -97,6 +97,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_MEM, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -123,6 +124,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
 
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
+        // Fence ensures all memory operations are completed before proceeding further
         asm volatile ("fence");
         from += frags[i].len;
     }
@@ -170,6 +172,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_MEM, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32c6/include/hal/aes_ll.h

@@ -143,7 +143,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32c6/include/hal/ds_ll.h

@@ -97,6 +97,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_MEM, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -123,6 +124,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
 
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
+        // Fence ensures all memory operations are completed before proceeding further
         asm volatile ("fence");
         from += frags[i].len;
     }
@@ -170,6 +172,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_MEM, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32h2/include/hal/aes_ll.h

@@ -146,7 +146,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32h2/include/hal/ds_ll.h

@@ -96,6 +96,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_MEM, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -122,6 +123,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
 
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
+        // Fence ensures all memory operations are completed before proceeding further
         asm volatile ("fence");
         from += frags[i].len;
     }
@@ -169,6 +171,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_MEM, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32h21/include/hal/aes_ll.h

@@ -143,7 +143,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32h21/include/hal/ds_ll.h

@@ -96,6 +96,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_MEM, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -122,6 +123,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
 
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
+        // Fence ensures all memory operations are completed before proceeding further
         asm volatile ("fence");
         from += frags[i].len;
     }
@@ -169,6 +171,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_MEM, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32p4/include/hal/aes_ll.h

@@ -152,7 +152,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/hal/esp32p4/include/hal/ds_ll.h

@@ -108,6 +108,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)
 static inline void ds_ll_write_message(const uint8_t *msg, size_t size)
 {
     memcpy((uint8_t*) DS_X_MEM, msg, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 
@@ -134,6 +135,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p
 
     for (int i = 0; i < NUM_FRAGS; i++) {
         memcpy((uint8_t *)frags[i].addr, from, frags[i].len);
+        // Fence ensures all memory operations are completed before proceeding further
         asm volatile ("fence");
         from += frags[i].len;
     }
@@ -181,6 +183,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)
 static inline void ds_ll_read_result(uint8_t *result, size_t size)
 {
     memcpy(result, (uint8_t*) DS_Z_MEM, size);
+    // Fence ensures all memory operations are completed before proceeding further
     asm volatile ("fence");
 }
 

components/hal/esp32s2/include/hal/aes_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -166,7 +166,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {
@@ -313,11 +313,11 @@ static inline void aes_ll_gcm_set_j0(const uint8_t *j0)
 }
 
 /**
- * @brief Sets the number of effective bits of incomplete blocks in plaintext/cipertext.
+ * @brief Sets the number of effective bits of incomplete blocks in plaintext/ciphertext.
  *
  * @note Only affects AES-GCM
  *
- * @param num_valid_bits the number of effective bits of incomplete blocks in plaintext/cipertext.
+ * @param num_valid_bits the number of effective bits of incomplete blocks in plaintext/ciphertext.
  */
 static inline void aes_ll_gcm_set_num_valid_bit(size_t num_valid_bits)
 {

components/hal/esp32s3/include/hal/aes_ll.h

@@ -151,7 +151,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)
  *
  * @note Only used for DMA transforms
  *
- * @param mode
+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)
  */
 static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)
 {

components/mbedtls/port/esp_ds/esp_rsa_sign_alt.c

@@ -11,22 +11,8 @@
 #include "rsa_sign_alt.h"
 #include "esp_memory_utils.h"
 
-#ifdef CONFIG_IDF_TARGET_ESP32S2
-#include "esp32s2/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32C3
-#include "esp32c3/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32S3
-#include "esp32s3/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32C6
-#include "esp32c6/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32H2
-#include "esp32h2/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32P4
-#include "esp32p4/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32C5
-#include "esp32c5/rom/digital_signature.h"
-#elif CONFIG_IDF_TARGET_ESP32H21
-#include "esp32h21/rom/digital_signature.h"
+#ifdef SOC_DIG_SIGN_SUPPORTED
+#include "rom/digital_signature.h"
 #else
 #error   "Selected target does not support esp_rsa_sign_alt (for DS)"
 #endif