Add repo-split migration guide
Also a section about the CMake being now
the only build system.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md
new file mode 100644
index 0000000..4e8da82
--- /dev/null
+++ b/docs/4.0-migration-guide/repo-split.md
@@ -0,0 +1,101 @@
+## CMake as the only build system
+CMake is now the only supported build system for Mbed TLS.
+Support for the legacy GNU Make and Microsoft Visual Studio project-based build systems has been removed.
+
+The GNU Make build system is still used internally for testing, but it will be removed once all test components have been migrated to CMake.
+The previous .sln/.vcxproj files are no longer distributed or generated.
+
+Builds must now be configured and executed through CMake. See `Compiling` section in README.md for initial build instructions.
+If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio.
+
+## Repository split
+In Mbed TLS 4.0, the project was split into two repositories:
+- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality.
+- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API.
+Mbed TLS consumes TF-PSA-Crypto as a submodule.
+You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the PSA Cryptography API through the `tf-psa-crypto` submodule.
+
+### File and directory relocations
+
+The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto.
+These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository.
+
+| Original location | New location(s) | Notes |
+|--------------------------------------|--------------------------------------------------------------------------------------|-------|
+| `library/` | `tf-psa-crypto/core/`<br>`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. |
+| `include/mbedtls/` | `tf-psa-crypto/include/mbedtls/`<br>`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. |
+| `include/psa/` | `tf-psa-crypto/include/` | All PSA headers consolidated here. |
+| `3rdparty/everest/`<br>`3rdparty/p256-m/` | `tf-psa-crypto/drivers/` | Third-party crypto driver implementations. |
+
+If you use your own build system to build Mbed TLS libraries, you will need to adapt to the new tree.
+
+### Configuration file split
+Cryptography and platform configuration options have been moved from `mbedtls_config.h` to `crypto_config.h`, which is now mandatory. See [Compile-time configuration](#compile-time-confiuration).
+
+### Impact on some usages of the library
+
+#### Checking out a branch or a tag
+After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule:
+```
+git submodule update --init --recursive
+```
+
+#### Linking directly to a built library
+The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them.
+The cryptography libraries are also now provided as `libtfpsacrypto.<ext>` like in the TF-PSA-Crypto repository.
+
+#### Linking through a CMake target of the cryptography library
+The base name of the CMake cryptography library target has been changed from `mbedcrypto` to `tfpsacrypto`.
+If no target prefix is specified through the MBEDTLS_TARGET_PREFIX option, the associated CMake target is thus now `tfpsacrypto`.
+
+The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package.
+When no global target prefix is defined, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`.
+
+As an example, the following CMake code:
+```
+find_package(MbedTLS REQUIRED)
+target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto)
+
+```
+would be updated to something like
+```
+find_package(MbedTLS REQUIRED)
+target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto)
+```
+
+For more information, see the CMake section of `README.md`.
+You can also refer to the following example programs demonstrating how to consume Mbed TLS via CMake:
+* `programs/test/cmake_subproject`
+* `programs/test/cmake_package`
+* `programs/test/cmake_package_install`.
+
+#### Using Mbed TLS Crypto pkg-config file
+The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the `tfpsacrypto` library.
+A new pkg-config file, `tfpsacrypto.pc`, is also provided.
+Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags.
+
+### Audience-Specific Notes
+
+#### Application Developers using a distribution package
+You should stay with Mbed TLS if you use TLS or X.509 functionality.
+- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
+ - Linking against the cryptography library or CMake targets.
+ - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`).
+
+### Developer or package maintainers
+If you build or distribute Mbed TLS:
+- The build system is now CMake only, Makefiles and Visual Studio projects are removed.
+- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule.
+- You should update submodules recursively after checkout.
+- Review [File and directory relocations](#file-and-directory-relocations) for updated paths.
+- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
+ - Linking against the cryptography library or CMake targets.
+ - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`).
+- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)).
+
+### Platform Integrators
+If you integrate Mbed TLS with a platform or hardware drivers:
+- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively.
+- The PSA driver wrapper is now generated in TF-PSA-Crypto.
+- Platform-specific configuration are now handled in `crypto_config.h`.
+- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto.