1IRQBALANCE(1)                     irqbalance                     IRQBALANCE(1)
2
3
4

NAME

6       irqbalance - distribute hardware interrupts across processors on a mul‐
7       tiprocessor system
8

SYNOPSIS

10       irqbalance
11
12

DESCRIPTION

14       The purpose of irqbalance is to distribute hardware  interrupts  across
15       processors on a multiprocessor system in order to increase performance.
16
17

OPTIONS

19       -o, --oneshot
20              Causes irqbalance to be run once, after which the daemon exits.
21
22
23       -d, --debug
24              Causes  irqbalance  to  print  extra debug information.  Implies
25              --foreground.
26
27
28       -f, --foreground
29              Causes irqbalance to run in the foreground (without --debug).
30
31
32       -j, --journal
33              Enables log output optimized for systemd-journal.
34
35
36       -p, --powerthresh=<threshold>
37              Set the threshold at which we attempt to move a CPU into  power‐
38              save mode If more than <threshold> CPUs are more than 1 standard
39              deviation below the average CPU softirq workload,  and  no  CPUs
40              are  more  than 1 standard deviation above (and have more than 1
41              IRQ assigned to them), attempt to place 1 CPU in powersave mode.
42              In  powersave mode, a CPU will not have any IRQs balanced to it,
43              in an effort to prevent that CPU from waking up without need.
44
45
46       -i, --banirq=<irqnum>
47              Add the specified IRQ to the set of banned IRQs. irqbalance will
48              not affect the affinity of any IRQs on the banned list, allowing
49              them to be specified manually.  This option is additive and  can
50              be  specified  multiple times. For example to ban IRQs 43 and 44
51              from balancing,  use  the  following  command  line:  irqbalance
52              --banirq=43 --banirq=44
53
54
55       -m, --banmod=<module_name>
56              Add  the  specified module to the set of banned modules, similar
57              to --banirq.  irqbalance will not affect  the  affinity  of  any
58              IRQs  of  given modules, allowing them to be specified manually.
59              This option is additive and can be specified multiple times. For
60              example  to  ban all IRQs of module foo and module bar from bal‐
61              ancing, use the following command line: irqbalance  --banmod=foo
62              --banmod=bar
63
64
65       -c, --deepestcache=<integer>
66              This  allows  a user to specify the cache level at which irqbal‐
67              ance partitions cache domains.  Specifying a  deeper  cache  may
68              allow  a  greater degree of flexibility for irqbalance to assign
69              IRQ affinity to achieve greater performance increases, but  set‐
70              ting a cache depth too large on some systems (specifically where
71              all CPUs on a system share the deepest cache level), will  cause
72              irqbalance  to see balancing as unnecessary.  irqbalance --deep‐
73              estcache=2
74
75       The default value for deepestcache is 2.
76
77
78       -l, --policyscript=<script>
79              When specified, the referenced script or directory will  execute
80              once for each discovered IRQ, with the sysfs device path and IRQ
81              number passed as arguments.  Note that the device path  argument
82              will point to the parent directory from which the IRQ attributes
83              directory may be directly opened.  Policy scripts specified need
84              to be owned and executable by the user of irqbalance process, if
85              a directory is specified, non-executable files will be  skipped.
86              The  script  may  specify zero or more key=value pairs that will
87              guide irqbalance in the management of that IRQ.  Key=value pairs
88              are  printed  by  the  script on stdout and will be captured and
89              interpreted by irqbalance.  Irqbalance expects a zero exit  code
90              from the provided utility.  Recognized key=value pairs are:
91
92       ban=[true | false]
93              Directs irqbalance to exclude the passed in IRQ from balancing.
94
95       balance_level=[none | package | cache | core]
96              This allows a user to override the balance level of a given IRQ.
97              By default the balance level is determined  automatically  based
98              on the pci device class of the device that owns the IRQ.
99
100       numa_node=<integer>
101              This  allows  a  user to override the NUMA node that sysfs indi‐
102              cates a given device IRQ is local to.  Often, systems  will  not
103              specify  this  information  in ACPI, and as a result devices are
104              considered equidistant from all NUMA nodes in  a  system.   This
105              option allows for that hardware provided information to be over‐
106              ridden, so that irqbalance  can  bias  IRQ  affinity  for  these
107              devices  toward  its most local node.  Note that specifying a -1
108              here forces irqbalance to consider an interrupt from a device to
109              be equidistant from all nodes.
110
111       Note  that, if a directory is specified rather than a regular file, all
112       files in
113              the directory will be considered policy scripts, and executed on
114              adding  of  an irq to a database.  If such a directory is speci‐
115              fied, scripts in the directory must additionally exit  with  one
116              of the following exit codes:
117
118       0      This  indicates  the script has a policy for the referenced irq,
119              and that further script processing should stop
120
121       1      This indicates that the script has no policy for the  referenced
122              irq, and that script processing should continue
123
124       2      This  indicates that an error has occurred in the script, and it
125              should be skipped (further processing to continue)
126
127
128       -s, --pid=<file>
129              Have irqbalance write its process id to the specified file.   By
130              default no pidfile is written.  The written pidfile is automati‐
131              cally unlinked when irqbalance exits. It is  ignored  when  used
132              with --debug or --foreground.
133
134       -t, --interval=<time>
135              Set  the measurement time for irqbalance.  irqbalance will sleep
136              for <time> seconds between samples of the irq load on the system
137              cpus. Defaults to 10.
138

ENVIRONMENT VARIABLES

140       IRQBALANCE_ONESHOT
141              Same as --oneshot.
142
143
144       IRQBALANCE_DEBUG
145              Same as --debug.
146
147
148       IRQBALANCE_BANNED_CPUS
149              Provides a mask of CPUs which irqbalance should ignore and never
150              assign interrupts to.  If not specified, irqbalance use mask  of
151              isolated  and  adaptive-ticks  CPUs on the system as the default
152              value.
153
154

SIGNALS

156       SIGHUP Forces a rescan of the available IRQs and system topology.
157
158

API

160       irqbalance is able to communicate via socket and  return  it's  current
161       assignment  tree  and  setup, as well as set new settings based on sent
162       values. Socket is abstract, with a name in form of irqbalance<PID>.sock
163       ,  where  <PID> is the process ID of irqbalance instance to communicate
164       with.  Possible values to send:
165
166       stats  Retrieve assignment tree of IRQs to CPUs, in  recursive  manner.
167              For  each  CPU node in tree, it's type, number, load and whether
168              the save mode is active are sent. For each  assigned  IRQ  type,
169              it's  number,  load,  number  of IRQs since last rebalancing and
170              it's class are sent. Refer to types.h file  for  explanation  of
171              defines.
172
173       setup  Get the current value of sleep interval, mask of banned CPUs and
174              list of banned IRQs.
175
176       settings sleep <s>
177              Set new value of sleep interval, <s> >= 1.
178
179       settings cpus <cpu_number1> <cpu_number2> ...
180              Ban listed CPUs from IRQ handling, all old values of banned CPUs
181              are forgotten.
182
183       settings ban irqs <irq1> <irq2> ...
184              Ban  listed  IRQs  from being balanced, all old values of banned
185              IRQs are forgotten.
186
187       irqbalance checks SCM_CREDENTIALS of sender (only root user is  allowed
188       to  interact).   Based  on chosen tools, ancillary message with creden‐
189       tials needs to be sent with request.
190
191

HOMEPAGE

193       https://github.com/Irqbalance/irqbalance
194
195
196
197
198Linux                              Dec 2006                      IRQBALANCE(1)
Impressum