|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
fwkpfv(1) BSD General Commands Manual fwkpfv(1)
NAME
fwkpfv -- FireWire kprintf viewer
SYNOPSIS
fwkpfv [--appendlog] [--openlog] [--newlog] [--prefix] [--publish] [--single] [--buffer=boot-args]
[--setargs[=boot-args]] [--setpm] [--disable] [--erase] [--ioff] [--restart] [--help]
DESCRIPTION
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 mecha-nism. mechanism.
nism. 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 ether-net ethernet
net is unavailable.
OPTIONS
The available options are as follows:
--appendlog, -a
Append output logging to /tmp/fwkpf.log.
--openlog, -o
Open log file with Console.app. Only valid with -a.
--newlog, -n
Create a new log file, rather than append. Only valid with -a.
--prefix, -p
Prefix logger machine's ID to each log.
--publish, -k
Do not publish FireWire unit directory keys.
--single, -s
Use a single window even if multiple loggers are present.
--buffer=size, -bsize
Sets the host's psuedo address space queue buffer to sizein bytes. Increasing this value may
help avoid potential packet loss. The default buffer size is 204,800 bytes.
--file=path, -b-path
Sets the log file path, if in use, to pathgiven as a path to a file. The tilde character is not
allowed.
--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 typical usage cases, when this tool 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.
--setpm, -m
Sets the nvram boot-args on the current machine to "debug=0x14e io=0x880". 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).
--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 fwkpfv.
COMPATABILITY
Unlike 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, how-ever, however,
ever, the old-style viewer will not work with the integrated FireWireKPrintf services.
USAGE
To use the FireWireKPrintf, two machines must be setup as such:
- On the Target machine (to be debugged):
1. Boot the Mac from the partition you wish to use.
2. Set kernel boot arguments to enable kernel printfs:
% sudo nvram boot-args="debug=0x8"
While only the debug bit equivalent to '0x8' is required for kprintf logging, you
may want to set the debug variable to '0x14e' to enable other debugging services.
For more information on the debug flags, please see Technical Note TN2118. For more
logging options, please see <Kernel/IOKit/IOKitDebug.h>.
3. Restart the target Mac.
4. Disconnect any FireWire device.
- On the debugger machine with Mac OS X and Developer Tools installed, run from Terminal.app:
% fwkpfv
(If the machine is running Tiger: Run the FireWireKPrintf viewer tool included in the
FireWireSDK available at http://developer.apple.com/sdk/.)
- Connect the two machines together using a FireWire cable.
- After 5 seconds, you should see output in the viewer and kprintf logging is flowing. Note: At
this point, normal FireWire services will cease to exist on the target until the machine is
restarted.
TARGET-SIDE OPTIONS
FireWireKPrintf implements a few options that can be set as a "boot-arg," much like the "debug" vari-able. variable.
able. The "fwkpf" variable specifies the timestamp format (calculated on the target, before transmis-sion), transmission),
sion), 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 (microsec-onds). (microseconds).
onds).
Timestamp Formats (not additive):
_x_ Converted FW Cycle Time Units (c) - Classic time format shown as "Seconds.Microseconds". The
Second unit rolls over every 128 seconds. Driven by the FireWire clock.
_x1 Absolute Time Units (a) - "Absolute" time units derived directly from the kernel's uptime
clock.
_x2 FireWire Time Units (w) - Shown as "Seconds:Cycles:Offset". Driven by the FireWire clock. Sec-onds Seconds
onds rollover every 128 seconds. 8000 cycles per second. 3072 offset counts per cycle. Equiva-lent Equivalent
lent to FireBug's time format.
_x3 Nanoseconds Time Units (n) - The kernel's uptime clock converted to nanoseconds.
_x4 Microseconds Time Units (u) - The kernel's uptime clock converted to microseconds.
_x5 Milliseconds Time Units (m) - The kernel's uptime clock converted to milliseconds.
_x6 Seconds Time Units (s) - Shown as "Seconds:Milliseconds:Microseconds". Converted from kernel's
uptime clock.
_x7 Day Time Units (d) - "Days:Hours:Minutes:Seconds:Milliseconds:Microseconds". Converted from
kernel's uptime clock.
_xF No Time Units (-) - No time units, displayed as "-".
Additive Options:
_x1_ Append output logging to /Library/Logs/FireWireKPrintf.log.
_x1__ Open log file with Console.app. Only valid with "-o".
_x8__ Create a new log file, rather than append. Only valid with "-o".
_x8___ Prefix logger machine's ID to each log.
For example, if you wish to display microsecond time units with padding, synchronous mode enabled, and
verbose printing disabled, the target's boot-args would be as follows: "debug=0x14e fwkpf=0x114". On
the target, run the following in Terminal.app: % sudo nvram boot-args="debug=0x14e fwkpf=0x114"
If not defined, the "fwkpf" variable defaults to "0x004."
DECIPHERING THE OUTPUT
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:
% fwkpfv
Welcome to FireWireKPrintf (viewer x.x.x).
c>50.097255 AppleFWOHCI_KPF version x.x.x
c>55.110783 AppleFWOHCI_KPF (re)initialized
c>55.110793 Log saver
c>55.129614 in.c: warning can't plumb proto if=fw0 type 144 error=17
'Welcome to FireWireKPrintf (viewer x.x.x)'
signifies viewer tool start correctly. If multiple interfaces are present on the debugger machine,
it will give an interface count.
'AppleFWOHCI_KPF version x.x.x'
signifies the AppleFireWireKPrintf kext has (re)initialized the FireWire hardware for use in a
FireWIreKPrintf manner.
'FWKPF: Time Format->...'
displays the time format declared in the target's boot-args. See the "Options" section of this
document to select a different time format.
'c>13.481567'
displays the time at which the kprintf call was logged. Prefixed with the letter that corresponds
to the time formats listed above. The format of this time log is displayed upon start and can be
changed in the target's boot-args. See above.
'... in.c: warning can't...'
the const char * string from the kprintf() call; the log. (This is a normal log.)
TROUBLESHOOTING
If you are seeing the following symptoms:
There is no output from the fwkpfv tool on the second machine:
- Make sure the two machines are connected with a good FireWire cable.
- Run "nvram boot-args" and verify that the boot-args are set correctly.
- Be sure you're using the new fwkpfv utility, version 2.1 or newer.
The machine hangs at boot:
- Sometimes the console will hang at boot when there is a high volume of logging to screen. Try
booting in non-verbose mode or limiting the volume of logging. Remove the "-v" from your
machine's boot-args. Or remove "io=0x80".
DISABLING
To disable the FireWireKPrintf, delete the target machine's boot-args. Within Terminal.app run the fol-lowing: following:
lowing:
- % sudo nvram -d boot-args
- OR set the boot-args variable to your previous setting.
- 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 vari-able variable
able "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 exam-ple, example,
ple, to add power management logging and verbose mode:
% sudo nvram boot-args="debug=0x8 io=0x80 -v"
The timestamps for very early boot logs are inconsistent:
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->...
The timestamps for very early wake logs are inconsistent:
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.
Synchronous or Non-Synchronous?:
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 syn-chronously. synchronously.
chronously. 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.
How do I know if I have enabled FireWireKPrintf and have 'normal' FireWire disabled?:
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.
My boot-args disappeared unexpectedly:
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.
My FireWire drive mounts on a second machine and then disappears off the first:
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.
I see an error when I first connect:
The following log is often shown when you first connect:
in.c: warning can't plumb proto if=fw0 type 144 error=17
It is a normal log from a different part of the system and should not be of any concern.
Compatibility with Intel and PPC:
FireWireKPrintf 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.
Other FireWire Devices:
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.
Logging from multiple machines:
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.
Using FireWireKPrintf with FireWireKDP:
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).
How do I clear the viewer?:
Remember, you can clear the scrollback buffer of Terminal.app by selecting "Clear Scrollback" (or Cmd-K) CmdK)
K) from the "Scrollback" menu.
Why do I see different logging with different machines?:
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 devel-oper developer
oper can change their kprintf() calls at any time.
Can I see more logging?:
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>.
What about FireLog?:
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 solu-tion solution
tion if you need high speed logging.
FILES
/usr/bin/fwkpfv
is installed as part of the Mac OS X Developer Tools.
SEE ALSO
fwkdp(1)
Mac OS X September 15, 2008 Mac OS X
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.