About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / debugging-via-ohci1394.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 22:56 EST.

1	
2	  Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
3	  ---------------------------------------------------------------------------
4	
5	Introduction
6	------------
7	
8	Basically all FireWire controllers which are in use today are compliant
9	to the OHCI-1394 specification which defines the controller to be a PCI
10	bus master which uses DMA to offload data transfers from the CPU and has
11	a "Physical Response Unit" which executes specific requests by employing
12	PCI-Bus master DMA after applying filters defined by the OHCI-1394 driver.
13	
14	Once properly configured, remote machines can send these requests to
15	ask the OHCI-1394 controller to perform read and write requests on
16	physical system memory and, for read requests, send the result of
17	the physical memory read back to the requester.
18	
19	With that, it is possible to debug issues by reading interesting memory
20	locations such as buffers like the printk buffer or the process table.
21	
22	Retrieving a full system memory dump is also possible over the FireWire,
23	using data transfer rates in the order of 10MB/s or more.
24	
25	Memory access is currently limited to the low 4G of physical address
26	space which can be a problem on IA64 machines where memory is located
27	mostly above that limit, but it is rarely a problem on more common
28	hardware such as hardware based on x86, x86-64 and PowerPC.
29	
30	Together with a early initialization of the OHCI-1394 controller for debugging,
31	this facility proved most useful for examining long debugs logs in the printk
32	buffer on to debug early boot problems in areas like ACPI where the system
33	fails to boot and other means for debugging (serial port) are either not
34	available (notebooks) or too slow for extensive debug information (like ACPI).
35	
36	Drivers
37	-------
38	
39	The ohci1394 driver in drivers/ieee1394 initializes the OHCI-1394 controllers
40	to a working state and enables physical DMA by default for all remote nodes.
41	This can be turned off by ohci1394's module parameter phys_dma=0.
42	
43	The alternative firewire-ohci driver in drivers/firewire uses filtered physical
44	DMA by default, which is more secure but not suitable for remote debugging.
45	Compile the driver with CONFIG_FIREWIRE_OHCI_REMOTE_DMA (Kernel hacking menu:
46	Remote debugging over FireWire with firewire-ohci) to get unfiltered physical
47	DMA.
48	
49	Because ohci1394 and firewire-ohci depend on the PCI enumeration to be
50	completed, an initialization routine which runs pretty early has been
51	implemented for x86.  This routine runs long before console_init() can be
52	called, i.e. before the printk buffer appears on the console.
53	
54	To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
55	Remote debugging over FireWire early on boot) and pass the parameter
56	"ohci1394_dma=early" to the recompiled kernel on boot.
57	
58	Tools
59	-----
60	
61	firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
62	it from PowerPC to x86 and x86_64 and added functionality, firescope can now
63	be used to view the printk buffer of a remote machine, even with live update.
64	
65	Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
66	from 32-bit firescope and vice versa:
67	- http://halobates.de/firewire/firescope-0.2.2.tar.bz2
68	
69	and he implemented fast system dump (alpha version - read README.txt):
70	- http://halobates.de/firewire/firedump-0.1.tar.bz2
71	
72	There is also a gdb proxy for firewire which allows to use gdb to access
73	data which can be referenced from symbols found by gdb in vmlinux:
74	- http://halobates.de/firewire/fireproxy-0.33.tar.bz2
75	
76	The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
77	yet stable) with kgdb over an memory-based communication module (kgdbom).
78	
79	Getting Started
80	---------------
81	
82	The OHCI-1394 specification regulates that the OHCI-1394 controller must
83	disable all physical DMA on each bus reset.
84	
85	This means that if you want to debug an issue in a system state where
86	interrupts are disabled and where no polling of the OHCI-1394 controller
87	for bus resets takes place, you have to establish any FireWire cable
88	connections and fully initialize all FireWire hardware __before__ the
89	system enters such state.
90	
91	Step-by-step instructions for using firescope with early OHCI initialization:
92	
93	1) Verify that your hardware is supported:
94	
95	   Load the ohci1394 or the fw-ohci module and check your kernel logs.
96	   You should see a line similar to
97	
98	   ohci1394: fw-host0: OHCI-1394 1.1 (PCI): IRQ=[18]  MMIO=[fe9ff800-fe9fffff]
99	   ... Max Packet=[2048]  IR/IT contexts=[4/8]
100	
101	   when loading the driver. If you have no supported controller, many PCI,
102	   CardBus and even some Express cards which are fully compliant to OHCI-1394
103	   specification are available. If it requires no driver for Windows operating
104	   systems, it most likely is. Only specialized shops have cards which are not
105	   compliant, they are based on TI PCILynx chips and require drivers for Win-
106	   dows operating systems.
107	
108	2) Establish a working FireWire cable connection:
109	
110	   Any FireWire cable, as long at it provides electrically and mechanically
111	   stable connection and has matching connectors (there are small 4-pin and
112	   large 6-pin FireWire ports) will do.
113	
114	   If an driver is running on both machines you should see a line like
115	
116	   ieee1394: Node added: ID:BUS[0-01:1023]  GUID[0090270001b84bba]
117	
118	   on both machines in the kernel log when the cable is plugged in
119	   and connects the two machines.
120	
121	3) Test physical DMA using firescope:
122	
123	   On the debug host,
124		- load the raw1394 module,
125		- make sure that /dev/raw1394 is accessible,
126	   then start firescope:
127	
128		$ firescope
129		Port 0 (ohci1394) opened, 2 nodes detected
130	
131		FireScope
132		---------
133		Target : <unspecified>
134		Gen    : 1
135		[Ctrl-T] choose target
136		[Ctrl-H] this menu
137		[Ctrl-Q] quit
138	
139	    ------> Press Ctrl-T now, the output should be similar to:
140	
141		2 nodes available, local node is: 0
142		 0: ffc0, uuid: 00000000 00000000 [LOCAL]
143		 1: ffc1, uuid: 00279000 ba4bb801
144	
145	   Besides the [LOCAL] node, it must show another node without error message.
146	
147	4) Prepare for debugging with early OHCI-1394 initialization:
148	
149	   4.1) Kernel compilation and installation on debug target
150	
151	   Compile the kernel to be debugged with CONFIG_PROVIDE_OHCI1394_DMA_INIT
152	   (Kernel hacking: Provide code for enabling DMA over FireWire early on boot)
153	   enabled and install it on the machine to be debugged (debug target).
154	
155	   4.2) Transfer the System.map of the debugged kernel to the debug host
156	
157	   Copy the System.map of the kernel be debugged to the debug host (the host
158	   which is connected to the debugged machine over the FireWire cable).
159	
160	5) Retrieving the printk buffer contents:
161	
162	   With the FireWire cable connected, the OHCI-1394 driver on the debugging
163	   host loaded, reboot the debugged machine, booting the kernel which has
164	   CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
165	
166	   Then, on the debugging host, run firescope, for example by using -A:
167	
168		firescope -A System.map-of-debug-target-kernel
169	
170	   Note: -A automatically attaches to the first non-local node. It only works
171	   reliably if only connected two machines are connected using FireWire.
172	
173	   After having attached to the debug target, press Ctrl-D to view the
174	   complete printk buffer or Ctrl-U to enter auto update mode and get an
175	   updated live view of recent kernel messages logged on the debug target.
176	
177	   Call "firescope -h" to get more information on firescope's options.
178	
179	Notes
180	-----
181	Documentation and specifications: http://halobates.de/firewire/
182	
183	FireWire is a trademark of Apple Inc. - for more information please refer to:
184	http://en.wikipedia.org/wiki/FireWire
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.