intctl(1M)

NAME

intctl — manage the interrupt configuration of the system

SYNOPSIS

/usr/sbin/intctl [-h | -F | -p | -c cpu_id]

/usr/sbin/intctl [-C class] [-H hw_path]

/usr/sbin/intctl [[-w] -M -H hw_path -I intr_id -c cpu_id]

/usr/sbin/intctl [[-w] -M -H hw_path -f file]

/usr/sbin/intctl [-r file | -s file]

/usr/sbin/intctl [-l [cell_id]]

DESCRIPTION

A processor receives an interrupt when either the processor's interrupt pin is asserted (for line based interrupts) or if a processor detects an interrupt message bus transaction on the system bus (for transaction based interrupts).

Interrupts from the interface cards can be line or transaction based. Interrupts are routed to different processors during boot time.

The intctl command is a tool that allows a performance expert to display and modify these interrupt assignments. The tool only supports migration of external device interrupts. The performance analyst can also save and restore the interrupt configuration. If interrupt migration process completes successfully, a message is logged to the console and/or to the /var/adm/syslog/syslog.log file.

intctl resides in /usr/sbin/bin (a symbolic link exists in /usr/contrib/bin), and the command can be executed only by the super user. The intctl command is not a general system administration command. It should be used only by performance tuning experts with a high level of system knowledge. The performance specialist can use the intctl command to view the interrupt configuration of the system and modify the interrupt assignments of the CPUs to re-distribute the system load across the CPUs.

intctl is synchronized with other High Availability (HA) events happening simultaneously on the system. An HA event can be a PCI OLA/R or Processor allocation/de-allocation. If any of these events are happening when intctl is trying to display interrupt information or is trying to migrate an interrupt to a CPU, intctl will exit with the error message, "Another HA event is in progress, try again!" and the user should retry the command.

Non-MP safe drivers do not support interrupt migration. The tool will display an error message if the user tries to move the interrupts of a non-MP safe driver to a different CPU.

On a system with virtual partitions (vPars), intctl will only display CPUs in the current partition. A CPU belonging to a partition can be either a bound or a floater CPU. A bound CPU is bound to the partition and the interrupt state of these CPUs can be either ENABLED, DISABLED or RESERVED for interrupts. Floater CPUs are not bound to the partition and the state of these CPUs is DISABLED; interrupts cannot be assigned to these CPUs. A bound CPU in DISABLED state can be ENABLED for interrupts through the PSETS interface. To get more information about the state of a floater CPU belonging to other partitions, the performance expert can use the vPars vparstatus command.

Options

By default, the command displays interrupt information about all the interface cards on the system.

intctl recognizes the following options:

-c cpu_id

By itself (without any other options), display interrupt information about the specified CPU.

When used with the -M option, -c cpu_id specifies the CPU ID of the CPU to which the interrupt is to be moved.

-C class

Display interrupt information about all the interface cards belonging to the specified class.

Can be used with the -H hw_path option to display interrupt information about the interface card under the hw_path that belongs to the specified class.

-f file

Migrate several interrupts of the specified hardware path. Each entry in the file is of the form intr_id cpu_id followed by another entry on a new line.

-F

Produce a compact listing of fields separated by colons ":".

-h

Display the usage of the command.

-H hw_path

Display interrupt information about all interface cards connected at the specified hardware path. For hardware paths / and 0, intctl prints the interrupt information about all the interface cards on the system.

When used with the -C class option, -H displays information about all interface cards connected to the path and which belong to the specified class.

When used with the -M option, -H hw_path specifies the hardware path of the interrupt that needs to be moved to a different CPU.

-I intr_id

Specify the interrupt ID of the interrupt to be moved (to be used with the -M option).

-l [cell_id]

Display the CPUs available in the Cell. The cell_id is an optional argument, when missing intctl will display the CPUs available in all the Cells.

-M

Migrate an interrupt to a specified CPU. This option must be specified with the -H, -I, -c options.

The -M option must be specified first in the command line followed by the remaining options which can be specified in any order.

-p

Display interrupt information about all the CPUs on the system in a long format with spacing in between the fields.

-r file

Restore the system interrupt configuration from the specified file, file. The interrupt configuration is restored only if all the interface cards and CPUs referenced in the saved configuration file are still present on the system and the CPUs are in the same state as in the saved configuration. If new cards and new CPUs are added to the system, intctl will continue to restore the interrupt configuration as long as the old configuration has not changed. intctl will fail to restore the interrupt configuration if the file permission is not 0600.

In restoring the system configuration, the command will assign interrupts from the interface cards to the CPUs as specified in the file.

-s file

Save the system interrupt configuration to the specified file, file, with file permission 0600. If the file exists, the content of the file will be overwritten and the file permissions will be changed to 0600. The command will store the interrupt information of all the CPUs on the system. This file can be used to restore the interrupt configuration of the system later using the -r option.

-w

Force the migration of interrupts even if warnings are found during migration verification. When this option is not specified, intctl displays a prompt, asking for user confirmation. This option can be used only with -M option.

Interrupt Configuration Display

The interrupt configuration can be displayed sorted by CPU ID (intctl -p) or sorted by interface card hardware path (intctl -H hw_path).

By default, the command displays interrupt information about all the interface cards on the system. Here is a sample interrupt configuration display, and the fields are explained below.

Note: For cards using two or more interrupts, only the CPU and interrupt information is displayed from the second interrupt entry. The option -F can be used to get all the information repeated for every interrupt entry (which is same as what previous version of intctl displayed for cards using multiple interrupts).

hw path    class    drv    card  cpu  cpu   intr  intr  card 
                    name   cell  ID   cell  type  ID    description 
=================================================================== 
0/0/0/0/0  tty      asio0  0     0    0     L     1     PCI SimpleComm 
                                                        (103c1290) 
0/0/0/0/1  tty      asio0  0     0    0     L     1     PCI Serial 
                                                        (103c1048) 
0/0/0/1/0  lan      igelan 0     2    0     L     1     HP A7109-60001 
                                                   PCI 1000Base-T Core 
0/0/0/2/0  ext_bus  c8xx   0     3    0     T     2     SCSI C1010 
                                               Ultra Wide Single-Ended 
                                 3    0     L     1 
0/0/0/2/1  ext_bus  c8xx   0     2    0     T     2     SCSI C1010 
                                               Ultra Wide Single-Ended 
                                 2    0     L     1 

hw path

A numerical string of hardware components separated by slash (/), to represent a bus converter. The first component in the hardware path is the cell (for a cell based system) or the system bus adapter (for a non-cell based system). The system bus adapter is followed by the address of the local bus adapter and the interface card. Subsequent numbers are separated by periods (.). Each number represents the location of a hardware component on the path of the device.

class

The class of the interface card, for example, lan, tty, ext_bus.

drv name

The driver associated with the card.

card cell

The cell number of the cell that the card is connected to.

cpu ID

An integer value representing the identity of the CPU that the card's interrupt is assigned to.

cpu cell

The cell number of the cell that the CPU is connected to.

intr type

A character representing the interrupt type:

L line based interrupt

T transaction based interrupt

M MSI based interrupt

X MSI-X based interrupt

intr ID

The identity of the interrupt to be moved.

card description

A brief description of the interface card.

cpu path

The hardware path of the CPU (relevant with -s and -r option).

cpu state

Integer value representing the state of the CPU: ENABLED(0), DISABLED(1) or RESERVED(2) (relevant with -s, -r, and -l options). These states are interrupt states and do not have any relationship to the thread state.

ENABLED: The CPU is capable of receiving external interrupts from interface cards.
DISABLED: The CPU cannot handle external interrupts from interface cards.
RESERVED: The state is reserved to receive interrupts from specific cards, e.g., for RTE (Real Time Extensions) some processors are reserved specifically to handle interrupts from RTE cards.

Redirection

The intctl command allows the performance specialist to modify the interrupt assignment of an interface card. The user must specify the hardware path of interface card, the interrupt ID that needs to be moved, and the new CPU ID that the interrupt will be routed to.

When an interrupt is moved from one CPU to another, if the interrupt shares a line with other interrupts, all the interrupts on that line will be moved to the specified CPU. The kernel will add a message to the /var/adm/syslog/syslog.log file which will contain the hardware path and interrupt IDs of the interrupts being moved and the CPU ID of the CPU to which these interrupts were moved.

When migrating an interrupt from one CPU to another, if the card to which the interrupt belongs is in timed-out state, from either a SUSPEND or RESUME operation (see olrad(1M)), then the interrupt will not be moved. If an interrupt shares a line with other interrupts, and if any of the cards is in timed-out state, then none of the interrupts on the line will be moved to the specified CPU.

Saving & Restoring System Interrupt Configurations

The intctl command can save and restore the system interrupt configuration in a user specified file. Before restoring the configuration, the intctl command checks to see if the system setup has changed by checking that all the interface cards and CPUs from the saved configuration are still present in the system and that the CPUs are in the same state as in the saved configuration. The command will continue to restore the configuration if new cards or CPUs have been added to the system since the interrupt configuration was saved.

RETURN VALUE

Exit values are:

0: Successful completion.
>0: An error condition occurred.

EXAMPLES

Display information about all interface cards which belong to the class lan:

intctl -C lan

Display the interrupt information of the card with hardware path 0/4/0/0/5/0:

intctl -H 0/4/0/0/5/0

Display interrupt information of all the interface cards under the path, 0/4:

intctl -H 0/4

Display interrupt information of all interface cards under the hardware path 0/4 and which belong to class lan:

intctl -C lan -H 0/4

Display interrupt information about the CPU with CPU ID 3:

intctl -c 3

Migrate the interrupt with ID 1, coming from the card whose hardware path is 0/4/0/0/5/0 to CPU 3.

intctl -M -H 0/4/0/0/5/0 -I 1 -c 3

Migrate interrupts of the card whose hardware path is 0/4/0/1 as specified by the entries in the file intr_assign.

intctl -M -H 0/4/0/1 -f intr_assign

Store the system interrupt configuration to myconfig. If myconfig already exists, its contents are overwritten.

intctl -s myconfig

Restore the system interrupt configuration from myconfig.

intctl -r myconfig

Display all the CPUs available in cell_id 2.

intctl -l 2

WARNINGS

The intctl command can be executed only by the super user. The intctl command should be used only by performance analysts for performance tuning purposes. If care is not taken to redistribute the interrupts properly, it could lead to a decrease in the overall system performance by overloading some processors and by not optimally utilizing the remaining processors.