Manual Pages for UNIX Darwin command on man fwkdp

fwkdp(1) BSD General Commands Manual fwkdp(1)

NAME

ffwwkkddpp - FireWire KDP Tool

SYNOPSIS

ffwwkkddpp [--sseettaarrggss[=boot-args]] [--pprrooxxyy] [--ggddbb] [--ccoorree] [--vveerrbboossee]

[--hheellpp]

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 GDB 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 sec-

tion "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. OOPPTTIIOONNSS

--sseettaarrggss[=boot-args], -rr[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.

--pprrooxxyy, -pp

Use proxy mode only.

--ggddbb, -gg

Use proxy mode only and automatically start gdb as a child process.

--ccoorree, -cc

Use core dump receive mode only.

--vveerrbboossee, -vv

Verbose mode.

--hheellpp, -hh

Displays usage info for fwkdp.

CCOOMMPPAATTAABBIILLIITTYY 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 kdpmatchname=firewire". UUSSAAGGEE 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

kdpmatchname=firewire" 2. Reboot the target.

3. Break into debug mode as you would with Ethernet. (NMI but-

ton, 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 GDB with the target OS' symbol file.

% gdb machkernel

See the Apple Development Kits webpage for the proper "Kernel Debug Kit" which will contain the proper "machkernel" symbol file. See step 6 for more info.

3. Within GDB set the target to remote-kdp.

(gdb) target remote-kdp

4. Within GDB, attach using kdp-reattach.

(gdb) kdp-reattach localhost

5. The connection should be established. Use gdb 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 Guide-

lines and Technical Note TN2118: Debugging With Kernel Core Dumps. CCOORREE DDUUMMPPSS

To capture kernel core dumps, set the proper bits of the boot-args' debug

variable and kdpmatchname equal to "firewire". In addition, an IP

address for the receiving computer is also required, although it's mean-

ingless over FireWire.

On the target machine, set the boot-args and restart.

% sudo nvram boot-args="debug=0xd46 panicdip=1.2.3.4

kdpmatchname=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. NNOOTTEESS

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. Having more than 2 nodes total (i.e. the two CPUs) may cause unexpected results. 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