1.. SPDX-License-Identifier: GPL-2.0 2 3============================================= 4Linux Kernel GPIO based sloppy logic analyzer 5============================================= 6 7:Author: Wolfram Sang 8 9Introduction 10============ 11 12This document briefly describes how to run the GPIO based in-kernel sloppy 13logic analyzer running on an isolated CPU. 14 15The sloppy logic analyzer will utilize a few GPIO lines in input mode on a 16system to rapidly sample these digital lines, which will, if the Nyquist 17criteria is met, result in a time series log with approximate waveforms as they 18appeared on these lines. One way to use it is to analyze external traffic 19connected to these GPIO lines with wires (i.e. digital probes), acting as a 20common logic analyzer. 21 22Another feature is to snoop on on-chip peripherals if the I/O cells of these 23peripherals can be used in GPIO input mode at the same time as they are being 24used as inputs or outputs for the peripheral. That means you could e.g. snoop 25I2C traffic without any wiring (if your hardware supports it). In the pin 26control subsystem such pin controllers are called "non-strict": a certain pin 27can be used with a certain peripheral and as a GPIO input line at the same 28time. 29 30Note that this is a last resort analyzer which can be affected by latencies, 31non-deterministic code paths and non-maskable interrupts. It is called 'sloppy' 32for a reason. However, for e.g. remote development, it may be useful to get a 33first view and aid further debugging. 34 35Setup 36===== 37 38Your kernel must have CONFIG_DEBUG_FS and CONFIG_CPUSETS enabled. Ideally, your 39runtime environment does not utilize cpusets otherwise, then isolation of a CPU 40core is easiest. If you do need cpusets, check that helper script for the 41sloppy logic analyzer does not interfere with your other settings. 42 43Tell the kernel which GPIOs are used as probes. For a Device Tree based system, 44you need to use the following bindings. Because these bindings are only for 45debugging, there is no official schema:: 46 47 i2c-analyzer { 48 compatible = "gpio-sloppy-logic-analyzer"; 49 probe-gpios = <&gpio6 21 GPIO_OPEN_DRAIN>, <&gpio6 4 GPIO_OPEN_DRAIN>; 50 probe-names = "SCL", "SDA"; 51 }; 52 53Note that you must provide a name for every GPIO specified. Currently a 54maximum of 8 probes are supported. 32 are likely possible but are not 55implemented yet. 56 57Usage 58===== 59 60The logic analyzer is configurable via files in debugfs. However, it is 61strongly recommended to not use them directly, but to use the script 62``tools/gpio/gpio-sloppy-logic-analyzer``. Besides checking parameters more 63extensively, it will isolate the CPU core so you will have the least 64disturbance while measuring. 65 66The script has a help option explaining the parameters. For the above DT 67snippet which analyzes an I2C bus at 400kHz on a Renesas Salvator-XS board, the 68following settings are used: The isolated CPU shall be CPU1 because it is a big 69core in a big.LITTLE setup. Because CPU1 is the default, we don't need a 70parameter. The bus speed is 400kHz. So, the sampling theorem says we need to 71sample at least at 800kHz. However, falling edges of both signals in an I2C 72start condition happen faster, so we need a higher sampling frequency, e.g. 73``-s 1500000`` for 1.5MHz. Also, we don't want to sample right away but wait 74for a start condition on an idle bus. So, we need to set a trigger to a falling 75edge on SDA while SCL stays high, i.e. ``-t 1H+2F``. Last is the duration, let 76us assume 15ms here which results in the parameter ``-d 15000``. So, 77altogether:: 78 79 gpio-sloppy-logic-analyzer -s 1500000 -t 1H+2F -d 15000 80 81Note that the process will return you back to the prompt but a sub-process is 82still sampling in the background. Unless this has finished, you will not find a 83result file in the current or specified directory. For the above example, we 84will then need to trigger I2C communication:: 85 86 i2cdetect -y -r <your bus number> 87 88Result is a .sr file to be consumed with PulseView or sigrok-cli from the free 89`sigrok`_ project. It is a zip file which also contains the binary sample data 90which may be consumed by other software. The filename is the logic analyzer 91instance name plus a since-epoch timestamp. 92 93.. _sigrok: https://sigrok.org/ 94