Add short introduction
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md
index 83ec90c..040194b 100644
--- a/docs/4.0-migration-guide.md
+++ b/docs/4.0-migration-guide.md
@@ -1,3 +1,16 @@
+# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0
+
+This guide details the steps required to migrate from Mbed TLS version 2.x to Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 3.0.
+
+Here's the list of breaking changes; each entry should help you answer these two questions: (1) am I affected? (2) if yes, what's my migration path?
+
+- Mbed TLS has been split between two products: TF-PSA-Crypto for cryptography, and Mbed TLS for X.509 and (D)TLS.
+- CMake is now the only supported build system.
+- The cryptography API is now mostly the PSA API: most legacy cryptography APIs have been removed. This has led to adaptations in some X.509 and TLS APIs, notably because the library always uses the PSA random generator.
+- Various deprecated or minor functionality has been removed.
+
+Please consult the [TF-PSA-Crypto migration guide](../tf-psa-crypto/docs/1.0-migration-guide.md) for all information related to the crytography part of the library.
+
## CMake as the only build system
Mbed TLS now uses CMake exclusively to configure and drive its build process.
Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed.
@@ -248,7 +261,7 @@
### Impact on application code
-The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled.
+The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled.
`psa_crypto_init()` must be called before performing any cryptographic operation, including indirect requests such as parsing a key or certificate or starting a TLS handshake.