Documentation/debugging-via-ohci1394.txt

   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 With most FireWire controllers, memory access is limited to the low 4 GB
  26 of physical address space.  This can be a problem on IA64 machines where
  27 memory is located mostly above that limit, but it is rarely a problem on
  28 more common hardware such as x86, x86-64 and PowerPC.  However, at least
  29 Agere/LSI FW643e and FW643e2 controllers are known to support access to
  30 physical addresses above 4 GB.
  31
  32 Together with a early initialization of the OHCI-1394 controller for debugging,
  33 this facility proved most useful for examining long debugs logs in the printk
  34 buffer on to debug early boot problems in areas like ACPI where the system
  35 fails to boot and other means for debugging (serial port) are either not
  36 available (notebooks) or too slow for extensive debug information (like ACPI).
  37
  38 Drivers
  39 -------
  40
  41 The firewire-ohci driver in drivers/firewire uses filtered physical
  42 DMA by default, which is more secure but not suitable for remote debugging.
  43 Pass the remote_dma=1 parameter to the driver to get unfiltered physical DMA.
  44
  45 Because the firewire-ohci driver depends on the PCI enumeration to be
  46 completed, an initialization routine which runs pretty early has been
  47 implemented for x86.  This routine runs long before console_init() can be
  48 called, i.e. before the printk buffer appears on the console.
  49
  50 To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
  51 Remote debugging over FireWire early on boot) and pass the parameter
  52 "ohci1394_dma=early" to the recompiled kernel on boot.
  53
  54 Tools
  55 -----
  56
  57 firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
  58 it from PowerPC to x86 and x86_64 and added functionality, firescope can now
  59 be used to view the printk buffer of a remote machine, even with live update.
  60
  61 Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
  62 from 32-bit firescope and vice versa:
  63 - http://v3.sk/~lkundrak/firescope/
  64
  65 and he implemented fast system dump (alpha version - read README.txt):
  66 - http://halobates.de/firewire/firedump-0.1.tar.bz2
  67
  68 There is also a gdb proxy for firewire which allows to use gdb to access
  69 data which can be referenced from symbols found by gdb in vmlinux:
  70 - http://halobates.de/firewire/fireproxy-0.33.tar.bz2
  71
  72 The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
  73 yet stable) with kgdb over an memory-based communication module (kgdbom).
  74
  75 Getting Started
  76 ---------------
  77
  78 The OHCI-1394 specification regulates that the OHCI-1394 controller must
  79 disable all physical DMA on each bus reset.
  80
  81 This means that if you want to debug an issue in a system state where
  82 interrupts are disabled and where no polling of the OHCI-1394 controller
  83 for bus resets takes place, you have to establish any FireWire cable
  84 connections and fully initialize all FireWire hardware __before__ the
  85 system enters such state.
  86
  87 Step-by-step instructions for using firescope with early OHCI initialization:
  88
  89 1) Verify that your hardware is supported:
  90
  91    Load the firewire-ohci module and check your kernel logs.
  92    You should see a line similar to
  93
  94    firewire_ohci 0000:15:00.1: added OHCI v1.0 device as card 2, 4 IR + 4 IT
  95    ... contexts, quirks 0x11
  96
  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
 104    The mentioned kernel log message contains ">4 GB phys DMA" in case of
 105    OHCI-1394 controllers which support accesses above this limit.
 106
 107 2) 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
 115    firewire_core 0000:15:00.1: created device fw1: GUID 00061b0020105917, S400
 116
 117    on both machines in the kernel log when the cable is plugged in
 118    and connects the two machines.
 119
 120 3) Test physical DMA using firescope:
 121
 122    On the debug host, make sure that /dev/fw* is accessible,
 123    then start firescope:
 124
 125         $ firescope
 126         Port 0 (/dev/fw1) opened, 2 nodes detected
 127
 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
 144 4) 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
 157 5) 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
 176 Notes
 177 -----
 178 Documentation and specifications: http://halobates.de/firewire/
 179
 180 FireWire is a trademark of Apple Inc. - for more information please refer to:
 181 http://en.wikipedia.org/wiki/FireWire