manpagez: man pages & more
man fwkdp(1)
Home | html | info | man
fwkdp(1)                  BSD General Commands Manual                 fwkdp(1)


NAME

     fwkdp -- FireWire KDP Tool


SYNOPSIS

     fwkdp [--setargs[=boot-args]] [--proxy] [--gdb] [--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 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.


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.

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

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


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 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 operating system's symbol file.
                      % gdb mach_kernel
                See the Apple Development Kits webpage for the proper "Kernel
                Debug Kit" which will contain the proper "mach_kernel" symbol
                file. See step 6 for more info.
           3.   Within GDB, load the appropriate "kgmacros" (commonly found
                along with symbolic mach_kernel).
                      (gdb) source kgmacros
           4.   Within GDB set the target to remote-kdp.
                      (gdb) target remote-kdp
           5.   Within GDB, attach using kdp-reattach.
                      (gdb) kdp-reattach localhost
           6.   The connection should be established. Use gdb as you would
                over Ethernet.
           7.   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.


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 mean-
     ingless 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                      September 18, 2008                      Mac OS X

Mac OS X 10.9 - Generated Sat Oct 12 11:17:37 CDT 2013
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.