Merge branch 'fix/refactor_source_code_and_comments' into 'master'

AdityaHPatwardhan · AdityaHPatwardhan · commit d3e3790fc950 · 2025-04-30T18:26:57.000+08:00
fix(hal): updated API description and added comments

Closes IDF-12618

See merge request espressif/esp-idf!38415
diff --git a/components/hal/esp32c3/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32c3/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32c5/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32c5/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32c6/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32c6/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32h2/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32h2/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32h21/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32h21/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32p4/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32p4/include/hal/ds_ll.h b/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");
 }
 
diff --git a/components/hal/esp32s2/include/hal/aes_ll.h b/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)
 {
diff --git a/components/hal/esp32s3/include/hal/aes_ll.h b/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)
 {
diff --git a/components/mbedtls/port/esp_ds/esp_rsa_sign_alt.c b/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

Original file line number	Diff line number	Diff line change
`@@ -151,7 +151,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)`
`151`	`151`	`*`
`152`	`152`	`* @note Only used for DMA transforms`
`153`	`153`	`*`
`154`		`- * @param mode`
	`154`	`+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)`
`155`	`155`	`*/`
`156`	`156`	`static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)`
`157`	`157`	`{`
Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)`
`104`	`104`	`static inline void ds_ll_write_message(const uint8_t *msg, size_t size)`
`105`	`105`	`{`
`106`	`106`	`memcpy((uint8_t*) DS_X_BASE, msg, size);`
	`107`	`+ // Fence ensures all memory operations are completed before proceeding further`
`107`	`108`	`asm volatile ("fence");`
`108`	`109`	`}`
`109`	`110`
`@@ -131,6 +132,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p`
`131`	`132`	`for (int i = 0; i < NUM_FRAGS; i++) {`
`132`	`133`	`memcpy((uint8_t *)frags[i].addr, from, frags[i].len);`
`133`	`134`	`asm volatile ("fence");`
	`135`	`+ // Fence ensures all memory operations are completed before proceeding further`
`134`	`136`	`from += frags[i].len;`
`135`	`137`	`}`
`136`	`138`	`}`
`@@ -177,6 +179,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)`
`177`	`179`	`static inline void ds_ll_read_result(uint8_t *result, size_t size)`
`178`	`180`	`{`
`179`	`181`	`memcpy(result, (uint8_t*) DS_Z_BASE, size);`
	`182`	`+ // Fence ensures all memory operations are completed before proceeding further`
`180`	`183`	`asm volatile ("fence");`
`181`	`184`	`}`
`182`	`185`
Original file line number	Diff line number	Diff line change
`@@ -143,7 +143,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)`
`143`	`143`	`*`
`144`	`144`	`* @note Only used for DMA transforms`
`145`	`145`	`*`
`146`		`- * @param mode`
	`146`	`+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)`
`147`	`147`	`*/`
`148`	`148`	`static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)`
`149`	`149`	`{`
Original file line number	Diff line number	Diff line change
`@@ -97,6 +97,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)`
`97`	`97`	`static inline void ds_ll_write_message(const uint8_t *msg, size_t size)`
`98`	`98`	`{`
`99`	`99`	`memcpy((uint8_t*) DS_X_MEM, msg, size);`
	`100`	`+ // Fence ensures all memory operations are completed before proceeding further`
`100`	`101`	`asm volatile ("fence");`
`101`	`102`	`}`
`102`	`103`
`@@ -123,6 +124,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p`
`123`	`124`
`124`	`125`	`for (int i = 0; i < NUM_FRAGS; i++) {`
`125`	`126`	`memcpy((uint8_t *)frags[i].addr, from, frags[i].len);`
	`127`	`+ // Fence ensures all memory operations are completed before proceeding further`
`126`	`128`	`asm volatile ("fence");`
`127`	`129`	`from += frags[i].len;`
`128`	`130`	`}`
`@@ -170,6 +172,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)`
`170`	`172`	`static inline void ds_ll_read_result(uint8_t *result, size_t size)`
`171`	`173`	`{`
`172`	`174`	`memcpy(result, (uint8_t*) DS_Z_MEM, size);`
	`175`	`+ // Fence ensures all memory operations are completed before proceeding further`
`173`	`176`	`asm volatile ("fence");`
`174`	`177`	`}`
`175`	`178`
Original file line number	Diff line number	Diff line change
`@@ -146,7 +146,7 @@ static inline esp_aes_state_t aes_ll_get_state(void)`
`146`	`146`	`*`
`147`	`147`	`* @note Only used for DMA transforms`
`148`	`148`	`*`
`149`		`- * @param mode`
	`149`	`+ * @param mode Mode of operation to set (e.g., ECB, CBC, CTR, etc.)`
`150`	`150`	`*/`
`151`	`151`	`static inline void aes_ll_set_block_mode(esp_aes_mode_t mode)`
`152`	`152`	`{`
Original file line number	Diff line number	Diff line change
`@@ -96,6 +96,7 @@ static inline void ds_ll_configure_iv(const uint32_t *iv)`
`96`	`96`	`static inline void ds_ll_write_message(const uint8_t *msg, size_t size)`
`97`	`97`	`{`
`98`	`98`	`memcpy((uint8_t*) DS_X_MEM, msg, size);`
	`99`	`+ // Fence ensures all memory operations are completed before proceeding further`
`99`	`100`	`asm volatile ("fence");`
`100`	`101`	`}`
`101`	`102`
`@@ -122,6 +123,7 @@ static inline void ds_ll_write_private_key_params(const uint8_t *encrypted_key_p`
`122`	`123`
`123`	`124`	`for (int i = 0; i < NUM_FRAGS; i++) {`
`124`	`125`	`memcpy((uint8_t *)frags[i].addr, from, frags[i].len);`
	`126`	`+ // Fence ensures all memory operations are completed before proceeding further`
`125`	`127`	`asm volatile ("fence");`
`126`	`128`	`from += frags[i].len;`
`127`	`129`	`}`
`@@ -169,6 +171,7 @@ static inline ds_signature_check_t ds_ll_check_signature(void)`
`169`	`171`	`static inline void ds_ll_read_result(uint8_t *result, size_t size)`
`170`	`172`	`{`
`171`	`173`	`memcpy(result, (uint8_t*) DS_Z_MEM, size);`
	`174`	`+ // Fence ensures all memory operations are completed before proceeding further`
`172`	`175`	`asm volatile ("fence");`
`173`	`176`	`}`
`174`	`177`