scsi_log(1M) — Series 700 Only

NAME

scsi_log − control and dump SCSI event log for sdisk, schgr, sflop, stape device drivers

SYNOPSIS

scsi_log [-V]
scsi_log [-h hpux_file] [-c core_file] [-f command_file] ... [command] ...
scsi_log [-s save_file] [-f command_file] ... [command] ...
scsi_log [-h hpux_file] [-i] [-f command_file] ... [command] ...

DESCRIPTION

scsi_log is the interface for control and decoding of the system’s SCSI event log. Information is logged at specific predetermined points throughout the SCSI I/O subsystem. SCSI event log information is most useful to the person who creates the log points; however, the information may also be useful for analysis of device-related issues.

scsi_log can be used to analyze the state of the SCSI I/O subsystem after a system crashes, using the “core” file created by use of savecore(1M). Specify the resulting /stand/vmunix and vm-core files using the -h and -c flag arguments.

scsi_log can be used on a running system to gain access to the current state of the SCSI I/O subsystem. When used in this way, scsi_log provides a logic-analyzer-like interface useful for limiting the events to be logged and stopping event logging when some trigger condition is met. scsi_log operates in this manner by default.

Scsi_log can be used on a kernel executable file to examine or modify the initial operation of event logging in the SCSI I/O subsystem. This type of operation is most useful for analysis of system reboot via the SCSI I/O subsystem.

Options and Arguments

-V Cause the scsi_log version to be printed. Because scsi_log works very closely with the system kernel and contains very detailed information about the SCSI I/O subsystem, the scsi_log version and system version (as shown by uname(1)) must match. Suspect mismatched system and scsi_log versions whenever scsi_log operates incorrectly or fails to decode log information.

-c Specify the core file to be analyzed. By default, scsi_log accesses the SCSI log of the currently running system using /dev/kmem. When accessing the SCSI event log contained in a core file, only status and log decoding commands may be used.

-hhpux_file Specify the appropriate HP-UX kernel file. By default, scsi_log obtains indexing (symbol table) information from the /stand/vmunix file.

-ssave_file Specify that log data should be taken from a save_file instead of a core file. The save_file should be the result of a save or running_save command executed with the same scsi_log version.

-i Examine or modify the initial operating parameters in the /stand/vmunix file. Changes to /stand/vmunix take effect when the system is next rebooted. This application of scsi_log is considerably slower than others; however, because /stand/vmunix file modifications require a system reboot to take effect, the additional time is insignificant.

-fcommand_file Specify a scsi_log command file. This is useful for complex command sequences, which might require unmanageable scsi_log argument lines. Multiple -f options can be used to execute a series of command files.

Commands

The following commands may be used to with -f to control the operation of scsi_log:

# Begin a comment, which is terminated by the end of the source line. Because end-of-line is somewhat ambiguous in the context of command-line arguments, comments are only permitted in command files.

status Decode and print the current event log status. The printed information includes a variety of information including the log state, and current limit and trigger conditions.

dump Decode and print the current contents of the SCSI event log. The dump format controls which log fields are printed and their order, and can be specified using the format command.

running_dump Continuously decode and print the contents of the SCSI event log by reading and rereading system memory. If the event log rate exceeds the event dump rate, events might be lost, a fact that will be noted in the dump. A running_dump operation continues until logging stops. This happens when a log run is completed (that is, the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled, this command will never terminate.

format =format_value
Print SCSI event log lines using the fields in the field indicated by format_value. A default dump format is used if an explicit dump format is not provided. The default dump format can be set using the SCSI_LOG_FORMAT environment variable. A format_value is made up of the following letters:

A Absolute event time based on the trigger event or the first dumped event in an easily readable form.

C Comment associated with the log point. Log point comments are optional and many log points do not have comments associated with them.

D Device number in hexadecimal.

E Absolute event number based on the first logged event.

F The name of the source file containing the log point.

L The line number in the source file of the log point.

M Decoded meaning of parameter data value.

N Relative event number based on the trigger event or the first dumped event.

P Parameter name.

Q Relative event time in a consistent, high-precision, numeric form.

R The name of the subroutine containing the log point.

T Relative event time in an easily readable form.

V Parameter value in decimal form.

X Parameter value in hexadecimal form.

Y Absolute event time based on the trigger event or the first dumped event in a consistent, high-precision, numeric form.

Z The character @ to mark the trigger event (otherwise blank).

dump_limit =condition
Cause only events meeting the indicated condition to be printed by a dump or running_dump command. The condition must be specified as NONE, ANY, or as an event_specification indicated later in this manpage.

dump_unlimit Disable the current dump limit condition. This causes all logged events to be printed by a dump or running_dump command.

save =save_file
Record the current contents of the SCSI event log in save_file. The contents of this file may be latter decoded using the scsi_log -s option.

running_save Continuously record the contents of the SCSI event log in file_name by reading and rereading system memory. If the event log rate exceeds the event dump rate, events may be lost. If events are lost, that fact will be noted in the save_file. A running_save command continues until logging is stopped. This happens when a log run is completed (that is, when the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled, this command will never terminate. Note that a running_save command can generate substantial quantities of data (the save_file can grow very quickly).

run Clear the event log and enable event logging. This command starts or restarts logging using the current limit and trigger conditions.

stop Disable event logging. This command does not clear the current limit or trigger conditions.

reset Restore SCSI event log to standard system boot operation. Use this command when scsi_log will not be used for an extended period. It will cause both the core file and the /stand/vmunix file to be changed.

on Clear the event log and enable SCSI event logging. This command starts or restarts logging with no limit or trigger conditions.

off Disable SCSI event logging. Use this command to shutdown SCSI event logging.

limit =condition
Log only events meeting the indicated condition. The condition must be specified as NONE, ANY, or as an event_specification indicated later in this manpage.

unlimit Disable the current limit condition. This causes all events to be logged.

limit_points Print the SCSI log points whose log events might meet the current limit condition.

trigger =condition
Disable SCSI event logging when the indicated condition is met and all of the post-store events have been logged. The condition must be specified as NONE, ANY, or as an event_specification indicated later in this manpage.

untrigger Disable the current trigger condition. This command does not clear the current trigger condition.

trigger_points
Print the SCSI log points whose log events might meet the current trigger condition.

wait_for_trigger
Wait until logging is stopped. This happens when a log run is completed (that is, the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled this command will never terminate.

center_store Stop logging events after the trigger condition is met (post-store) such that the trigger event ends up in the center of the SCSI event log.

pre_store [ =number_of_events]
Stop logging events after the trigger condition is met and the indicated number_of_events from before the trigger event (pre-store events) remain in the SCSI event log. If the number of events to pre-store is not specified, event logging will stop as soon as the trigger condition is met. This causes the entire log to be used to hold events which occurred before the trigger event.

post_store [ =number_of_events]
Stop logging events after the trigger condition is met and the indicated number_of_events after the trigger event (pre-store events) have been logged. Note that number_of_events may be larger than the total size of the SCSI event log. Such a number_of_events will cause the trigger event to be pushed out of the log. If the number of events to post-store is not specified, event logging will stop when the entire log is filled with events which occurred after the trigger event.

clock =clock_mode
Clock SCSI events to be logged as specified by clock_mode. A high-precision clock is best used for events that occur over short intervals. A high-accuracy clock is best used for events that occur over long intervals. Clock_mode must be one of the following values:

normal Select between clocks to achieve a balance of precision and accuracy.

precise Favor the high precision clock when possible. This clock_mode should be used to obtain maximally precise timing between successive events.

accurate Favor the high accuracy clock when possible. This clock_mode should be used to obtain maximally accurate timing between events which are widely separated in time and event number.

log_size =number_of_events
Change the SCSI event log size to the indicated number_of_events. This command changes the length of the SCSI log, as specified in the /stand/vmunix file. A system reboot is required to cause the this change to take effect.

trace Decode and print the current SCSI command trace condition. SCSI command tracing causes data to be stored in the kernel /usr/sbin/dmesg buffer. The dmesg(1M) command can be used to print this stored data. Note that SCSI command tracing is independent from SCSI event logging.

trace_on =trace_specification
Trace SCSI commands and command information meeting the specified trace_specification. Trace information may be accessed via dmesg(1M). The trace_specification must be a list of relational expressions surrounded by parenthesis and separated by the logical operator && (AND). The following relational terms may appear in an event_specification:

device [ &dev_mask] ==dev_value
The device associated with the SCSI command must equal dev_value after being bitwise ANDed with dev_mask. If no dev_mask is specified, the device associated with the SCSI command must exactly match dev_value.

major ==dev_value
The device associated with the SCSI command must have the major number indicated by dev_value.

dev ==dev_value
The device associated with the SCSI command must have the minor number indicated by dev_value.

lun ==dev_value
The device associated with the SCSI command must have the SCSI bus, target and LUN indicated by dev_value.

tgt ==dev_value
The device associated with the SCSI command must have the SCSI bus and target indicated by dev_value.

bus ==dev_value
The device associated with the SCSI command must have the SCSI bus indicated by dev_value.

dmesg_lines ==dmesg_lines_value
The trace information contained in the dmesg(1M) buffer lines indicated by dmesg_lines_value should be recorded.

trace_off Discontinue tracing additional SCSI commands. Normally the SCSI I/O subsystem records only information associated with commands which unexpectedly fail. The trace_off command restores this system default operation.

Event Specifications

An event_specification consists of a list of relational expressions surrounded by parenthesis and separated by the logical operators && (AND) and || (OR). Since the SCSI tracing uses a fixed AND-OR (SUM of products) event_specification evaluation scheme, there is no need (nor support) for additional parenthesis imbeded within an event_specification. The following relational terms may appear in an event_specification:

device [ &dev_mask] ==dev_value
The device associated with the event must equal dev_value after being bitwise ANDed with dev_mask. If no dev_mask is specified, the device associated with the event must exactly match dev_value.

major ==dev_value
The device associated with the event must have the major number indicated by dev_value.

dev ==dev_value
The device associated with the event must have the minor number indicated by dev_value.

lun ==dev_value
The device associated with the event must have the SCSI bus, target and LUN indicated by dev_value.

tgt ==dev_value
The device associated with the event must have the SCSI bus and target indicated by dev_value.

bus ==dev_value
The device associated with the event must have the SCSI bus indicated by dev_value.

file ==file_name
The log point generating the event must be in the SCSI I/O subsystem source file indicated by file_name. This term also establishes the context for use of symbolic literals in successive terms separated by && operators.

routine ==routine_name
The log point generating the event must be in the SCSI I/O subsystem source subroutine indicated by routine_name. This term also establishes the context for use of symbolic literals in successive terms separated by && operators.

function ==function_value
The log point generating the event must be associated with the functional portion of the SCSI I/O subsystem indicated by function_name.

line ==number[ ...number]
The log point generating the event must be at the indicated line number or in the indicated range of line numbers.

parameter ==parameter_name
The log point generating the event must reference the parameter name indicated by parameter_name.

parameter_name[ &value_mask]relational_operator value
The log point generating the event must reference the parameter name indicated by parameter_name and the parameter value being logged must satisfy the indicated relational expression. Specifically, the result of bitwise ANDing the parameter value with value_mask must compare in the manner indicated by relational_operator with the value indicated by value. The relational_operator must be one of the following relation operators: == (equal), != (not equal), < (less than), > (greater than), <= (less than or equal to), or >= (greater than or equal to).

Value and value masks in relational terms may be specified using multiple numeric and symbolic literals in a bitwise logical OR expression using | operators. Device values and device masks may also include device file names.

EXAMPLES

The following scsi_log command line causes accesses by any device driver to the indicated SCSI target addresses to be logged:

scsi_log ’limit = ( tgt == /dev/rdsk/0s0 || tgt == /dev/rdsk/6s0 )’

The following scsi_log command line causes all SCSI tape-driver open and close operations to be logged:

scsi_log ’limit = ( file == scsi_tape.c && function == OPEN_CLOSE )’

The following scsi_log command line causes all SCSI events associated with the indicated device file to be logged, but stops logging when an ENXIO error occurs:

scsi_log ’limit = ( dev == /dev/rmt/0m )’ ’trigger = ( error == ENXIO )’

The following scsi_log command line causes all SCSI commands associated with the indicated device file to be traced in the kernel /usr/sbin/dmesg buffer:

scsi_log ’trace_on = ( dev == /dev/rmt/0m )’

AUTHOR

scsi_log was developed by HP.

Museum

Related Articles