1 ===================================
2 In-kernel memory-mapped I/O tracing
3 ===================================
4
5
6 Home page and links to optional user space too
7
8 https://nouveau.freedesktop.org/wiki/M
9
10 MMIO tracing was originally developed by Intel
11 Injection Test Harness. In Dec 2006 - Jan 2007
12 Jeff Muizelaar created a tool for tracing MMIO
13 project in mind. Since then many people have c
14
15 Mmiotrace was built for reverse engineering an
16 the Nouveau project as the first real user. On
17 are supported.
18
19 Out-of-tree mmiotrace was originally modified
20 ftrace framework by Pekka Paalanen <pq@iki.fi>.
21
22
23 Preparation
24 -----------
25
26 Mmiotrace feature is compiled in by the CONFIG
27 disabled by default, so it is safe to have thi
28 supported, but tracing is unreliable and may m
29 is on-line, therefore mmiotrace takes all but
30 activation. You can re-enable CPUs by hand, bu
31 is no way to automatically detect if you are l
32
33
34 Usage Quick Reference
35 ---------------------
36 ::
37
38 $ mount -t debugfs debugfs /sys/kernel
39 $ echo mmiotrace > /sys/kernel/tracing
40 $ cat /sys/kernel/tracing/trace_pipe >
41 Start X or whatever.
42 $ echo "X is up" > /sys/kernel/tracing
43 $ echo nop > /sys/kernel/tracing/curre
44 Check for lost events.
45
46
47 Usage
48 -----
49
50 Make sure debugfs is mounted to /sys/kernel/de
51 If not (requires root privileges)::
52
53 $ mount -t debugfs debugfs /sys/kernel
54
55 Check that the driver you are about to trace i
56
57 Activate mmiotrace (requires root privileges):
58
59 $ echo mmiotrace > /sys/kernel/tracing
60
61 Start storing the trace::
62
63 $ cat /sys/kernel/tracing/trace_pipe >
64
65 The 'cat' process should stay running (sleepin
66
67 Load the driver you want to trace and use it.
68 accesses to areas that are ioremapped while mm
69
70 During tracing you can place comments (markers
71 $ echo "X is up" > /sys/kernel/tracing/trace_m
72 This makes it easier to see which part of the
73 which action. It is recommended to place descr
74 do.
75
76 Shut down mmiotrace (requires root privileges)
77
78 $ echo nop > /sys/kernel/tracing/curre
79
80 The 'cat' process exits. If it does not, kill
81 pressing ctrl+c.
82
83 Check that mmiotrace did not lose events due t
84
85 $ grep -i lost mydump.txt
86
87 which tells you exactly how many events were l
88
89 $ dmesg
90
91 to view your kernel log and look for "mmiotrac
92 events were lost, the trace is incomplete. You
93 try again. Buffers are enlarged by first seein
94 are::
95
96 $ cat /sys/kernel/tracing/buffer_size_
97
98 gives you a number. Approximately double this
99 instance::
100
101 $ echo 128000 > /sys/kernel/tracing/bu
102
103 Then start again from the top.
104
105 If you are doing a trace for a driver project,
106 do the following before sending your results::
107
108 $ lspci -vvv > lspci.txt
109 $ dmesg > dmesg.txt
110 $ tar zcf pciid-nick-mmiotrace.tar.gz
111
112 and then send the .tar.gz file. The trace comp
113 "pciid" and "nick" with the PCI ID or model na
114 under investigation and your nickname.
115
116
117 How Mmiotrace Works
118 -------------------
119
120 Access to hardware IO-memory is gained by mapp
121 calling one of the ioremap_*() functions. Mmio
122 __ioremap() function and gets called whenever
123 an event that is recorded into the trace log.
124 are not caught, since the mapping always exist
125
126 MMIO accesses are recorded via page faults. Ju
127 the mapped pages are marked as not present. An
128 fault. The page fault handler calls mmiotrace
129 marks the page present, sets TF flag to achiev
130 fault handler. The instruction that faulted is
131 entered. Here mmiotrace again marks the page a
132 is decoded to get the type of operation (read/
133 read or written. These are stored to the trace
134
135 Setting the page present in the page fault han
136 machines. During the single stepping other CPU
137 and events can be missed without a notice. Re-
138 tracing is discouraged.
139
140
141 Trace Log Format
142 ----------------
143
144 The raw log is text and easily filtered with e
145 one line in the log. A record starts with a ke
146 dependent arguments. Arguments are separated b
147 end of line. The format for version 20070824 i
148
149 Explanation Keyword Space-separated argume
150 ----------------------------------------------
151
152 read event R width, timestamp, map
153 write event W width, timestamp, map
154 ioremap event MAP timestamp, map id, phy
155 iounmap event UNMAP timestamp, map id, PC,
156 marker MARK timestamp, text
157 version VERSION the string "20070824"
158 info for reader LSPCI one line from lspci -v
159 PCI address map PCIDEV space-separated /proc/
160 unk. opcode UNKNOWN timestamp, map id, phy
161
162 Timestamp is in seconds with decimals. Physica
163 is a kernel virtual address. Width is the data
164 data value. Map id is an arbitrary id number i
165 used in an operation. PC is the program counte
166 zero if it is not recorded. PID is always zero
167 originating in user space memory is not yet su
168
169 For instance, the following awk filter will pa
170 physical addresses in the range [0xfb73ce40, 0
171 ::
172
173 $ awk '/W 4 / { adr=strtonum($5); if (
174 adr < 0xfb800000) print; }'
175
176
177 Tools for Developers
178 --------------------
179
180 The user space tools include utilities for:
181 - replacing numeric addresses and values wit
182 - replaying MMIO logs, i.e., re-executing th
183
184
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.