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