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