| fwkpfv(1) | General Commands Manual | fwkpfv(1) |
fwkpfv — FireWire
kprintf viewer
fwkpfv |
[--appendlog]
[--openlog] [--newlog]
[--prefix] [--publish]
[--single]
[--buffer=boot-args]
[--setargs[=boot-args]]
[--setpm] [--disable]
[--erase] [--ioff]
[--restart] [--help] |
Use fwkpfv to receive FireWire kprintf logging. FireWireKPrintf redirects "kprintf()" logging to FireWire. Kernel printfs or "kprintfs" are used by many kernel services as a low level logging mechanism. They can also be used in third party kernel extensions. FireWire kprintfs are available very early in the kernel's startup and right until the cpu is powered down at sleep, restarted, or shutdown. Similarly, they are available almost as soon as the cpu is powered when waking. They can be useful for debugging kernel code (including KEXTs), particularly sleep/wake issues where the display and/or ethernet is unavailable.
The available options are as follows:
--appendlog,
-a--openlog,
-o-a.--newlog,
-n-a.--prefix,
-p--publish,
-k--single,
-s--buffer=size,
-bsize--file=path,
-b-path--setargs[=boot-args],
-r[boot-args]--setpm,
-m--disable,
-x--erase,
-e--ioff--restart--help,
-hUnlike in the past, Mac OS X 10.5 has integrated FireWireKPrintf functionality, so it is not necessary to install a separate kext to enable kprintf logging over FireWire.
While the symbol for kprintf() is available at all times, the calls are essentially ignored unless activated with a boot argument (see below).
While the new FireWireKPrintf is integrated with the normal FireWire stack, once the machine begins logging kprintfs via FireWire, normal FireWire services will stop until the machine is restarted. Once in logging mode, all typical FireWire services (like FireWire hard disk access) will be unavailable. It is expected that any devices connected before logging will be forcefully removed. If you need to log while also using the FireWire stack, please use FireLog (see the FireWireSDK).
The new integrated FireWireKPrintf cannot be used while the old AppleFireWireKPrintf.kext is installed. Remove it to use the integrated version.
The new viewer will be able to capture kprintf logs from the old-style AppleFireWireKPrintf.kext, however, the old-style viewer will not work with the integrated FireWireKPrintf services.
To use the FireWireKPrintf, two machines must be setup as such:
% sudo nvram
boot-args="debug=0x8"% fwkpfv(If the machine is running Tiger:
Run the FireWireKPrintf viewer tool included in the FireWireSDK available
at http://developer.apple.com/sdk/.)FireWireKPrintf implements a few options that can be set as a "boot-arg," much like the "debug" variable. The "fwkpf" variable specifies the timestamp format (calculated on the target, before transmission), timestamp padding, verbose kprintf printing, and synchronous mode. To set the "fwkpf" variable, choose a timestamp unit and add any of the "additive" options. The default timestamp is 0x4 (microseconds).
Timestamp Formats (not additive):
Additive Options:
If not defined, the "fwkpf" variable defaults to "0x004."
Once the viewer is running, he target machine is logging, and both machines are connected with a FireWire cable, you will see output similar to the following:
% fwkpfvWelcome to FireWireKPrintf (viewer
x.x.x).c>50.097255 AppleFWOHCI_KPF
version x.x.xc>55.110783 AppleFWOHCI_KPF
(re)initializedc>55.110793 Log saverc>55.129614 in.c: warning can't
plumb proto if=fw0 type 144 error=17If you are seeing the following symptoms:
There is no output from the fwkpfv tool on the second machine:
The machine hangs at boot:
To disable the FireWireKPrintf, delete the target machine's boot-args. Within Terminal.app run the following:
For more information on the debug flags, please see Technical Note TN2118. Setting the boot-arg variable "io" to "0x80" will turn on a significant 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"FireWireKPrintf tries to catch kprintf calls as soon as its start() routine is called. All kprintf calls after this point will be saved until the FireWire hardware has been initialized completely (which is also early in the boot process), however, the timestamps for these very early logs will reference the time they were sent via FireWire, not when kprintf() was called. All timestamps can be assumed accurate after the log from FireWireKPrintf that reads something similar to:
FWKPF: Time
Format->...Similar to very early boot logs, kprintf() calls by the kernel very early upon wake will be saved and sent after the FireWire hardware has had time to initialize. Likewise, the timestamps for these early logs may reflect a yet-to-be-initialized cpu time. These timestamps will be extremely large and clearly recognizable.
With exception to the two cases above (very early boot and very early sleep) when the FireWire hardware cannot be initialized without stopping kernel progression, all FireWireKPrintf logs are sent synchronously. This means that if the log is sent successfully, it is guaranteed to be on the wire before the call returns. If the log cannot be sent, an error will be written to system.log.
The "FireWire" tab of "/Applications/Utilities/System Profiler.app" will allow you to see if FireWireKPrintf has disabled normal FireWire services. To this end, if FireWire is disabled, unplug any FireWire cables and restart the Mac to restore normal FireWire services. Additionally, be mindful to restart machines that have dropped into logging mode as soon as you have finished using FireWireKPrintf logging.
Some applications, such as the Startup Disk preference pane, set the boot-args themselves. Therefore, it is always best to boot to the partition you wish to debug, set the boot-args, and then restart.
When a viewer Mac is connected to a logging (target) Mac, all normal FireWire services stop, including FireWire disk access. It may take a few moments for the disk to disappear on the logging Mac, but once you have connected a viewer Mac, it will be impossible to use a FireWire hard disk without restarting.
The following log is often shown when you first connect:
in.c: warning can't plumb proto
if=fw0 type 144 error=17FireWireKPrintf works on both Intel and PowerPC based Macs. The integrated FireWireKPrintf and fwkpfv is new for Leopard and is not included in any previous OS release.
To avoid conflicts it is best not to have other FireWire devices plugged into the host or target machines while using FireWireKPrintf. Having more than 2 nodes total (i.e. the two CPUs) may cause unexpected results.
The fwkpfv utility is able to receive logging from multiple machines. Connecting more than one logging target machine to a viewer will result in individual Terminal windows showing machine specific logs. A full, unparsed log is saved to "/Library/Logs/fwkpf.log". You may also force machine ID prefixation to each log by specifying the "-i" flags to fwkpfv.
FireWireKPrintf is compatible with FireWireKDP. To use both, it is recommended to set the boot-args using the following command: % sudo nvram boot-args="debug=0x14e kdp_match_name=firewire" Of course, you may modify or add boot-args to suit your needs (see note above).
Remember, you can clear the scrollback buffer of Terminal.app by selecting "Clear Scrollback" (or Cmd-K) from the "Scrollback" menu.
The "built-in" kprintf output is target machine specific. This is due to special casing of hardware and other states. It may also vary with operating system version and even kext versions. Remember, a developer can change their kprintf() calls at any time.
Most Macs have the ability to output a significant volume of power management logging, which may be useful while debugging sleep/wake issues. Many options are defined in <Kernel/IOKit/IOKitDebug.h>.
FireLog and FireWireKPrintf are different, both in theory and practice. FireLog is a high speed logging system which requires a framework. Most importantly, FireLog uses a buffering system (in a pull manner) to prevent the loss of logs during high logging volume or low processing time. Conversely, FireWireKPrintf employs a push method of sending each log onto the wire as soon as it is available. Furthermore, FireWireKPrintf is available sooner in the kernel's startup. FireLog is an excellent solution if you need high speed logging.
| September 15, 2008 | Mac OS X |