linux/Documentation/debugging-via-ohci1394.txt
<<
>>
Prefs
   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 ohci1394 driver in drivers/ieee1394 initializes the OHCI-1394 controllers
  40to a working state and enables physical DMA by default for all remote nodes.
  41This can be turned off by ohci1394's module parameter phys_dma=0.
  42
  43The alternative firewire-ohci driver in drivers/firewire uses filtered physical
  44DMA by default, which is more secure but not suitable for remote debugging.
  45Compile the driver with CONFIG_FIREWIRE_OHCI_REMOTE_DMA (Kernel hacking menu:
  46Remote debugging over FireWire with firewire-ohci) to get unfiltered physical
  47DMA.
  48
  49Because ohci1394 and firewire-ohci depend on the PCI enumeration to be
  50completed, an initialization routine which runs pretty early has been
  51implemented for x86.  This routine runs long before console_init() can be
  52called, i.e. before the printk buffer appears on the console.
  53
  54To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
  55Remote debugging over FireWire early on boot) and pass the parameter
  56"ohci1394_dma=early" to the recompiled kernel on boot.
  57
  58Tools
  59-----
  60
  61firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
  62it from PowerPC to x86 and x86_64 and added functionality, firescope can now
  63be used to view the printk buffer of a remote machine, even with live update.
  64
  65Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
  66from 32-bit firescope and vice versa:
  67- http://halobates.de/firewire/firescope-0.2.2.tar.bz2
  68
  69and he implemented fast system dump (alpha version - read README.txt):
  70- http://halobates.de/firewire/firedump-0.1.tar.bz2
  71
  72There is also a gdb proxy for firewire which allows to use gdb to access
  73data which can be referenced from symbols found by gdb in vmlinux:
  74- http://halobates.de/firewire/fireproxy-0.33.tar.bz2
  75
  76The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
  77yet stable) with kgdb over an memory-based communication module (kgdbom).
  78
  79Getting Started
  80---------------
  81
  82The OHCI-1394 specification regulates that the OHCI-1394 controller must
  83disable all physical DMA on each bus reset.
  84
  85This means that if you want to debug an issue in a system state where
  86interrupts are disabled and where no polling of the OHCI-1394 controller
  87for bus resets takes place, you have to establish any FireWire cable
  88connections and fully initialize all FireWire hardware __before__ the
  89system enters such state.
  90
  91Step-by-step instructions for using firescope with early OHCI initialization:
  92
  931) 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
 1082) 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
 1213) 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
 1474) 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
 1605) 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
 179Notes
 180-----
 181Documentation and specifications: http://halobates.de/firewire/
 182
 183FireWire is a trademark of Apple Inc. - for more information please refer to:
 184http://en.wikipedia.org/wiki/FireWire
 185
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.