|
|
Zenoss Core: 2.2.4 is Now Available
09-30-2008
|
|
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 kernel core dump images transmitted over USB. As a complete technology, USBKDP redirects the kernel debugging KDP protocol 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 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 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 con- nected 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 information 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 supports: 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 run- ning 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 Terminal.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