[PATCH i-g-t v2 39/39] docs: Add Chamelium v3

[Louis Chauvet <louis.chauvet@bootlin.com>]

Add documentation around the Chamelium v3, its new features and its
capabilities.

Signed-off-by: Louis Chauvet <louis.chauvet@bootlin.com>
---
 docs/chamelium.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 83 insertions(+), 7 deletions(-)

diff --git a/docs/chamelium.txt b/docs/chamelium.txt
index 64f851c2841c..3179b39dc155 100644
--- a/docs/chamelium.txt
+++ b/docs/chamelium.txt
@@ -19,7 +19,10 @@ part of the ChromeOS effort under the name Chameleon and was later made external
 as part of the ChromiumOS effort, under the name Chamelium.
 
 A new Chamelium V3 (Cv3) was released in 2022, which is built with different
-hardware while maintaining software backwards compatibility with v2.
+hardware, using almost the same API with chamelium v2. Some features are not
+present in the chamelium v3: plug all ports at the same time, take a screen
+capture of a small part of the screen, audio recording... The main goal of the
+Cv3 is to bring MST support.
 
 Chamelium V2
 ------------
@@ -41,7 +44,7 @@ While the FPGA is used for logic control, the CPU runs daemons that allow the
 board to be controlled over the network via a XMLRPC interface.
 
 [Current limitation] Cv3 hardware uses an ITE chip which allows only 1 port to
-be plugged in a time. This limitation will be fixed in the upcoming iteration. 
+be plugged in a time. This limitation will be fixed in the upcoming iteration.
 
 Chamelium V2 Documentation
 --------------------------
@@ -50,6 +53,12 @@ Documentation about the Chamelium is made available by Google through the
 ChromiumOS projet wiki:
 https://www.chromium.org/chromium-os/developer-library/guides/hardware-schematics/chamelium/
 
+Chamelium V2 Documentation
+--------------------------
+
+Documentation about the Cv3 is made available by Google directly in the git
+repository: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/chameleon/v3/doc/
+
 Setting up Chamelium V2
 -----------------------
 
@@ -76,6 +85,16 @@ and then configure eth0 like so:
 This document supposes that target PC's network IP has "192.168.1.1/24" and
 the Chamelium's network IP has "192.168.1.2/24".
 
+Setting up Chamelium V3
+-----------------------
+
+To setup the chamelium software, you can refer to the chamelium documentation:
+https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/chameleon/v3/doc/first_boot.md
+
+Once setup you can define a static IP address with network manager (a nice TUI
+is installed: `nmtui`) or use DHCP to set a stable one. It is required as the IGT
+tests will need to communicate with the chamelium.
+
 Deploying the Chamelium With IGT
 --------------------------------
 
@@ -115,6 +134,16 @@ example (only Chamelium.URL is mandatory):
     # The URL used for connecting to the Chamelium's RPC server
     URL=http://192.168.1.2:9992
 
+
+By default, the IGT tests will perform autodiscovery. As it can take some time, you can
+manually define a static configuration. This configuration will be trusted by the test
+and no autodetection will be performed, so if the physical connexion is not exactly
+the same the tests will fail.
+
+As the Cv3 brings support for MST, two different configuration format are used.
+
+For chamelium v2:
+
     # The rest of the sections are used for defining connector mappings. This
     # is optional if the same connector type (ex. DP-DP) is used on both sides,
     # the mappings will be discovered automatically.
@@ -142,6 +171,38 @@ example (only Chamelium.URL is mandatory):
     [Chamelium:VGA-1]
     ChameliumPortID=4
 
+For chamelium v3:
+
+    # For physical ports
+    [Chameliumv3:<port_id>]
+    PortName=<drm connector name>
+
+    # For MST parent ports
+    [Chameliumv3:<port_id>]
+    MstPath=<mst path of this port>
+
+    # For MST children ports
+    [Chameliumv3:<port_id>]
+    MstPath=<mst path of this port>
+    ChameliumParentID=<parent id on the chamelium side>
+
+To generate the Cv3 configuration, you can use this minimal file, the
+first chamelium test will perform an autodetection and save the result in igtrc:
+
+    [Chamelium]
+    # The URL used for connecting to the Chamelium's RPC server
+    URL=http://192.168.1.2:9992
+    ChameliumAutodetectSave=1
+
+As the chamelium is also used for emulating display, it can be useful to plug some ports during "normal" testings. To do
+so, you have to use the options ConnectOnAnyTest and, if needed, EDID. This does not work yet for MST.
+
+    [Chameliumv3:<port_id>]
+    PortName=<drm connector name>
+    ConnectOnAnyTest=true
+    EDID=<EDID name you want to plug, leave empty to get the list of supported EDID>
+
+
 Chamelium V2 Port IDs
 ---------------------
 defined at: https://chromium.googlesource.com/chromiumos/platform/chameleon/+/master/chameleond/utils/ids.py
@@ -150,12 +211,27 @@ DP2 (located next to the VGA connector) = 2
 HDMI = 3
 VGA = 4
 
-Cv3 Port IDs
+Chamelium V3 Port IDs
 ---------------------
-DP1 (top left) = 0
-DP2 (top right) = 1
-HDMI1 (bottom left) = 2
-HDMI2 (bottom right) = 3
+
+Four ports are available with the Cv3: 2 DP and 2 HDMI. With MST, 4 more virtual ports
+are available. Obviously, as the same physical port is connected to different hardware
+emulation, you can't plug all the chamelium ports at the same time.
+
+
+DP1, at the top left, can be used as:
+- Physical DP, port_id = 0
+- Emulated DP, port_id = 4
+
+DP2, at the top right can be used as:
+- Physical DP, port_id = 1
+- MST DP, port_id = 5, and its children 6, 7, 8
+
+HDMI1 (bottom left):
+- Physical HDMI, port_id = 2
+
+HDMI2 (bottom right):
+- Physical HDMI, port_id = 3
 
 Running the Chamelium With IGT
 ------------------------------

-- 
2.44.2