manpagez: man pages & more
man usbkdp(1)
Home | html | info | man

usbkdp(1)                 BSD General Commands Manual                usbkdp(1)


NAME

     usbkdp -- USB KDP Tool


SYNOPSIS

     usbkdp


DESCRIPTION

     The usbkdp commandline tool is built to act as a proxy for the kernel
     debugging, which uses the KDP protocol over USB. It will also accept ker-
     nel core dump images transmitted over USB.
     As a complete technology, USBKDP redirects the kernel debugging KDP pro-
     tocol over USB. It enables live LLDB debugging of a trapped kernel over a
     Standard Type A USB debug cable. The debug cable only has the SS Tx-Rx
     pairs. The Vbus and Ground pins are shorted. It follows the same seamless
     operation as the Ethernet debugging.
     It provides the following advantages over Ethernet based remote debug-
     ging: - 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 required.  - Data
     rates upto, 5Gb/s.
     USBKDP also enables Remote Kernel Core Dumps over USB. 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 the kernel core dumps, see the section "Core
     Dumps". For more information on debugging with Kernel Core Dumps, please
     see: Technical Note TN2118: Debugging With Kernel Core Dumps.
     USBKDP works in two parts: kernel software on the target side (i.e. -
     machine to be debugged) and user-space software on the host side. Now,
     the target side software is integrated into the OS. This means that the
     USBKDP functionality is part of the IOUSBFamily.kext.


OPTIONS

     -v : Turn on verbose mode. It enables logging.  -h : Print help informa-
     tion about usbkdp.


COMPATABILITY

     It is compatible with the OSX platforms having XHCI support.


USAGE

     Connect two MACs via the USB debug cable and follow the steps below:
     On the target (machine to be debugged): 1. Set the boot-args to enable
     debugging over USB: a. To support legacy behavior we have the boot-args
     as (defaults to XHC1): % sudo nvram boot-args="debug=0x14e
     kdp_match_name=usb" b. In case of multiple controllers we explicitly are
     required to specify the controller, example: % sudo nvram boot-
     args="debug=0x14e kdp_match_name=XHC2"
     2. Reboot the target: % sudo reboot 3. Break into the debug mode as you
     would for Ethernet/Firewire i.e. NMI button, panic, debugger traps, etc.
     On the host (machine where lldb session will run) 1. Run usbkdp: % usbkdp
     The USBKDP tool, currently, has only one default behaviour where it sup-
     ports: a. Live debugging using lldb.  b. Receving core-dumps, via lldb
     session, using sendcore macro.
     USBKDP is a stateless translator that shunts data between the network
     KDP/UDP port and the USB connection.  Once started it can be left running
     indefinitely, for one lldb session.
     2. On another terminal window, run the lldb with the target operating
     system's symbol file.  % lldb ./kernel See the Apple Development Kits
     webpage for the "Kernel Debug Kit" which will contain the matching kernel
     symbols.
     3. Attach to the panicked target: (lldb) kdp-remote localhost This will
     establish the connection and load the appropriate symbols, if lldb is
     configured correctly.  Use all the standard lldb commands and macros as
     you would for debugging over Ethernet.
     4. To send the core to the host you will have to use the following:
     (lldb) sendcore localhost (lldb) detach or (lldb) sendcore localhost
     (lldb) continue


DISABLING

     To disable the USBKDP, delete the target machine's boot-args. Within Ter-
     minal.app run the following:
           -   % sudo nvram -d boot-args
           -   OR set the boot-args variable to your previous setting, by
               removing the kdp_match_name=usb.
           -   Restart to target Mac.


NOTES

   Other debug/boot-arg options:
     For more information on the debug flags, please see Technical Note
     TN2118. Setting the boot-arg variable "io" to "0x80" will turn on a sig-
     nificant volume of power management logging, which may be useful while
     debugging sleep/wake issues. Similarly, adding the "-v" argument to the
     boot-args will enable Mac OS X's verbose mode. This may be useful for
     watching local logging during boot or shutdown. For example, to add power
     management logging and verbose mode:
           % sudo nvram boot-args="debug=0x8 io=0x80 -v"


FILES

     /usr/bin/usbkdp
             is installed as part of the Mac OS X Developer Tools.


SEE ALSO

     fwkdp(1)

Mac OS X                         March 3, 2016                        Mac OS X

Mac OS X 10.12.3 - Generated Sat Feb 4 18:20:53 CST 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.