1Chamelium Support in IGT 2======================== 3 4This document provides information, instructions and a tasks list for Chamelium 5support in IGT. 6 7Introduction 8------------ 9 10The Chamelium is a platform that acts as a display monitor emulator. It provides 11advanced access and control over the various signals a display receives. 12 13As such, it allows testing display features that can otherwise not be tested in 14IGT without external hardware. 15 16The platform was developed by Google in order to test display and audio-related 17features of ChromeOS devices. It was initially developed internally by Google as 18part of the ChromeOS effort under the name Chameleon and was later made external 19as part of the ChromiumOS effort, under the name Chamelium. 20 21It consists of a custom-made display emulator board connected to an Arrow SoCKit 22via a flexible cable, with two DisplayPort connectors, one HDMI and one VGA. 23 24The SoCKit uses a Cyclone V SoC, with both a FPGA and an ARM CPU. While the FPGA 25is used for logic control, the CPU runs daemons that allow the board to be 26controlled over the network via a XMLRPC interface. 27 28Documentation 29------------- 30 31Documentation about the Chamelium is made available by Google through the 32ChromiumOS projet wiki: https://www.chromium.org/chromium-os/testing/chamelium 33 34Deploying the Chamelium With IGT 35-------------------------------- 36 37Instructions from the ChromiumOS wiki detail how to setup the Chamelium: 38https://www.chromium.org/chromium-os/testing/chamelium#TOC-Setting-up-Chamelium 39 40The should be followed up until the "Setup your Linux host, DUT and the FPGA" 41section. At this point, IGT has to be configured to connect to the Chamelium. 42 43It may be necessary to give the Chamelium a static IP address, depending on 44the network setup. This can be configured (via the serial console) by editing 45the Debian-styled /etc/network/interfaces configuration file. Example setup: 46 47 sudo screen /dev/ttyUSB0 115200 48 sudo vi /etc/network/interfaces 49 50and then configure eth0 like so: 51 52 iface eth0 inet static 53 address 192.168.1.2 54 netmask 255.255.255.0 55 gateway 192.168.1.1 56 57This document supposes that target PC's network IP has "192.168.1.1/24" and 58the Chamelium's network IP has "192.168.1.2/24". 59 60Chamelium support requires setting up dedicated IGT configuration, as explained 61in the Core and Chamelium parts of the IGT API Reference in the documentation. 62 63Note that running the chamelium tests with the Chamelium configuration deployed 64and the Chamelium disconnected or unreachable will result in network timeouts 65that take seconds. It is thus preferable (especially in the case of an automated 66CI system with a shared testlist) to remove the Chamelium configuration from the 67hosts that shouldn't connect to the Chamelium so that they can be skipped, which 68is faster than a network timeout. 69 70It should also be noted that each Chamelium platform should only be used for 71testing a single target device at a time. This is because the reset call issued 72by the IGT tests is common to all connectors and thus one machine running a test 73on a given connector may reset the Chamelium while another machine is running 74a test on another connector. 75 76IGT's behavior can be configured through a configuration file. 77By default, this file is expected to exist in ~/.igtrc 78In order to run tests using the Chamelium, a valid configuration file must be 79present. It must contain Chamelium-specific keys as shown with the following 80example (only Chamelium.URL is mandatory): 81 82 # The common configuration section follows. 83 [Common] 84 # The path to dump frames that fail comparison checks 85 FrameDumpPath=/root/ 86 87 # The following section is used for configuring the Device Under Test. 88 # It is not mandatory and allows overriding default values. 89 [DUT] 90 SuspendResumeDelay=15 91 92 [Chamelium] 93 # The URL used for connecting to the Chamelium's RPC server 94 URL=http://192.168.1.2:9992 95 96 # The rest of the sections are used for defining connector mappings. This 97 # is optional, the mappings will be discovered automatically. 98 99 # The name of the DRM connector 100 # The DP-1 of [Chamelium:DP-1] and the HDMI-A-1 of [Chamelium:HDMI-A-1] indicate 101 # "connector info type" of /sys/kernel/debug/dri/0/i915_display_info. 102 [Chamelium:DP-1] 103 # The ChameliumPortID indicates physical port (device) id of a Chamelium Board. 104 # A Chamelium daemon program defines these port ids as 105 # DP1 (located next to the HDMI port) = 1 106 # DP2 (located next to the VGA connector) = 2 107 # HDMI = 3 and VGA = 4 108 # The port ids are defined at: 109 # https://chromium.googlesource.com/chromiumos/platform/chameleon/+/master/chameleond/utils/ids.py 110 ChameliumPortID=1 111 112 [Chamelium:HDMI-A-2] 113 ChameliumPortID=3 114 115 [Chamelium:VGA-1] 116 ChameliumPortID=4 117 118Running the Chamelium With IGT 119------------------------------ 120 121$ ./scripts/run-tests.sh -t chamelium 122 123Debugging the Chamelium 124----------------------- 125 126It is possible to manually send Chamelium RPC calls with the xmlrpc utility 127(from xmlrpc-c). For instance, to plug the DisplayPort port: 128$ xmlrpc http://192.168.1.2:9992 Plug i/1 129 130The xmlrpc utility documentation is available at: 131http://xmlrpc-c.sourceforge.net/doc/xmlrpc.html 132 133The XML-RPC Chamelium interface is described here: 134https://chromium.googlesource.com/chromiumos/platform/chameleon/+/refs/heads/master/chameleond/interface.py 135 136Logs that may be useful for debugging can be obtained either by connecting to 137the board via SSH or serial console and looking at the daemon logs from 138/var/log, such as: 139$ tail -f /var/log/chameleon* 140 141Daemon Source, Build and Deploy 142------------------------------- 143 144Source code for the daemon running on the Chamelium is available at: 145https://chromium.googlesource.com/chromiumos/platform/chameleon/ 146 147Building the daemon requires a GNU EABI ARMv7 GCC toolchain, that must be 148specified via the CC variable, such as: 149$ make CC=arm-linux-gnueabihf-gcc 150 151The result can be deployed to the chamelium with the remote-install target and 152specifying the network address for the chamelium via the CHAMELEON_HOST 153variable, such as: 154$ make remote-install CHAMELEON_HOST=192.168.72.1 155 156The process requires the Chamelium to be connected to the Internet to succeed. 157 158Audio Capture 159------------- 160 161The Chamelium supports audio capture. IGT tests take advantage of the 162Chamelium streaming server to download audio samples from the Chamelium. 163 164IGT needs direct access to audio devices through ALSA, so PulseAudio needs to 165be stopped (otherwise audio tests will automatically get skipped). To make sure 166PulseAudio isn't running: 167 168- Edit /etc/pulse/client.conf and add autospawn=no 169- Run `pulseaudio --kill` (if it succeeds, it means PulseAudio was running) 170- Make sure a DE that automatically spawns PulseAudio isn't running 171 172In case a test fails, the raw captured audio files will be dumped in a WAV 173file. 174 175Contributing Changes to the Daemon 176---------------------------------- 177 178Contributions to the Chamelium daemon, just like any contribution to ChromiumOS, 179are submitted and reviewed at: https://chromium-review.googlesource.com/ 180 181The ChromiumOS project provides an extensive developer guide: 182https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md 183It assumes running within the ChromiumOS build system. Since this is likely not 184the case for contributing to the Chamelium daemon, only the part about 185uploading changes is relevant: 186https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Upload-your-changes-and-get-a-code-review 187 188Most of the process is about using the Gerrit web interface for submitting and 189having the change reviewed and not forgetting the Change-Id, TEST= and BUG= 190fields in the commit. 191 192Current Support in IGT 193---------------------- 194 195Support for the Chamelium platform in IGT is found in the following places: 196* lib/igt_chamelium.c: library with Chamelium-related helpers 197* tests/kms_chamelium.c: sub-tests using the Chamelium 198 199As of early April 2019, the following features are tested by IGT: 200* Pixel-by-pixel frame integrity tests for DP and HDMI 201* Error-trend-based frame integrity tests for VGA 202* CRC-based frame integrity tests for DP and HDMI 203* Hotplug event simple tests for all interfaces 204* Hotplug event stressing tests, emulating a flaky cable for DisplayPort and 205 HDMI 206* Hotplug event during suspend test for all interfaces, either separately for 207 each interface or combined 208* EDID display identifier integrity check for all interfaces 209* EDID display identifier change during suspend for all interfaces 210* Audio Fourier-based tests for DP at 48KHz 211 212Future Developments 213------------------- 214 215With the current generation of the hardware platform, support for testing a 216number of additional display features could be included as future developments, 217including: 218* Audio capture from HDMI 219* Check all channels are independent from each other 220* Playback using more than 2 channels, different sampling rates and different 221 sample sizes 222* High-bandwidth Digital Content Protection (HDCP) streaming to the display 223* Remote control forwarding (CEC) sent from the display 224* YUV colorspace for HDMI, instead of RGB 225* Partial testing of DP Multi-Stream Transport (MST) using an external MST hub 226 and the two available DP connectors of the platform 227 228While HDCP is already supported by the Chamelium daemon, features such as CEC 229and YUV are not and must be implemented there before any support for them can 230be added to IGT. Audio is supported by the Chamelium daemon for HDMI only and 231a way to retrieve the captured data via the XMLRPC interface needs to be added 232to the daemon. 233