Back to home page

LXR

 
 

    


0001 
0002   Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
0003   ---------------------------------------------------------------------------
0004 
0005 Introduction
0006 ------------
0007 
0008 Basically all FireWire controllers which are in use today are compliant
0009 to the OHCI-1394 specification which defines the controller to be a PCI
0010 bus master which uses DMA to offload data transfers from the CPU and has
0011 a "Physical Response Unit" which executes specific requests by employing
0012 PCI-Bus master DMA after applying filters defined by the OHCI-1394 driver.
0013 
0014 Once properly configured, remote machines can send these requests to
0015 ask the OHCI-1394 controller to perform read and write requests on
0016 physical system memory and, for read requests, send the result of
0017 the physical memory read back to the requester.
0018 
0019 With that, it is possible to debug issues by reading interesting memory
0020 locations such as buffers like the printk buffer or the process table.
0021 
0022 Retrieving a full system memory dump is also possible over the FireWire,
0023 using data transfer rates in the order of 10MB/s or more.
0024 
0025 With most FireWire controllers, memory access is limited to the low 4 GB
0026 of physical address space.  This can be a problem on IA64 machines where
0027 memory is located mostly above that limit, but it is rarely a problem on
0028 more common hardware such as x86, x86-64 and PowerPC.
0029 
0030 At least LSI FW643e and FW643e2 controllers are known to support access to
0031 physical addresses above 4 GB, but this feature is currently not enabled by
0032 Linux.
0033 
0034 Together with a early initialization of the OHCI-1394 controller for debugging,
0035 this facility proved most useful for examining long debugs logs in the printk
0036 buffer on to debug early boot problems in areas like ACPI where the system
0037 fails to boot and other means for debugging (serial port) are either not
0038 available (notebooks) or too slow for extensive debug information (like ACPI).
0039 
0040 Drivers
0041 -------
0042 
0043 The firewire-ohci driver in drivers/firewire uses filtered physical
0044 DMA by default, which is more secure but not suitable for remote debugging.
0045 Pass the remote_dma=1 parameter to the driver to get unfiltered physical DMA.
0046 
0047 Because the firewire-ohci driver depends on the PCI enumeration to be
0048 completed, an initialization routine which runs pretty early has been
0049 implemented for x86.  This routine runs long before console_init() can be
0050 called, i.e. before the printk buffer appears on the console.
0051 
0052 To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
0053 Remote debugging over FireWire early on boot) and pass the parameter
0054 "ohci1394_dma=early" to the recompiled kernel on boot.
0055 
0056 Tools
0057 -----
0058 
0059 firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
0060 it from PowerPC to x86 and x86_64 and added functionality, firescope can now
0061 be used to view the printk buffer of a remote machine, even with live update.
0062 
0063 Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
0064 from 32-bit firescope and vice versa:
0065 - http://v3.sk/~lkundrak/firescope/
0066 
0067 and he implemented fast system dump (alpha version - read README.txt):
0068 - http://halobates.de/firewire/firedump-0.1.tar.bz2
0069 
0070 There is also a gdb proxy for firewire which allows to use gdb to access
0071 data which can be referenced from symbols found by gdb in vmlinux:
0072 - http://halobates.de/firewire/fireproxy-0.33.tar.bz2
0073 
0074 The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
0075 yet stable) with kgdb over an memory-based communication module (kgdbom).
0076 
0077 Getting Started
0078 ---------------
0079 
0080 The OHCI-1394 specification regulates that the OHCI-1394 controller must
0081 disable all physical DMA on each bus reset.
0082 
0083 This means that if you want to debug an issue in a system state where
0084 interrupts are disabled and where no polling of the OHCI-1394 controller
0085 for bus resets takes place, you have to establish any FireWire cable
0086 connections and fully initialize all FireWire hardware __before__ the
0087 system enters such state.
0088 
0089 Step-by-step instructions for using firescope with early OHCI initialization:
0090 
0091 1) Verify that your hardware is supported:
0092 
0093    Load the firewire-ohci module and check your kernel logs.
0094    You should see a line similar to
0095 
0096    firewire_ohci 0000:15:00.1: added OHCI v1.0 device as card 2, 4 IR + 4 IT
0097    ... contexts, quirks 0x11
0098 
0099    when loading the driver. If you have no supported controller, many PCI,
0100    CardBus and even some Express cards which are fully compliant to OHCI-1394
0101    specification are available. If it requires no driver for Windows operating
0102    systems, it most likely is. Only specialized shops have cards which are not
0103    compliant, they are based on TI PCILynx chips and require drivers for Win-
0104    dows operating systems.
0105 
0106    The mentioned kernel log message contains the string "physUB" if the
0107    controller implements a writable Physical Upper Bound register.  This is
0108    required for physical DMA above 4 GB (but not utilized by Linux yet).
0109 
0110 2) Establish a working FireWire cable connection:
0111 
0112    Any FireWire cable, as long at it provides electrically and mechanically
0113    stable connection and has matching connectors (there are small 4-pin and
0114    large 6-pin FireWire ports) will do.
0115 
0116    If an driver is running on both machines you should see a line like
0117 
0118    firewire_core 0000:15:00.1: created device fw1: GUID 00061b0020105917, S400
0119 
0120    on both machines in the kernel log when the cable is plugged in
0121    and connects the two machines.
0122 
0123 3) Test physical DMA using firescope:
0124 
0125    On the debug host, make sure that /dev/fw* is accessible,
0126    then start firescope:
0127 
0128         $ firescope
0129         Port 0 (/dev/fw1) opened, 2 nodes detected
0130 
0131         FireScope
0132         ---------
0133         Target : <unspecified>
0134         Gen    : 1
0135         [Ctrl-T] choose target
0136         [Ctrl-H] this menu
0137         [Ctrl-Q] quit
0138 
0139     ------> Press Ctrl-T now, the output should be similar to:
0140 
0141         2 nodes available, local node is: 0
0142          0: ffc0, uuid: 00000000 00000000 [LOCAL]
0143          1: ffc1, uuid: 00279000 ba4bb801
0144 
0145    Besides the [LOCAL] node, it must show another node without error message.
0146 
0147 4) Prepare for debugging with early OHCI-1394 initialization:
0148 
0149    4.1) Kernel compilation and installation on debug target
0150 
0151    Compile the kernel to be debugged with CONFIG_PROVIDE_OHCI1394_DMA_INIT
0152    (Kernel hacking: Provide code for enabling DMA over FireWire early on boot)
0153    enabled and install it on the machine to be debugged (debug target).
0154 
0155    4.2) Transfer the System.map of the debugged kernel to the debug host
0156 
0157    Copy the System.map of the kernel be debugged to the debug host (the host
0158    which is connected to the debugged machine over the FireWire cable).
0159 
0160 5) Retrieving the printk buffer contents:
0161 
0162    With the FireWire cable connected, the OHCI-1394 driver on the debugging
0163    host loaded, reboot the debugged machine, booting the kernel which has
0164    CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
0165 
0166    Then, on the debugging host, run firescope, for example by using -A:
0167 
0168         firescope -A System.map-of-debug-target-kernel
0169 
0170    Note: -A automatically attaches to the first non-local node. It only works
0171    reliably if only connected two machines are connected using FireWire.
0172 
0173    After having attached to the debug target, press Ctrl-D to view the
0174    complete printk buffer or Ctrl-U to enter auto update mode and get an
0175    updated live view of recent kernel messages logged on the debug target.
0176 
0177    Call "firescope -h" to get more information on firescope's options.
0178 
0179 Notes
0180 -----
0181 Documentation and specifications: http://halobates.de/firewire/
0182 
0183 FireWire is a trademark of Apple Inc. - for more information please refer to:
0184 https://en.wikipedia.org/wiki/FireWire