From 5341c8687773252ac3fd841ddd8c78ad4e1ecc9b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
 <manuel.pegourie-gonnard@arm.com>
Date: Tue, 2 Dec 2025 12:35:20 +0100
Subject: [PATCH] Add comments for remaining internal includes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
---
 include/mbedtls/error.h | 8 +++-----
 library/ssl_misc.h      | 2 +-
 library/ssl_msg.c       | 2 +-
 library/ssl_tls.c       | 2 +-
 library/x509_internal.h | 3 +--
 5 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 21707b1ca3..738440398c 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -11,11 +11,9 @@
 #define MBEDTLS_ERROR_H
 
 #include "mbedtls/build_info.h"
-// XXX: internal crypto include, used for:
-// - MBEDTLS_ERROR_ADD
-// - MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
-// - possibly others (the above are just the first build errors)
-#include "mbedtls/private/error_common.h"
+#include "mbedtls/private/error_common.h" // for MBEDTLS_ERROR_ADD + see below
+// MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED
+// MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED
 
 #include <stddef.h>
 
diff --git a/library/ssl_misc.h b/library/ssl_misc.h
index 9f9ed0bf70..f8c03dfa2f 100644
--- a/library/ssl_misc.h
+++ b/library/ssl_misc.h
@@ -20,7 +20,7 @@
 #include "debug_internal.h"
 
 #include "psa/crypto.h"
-#include "psa_util_internal.h" // XXX: internal crypto header
+#include "psa_util_internal.h" // for mbedtls_error_pair_t, psa_status_to_mbedtls
 extern const mbedtls_error_pair_t psa_to_ssl_errors[7];
 
 #include "mbedtls/pk.h"
diff --git a/library/ssl_msg.c b/library/ssl_msg.c
index 4430db993e..d4b915aa74 100644
--- a/library/ssl_msg.c
+++ b/library/ssl_msg.c
@@ -21,7 +21,7 @@
 #include "mbedtls/error.h"
 #include "mbedtls/platform_util.h"
 #include "mbedtls/version.h"
-#include "constant_time_internal.h"
+#include "constant_time_internal.h" // for internal mbedtls_ct_xxx functions
 #include "mbedtls/constant_time.h"
 
 #include <string.h>
diff --git a/library/ssl_tls.c b/library/ssl_tls.c
index ea5924c3c1..36c6bf9586 100644
--- a/library/ssl_tls.c
+++ b/library/ssl_tls.c
@@ -29,7 +29,7 @@
 #include <string.h>
 
 #include "mbedtls/psa_util.h"
-#include "md_psa.h"
+#include "md_psa.h" // for mbedtls_md_error_from_psa()
 #include "psa/crypto.h"
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
diff --git a/library/x509_internal.h b/library/x509_internal.h
index 9bad6a2ad8..ea3aeb6351 100644
--- a/library/x509_internal.h
+++ b/library/x509_internal.h
@@ -17,8 +17,7 @@
 #include "mbedtls/x509.h"
 #include "mbedtls/asn1.h"
 
-// XXX: internal crypto header - used for mbedtls_pk_load_file()
-#include "pk_internal.h"
+#include "pk_internal.h" // for a lot of things, including in SSL
 
 int mbedtls_x509_get_name(unsigned char **p, const unsigned char *end,
                           mbedtls_x509_name *cur);