1 files changed, 35 insertions, 0 deletions

diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index a60e3e9a80..de2ea773e5 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -105,6 +105,41 @@ some obscure bugs.
 Any logic based on ``BB_CURRENT_MC`` equalling to ``default`` by default should
 be changed to be equal to an empty string.
 
+Virtual toolchain provider changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Support was added for virtual providers on a per-recipe basis for specific
+key toolchain providers listed in ``BB_VIRTUAL_RECIPE_PROVIDERS``. As part of
+that support, the ``cross`` providers were simplified to remove the triplet
+prefix (:term:`TARGET_PREFIX`, :term:`SDK_PREFIX` and :term:`HOST_PREFIX`) and
+generalise the naming. Here are examples of how references to these variables
+can be changed to use the new ``cross`` syntax::
+
+   virtual/${HOST_PREFIX}binutils -> virtual/cross-binutils
+   virtual/${TARGET_PREFIX}binutils -> virtual/cross-binutils
+
+   virtual/${HOST_PREFIX}gcc -> virtual/cross-cc
+   virtual/${TARGET_PREFIX}gcc -> virtual/cross-cc
+   virtual/${SDK_PREFIX}gcc -> virtual/nativesdk-cross-cc
+
+   virtual/${HOST_PREFIX}compilerlibs -> virtual/compilerlibs
+   virtual/${TARGET_PREFIX}compilerlibs -> virtual/compilerlibs
+   virtual/nativesdk-${SDK_PREFIX}compilerlibs -> virtual/nativesdk-compilerlibs
+
+   virtual/${TARGET_PREFIX}g++ -> virtual/cross-c++
+
+A :term:`PREFERRED_PROVIDER` assignment can be transformed as follows::
+
+   PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}binutils -> PREFERRED_PROVIDER_virtual/cross-binutils
+   PREFERRED_PROVIDER_virtual/${SDK_PREFIX}binutils -> PREFERRED_PROVIDER_virtual/cross-binutils:class-nativesdk
+   PREFERRED_PROVIDER_virtual/${SDK_PREFIX}g++ -> PREFERRED_PROVIDER_virtual/nativesdk-cross-c++
+
+The above examples should cover most cases, but there might be situations where
+replacing is not as straightforward. For more examples, see the commit
+:oe_git:`"classes/recipes: Switch virtual/XXX-gcc to virtual/cross-cc (and
+c++/binutils)" </openembedded-core/commit/?id=4ccc3bc8266c>` in
+:term:`OpenEmbedded-Core (OE-Core)`.
+
 Recipe changes
 ~~~~~~~~~~~~~~