Update documentation in legacy_or_psa.h
- Some things that were indicated as in the near future are now done.
- Clarify when these macros are needed and when they're not.
- Prepare to make the header public.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/docs/architecture/psa-migration/strategy.md b/docs/architecture/psa-migration/strategy.md
index 8d2d59f..a13c100 100644
--- a/docs/architecture/psa-migration/strategy.md
+++ b/docs/architecture/psa-migration/strategy.md
@@ -345,7 +345,7 @@
only be included in the build if it is possible to use that hash in some way.
In order to cater to these new needs, new families of macros are introduced in
-`library/legacy_or_psa.h`, see its documentation for details.
+`legacy_or_psa.h`, see its documentation for details.
It should be noted that there are currently:
- too many different ways of computing a hash (low-level, MD, PSA);
@@ -358,6 +358,16 @@
based on PSA Crypto. In the meantime, long and explicit names where chosen for
the new macros in the hope of avoiding confusion.
+Note: the new macros supplement but do not replace the existing macros:
+- code that always uses PSA Crypto (for example, code specific to TLS 1.3)
+ should use `PSA_WANT_xxx`;
+- code that always uses the legacy API (for exmaple, crypto modules that have
+ not undergone step 1 yet) should use `MBEDTLS_xxx_C`;
+- code that may use one of the two APIs, either based on
+ `MBEDTLS_USE_PSA_CRYPTO` (X.509, TLS 1.2, shared between TLS 1.2 and 1.3),
+or based on availability (crypto modules after step 1), should use one of the
+new macros from `legacy_or_psa.h`.
+
Executing step 3 will mostly consist of using the right dependency macros in
the right places (once the previous steps are done).