aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorBernhard Kaindl <bk@suse.de>2008-01-30 07:34:11 -0500
committerIngo Molnar <mingo@elte.hu>2008-01-30 07:34:11 -0500
commitf212ec4b7b4d84290f12c9c0416cdea283bf5f40 (patch)
tree9beb7e5b87bac80410767fd3aacd93f92ecb0c04 /Documentation
parent6194ba6ff6ccf8d5c54c857600843c67aa82c407 (diff)
x86: early boot debugging via FireWire (ohci1394_dma=early)
This patch adds a new configuration option, which adds support for a new early_param which gets checked in arch/x86/kernel/setup_{32,64}.c:setup_arch() to decide wether OHCI-1394 FireWire controllers should be initialized and enabled for physical DMA access to allow remote debugging of early problems like issues ACPI or other subsystems which are executed very early. If the config option is not enabled, no code is changed, and if the boot paramenter is not given, no new code is executed, and independent of that, all new code is freed after boot, so the config option can be even enabled in standard, non-debug kernels. With specialized tools, it is then possible to get debugging information from machines which have no serial ports (notebooks) such as the printk buffer contents, or any data which can be referenced from global pointers, if it is stored below the 4GB limit and even memory dumps of of the physical RAM region below the 4GB limit can be taken without any cooperation from the CPU of the host, so the machine can be crashed early, it does not matter. In the extreme, even kernel debuggers can be accessed in this way. I wrote a small kgdb module and an accompanying gdb stub for FireWire which allows to gdb to talk to kgdb using remote remory reads and writes over FireWire. An version of the gdb stub fore FireWire is able to read all global data from a system which is running a a normal kernel without any kernel debugger, without any interruption or support of the system's CPU. That way, e.g. the task struct and so on can be read and even manipulated when the physical DMA access is granted. A HOWTO is included in this patch, in Documentation/debugging-via-ohci1394.txt and I've put a copy online at ftp://ftp.suse.de/private/bk/firewire/docs/debugging-via-ohci1394.txt It also has links to all the tools which are available to make use of it another copy of it is online at: ftp://ftp.suse.de/private/bk/firewire/kernel/ohci1394_dma_early-v2.diff Signed-Off-By: Bernhard Kaindl <bk@suse.de> Tested-By: Thomas Renninger <trenn@suse.de> Signed-off-by: Ingo Molnar <mingo@elte.hu> Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/debugging-via-ohci1394.txt179
1 files changed, 179 insertions, 0 deletions
diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.txt
new file mode 100644
index 000000000000..de4804e8b396
--- /dev/null
+++ b/Documentation/debugging-via-ohci1394.txt
@@ -0,0 +1,179 @@
1
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
25Memory access is currently limited to the low 4G of physical address
26space which can be a problem on IA64 machines where memory is located
27mostly above that limit, but it is rarely a problem on more common
28hardware such as hardware based on x86, x86-64 and PowerPC.
29
30Together with a early initialization of the OHCI-1394 controller for debugging,
31this facility proved most useful for examining long debugs logs in the printk
32buffer on to debug early boot problems in areas like ACPI where the system
33fails to boot and other means for debugging (serial port) are either not
34available (notebooks) or too slow for extensive debug information (like ACPI).
35
36Drivers
37-------
38
39The OHCI-1394 drivers in drivers/firewire and drivers/ieee1394 initialize
40the OHCI-1394 controllers to a working state and can be used to enable
41physical DMA. By default you only have to load the driver, and physical
42DMA access will be granted to all remote nodes, but it can be turned off
43when using the ohci1394 driver.
44
45Because these drivers depend on the PCI enumeration to be completed, an
46initialization routine which can runs pretty early (long before console_init(),
47which makes the printk buffer appear on the console can be called) was written.
48
49To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
50Provide code for enabling DMA over FireWire early on boot) and pass the
51parameter "ohci1394_dma=early" to the recompiled kernel on boot.
52
53Tools
54-----
55
56firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
57it from PowerPC to x86 and x86_64 and added functionality, firescope can now
58be used to view the printk buffer of a remote machine, even with live update.
59
60Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
61from 32-bit firescope and vice versa:
62- ftp://ftp.suse.de/private/bk/firewire/tools/firescope-0.2.2.tar.bz2
63
64and he implemented fast system dump (alpha version - read README.txt):
65- ftp://ftp.suse.de/private/bk/firewire/tools/firedump-0.1.tar.bz2
66
67There is also a gdb proxy for firewire which allows to use gdb to access
68data which can be referenced from symbols found by gdb in vmlinux:
69- ftp://ftp.suse.de/private/bk/firewire/tools/fireproxy-0.33.tar.bz2
70
71The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
72yet stable) with kgdb over an memory-based communication module (kgdbom).
73
74Getting Started
75---------------
76
77The OHCI-1394 specification regulates that the OHCI-1394 controller must
78disable all physical DMA on each bus reset.
79
80This means that if you want to debug an issue in a system state where
81interrupts are disabled and where no polling of the OHCI-1394 controller
82for bus resets takes place, you have to establish any FireWire cable
83connections and fully initialize all FireWire hardware __before__ the
84system enters such state.
85
86Step-by-step instructions for using firescope with early OHCI initialization:
87
881) Verify that your hardware is supported:
89
90 Load the ohci1394 or the fw-ohci module and check your kernel logs.
91 You should see a line similar to
92
93 ohci1394: fw-host0: OHCI-1394 1.1 (PCI): IRQ=[18] MMIO=[fe9ff800-fe9fffff]
94 ... Max Packet=[2048] IR/IT contexts=[4/8]
95
96 when loading the driver. If you have no supported controller, many PCI,
97 CardBus and even some Express cards which are fully compliant to OHCI-1394
98 specification are available. If it requires no driver for Windows operating
99 systems, it most likely is. Only specialized shops have cards which are not
100 compliant, they are based on TI PCILynx chips and require drivers for Win-
101 dows operating systems.
102
1032) Establish a working FireWire cable connection:
104
105 Any FireWire cable, as long at it provides electrically and mechanically
106 stable connection and has matching connectors (there are small 4-pin and
107 large 6-pin FireWire ports) will do.
108
109 If an driver is running on both machines you should see a line like
110
111 ieee1394: Node added: ID:BUS[0-01:1023] GUID[0090270001b84bba]
112
113 on both machines in the kernel log when the cable is plugged in
114 and connects the two machines.
115
1163) Test physical DMA using firescope:
117
118 On the debug host,
119 - load the raw1394 module,
120 - make sure that /dev/raw1394 is accessible,
121 then start firescope:
122
123 $ firescope
124 Port 0 (ohci1394) opened, 2 nodes detected
125
126 FireScope
127 ---------
128 Target : <unspecified>
129 Gen : 1
130 [Ctrl-T] choose target
131 [Ctrl-H] this menu
132 [Ctrl-Q] quit
133
134 ------> Press Ctrl-T now, the output should be similar to:
135
136 2 nodes available, local node is: 0
137 0: ffc0, uuid: 00000000 00000000 [LOCAL]
138 1: ffc1, uuid: 00279000 ba4bb801
139
140 Besides the [LOCAL] node, it must show another node without error message.
141
1424) Prepare for debugging with early OHCI-1394 initialization:
143
144 4.1) Kernel compilation and installation on debug target
145
146 Compile the kernel to be debugged with CONFIG_PROVIDE_OHCI1394_DMA_INIT
147 (Kernel hacking: Provide code for enabling DMA over FireWire early on boot)
148 enabled and install it on the machine to be debugged (debug target).
149
150 4.2) Transfer the System.map of the debugged kernel to the debug host
151
152 Copy the System.map of the kernel be debugged to the debug host (the host
153 which is connected to the debugged machine over the FireWire cable).
154
1555) Retrieving the printk buffer contents:
156
157 With the FireWire cable connected, the OHCI-1394 driver on the debugging
158 host loaded, reboot the debugged machine, booting the kernel which has
159 CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
160
161 Then, on the debugging host, run firescope, for example by using -A:
162
163 firescope -A System.map-of-debug-target-kernel
164
165 Note: -A automatically attaches to the first non-local node. It only works
166 reliably if only connected two machines are connected using FireWire.
167
168 After having attached to the debug target, press Ctrl-D to view the
169 complete printk buffer or Ctrl-U to enter auto update mode and get an
170 updated live view of recent kernel messages logged on the debug target.
171
172 Call "firescope -h" to get more information on firescope's options.
173
174Notes
175-----
176Documentation and specifications: ftp://ftp.suse.de/private/bk/firewire/docs
177
178FireWire is a trademark of Apple Inc. - for more information please refer to:
179http://en.wikipedia.org/wiki/FireWire