intctl(1M)																intctl(1M)

NAME

       intctl - manage the interrupt configuration of the system

SYNOPSIS

       cpu_id]

       class] hw_path]

       hw_path

       hw_path

       file | file]

       [cell_id]]

       algorithm]

DESCRIPTION

       A processor receives an interrupt in one or more of these occurrences:

       o  When the processor's interrupt pin is asserted (for line based interrupts).

       o  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 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 file.

       resides	in (a symbolic link exists in and the command can be executed only by the superuser.  The command is not a general system adminis-
       tration command.  It should be used only by performance tuning experts with a high level of system knowledge.  The  performance	specialist
       can use the 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.

       is synchronized with other High Availability (HA) events happening simultaneously on the system.  An HA event can be a PCI OLA/R or Proces-
       sor allocation/de-allocation.  If any of these events are happening when is trying to display interrupt information or is trying to migrate
       an interrupt to a CPU, exits with the error message below, and the user should retry the command:

       Non-MP safe drivers do not support interrupt migration.	The command displays 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), displays only CPUs in the current partition.

       Using  the  option,  the  command balances the interrupt distribution on a system.  Interrupt assignments to CPUs on a given system are not
       always distributed in a balanced manner.  Most of the time, imbalance in distribution is caused by CPU migrations.   These  migrations  may
       cause the interrupts to get assigned to CPUs available in the system in a non-optimal fashion and the interrupts are not redistributed when
       more CPUs become available.  In such a scenario, the option of the command can be used to balance the interrupt distribution on the system.

       By default, HP-UX distributes interrupts at boot time using a "round robin" allocation method.  In this	method,  the  first  interrupt	is
       assigned  to the first available CPU.  Then the next interrupt is assigned to the next available CPU and these assignments continue.  After
       all the CPUs have been assigned, the interrupt assignment starts from the first CPU again.

       CPU migrations can occur because of Work  Load  Manager	(WLM)  configuration,  vPars  administration  activity,  and/or  Instant  Capacity
       (iCAP/TiCAP)  administration activity.  These migrations can cause the interrupts to be assigned to a smaller set of CPUs causing an imbal-
       ance and thus a non-optimally configured system.

       Using the option allows the user to manually balance the interrupt distribution of the system.  Users can choose one of these two balancing
       algorithms to balance interrupts:

       o

	  The  default balancing algorithm used by is This balancing algorithm associates weights to each driver based on its interrupt frequency.
	  The system is balanced such that each CPU is loaded with a similar average weight from the interrupt load perspective.

       o

	  The balancing algorithm assigns interrupts to the available CPUs in a rotating round robin fashion.  The round robin assignment is simi-
	  lar  to the HP-UX default boot time interrupt distribution method.  However, the interrupt assignments can differ because of the differ-
	  ent ways that I/O cards and CPUs are discovered.

       is a better choice of algorithm for systems having I/O cards that demand largely varying range of interrupt processing  needs.	Hence,	is
       the default algorithm.

       In  systems  where all I/O cards demand similar interrupt processing capacity or when there is difficulty determining interrupt load gener-
       ated by each driver, then the algorithm can be used.

       Administrators can also configure automatic balancing of interrupts at periodic intervals.  Balancing is performed  only  if  there  is	an
       interrupt  distribution	imbalance.  This kind of interrupt balancing is desirable in a dynamic CPU migration environment such as WLM (Work
       load Manager).  Refer to intrbald(1M) for more details.

       Several settings are provided for managing balancing of interrupts.  These settings are to be provided using the command  line  options	or
       can be persistently configured in the configuration file.  See the section below.

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

       recognizes the following options:

       Balancing of interrupts can be performed any time during system up
		      time to reduce CPU overload because of interrupt handling.

		      The algorithm parameter specifies which of the following interrupt balancing algorithms to use:

		      o  This  balancing  algorithm  is  also the default algorithm.  The default can also be set by changing in the configuration
			 file to Refer to the section of this manpage for more information.

			 Each driver is given a weight based on the number of interrupts it can generate.  Balancing operations ensure	that  each
			 CPU  is loaded (from interrupt load perspective) with a comparable total driver weight.  These weights can be between and
			 (see limits(5)).  Most of the HP-UX drivers are already defined in the configuration file section, Users  can	modify	or
			 override these driver weights, but they should make sure not to set unrealistic driver weights without knowing the amount
			 of interrupt load the driver could generate.

		      o  round_robin

			 Each interrupt in the system is assigned an available CPU in round robin fashion.  This balancing approach  can  be  used
			 when  it  becomes  difficult to differentiate drivers based on their interrupt load.  Compared to the driver weight based
			 approach, round robin could result in more interrupt migrations while balancing interrupts.

       Balance the interrupt distribution of the system by
		      performing the least number of migrations that can distribute interrupt load across a specified set of CPUs.

		      Options are provided to be (optionally) used in conjunction with the  option.   These  options  are  basically  provided	to
		      improve the control and flexibility of the user while balancing interrupts.  See the description for the options.

		      If  the  option  is not specified, the user then has the choice to confirm or skip all migrations or selectively pick only a
		      few migrations.  If the option is also specified, no confirmation message is displayed.

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

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

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

		      This option can be used with the option to display interrupt information about the interface card  under	the  hw_path  that
		      belongs to the specified class.

       Migrate several interrupts of the hardware path specified by the
		      option.	Define	the interrupt ID and CPU ID pairs in file.  Each entry in the specified file is of the form intr_id cpu_id
		      followed by another entry on a new line.	For example, in the following command:

		      the file contains the entries of The command tries to migrate the interrupt ID of the hardware path to the CPU with the  CPU
		      ID of

       Produce a compact listing of fields separated by colons

       Display the usage of the command.

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

		      When used with the option, displays information about all interface cards connected  to  the  specified  hardware  path  and
		      belonging to the specified class.

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

       Ignore interrupt assignments based on the I/O cards, CPUs, and I/O card drivers.
		      While  balancing	interrupts, the user may want to use the option to ignore certain interrupt assignments.  Multiple parame-
		      ters can be specified by using the option parameters multiple times.

		      NOTE: Specifying too many parameters can reduce the scope of balancing  interrupts  and  can  cause  interrupt  distribution
		      imbalance.

		      The option parameters are as follows:

		      o  Ignore I/O Card Interrupt

			 While	balancing  interrupts,	interrupt  intr_id  associated with this I/O card at the hardware path hw_path will not be
			 migrated.  intr_id represents a specific interrupt ID or all interrupt IDs of the specified I/O card if is  used.   These
			 values can also be specified in the INTCTL_HW_IGNORE section of the configuration file.

		      o  Ignore CPU

			 None  of the interrupts assigned to the CPU with the specified hw_path can be migrated while balancing interrupts.  Also,
			 no new interrupts are assigned to these CPUs while balancing interrupts.  The same information can be	specified  in  the
			 INTCTL_CPU_IGNORE section of the configuration file.

		      o  Ignore Driver

			 None  of  the I/O cards claimed by the driver driver_name can be selected for interrupt migrations while balancing inter-
			 rupts.  Be careful while specifying driver_name, because one driver could possibly claim multiple I/O cards and  specify-
			 ing  such a driver reduces the scope of balancing of interrupts.  The same information can be specified in the section of
			 the configuration file.

		      NOTE: Refer to the section of the configuration file for other drivers that are  currently  not  supported  while  balancing
		      interrupts.

		      Refer also to the and sections of this manpage for more interrupt configuration information.

       Specify the interrupt ID
		      of the interrupt to be moved or migrated (to be used with the option).

       Display the CPUs available in the specified Cell.
		      The cell_id is an optional argument.  If cell_id is not specified, will display the CPUs available in all the Cells.

       Migrate an interrupt to a specified CPU.
		      The option must be specified first followed by a combination of and options or followed by a combination of and options.	An
		      additional option can be specified with either of the two combinations to force migration of interrupts without  asking  for
		      user input.

		      If  the CPU specified is not the preferred CPU for migration, the migration can potentially impact the performance.  In that
		      scenario, an appropriate warning message and a prompt is displayed to the user.  The warning message asks  for  confirmation
		      before proceeding with the migration.  The warning message also displays a list of CPU IDs that are preferred by this inter-
		      rupt.  Note that this list of CPU IDs might also include CPU IDs of those CPUs that are currently not configured in the sys-
		      tem.

       Override existing parameters specified in the
		      interrupt configuration file which is explained in the section of this manpage.  This option can also be used for specifying
		      new parameters.

		      o  Override driver weight information

			 Specify a new driver weight or override an existing driver weight.  driver_name is either the existing driver in the sec-
			 tion  of  the interrupt configuration file or a new driver name.  weight is the interrupt load that the driver may gener-
			 ate.  Refer also to the option explanation of driver weight.

			 NOTE: All I/O card drivers present on the system but not specified in the section  of	the  configuration  file  will	be
			 assigned a default weight of 10.

		      o  Override the trigger for balancing of interrupts

			 The  balance_on_cpu  and  the	distribute_to_cpu percentage values determine when the interrupts will be balanced and the
			 scope of balancing interrupts.

			 balance_on_cpu is the minimum percentage of available number of CPUs that should be handling  interrupts.   Balancing	of
			 interrupts  will start only if the number of CPUs handling the interrupts is less than this percentage.  A value 100 will
			 always trigger balancing of interrupts.  However, if the system is optimally balanced with respect to interrupt distribu-
			 tion,	then  there might not be any interrupt migrations.  The default value is For example, if there are 4 CPUs and bal-
			 ance_on_cpu is set to 50, then the actual balancing of interrupts will start when the number of CPUs  currently  handling
			 the interrupts is less than 2 (50% of 4 CPUs).

			 distribute_to_cpu  is the percentage of available number of CPUs that should be handling interrupts.  Balancing of inter-
			 rupts distribute interrupts across this percentage of available number of CPUs.  The default value  is  For  example,	if
			 there	are  4 CPUs and distribute_to_cpu is set to 75, then the interrupts are distributed among a maximum of 3 CPUs (75%
			 of 4 CPUs).

			 NOTE: If WLM (Work Load Manager) is configured to load balance across partitions by migrating CPUs,  HP  recommends  that
			 distribute_to_cpu should not be set to more than 75.  That is, it should be set to 75 or less.

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

       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	configura-
		      tion.   If  new  cards and new CPUs are added to the system, will continue to restore the interrupt configuration as long as
		      the old configuration has not changed.  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.

       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  sys-
		      tem.  This file can be used to restore the interrupt configuration of the system later using the using the option.

       Force migration of interrupts without asking for user input.
		      This  option  can  be used only with the option or the option.  When is used with the option, the migration of interrupts is
		      forced even if warnings are found during migration verification.	When is used with the  option,	migrations  occur  without
		      asking for confirmation.	When the option is not specified, displays a prompt, asking for user confirmation.

   Interrupt Configuration Display
       The  interrupt  configuration  can  be  displayed  sorted by CPU ID (by specifying or sorted by interface card hardware path (by specifying
       hw_path).

       By default, the command displays interrupt information about all the interface cards on the system.  Here is a sample interrupt	configura-
       tion 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 can be used to get all the information repeated for every interrupt entry (which is same as what previous version of  displayed  for
       cards using multiple interrupts).

       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.

       The class of the interface
		      card, such as:

       The driver associated
		      with the card.

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

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

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

       A character representing the interrupt type:

		      line based interrupt
		      transaction based interrupt
		      MSI based interrupt
		      MSI-X based interrupt

       The identity of the interrupt to be moved.

       A brief description of the interface card.

       The hardware path of the CPU (relevant with the
		      and options).  The and fields are displayed when specifying the option.

       Integer value representing the state of the
		      CPU: ENABLED(0), DISABLED(1) or RESERVED(2) (relevant with the and 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, for example, for RTE (Real Time Extensions)
				     some processors are reserved specifically to handle interrupts from RTE cards.

		      The and fields are displayed when specifying the option.

       NOTE: value is returned in some fields if the value is not available or the feature is not applicable.

       The following output is an example from the command for balancing interrupts.

       Following interrupt migrations will be performed for balancing interrupts (algorithm selected:

       Please select the migrations you want to skip.
       Comma separated serial numbers or 'all' or 'none' : 1,2,7
       Following migrations (serial number(s)) will be skipped.
       1 2 7
       Do you wish to skip these migrations (y/n):y
       intctl: Moved the interrupt: 1, of card 1/0/0/1/0, driver igelan, from CPU:0 to CPU:5
       intctl: Moved the interrupt: 2, of card 1/0/0/3/0, driver c8xx, from CPU:0 to CPU:4
       intctl: Moved the interrupt: 1, of card 1/0/0/3/0, driver c8xx, from CPU:0 to CPU:4
       intctl: Moved the interrupt: 2, of card 1/0/0/2/1, driver c8xx, from CPU:0 to CPU:4
       Balancing of interrupts done.

       The following descriptions explain each column in the table:
       Serial number (starting from 1) of all the migrations that will be performed for balancing of interrupts.  These serial numbers can be used
       in selecting migrations that have to be skipped.

       The hardware path of I/O cards whose interrupt is getting migrated.

       The driver associated with the card.

       The identity of the interrupt to be moved.

       The CPU ID and CPU hardware path to which the interrupt is currently
	      bound, and the interrupt will be migrated off this CPU.

       The CPU ID and CPU hardware path to which the interrupt will get
	      migrated.

   Redirection
       The  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 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  SUS-
       PEND  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 and Restoring System Interrupt Configurations
       The command can save and restore the system interrupt configuration in a user specified file (see the and options).  Before  restoring  the
       configuration,  the  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 con-
       tinue to restore the configuration if new cards or CPUs have been added to the system since the interrupt configuration was saved.

   Interrupt Configuration File
       is  the	interrupt  configuration file.	The parameters can be saved in this configuration file, which makes them persistent across reboot.
       These parameters can be changed or overridden by the command line options of and

       The different sections in the configuration file are described as follows:

       1.

	  Each line after the above string is expected to be of the form driver_name weight.  driver_name is a string corresponding to the  driver
	  and weight is an integer corresponding to the driver's weight.  The weight will be used while balancing interrupts using the based algo-
	  rithm.  If a driver is not specified in this section and is present on the system, then a default weight  of	is  assumed.   Weight  can
	  range from to (see limits(5)).  A weight is considered as no interrupt load.	A positive integer is considered as the relative interrupt
	  load on the CPU with respect to different driver weights.  More weight (that is, a large weight number) corresponds  to  more  interrupt
	  load on the CPU.

	  The option can be used to override an existing driver weight or to specify new driver weights temporarily.

	  Example:

       2.

	  Each	line after the above string is expected to be of the form hw_path intr_id.  hw_path is a string corresponding to the hardware path
	  of the I/O card and intr_id is an integer corresponding to the interrupt ID.	The specified I/O card and the interrupt ID combination is
	  ignored  (that is, will not be migrated) while balancing interrupts.	If interrupt ID is then all the interrupt IDs associated with that
	  I/O card are ignored.

	  The option can be used to specify more I/O cards to be ignored temporarily.

	  NOTE: If an I/O card shares the interrupt line with another I/O card whose driver is non MP-safe, then the interrupt of  this  I/O  card
	  cannot be migrated.  will display the following message if this situation happens (the actual hardware path will be different):

	  This	entry needs to be made in the section of the configuration file.  Specifying this entry will avoid selecting this card for further
	  migrations while balancing interrupts.  There is no impact on the system or balancing of interrupts if this activity is  not	performed.
	  The only impact will be an interrupt migration failure message in file and the display of the above message.

	  Example:

       3.

	  Each	line  after the above string is expected to be of the form hw_path.  hw_path is a string corresponding to the hardware path of the
	  CPU that should be ignored while balancing interrupts.  These CPUs will not be affected by balancing of interrupts.

	  The option can be used to ignore more CPUs temporarily.

	  Example:

       4.

	  Each line after the above string is expected to be of the form driver_name.  driver_name is a string corresponding to the driver name of
	  the  driver  that  should be ignored while balancing interrupts.  Any I/O card claimed by this driver will not be selected for interrupt
	  migrations while balancing interrupts (irrespective of the balancing algorithm chosen).

	  The option can be used to ignore more drivers temporarily.

	  Example:

	  NOTE: Refer to this section of the configuration file for drivers that are currently not supported while balancing interrupts.

       5.

	  The line that follows specifies the default algorithm to be used while balancing interrupts (when is not  used).   The  supported  algo-
	  rithms are and

	  The option can be used to change the algorithm temporarily.

	  Example:

       6.

	  The  line  that  follows  specifies  the  trigger  for balancing of interrupts and is expected to be of the form balance_on_cpu distrib-
	  ute_to_cpu.  balance_on_cpu is an integer that specifies the minimum percentage of number of available CPUs that should be handling  the
	  interrupts.	distribute_to_cpu is an integer that specifies the percentage of number of available CPUs that can handle interrupts after
	  balancing interrupts.

	  If the percentage of number of available CPUs handling the interrupts is less than the balance_on_cpu, then balancing of  interrupts	is
	  performed and interrupts are distributed across distribute_to_cpu percentage of CPUs.  Both values should be in the range 0-100 and bal-
	  ance_on_cpu should be smaller than distribute_to_cpu.

	  NOTE: If WLM (Work Load Manager) is configured to load balance across partitions by migrating CPUs, HP recommends that distribute_to_cpu
	  should not be set to more than 75.  That is, it should be set to 75 or less.

	  The option can be used to override this setting temporarily.

	  Example:

RETURN VALUE

       Exit values are:

       Successful completion.
       An error condition occurred.

EXAMPLES

       Display information about all interface cards which belong to the class

       Display the interrupt information of the card with hardware path

       Display interrupt information of all the interface cards under the path,

       Display interrupt information of all interface cards under the hardware path and which belong to class

       Display interrupt information about the CPU with CPU ID

       Migrate the interrupt with ID 1, coming from the card whose hardware path is to CPU

       Migrate interrupts of the card whose hardware path is as specified by the entries in the file

       Store the system interrupt configuration to if already exists, its contents are overwritten:

       Restore the system interrupt configuration from

       Display all the CPUs available in

       Balance interrupts using the algorithm and without user confirmation:

       Balance	interrupts  only  if  less than 40% of the available CPUs are handling interrupts, and distribute the interrupts across 75% of the
       CPUs available:

       Balance interrupts ignoring all interrupts of the I/O card with hardware path ignore the CPU with hardware path and ignore the driver also,
       ask for confirmation before performing interrupt migrations:

       Balance	interrupts according to the configuration file, but add a new driver with weight 300 and change the weight of existing driver from
       10 (specified in the configuration file) to 15:

       Balance interrupts if the current percentage of number of available CPUs handling interrupts is below 60%  and  distribute  the	interrupts
       across 80% of number of available CPUs the system:

WARNINGS

       The  command  can  be  executed only by the superuser.  The command should be used only by performance analysts for performance tuning pur-
       poses.  If care is not taken to redistribute the interrupts properly, a decrease in the overall system performance could occur by overload-
       ing some processors and by not optimally utilizing the remaining processors.

FILES

       interrupt configuration file.
				See the section above.

SEE ALSO

       intrbald(1M), ioscan(1M), limits(5).

																	intctl(1M)