Improve explanations around config_psa.h
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md
index feface7..3327ace 100644
--- a/docs/proposed/psa-conditional-inclusion-c.md
+++ b/docs/proposed/psa-conditional-inclusion-c.md
@@ -5,7 +5,7 @@
This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA.
-Time-stamp: "2020/11/16 11:04:35 GMT"
+Time-stamp: "2020/11/16 13:35:03 GMT"
## Introduction
@@ -115,18 +115,25 @@
### Architecture of symbol definitions
-#### Definition of internal inclusion symbols
+#### New-style definition of configuration symbols
When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols.
-When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that contains code that's specific to a given cryptographic mechanism (which is reflected in Mbed TLS in code under `MBEDTLS_USE_PSA_CRYPTO` and in conditional compilation guards in tests and sample programs).
+`mbedtls/config_psa.h` includes `psa/crypto_config.h`, the user-editable file that defines application requirements.
-`mbedtls/config_psa.h` includes two header files:
+#### New-style definition of configuration symbols
-* `psa/crypto_config.h` is the user-editable file that defines application requirements. It is only included when `MBEDTLS_PSA_CRYPTO_CONFIG` is set.
-* `mbedtls/crypto_drivers.h` is a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback.
+When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, a new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`).
-The following table summarized where symbols are defined depending on the configuration mode.
+The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that's specific to a given cryptographic mechanism. In Mbed TLS itself, code under `MBEDTLS_USE_PSA_CRYPTO` and conditional compilation guards in tests and sample programs need `PSA_WANT_xxx`.
+
+Since some existing applications use a handwritten `mbedtls/config.h` or an edited copy of `mbedtls/config.h` from an earlier version of Mbed TLS, `mbedtls/config_psa.h` must be included via an already existing header that is not `mbedtls/config.h`, so it is included via `psa/crypto.h` (for example from `psa/crypto_platform.h`).
+
+#### Summary of definitions of configuration symbols
+
+Both with and without `MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls/config_psa.h` includes `mbedtls/crypto_drivers.h`, a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback.
+
+The following table summarizes where symbols are defined depending on the configuration mode.
* (U) indicates a symbol that is defined by the user (application).
* (D) indicates a symbol that is deduced from other symbols by code that ships with Mbed TLS.