fwkdp
fwkdp(1) General Commands Manual fwkdp(1)
NAME
fwkdp – FireWire KDP Tool
SYNOPSIS
fwkdp [--setargs[=boot-args]] [--proxy] [--core] [--verbose] [--disable]
[--erase] [--ioff] [--restart] [--help]
DESCRIPTION
Use fwkdp to act as a proxy for the kernel debugging KDP protocol over
FireWire. It will also accept kernel core dump images transmitted over
FireWire. Additionally, fwkdp can be used to set the boot-args necessary
for a target machine which is to be debugged.
As a complete technology, FireWireKDP redirects the kernel debugging KDP
protocol over FireWire. It enables live LLDB debugging of a trapped kernel
over a FireWire cable, just as you would over Ethernet. It provides the
following advantages over remote Ethernet kernel debugging:
- Available sooner in the kernel's startup.
- Available until right when the cpu is powered down at sleep and
almost as soon as the cpu is powered when waking.
- No IP network configuration is required.
FireWireKDP also enables Remote Kernel Core Dumps over FireWire. This
allows you to debug a static kernel at a later time without the need to be
connected at the time of debug. To enable kernel core dumps, see section
"CORE DUMPS". For more info on debugging with Kernel Core Dumps, please
see: Technical Note TN2118: Debugging With Kernel Core Dumps.
FireWireKDP works in two parts: kernel software on the target side (machine
to be debugged) and user-space software on the side of the host. Now, the
target side software is integrated into the OS. This means that
AppleFireWireKDP.kext is no longer necessary. See the installation
instructions below.
OPTIONS
--setargs[=boot-args], -r[boot-args]
Sets the nvram boot-args on the current machine to boot-args. This
flag should only be used on the target machine (which is contrary to
all other usage cases, when it is used on the host). If boot-args is
not passed, the tool will prompt the user as to which boot-args are
to be set.
--proxy, -p
Use proxy mode only.
--core, -c
Use core dump receive mode only.
--verbose, -v
Verbose mode.
--disable, -x
Sets the nvram boot-args on the current machine to "debug=0x146"
which disables kprintf logging. This flag should only be used on the
target machine (which is contrary to typical usage cases, when this
tool is used on the host).
--erase, -e
Deletes the boot-args variable from nvram. This flag should only be
used on the target machine (which is contrary to typical usage
cases, when this tool is used on the host).
--ioff
Turns off interactive mode.
--restart
Automatically restarts the machine only after the nvram has been
modified by this tool.
--help, -h
Displays usage info for fwkdp.
COMPATABILITY
FireWireKDP doesn't interfere with the loading of the normal FireWire stack
- it only touches the FireWire hardware when the kernel debugger is
invoked, either by a panic, NMI, trap, or similar.
Furthermore, FireWireKDP is designed to work cooperatively with
FireWireKPrintf. To use both you must use a combination of boot-args such
as "debug=0x14e kdp_match_name=firewire".
To use FireWireKDP on a non-built-in FireWire interface (e.g. when using a
Thunderbolt to FireWire adapter) add fwkdp=0x8000 to your boot-args.
USAGE
Connect two Macs via FireWire and follow the steps below.
On the target (machine to be debugged):
1. Use fwkdp to set the kernel boot arguments to enable live
debugging:
% fwkdp -r
If using FireWireKDP with FireWireKPrintf try:
% sudo nvram boot-args="debug=0x14e
kdp_match_name=firewire"
2. Reboot the target.
3. Break into debug mode as you would with Ethernet. (NMI button,
panic, debugger traps, etc.)
On the debugger machine:
1. Run fwkdp:
% fwkdp
The FireWireKDP tool defaults to both proxy and core-dump
receive mode. It is a stateless translator that shunts data
between the network KDP/UDP port and the FireWire connection.
Once started it can be left running indefinitely.
2. Run LLDB with the target operating system's symbol file.
% lldb kernel.development
See the Apple Development Kits webpage for the proper "Kernel
Debug Kit" which will contain the proper "kernel.development" or
"kernel.debug" "symbol file. See step 6 for more info.
3. Within LLDB, allow script loading to import the appropriate
kernel macros (commonly found along with symbolic mach_kernel).
(lldb) settings set target.load-script-from-symbol-file
true
4. Within LLDB, attach using kdp-remote.
(lldb) kdp-remote localhost
5. The connection should be established. Use lldb as you would over
Ethernet.
6. For more info on remote kernel debugging, please see "Two-
machine Debugging" of the I/O Kit Device Driver Design
Guidelines and Technical Note TN2118: Debugging With Kernel Core
Dumps.
CORE DUMPS
To capture kernel core dumps, set the proper bits of the boot-args' debug
variable and kdp_match_name equal to "firewire". In addition, an IP address
for the receiving computer is also required, although it's meaningless over
FireWire.
On the target machine, set the boot-args and restart.
% sudo nvram boot-args="debug=0xd46 _panicd_ip=1.2.3.4
kdp_match_name=firewire"
Connect the machine to be debugged to a second Mac with a FireWire cable.
Run "fwkdp" from a Terminal window on the second Mac; it will wait for the
target to transmit it's core after it drops to the debugger (panic, NMI,
etc.). For more info on the debugging with Kernel Core Dumps, please see
Technical Note TN2118: Debugging With Kernel Core Dumps.
NOTES
Post-Panic Hot-Plugs
Some Macs do not support post-panic debugging after hot-plugging
another Mac. To avoid this problem, keep a debugger Mac connected in
anticipation of a panic.
64-bit Debugging
FireWireKDP does work when running the kernel in 64-bit mode.
Sleep/Wake Notes
FireWireKDP will work if the target has been through a sleep/wake
cycle. However, if FireWireKDP has run (e.g. drop into debugger and
conitnue) on the target once, it might not work again if the machine
is sleep/wake cycled afterwards. Therefore, if you would like to
debug a sleep/wake issue with FireWireKDP, do not sleep between
breaks to the debugger.
Other FireWire Devices
To avoid conflicts it is best not to have other FireWire devices
plugged into the host or target machines while using any FireWire
debugging tools. However, it is possible to connect more than one
target machine to a single host (e.g. to collect core dumps).
Second FireWire Interface
FireWireKDP does not work on multiple FireWire interfaces. Please use
a built-in FireWire port without installing any FireWire add-in
cards.
FILES
/usr/bin/fwkdp is installed as part of the Mac OS X Developer Tools.
SEE ALSO
fwkpfv(1)
Mac OS X July 7, 2015 Mac OS X