blob: fa0151a712f9c5a0d9fe43db6e0746ff4046a5e0 [file] [log] [blame]
Bernhard Kaindlf212ec42008-01-30 13:34:11 +01001
2 Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
3 ---------------------------------------------------------------------------
4
5Introduction
6------------
7
8Basically all FireWire controllers which are in use today are compliant
9to the OHCI-1394 specification which defines the controller to be a PCI
10bus master which uses DMA to offload data transfers from the CPU and has
11a "Physical Response Unit" which executes specific requests by employing
12PCI-Bus master DMA after applying filters defined by the OHCI-1394 driver.
13
14Once properly configured, remote machines can send these requests to
15ask the OHCI-1394 controller to perform read and write requests on
16physical system memory and, for read requests, send the result of
17the physical memory read back to the requester.
18
19With that, it is possible to debug issues by reading interesting memory
20locations such as buffers like the printk buffer or the process table.
21
22Retrieving a full system memory dump is also possible over the FireWire,
23using data transfer rates in the order of 10MB/s or more.
24
Stefan Richterfcd46b32014-01-18 17:32:20 +010025With most FireWire controllers, memory access is limited to the low 4 GB
26of physical address space. This can be a problem on IA64 machines where
27memory is located mostly above that limit, but it is rarely a problem on
28more common hardware such as x86, x86-64 and PowerPC. However, at least
29Agere/LSI FW643e and FW643e2 controllers are known to support access to
30physical addresses above 4 GB.
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010031
32Together with a early initialization of the OHCI-1394 controller for debugging,
33this facility proved most useful for examining long debugs logs in the printk
34buffer on to debug early boot problems in areas like ACPI where the system
35fails to boot and other means for debugging (serial port) are either not
36available (notebooks) or too slow for extensive debug information (like ACPI).
37
38Drivers
39-------
40
Lubomir Rintela9954ce2013-12-22 11:31:41 +010041The firewire-ohci driver in drivers/firewire uses filtered physical
Stefan Richter080de8c2008-02-28 20:54:43 +010042DMA by default, which is more secure but not suitable for remote debugging.
Lubomir Rintel8bc588e2013-12-22 11:34:22 +010043Pass the remote_dma=1 parameter to the driver to get unfiltered physical DMA.
Stefan Richter09d73282008-02-18 21:38:35 +010044
Lubomir Rintela9954ce2013-12-22 11:31:41 +010045Because the firewire-ohci driver depends on the PCI enumeration to be
Stefan Richter080de8c2008-02-28 20:54:43 +010046completed, an initialization routine which runs pretty early has been
47implemented for x86. This routine runs long before console_init() can be
48called, i.e. before the printk buffer appears on the console.
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010049
50To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
Stefan Richter080de8c2008-02-28 20:54:43 +010051Remote debugging over FireWire early on boot) and pass the parameter
52"ohci1394_dma=early" to the recompiled kernel on boot.
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010053
54Tools
55-----
56
57firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
58it from PowerPC to x86 and x86_64 and added functionality, firescope can now
59be used to view the printk buffer of a remote machine, even with live update.
60
61Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
62from 32-bit firescope and vice versa:
Lubomir Rintela9954ce2013-12-22 11:31:41 +010063- http://v3.sk/~lkundrak/firescope/
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010064
65and he implemented fast system dump (alpha version - read README.txt):
Justin P. Mattock211a6412009-09-29 15:13:58 -070066- http://halobates.de/firewire/firedump-0.1.tar.bz2
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010067
68There is also a gdb proxy for firewire which allows to use gdb to access
69data which can be referenced from symbols found by gdb in vmlinux:
Justin P. Mattock211a6412009-09-29 15:13:58 -070070- http://halobates.de/firewire/fireproxy-0.33.tar.bz2
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010071
72The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
73yet stable) with kgdb over an memory-based communication module (kgdbom).
74
75Getting Started
76---------------
77
78The OHCI-1394 specification regulates that the OHCI-1394 controller must
79disable all physical DMA on each bus reset.
80
81This means that if you want to debug an issue in a system state where
82interrupts are disabled and where no polling of the OHCI-1394 controller
83for bus resets takes place, you have to establish any FireWire cable
84connections and fully initialize all FireWire hardware __before__ the
85system enters such state.
86
87Step-by-step instructions for using firescope with early OHCI initialization:
88
891) Verify that your hardware is supported:
90
Lubomir Rintela9954ce2013-12-22 11:31:41 +010091 Load the firewire-ohci module and check your kernel logs.
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010092 You should see a line similar to
93
Lubomir Rintela9954ce2013-12-22 11:31:41 +010094 firewire_ohci 0000:15:00.1: added OHCI v1.0 device as card 2, 4 IR + 4 IT
95 ... contexts, quirks 0x11
Bernhard Kaindlf212ec42008-01-30 13:34:11 +010096
97 when loading the driver. If you have no supported controller, many PCI,
98 CardBus and even some Express cards which are fully compliant to OHCI-1394
99 specification are available. If it requires no driver for Windows operating
100 systems, it most likely is. Only specialized shops have cards which are not
101 compliant, they are based on TI PCILynx chips and require drivers for Win-
102 dows operating systems.
103
Stefan Richterfcd46b32014-01-18 17:32:20 +0100104 The mentioned kernel log message contains ">4 GB phys DMA" in case of
105 OHCI-1394 controllers which support accesses above this limit.
106
Bernhard Kaindlf212ec42008-01-30 13:34:11 +01001072) Establish a working FireWire cable connection:
108
109 Any FireWire cable, as long at it provides electrically and mechanically
110 stable connection and has matching connectors (there are small 4-pin and
111 large 6-pin FireWire ports) will do.
112
113 If an driver is running on both machines you should see a line like
114
Lubomir Rintela9954ce2013-12-22 11:31:41 +0100115 firewire_core 0000:15:00.1: created device fw1: GUID 00061b0020105917, S400
Bernhard Kaindlf212ec42008-01-30 13:34:11 +0100116
117 on both machines in the kernel log when the cable is plugged in
118 and connects the two machines.
119
1203) Test physical DMA using firescope:
121
Lubomir Rintela9954ce2013-12-22 11:31:41 +0100122 On the debug host, make sure that /dev/fw* is accessible,
Bernhard Kaindlf212ec42008-01-30 13:34:11 +0100123 then start firescope:
124
125 $ firescope
Lubomir Rintela9954ce2013-12-22 11:31:41 +0100126 Port 0 (/dev/fw1) opened, 2 nodes detected
Bernhard Kaindlf212ec42008-01-30 13:34:11 +0100127
128 FireScope
129 ---------
130 Target : <unspecified>
131 Gen : 1
132 [Ctrl-T] choose target
133 [Ctrl-H] this menu
134 [Ctrl-Q] quit
135
136 ------> Press Ctrl-T now, the output should be similar to:
137
138 2 nodes available, local node is: 0
139 0: ffc0, uuid: 00000000 00000000 [LOCAL]
140 1: ffc1, uuid: 00279000 ba4bb801
141
142 Besides the [LOCAL] node, it must show another node without error message.
143
1444) Prepare for debugging with early OHCI-1394 initialization:
145
146 4.1) Kernel compilation and installation on debug target
147
148 Compile the kernel to be debugged with CONFIG_PROVIDE_OHCI1394_DMA_INIT
149 (Kernel hacking: Provide code for enabling DMA over FireWire early on boot)
150 enabled and install it on the machine to be debugged (debug target).
151
152 4.2) Transfer the System.map of the debugged kernel to the debug host
153
154 Copy the System.map of the kernel be debugged to the debug host (the host
155 which is connected to the debugged machine over the FireWire cable).
156
1575) Retrieving the printk buffer contents:
158
159 With the FireWire cable connected, the OHCI-1394 driver on the debugging
160 host loaded, reboot the debugged machine, booting the kernel which has
161 CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
162
163 Then, on the debugging host, run firescope, for example by using -A:
164
165 firescope -A System.map-of-debug-target-kernel
166
167 Note: -A automatically attaches to the first non-local node. It only works
168 reliably if only connected two machines are connected using FireWire.
169
170 After having attached to the debug target, press Ctrl-D to view the
171 complete printk buffer or Ctrl-U to enter auto update mode and get an
172 updated live view of recent kernel messages logged on the debug target.
173
174 Call "firescope -h" to get more information on firescope's options.
175
176Notes
177-----
Justin P. Mattock211a6412009-09-29 15:13:58 -0700178Documentation and specifications: http://halobates.de/firewire/
Bernhard Kaindlf212ec42008-01-30 13:34:11 +0100179
180FireWire is a trademark of Apple Inc. - for more information please refer to:
181http://en.wikipedia.org/wiki/FireWire