From 63c00a545e539d5b156ae0bec028ac5764931e03 Mon Sep 17 00:00:00 2001
From: Peter Ujfalusi <peter.ujfalusi@linux.intel.com>
Date: Wed, 3 Jan 2024 15:08:42 +0200
Subject: [PATCH] intel_debug: introduction: Update default IPC4 topology path
 with example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We need to keep the topology files for different ADSP generations separate
because they can include NHLT blobs and the blobs are not compatible among
different versions.

While this only affects generically named topology files
(sof-hda-generic*.tplg), it is cleaner to expect the topology files to be
stored under different directories rather than having some in sof-ipc4-tplg
root and some under directories.
Keeping the generational topology files in separate directory also enables
us to offer backwards compatibility for deployed MTL installs with older
kernels.

The new default topology path shall be:
/lib/firmware/intel/sof-ipc4-tplg/PLAT/sof-CONFIG.tplg

With a practical note that the PLAT is symlinked to a common directory for
the generation they belopng to:
.
└── intel
    ├── sof-ace-tplg -> sof-ipc4-tplg/ACE1
    └── sof-ipc4-tplg
        ├── ACE1
        ├── CAVS2.5
        ├── mtl -> ACE1
        ├── tgl -> CAVS2.5
        └── tgl-h -> CAVS2.5

Signed-off-by: Peter Ujfalusi <peter.ujfalusi@linux.intel.com>
---
 getting_started/intel_debug/introduction.rst | 35 ++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/getting_started/intel_debug/introduction.rst b/getting_started/intel_debug/introduction.rst
index 37fddd1..2c68707 100644
--- a/getting_started/intel_debug/introduction.rst
+++ b/getting_started/intel_debug/introduction.rst
@@ -178,11 +178,42 @@ reconfigured with tools but requires expert knowledge of the ALSA/ASoC/topology
      - CONFIG = topology variant needed for detected hardware configuration
    * - Tiger Lake and newer
      - IPC4
-     - /lib/firmware/intel/sof-ipc4-tplg/sof-CONFIG.tplg
+     - /lib/firmware/intel/sof-ipc4-tplg/PLAT/sof-CONFIG.tplg
      - CONFIG = topology variant needed for detected hardware configuration
 
+Practical notes on IPC4 deployment
+ - In practice the topology files should be grouped by generations and platforms should be symlinked to the matching generation
+ - For compatibility reasons for **Meteor Lake**'s ``/lib/firmware/intel/sof-ace-tplg`` must be symlinked to ``/lib/firmware/intel/sof-ipc4-tplg/ACE1``
+
+::
+
+   .
+   └── intel
+       ├── sof-ace-tplg -> sof-ipc4-tplg/ACE1
+       └── sof-ipc4-tplg
+           ├── ACE1
+           │   ├── sof-*.tplg
+           │   ├── ...
+           │   └── sof-*.tplg
+           ├── ACE2 -> ACE1
+           ├── adl -> CAVS2.5
+           ├── adl-n -> CAVS2.5
+           ├── adl-s -> CAVS2.5
+           ├── arl -> ACE1
+           ├── arl-s -> ACE1
+           ├── CAVS2.5
+           │   ├── sof-*.tplg
+           │   ├── ...
+           │   └── sof-*.tplg
+           ├── ehl -> CAVS2.5
+           ├── lnl -> ACE2
+           ├── mtl -> ACE1
+           ├── rpl -> CAVS2.5
+           ├── rpl-s -> CAVS2.5
+           ├── tgl -> CAVS2.5
+           └── tgl-h -> CAVS2.5
+
 Important notices:
- - For compatibility reasons for **Meteor Lake and newer** ``/lib/firmware/intel/sof-ace-tplg`` must be symlinked to ``/lib/firmware/intel/sof-ipc4-tplg``
  - The standard Linux firmware search path and order is followed. The above table covers the base "/lib/firmware" case. See https://docs.kernel.org/driver-api/firmware/fw_search_path.html for more information.
  - The topology folder and filename can be overridden with "tplg_path" and "tplg_filename" `snd_sof_pci` kernel parameters.