| 1 | =====================
|
| 2 | The Linux IPMI Driver
|
| 3 | =====================
|
| 4 |
|
| 5 | :Author: Corey Minyard <[email protected]> / <[email protected]>
|
| 6 |
|
| 7 | The Intelligent Platform Management Interface, or IPMI, is a
|
| 8 | standard for controlling intelligent devices that monitor a system.
|
| 9 | It provides for dynamic discovery of sensors in the system and the
|
| 10 | ability to monitor the sensors and be informed when the sensor's
|
| 11 | values change or go outside certain boundaries. It also has a
|
| 12 | standardized database for field-replaceable units (FRUs) and a watchdog
|
| 13 | timer.
|
| 14 |
|
| 15 | To use this, you need an interface to an IPMI controller in your
|
| 16 | system (called a Baseboard Management Controller, or BMC) and
|
| 17 | management software that can use the IPMI system.
|
| 18 |
|
| 19 | This document describes how to use the IPMI driver for Linux. If you
|
| 20 | are not familiar with IPMI itself, see the web site at
|
| 21 | https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
|
| 22 | subject and I can't cover it all here!
|
| 23 |
|
| 24 | Configuration
|
| 25 | -------------
|
| 26 |
|
| 27 | The Linux IPMI driver is modular, which means you have to pick several
|
| 28 | things to have it work right depending on your hardware. Most of
|
| 29 | these are available in the 'Character Devices' menu then the IPMI
|
| 30 | menu.
|
| 31 |
|
| 32 | No matter what, you must pick 'IPMI top-level message handler' to use
|
| 33 | IPMI. What you do beyond that depends on your needs and hardware.
|
| 34 |
|
| 35 | The message handler does not provide any user-level interfaces.
|
| 36 | Kernel code (like the watchdog) can still use it. If you need access
|
| 37 | from userland, you need to select 'Device interface for IPMI' if you
|
| 38 | want access through a device driver.
|
| 39 |
|
| 40 | The driver interface depends on your hardware. If your system
|
| 41 | properly provides the SMBIOS info for IPMI, the driver will detect it
|
| 42 | and just work. If you have a board with a standard interface (These
|
| 43 | will generally be either "KCS", "SMIC", or "BT", consult your hardware
|
| 44 | manual), choose the 'IPMI SI handler' option. A driver also exists
|
| 45 | for direct I2C access to the IPMI management controller. Some boards
|
| 46 | support this, but it is unknown if it will work on every board. For
|
| 47 | this, choose 'IPMI SMBus handler', but be ready to try to do some
|
| 48 | figuring to see if it will work on your system if the SMBIOS/ACPI
|
| 49 | information is wrong or not present. It is fairly safe to have both
|
| 50 | these enabled and let the drivers auto-detect what is present.
|
| 51 |
|
| 52 | You should generally enable ACPI on your system, as systems with IPMI
|
| 53 | can have ACPI tables describing them.
|
| 54 |
|
| 55 | If you have a standard interface and the board manufacturer has done
|
| 56 | their job correctly, the IPMI controller should be automatically
|
| 57 | detected (via ACPI or SMBIOS tables) and should just work. Sadly,
|
| 58 | many boards do not have this information. The driver attempts
|
| 59 | standard defaults, but they may not work. If you fall into this
|
| 60 | situation, you need to read the section below named 'The SI Driver' or
|
| 61 | "The SMBus Driver" on how to hand-configure your system.
|
| 62 |
|
| 63 | IPMI defines a standard watchdog timer. You can enable this with the
|
| 64 | 'IPMI Watchdog Timer' config option. If you compile the driver into
|
| 65 | the kernel, then via a kernel command-line option you can have the
|
| 66 | watchdog timer start as soon as it initializes. It also has a lot
|
| 67 | of other options, see the 'Watchdog' section below for more details.
|
| 68 | Note that you can also have the watchdog continue to run if it is
|
| 69 | closed (by default it is disabled on close). Go into the 'Watchdog
|
| 70 | Cards' menu, enable 'Watchdog Timer Support', and enable the option
|
| 71 | 'Disable watchdog shutdown on close'.
|
| 72 |
|
| 73 | IPMI systems can often be powered off using IPMI commands. Select
|
| 74 | 'IPMI Poweroff' to do this. The driver will auto-detect if the system
|
| 75 | can be powered off by IPMI. It is safe to enable this even if your
|
| 76 | system doesn't support this option. This works on ATCA systems, the
|
| 77 | Radisys CPI1 card, and any IPMI system that supports standard chassis
|
| 78 | management commands.
|
| 79 |
|
| 80 | If you want the driver to put an event into the event log on a panic,
|
| 81 | enable the 'Generate a panic event to all BMCs on a panic' option. If
|
| 82 | you want the whole panic string put into the event log using OEM
|
| 83 | events, enable the 'Generate OEM events containing the panic string'
|
| 84 | option. You can also enable these dynamically by setting the module
|
| 85 | parameter named "panic_op" in the ipmi_msghandler module to "event"
|
| 86 | or "string". Setting that parameter to "none" disables this function.
|
| 87 |
|
| 88 | Basic Design
|
| 89 | ------------
|
| 90 |
|
| 91 | The Linux IPMI driver is designed to be very modular and flexible, you
|
| 92 | only need to take the pieces you need and you can use it in many
|
| 93 | different ways. Because of that, it's broken into many chunks of
|
| 94 | code. These chunks (by module name) are:
|
| 95 |
|
| 96 | ipmi_msghandler - This is the central piece of software for the IPMI
|
| 97 | system. It handles all messages, message timing, and responses. The
|
| 98 | IPMI users tie into this, and the IPMI physical interfaces (called
|
| 99 | System Management Interfaces, or SMIs) also tie in here. This
|
| 100 | provides the kernelland interface for IPMI, but does not provide an
|
| 101 | interface for use by application processes.
|
| 102 |
|
| 103 | ipmi_devintf - This provides a userland IOCTL interface for the IPMI
|
| 104 | driver, each open file for this device ties in to the message handler
|
| 105 | as an IPMI user.
|
| 106 |
|
| 107 | ipmi_si - A driver for various system interfaces. This supports KCS,
|
| 108 | SMIC, and BT interfaces. Unless you have an SMBus interface or your
|
| 109 | own custom interface, you probably need to use this.
|
| 110 |
|
| 111 | ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the
|
| 112 | I2C kernel driver's SMBus interfaces to send and receive IPMI messages
|
| 113 | over the SMBus.
|
| 114 |
|
| 115 | ipmi_powernv - A driver for access BMCs on POWERNV systems.
|
| 116 |
|
| 117 | ipmi_watchdog - IPMI requires systems to have a very capable watchdog
|
| 118 | timer. This driver implements the standard Linux watchdog timer
|
| 119 | interface on top of the IPMI message handler.
|
| 120 |
|
| 121 | ipmi_poweroff - Some systems support the ability to be turned off via
|
| 122 | IPMI commands.
|
| 123 |
|
| 124 | bt-bmc - This is not part of the main driver, but instead a driver for
|
| 125 | accessing a BMC-side interface of a BT interface. It is used on BMCs
|
| 126 | running Linux to provide an interface to the host.
|
| 127 |
|
| 128 | These are all individually selectable via configuration options.
|
| 129 |
|
| 130 | Much documentation for the interface is in the include files. The
|
| 131 | IPMI include files are:
|
| 132 |
|
| 133 | linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
|
| 134 |
|
| 135 | linux/ipmi_smi.h - Contains the interface for system management interfaces
|
| 136 | (things that interface to IPMI controllers) to use.
|
| 137 |
|
| 138 | linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.
|
| 139 |
|
| 140 |
|
| 141 | Addressing
|
| 142 | ----------
|
| 143 |
|
| 144 | The IPMI addressing works much like IP addresses, you have an overlay
|
| 145 | to handle the different address types. The overlay is::
|
| 146 |
|
| 147 | struct ipmi_addr
|
| 148 | {
|
| 149 | int addr_type;
|
| 150 | short channel;
|
| 151 | char data[IPMI_MAX_ADDR_SIZE];
|
| 152 | };
|
| 153 |
|
| 154 | The addr_type determines what the address really is. The driver
|
| 155 | currently understands two different types of addresses.
|
| 156 |
|
| 157 | "System Interface" addresses are defined as::
|
| 158 |
|
| 159 | struct ipmi_system_interface_addr
|
| 160 | {
|
| 161 | int addr_type;
|
| 162 | short channel;
|
| 163 | };
|
| 164 |
|
| 165 | and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking
|
| 166 | straight to the BMC on the current card. The channel must be
|
| 167 | IPMI_BMC_CHANNEL.
|
| 168 |
|
| 169 | Messages that are destined to go out on the IPMB bus going through the
|
| 170 | BMC use the IPMI_IPMB_ADDR_TYPE address type. The format is::
|
| 171 |
|
| 172 | struct ipmi_ipmb_addr
|
| 173 | {
|
| 174 | int addr_type;
|
| 175 | short channel;
|
| 176 | unsigned char slave_addr;
|
| 177 | unsigned char lun;
|
| 178 | };
|
| 179 |
|
| 180 | The "channel" here is generally zero, but some devices support more
|
| 181 | than one channel, it corresponds to the channel as defined in the IPMI
|
| 182 | spec.
|
| 183 |
|
| 184 | There is also an IPMB direct address for a situation where the sender
|
| 185 | is directly on an IPMB bus and doesn't have to go through the BMC.
|
| 186 | You can send messages to a specific management controller (MC) on the
|
| 187 | IPMB using the IPMI_IPMB_DIRECT_ADDR_TYPE with the following format::
|
| 188 |
|
| 189 | struct ipmi_ipmb_direct_addr
|
| 190 | {
|
| 191 | int addr_type;
|
| 192 | short channel;
|
| 193 | unsigned char slave_addr;
|
| 194 | unsigned char rq_lun;
|
| 195 | unsigned char rs_lun;
|
| 196 | };
|
| 197 |
|
| 198 | The channel is always zero. You can also receive commands from other
|
| 199 | MCs that you have registered to handle and respond to them, so you can
|
| 200 | use this to implement a management controller on a bus..
|
| 201 |
|
| 202 | Messages
|
| 203 | --------
|
| 204 |
|
| 205 | Messages are defined as::
|
| 206 |
|
| 207 | struct ipmi_msg
|
| 208 | {
|
| 209 | unsigned char netfn;
|
| 210 | unsigned char lun;
|
| 211 | unsigned char cmd;
|
| 212 | unsigned char *data;
|
| 213 | int data_len;
|
| 214 | };
|
| 215 |
|
| 216 | The driver takes care of adding/stripping the header information. The
|
| 217 | data portion is just the data to be send (do NOT put addressing info
|
| 218 | here) or the response. Note that the completion code of a response is
|
| 219 | the first item in "data", it is not stripped out because that is how
|
| 220 | all the messages are defined in the spec (and thus makes counting the
|
| 221 | offsets a little easier :-).
|
| 222 |
|
| 223 | When using the IOCTL interface from userland, you must provide a block
|
| 224 | of data for "data", fill it, and set data_len to the length of the
|
| 225 | block of data, even when receiving messages. Otherwise the driver
|
| 226 | will have no place to put the message.
|
| 227 |
|
| 228 | Messages coming up from the message handler in kernelland will come in
|
| 229 | as::
|
| 230 |
|
| 231 | struct ipmi_recv_msg
|
| 232 | {
|
| 233 | struct list_head link;
|
| 234 |
|
| 235 | /* The type of message as defined in the "Receive Types"
|
| 236 | defines above. */
|
| 237 | int recv_type;
|
| 238 |
|
| 239 | ipmi_user_t *user;
|
| 240 | struct ipmi_addr addr;
|
| 241 | long msgid;
|
| 242 | struct ipmi_msg msg;
|
| 243 |
|
| 244 | /* Call this when done with the message. It will presumably free
|
| 245 | the message and do any other necessary cleanup. */
|
| 246 | void (*done)(struct ipmi_recv_msg *msg);
|
| 247 |
|
| 248 | /* Place-holder for the data, don't make any assumptions about
|
| 249 | the size or existence of this, since it may change. */
|
| 250 | unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
|
| 251 | };
|
| 252 |
|
| 253 | You should look at the receive type and handle the message
|
| 254 | appropriately.
|
| 255 |
|
| 256 |
|
| 257 | The Upper Layer Interface (Message Handler)
|
| 258 | -------------------------------------------
|
| 259 |
|
| 260 | The upper layer of the interface provides the users with a consistent
|
| 261 | view of the IPMI interfaces. It allows multiple SMI interfaces to be
|
| 262 | addressed (because some boards actually have multiple BMCs on them)
|
| 263 | and the user should not have to care what type of SMI is below them.
|
| 264 |
|
| 265 |
|
| 266 | Watching For Interfaces
|
| 267 | ^^^^^^^^^^^^^^^^^^^^^^^
|
| 268 |
|
| 269 | When your code comes up, the IPMI driver may or may not have detected
|
| 270 | if IPMI devices exist. So you might have to defer your setup until
|
| 271 | the device is detected, or you might be able to do it immediately.
|
| 272 | To handle this, and to allow for discovery, you register an SMI
|
| 273 | watcher with ipmi_smi_watcher_register() to iterate over interfaces
|
| 274 | and tell you when they come and go.
|
| 275 |
|
| 276 |
|
| 277 | Creating the User
|
| 278 | ^^^^^^^^^^^^^^^^^
|
| 279 |
|
| 280 | To use the message handler, you must first create a user using
|
| 281 | ipmi_create_user. The interface number specifies which SMI you want
|
| 282 | to connect to, and you must supply callback functions to be called
|
| 283 | when data comes in. This also allows you to pass in a piece of data,
|
| 284 | the handler_data, that will be passed back to you on all calls.
|
| 285 |
|
| 286 | Once you are done, call ipmi_destroy_user() to get rid of the user.
|
| 287 |
|
| 288 | From userland, opening the device automatically creates a user, and
|
| 289 | closing the device automatically destroys the user.
|
| 290 |
|
| 291 |
|
| 292 | Messaging
|
| 293 | ^^^^^^^^^
|
| 294 |
|
| 295 | To send a message from kernel-land, the ipmi_request_settime() call does
|
| 296 | pretty much all message handling. Most of the parameter are
|
| 297 | self-explanatory. However, it takes a "msgid" parameter. This is NOT
|
| 298 | the sequence number of messages. It is simply a long value that is
|
| 299 | passed back when the response for the message is returned. You may
|
| 300 | use it for anything you like.
|
| 301 |
|
| 302 | Responses come back in the function pointed to by the ipmi_recv_hndl
|
| 303 | field of the "handler" that you passed in to ipmi_create_user().
|
| 304 | Remember to look at the receive type, too.
|
| 305 |
|
| 306 | From userland, you fill out an ipmi_req_t structure and use the
|
| 307 | IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select()
|
| 308 | or poll() to wait for messages to come in. However, you cannot use
|
| 309 | read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
|
| 310 | ipmi_recv_t structure to actually get the message. Remember that you
|
| 311 | must supply a pointer to a block of data in the msg.data field, and
|
| 312 | you must fill in the msg.data_len field with the size of the data.
|
| 313 | This gives the receiver a place to actually put the message.
|
| 314 |
|
| 315 | If the message cannot fit into the data you provide, you will get an
|
| 316 | EMSGSIZE error and the driver will leave the data in the receive
|
| 317 | queue. If you want to get it and have it truncate the message, use
|
| 318 | the IPMICTL_RECEIVE_MSG_TRUNC ioctl.
|
| 319 |
|
| 320 | When you send a command (which is defined by the lowest-order bit of
|
| 321 | the netfn per the IPMI spec) on the IPMB bus, the driver will
|
| 322 | automatically assign the sequence number to the command and save the
|
| 323 | command. If the response is not received in the IPMI-specified 5
|
| 324 | seconds, it will generate a response automatically saying the command
|
| 325 | timed out. If an unsolicited response comes in (if it was after 5
|
| 326 | seconds, for instance), that response will be ignored.
|
| 327 |
|
| 328 | In kernelland, after you receive a message and are done with it, you
|
| 329 | MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note
|
| 330 | that you should NEVER mess with the "done" field of a message, that is
|
| 331 | required to properly clean up the message.
|
| 332 |
|
| 333 | Note that when sending, there is an ipmi_request_supply_msgs() call
|
| 334 | that lets you supply the smi and receive message. This is useful for
|
| 335 | pieces of code that need to work even if the system is out of buffers
|
| 336 | (the watchdog timer uses this, for instance). You supply your own
|
| 337 | buffer and own free routines. This is not recommended for normal use,
|
| 338 | though, since it is tricky to manage your own buffers.
|
| 339 |
|
| 340 |
|
| 341 | Events and Incoming Commands
|
| 342 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
| 343 |
|
| 344 | The driver takes care of polling for IPMI events and receiving
|
| 345 | commands (commands are messages that are not responses, they are
|
| 346 | commands that other things on the IPMB bus have sent you). To receive
|
| 347 | these, you must register for them, they will not automatically be sent
|
| 348 | to you.
|
| 349 |
|
| 350 | To receive events, you must call ipmi_set_gets_events() and set the
|
| 351 | "val" to non-zero. Any events that have been received by the driver
|
| 352 | since startup will immediately be delivered to the first user that
|
| 353 | registers for events. After that, if multiple users are registered
|
| 354 | for events, they will all receive all events that come in.
|
| 355 |
|
| 356 | For receiving commands, you have to individually register commands you
|
| 357 | want to receive. Call ipmi_register_for_cmd() and supply the netfn
|
| 358 | and command name for each command you want to receive. You also
|
| 359 | specify a bitmask of the channels you want to receive the command from
|
| 360 | (or use IPMI_CHAN_ALL for all channels if you don't care). Only one
|
| 361 | user may be registered for each netfn/cmd/channel, but different users
|
| 362 | may register for different commands, or the same command if the
|
| 363 | channel bitmasks do not overlap.
|
| 364 |
|
| 365 | To respond to a received command, set the response bit in the returned
|
| 366 | netfn, use the address from the received message, and use the same
|
| 367 | msgid that you got in the received message.
|
| 368 |
|
| 369 | From userland, equivalent IOCTLs are provided to do these functions.
|
| 370 |
|
| 371 |
|
| 372 | The Lower Layer (SMI) Interface
|
| 373 | -------------------------------
|
| 374 |
|
| 375 | As mentioned before, multiple SMI interfaces may be registered to the
|
| 376 | message handler, each of these is assigned an interface number when
|
| 377 | they register with the message handler. They are generally assigned
|
| 378 | in the order they register, although if an SMI unregisters and then
|
| 379 | another one registers, all bets are off.
|
| 380 |
|
| 381 | The ipmi_smi.h defines the interface for management interfaces, see
|
| 382 | that for more details.
|
| 383 |
|
| 384 |
|
| 385 | The SI Driver
|
| 386 | -------------
|
| 387 |
|
| 388 | The SI driver allows KCS, BT, and SMIC interfaces to be configured
|
| 389 | in the system. It discovers interfaces through a host of different
|
| 390 | methods, depending on the system.
|
| 391 |
|
| 392 | You can specify up to four interfaces on the module load line and
|
| 393 | control some module parameters::
|
| 394 |
|
| 395 | modprobe ipmi_si.o type=<type1>,<type2>....
|
| 396 | ports=<port1>,<port2>... addrs=<addr1>,<addr2>...
|
| 397 | irqs=<irq1>,<irq2>...
|
| 398 | regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,...
|
| 399 | regshifts=<shift1>,<shift2>,...
|
| 400 | slave_addrs=<addr1>,<addr2>,...
|
| 401 | force_kipmid=<enable1>,<enable2>,...
|
| 402 | kipmid_max_busy_us=<ustime1>,<ustime2>,...
|
| 403 | unload_when_empty=[0|1]
|
| 404 | trydmi=[0|1] tryacpi=[0|1]
|
| 405 | tryplatform=[0|1] trypci=[0|1]
|
| 406 |
|
| 407 | Each of these except try... items is a list, the first item for the
|
| 408 | first interface, second item for the second interface, etc.
|
| 409 |
|
| 410 | The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it
|
| 411 | defaults to "kcs".
|
| 412 |
|
| 413 | If you specify addrs as non-zero for an interface, the driver will
|
| 414 | use the memory address given as the address of the device. This
|
| 415 | overrides si_ports.
|
| 416 |
|
| 417 | If you specify ports as non-zero for an interface, the driver will
|
| 418 | use the I/O port given as the device address.
|
| 419 |
|
| 420 | If you specify irqs as non-zero for an interface, the driver will
|
| 421 | attempt to use the given interrupt for the device.
|
| 422 |
|
| 423 | The other try... items disable discovery by their corresponding
|
| 424 | names. These are all enabled by default, set them to zero to disable
|
| 425 | them. The tryplatform disables openfirmware.
|
| 426 |
|
| 427 | The next three parameters have to do with register layout. The
|
| 428 | registers used by the interfaces may not appear at successive
|
| 429 | locations and they may not be in 8-bit registers. These parameters
|
| 430 | allow the layout of the data in the registers to be more precisely
|
| 431 | specified.
|
| 432 |
|
| 433 | The regspacings parameter give the number of bytes between successive
|
| 434 | register start addresses. For instance, if the regspacing is set to 4
|
| 435 | and the start address is 0xca2, then the address for the second
|
| 436 | register would be 0xca6. This defaults to 1.
|
| 437 |
|
| 438 | The regsizes parameter gives the size of a register, in bytes. The
|
| 439 | data used by IPMI is 8-bits wide, but it may be inside a larger
|
| 440 | register. This parameter allows the read and write type to be specified.
|
| 441 | It may be 1, 2, 4, or 8. The default is 1.
|
| 442 |
|
| 443 | Since the register size may be larger than 32 bits, the IPMI data may not
|
| 444 | be in the lower 8 bits. The regshifts parameter give the amount to shift
|
| 445 | the data to get to the actual IPMI data.
|
| 446 |
|
| 447 | The slave_addrs specifies the IPMI address of the local BMC. This is
|
| 448 | usually 0x20 and the driver defaults to that, but in case it's not, it
|
| 449 | can be specified when the driver starts up.
|
| 450 |
|
| 451 | The force_ipmid parameter forcefully enables (if set to 1) or disables
|
| 452 | (if set to 0) the kernel IPMI daemon. Normally this is auto-detected
|
| 453 | by the driver, but systems with broken interrupts might need an enable,
|
| 454 | or users that don't want the daemon (don't need the performance, don't
|
| 455 | want the CPU hit) can disable it.
|
| 456 |
|
| 457 | If unload_when_empty is set to 1, the driver will be unloaded if it
|
| 458 | doesn't find any interfaces or all the interfaces fail to work. The
|
| 459 | default is one. Setting to 0 is useful with the hotmod, but is
|
| 460 | obviously only useful for modules.
|
| 461 |
|
| 462 | When compiled into the kernel, the parameters can be specified on the
|
| 463 | kernel command line as::
|
| 464 |
|
| 465 | ipmi_si.type=<type1>,<type2>...
|
| 466 | ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
|
| 467 | ipmi_si.irqs=<irq1>,<irq2>...
|
| 468 | ipmi_si.regspacings=<sp1>,<sp2>,...
|
| 469 | ipmi_si.regsizes=<size1>,<size2>,...
|
| 470 | ipmi_si.regshifts=<shift1>,<shift2>,...
|
| 471 | ipmi_si.slave_addrs=<addr1>,<addr2>,...
|
| 472 | ipmi_si.force_kipmid=<enable1>,<enable2>,...
|
| 473 | ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,...
|
| 474 |
|
| 475 | It works the same as the module parameters of the same names.
|
| 476 |
|
| 477 | If your IPMI interface does not support interrupts and is a KCS or
|
| 478 | SMIC interface, the IPMI driver will start a kernel thread for the
|
| 479 | interface to help speed things up. This is a low-priority kernel
|
| 480 | thread that constantly polls the IPMI driver while an IPMI operation
|
| 481 | is in progress. The force_kipmid module parameter will allow the user
|
| 482 | to force this thread on or off. If you force it off and don't have
|
| 483 | interrupts, the driver will run VERY slowly. Don't blame me,
|
| 484 | these interfaces suck.
|
| 485 |
|
| 486 | Unfortunately, this thread can use a lot of CPU depending on the
|
| 487 | interface's performance. This can waste a lot of CPU and cause
|
| 488 | various issues with detecting idle CPU and using extra power. To
|
| 489 | avoid this, the kipmid_max_busy_us sets the maximum amount of time, in
|
| 490 | microseconds, that kipmid will spin before sleeping for a tick. This
|
| 491 | value sets a balance between performance and CPU waste and needs to be
|
| 492 | tuned to your needs. Maybe, someday, auto-tuning will be added, but
|
| 493 | that's not a simple thing and even the auto-tuning would need to be
|
| 494 | tuned to the user's desired performance.
|
| 495 |
|
| 496 | The driver supports a hot add and remove of interfaces. This way,
|
| 497 | interfaces can be added or removed after the kernel is up and running.
|
| 498 | This is done using /sys/module/ipmi_si/parameters/hotmod, which is a
|
| 499 | write-only parameter. You write a string to this interface. The string
|
| 500 | has the format::
|
| 501 |
|
| 502 | <op1>[:op2[:op3...]]
|
| 503 |
|
| 504 | The "op"s are::
|
| 505 |
|
| 506 | add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]]
|
| 507 |
|
| 508 | You can specify more than one interface on the line. The "opt"s are::
|
| 509 |
|
| 510 | rsp=<regspacing>
|
| 511 | rsi=<regsize>
|
| 512 | rsh=<regshift>
|
| 513 | irq=<irq>
|
| 514 | ipmb=<ipmb slave addr>
|
| 515 |
|
| 516 | and these have the same meanings as discussed above. Note that you
|
| 517 | can also use this on the kernel command line for a more compact format
|
| 518 | for specifying an interface. Note that when removing an interface,
|
| 519 | only the first three parameters (si type, address type, and address)
|
| 520 | are used for the comparison. Any options are ignored for removing.
|
| 521 |
|
| 522 | The SMBus Driver (SSIF)
|
| 523 | -----------------------
|
| 524 |
|
| 525 | The SMBus driver allows up to 4 SMBus devices to be configured in the
|
| 526 | system. By default, the driver will only register with something it
|
| 527 | finds in DMI or ACPI tables. You can change this
|
| 528 | at module load time (for a module) with::
|
| 529 |
|
| 530 | modprobe ipmi_ssif.o
|
| 531 | addr=<i2caddr1>[,<i2caddr2>[,...]]
|
| 532 | adapter=<adapter1>[,<adapter2>[...]]
|
| 533 | dbg=<flags1>,<flags2>...
|
| 534 | slave_addrs=<addr1>,<addr2>,...
|
| 535 | tryacpi=[0|1] trydmi=[0|1]
|
| 536 | [dbg_probe=1]
|
| 537 | alerts_broken
|
| 538 |
|
| 539 | The addresses are normal I2C addresses. The adapter is the string
|
| 540 | name of the adapter, as shown in /sys/bus/i2c/devices/i2c-<n>/name.
|
| 541 | It is *NOT* i2c-<n> itself. Also, the comparison is done ignoring
|
| 542 | spaces, so if the name is "This is an I2C chip" you can say
|
| 543 | adapter_name=ThisisanI2cchip. This is because it's hard to pass in
|
| 544 | spaces in kernel parameters.
|
| 545 |
|
| 546 | The debug flags are bit flags for each BMC found, they are:
|
| 547 | IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8
|
| 548 |
|
| 549 | The tryxxx parameters can be used to disable detecting interfaces
|
| 550 | from various sources.
|
| 551 |
|
| 552 | Setting dbg_probe to 1 will enable debugging of the probing and
|
| 553 | detection process for BMCs on the SMBusses.
|
| 554 |
|
| 555 | The slave_addrs specifies the IPMI address of the local BMC. This is
|
| 556 | usually 0x20 and the driver defaults to that, but in case it's not, it
|
| 557 | can be specified when the driver starts up.
|
| 558 |
|
| 559 | alerts_broken does not enable SMBus alert for SSIF. Otherwise SMBus
|
| 560 | alert will be enabled on supported hardware.
|
| 561 |
|
| 562 | Discovering the IPMI compliant BMC on the SMBus can cause devices on
|
| 563 | the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI
|
| 564 | message as a block write to the I2C bus and waits for a response.
|
| 565 | This action can be detrimental to some I2C devices. It is highly
|
| 566 | recommended that the known I2C address be given to the SMBus driver in
|
| 567 | the smb_addr parameter unless you have DMI or ACPI data to tell the
|
| 568 | driver what to use.
|
| 569 |
|
| 570 | When compiled into the kernel, the addresses can be specified on the
|
| 571 | kernel command line as::
|
| 572 |
|
| 573 | ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]]
|
| 574 | ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]
|
| 575 | ipmi_ssif.dbg=<flags1>[,<flags2>[...]]
|
| 576 | ipmi_ssif.dbg_probe=1
|
| 577 | ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]
|
| 578 | ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1]
|
| 579 |
|
| 580 | These are the same options as on the module command line.
|
| 581 |
|
| 582 | The I2C driver does not support non-blocking access or polling, so
|
| 583 | this driver cannot do IPMI panic events, extend the watchdog at panic
|
| 584 | time, or other panic-related IPMI functions without special kernel
|
| 585 | patches and driver modifications. You can get those at the openipmi
|
| 586 | web page.
|
| 587 |
|
| 588 | The driver supports a hot add and remove of interfaces through the I2C
|
| 589 | sysfs interface.
|
| 590 |
|
| 591 | The IPMI IPMB Driver
|
| 592 | --------------------
|
| 593 |
|
| 594 | This driver is for supporting a system that sits on an IPMB bus; it
|
| 595 | allows the interface to look like a normal IPMI interface. Sending
|
| 596 | system interface addressed messages to it will cause the message to go
|
| 597 | to the registered BMC on the system (default at IPMI address 0x20).
|
| 598 |
|
| 599 | It also allows you to directly address other MCs on the bus using the
|
| 600 | ipmb direct addressing. You can receive commands from other MCs on
|
| 601 | the bus and they will be handled through the normal received command
|
| 602 | mechanism described above.
|
| 603 |
|
| 604 | Parameters are::
|
| 605 |
|
| 606 | ipmi_ipmb.bmcaddr=<address to use for system interface addresses messages>
|
| 607 | ipmi_ipmb.retry_time_ms=<Time between retries on IPMB>
|
| 608 | ipmi_ipmb.max_retries=<Number of times to retry a message>
|
| 609 |
|
| 610 | Loading the module will not result in the driver automatically
|
| 611 | starting unless there is device tree information setting it up. If
|
| 612 | you want to instantiate one of these by hand, do::
|
| 613 |
|
| 614 | echo ipmi-ipmb <addr> > /sys/class/i2c-dev/i2c-<n>/device/new_device
|
| 615 |
|
| 616 | Note that the address you give here is the I2C address, not the IPMI
|
| 617 | address. So if you want your MC address to be 0x60, you put 0x30
|
| 618 | here. See the I2C driver info for more details.
|
| 619 |
|
| 620 | Command bridging to other IPMB buses through this interface does not
|
| 621 | work. The receive message queue is not implemented, by design. There
|
| 622 | is only one receive message queue on a BMC, and that is meant for the
|
| 623 | host drivers, not something on the IPMB bus.
|
| 624 |
|
| 625 | A BMC may have multiple IPMB buses, which bus your device sits on
|
| 626 | depends on how the system is wired. You can fetch the channels with
|
| 627 | "ipmitool channel info <n>" where <n> is the channel, with the
|
| 628 | channels being 0-7 and try the IPMB channels.
|
| 629 |
|
| 630 | Other Pieces
|
| 631 | ------------
|
| 632 |
|
| 633 | Get the detailed info related with the IPMI device
|
| 634 | --------------------------------------------------
|
| 635 |
|
| 636 | Some users need more detailed information about a device, like where
|
| 637 | the address came from or the raw base device for the IPMI interface.
|
| 638 | You can use the IPMI smi_watcher to catch the IPMI interfaces as they
|
| 639 | come or go, and to grab the information, you can use the function
|
| 640 | ipmi_get_smi_info(), which returns the following structure::
|
| 641 |
|
| 642 | struct ipmi_smi_info {
|
| 643 | enum ipmi_addr_src addr_src;
|
| 644 | struct device *dev;
|
| 645 | union {
|
| 646 | struct {
|
| 647 | void *acpi_handle;
|
| 648 | } acpi_info;
|
| 649 | } addr_info;
|
| 650 | };
|
| 651 |
|
| 652 | Currently special info for only for SI_ACPI address sources is
|
| 653 | returned. Others may be added as necessary.
|
| 654 |
|
| 655 | Note that the dev pointer is included in the above structure, and
|
| 656 | assuming ipmi_smi_get_info returns success, you must call put_device
|
| 657 | on the dev pointer.
|
| 658 |
|
| 659 |
|
| 660 | Watchdog
|
| 661 | --------
|
| 662 |
|
| 663 | A watchdog timer is provided that implements the Linux-standard
|
| 664 | watchdog timer interface. It has three module parameters that can be
|
| 665 | used to control it::
|
| 666 |
|
| 667 | modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
|
| 668 | preaction=<preaction type> preop=<preop type> start_now=x
|
| 669 | nowayout=x ifnum_to_use=n panic_wdt_timeout=<t>
|
| 670 |
|
| 671 | ifnum_to_use specifies which interface the watchdog timer should use.
|
| 672 | The default is -1, which means to pick the first one registered.
|
| 673 |
|
| 674 | The timeout is the number of seconds to the action, and the pretimeout
|
| 675 | is the amount of seconds before the reset that the pre-timeout panic will
|
| 676 | occur (if pretimeout is zero, then pretimeout will not be enabled). Note
|
| 677 | that the pretimeout is the time before the final timeout. So if the
|
| 678 | timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout
|
| 679 | will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout
|
| 680 | is the value of timeout which is set on kernel panic, in order to let actions
|
| 681 | such as kdump to occur during panic.
|
| 682 |
|
| 683 | The action may be "reset", "power_cycle", or "power_off", and
|
| 684 | specifies what to do when the timer times out, and defaults to
|
| 685 | "reset".
|
| 686 |
|
| 687 | The preaction may be "pre_smi" for an indication through the SMI
|
| 688 | interface, "pre_int" for an indication through the SMI with an
|
| 689 | interrupts, and "pre_nmi" for a NMI on a preaction. This is how
|
| 690 | the driver is informed of the pretimeout.
|
| 691 |
|
| 692 | The preop may be set to "preop_none" for no operation on a pretimeout,
|
| 693 | "preop_panic" to set the preoperation to panic, or "preop_give_data"
|
| 694 | to provide data to read from the watchdog device when the pretimeout
|
| 695 | occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data"
|
| 696 | because you can't do data operations from an NMI.
|
| 697 |
|
| 698 | When preop is set to "preop_give_data", one byte comes ready to read
|
| 699 | on the device when the pretimeout occurs. Select and fasync work on
|
| 700 | the device, as well.
|
| 701 |
|
| 702 | If start_now is set to 1, the watchdog timer will start running as
|
| 703 | soon as the driver is loaded.
|
| 704 |
|
| 705 | If nowayout is set to 1, the watchdog timer will not stop when the
|
| 706 | watchdog device is closed. The default value of nowayout is true
|
| 707 | if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.
|
| 708 |
|
| 709 | When compiled into the kernel, the kernel command line is available
|
| 710 | for configuring the watchdog::
|
| 711 |
|
| 712 | ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>
|
| 713 | ipmi_watchdog.action=<action type>
|
| 714 | ipmi_watchdog.preaction=<preaction type>
|
| 715 | ipmi_watchdog.preop=<preop type>
|
| 716 | ipmi_watchdog.start_now=x
|
| 717 | ipmi_watchdog.nowayout=x
|
| 718 | ipmi_watchdog.panic_wdt_timeout=<t>
|
| 719 |
|
| 720 | The options are the same as the module parameter options.
|
| 721 |
|
| 722 | The watchdog will panic and start a 120 second reset timeout if it
|
| 723 | gets a pre-action. During a panic or a reboot, the watchdog will
|
| 724 | start a 120 timer if it is running to make sure the reboot occurs.
|
| 725 |
|
| 726 | Note that if you use the NMI preaction for the watchdog, you MUST NOT
|
| 727 | use the nmi watchdog. There is no reasonable way to tell if an NMI
|
| 728 | comes from the IPMI controller, so it must assume that if it gets an
|
| 729 | otherwise unhandled NMI, it must be from IPMI and it will panic
|
| 730 | immediately.
|
| 731 |
|
| 732 | Once you open the watchdog timer, you must write a 'V' character to the
|
| 733 | device to close it, or the timer will not stop. This is a new semantic
|
| 734 | for the driver, but makes it consistent with the rest of the watchdog
|
| 735 | drivers in Linux.
|
| 736 |
|
| 737 |
|
| 738 | Panic Timeouts
|
| 739 | --------------
|
| 740 |
|
| 741 | The OpenIPMI driver supports the ability to put semi-custom and custom
|
| 742 | events in the system event log if a panic occurs. if you enable the
|
| 743 | 'Generate a panic event to all BMCs on a panic' option, you will get
|
| 744 | one event on a panic in a standard IPMI event format. If you enable
|
| 745 | the 'Generate OEM events containing the panic string' option, you will
|
| 746 | also get a bunch of OEM events holding the panic string.
|
| 747 |
|
| 748 |
|
| 749 | The field settings of the events are:
|
| 750 |
|
| 751 | * Generator ID: 0x21 (kernel)
|
| 752 | * EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)
|
| 753 | * Sensor Type: 0x20 (OS critical stop sensor)
|
| 754 | * Sensor #: The first byte of the panic string (0 if no panic string)
|
| 755 | * Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info)
|
| 756 | * Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)
|
| 757 | * Event data 2: second byte of panic string
|
| 758 | * Event data 3: third byte of panic string
|
| 759 |
|
| 760 | See the IPMI spec for the details of the event layout. This event is
|
| 761 | always sent to the local management controller. It will handle routing
|
| 762 | the message to the right place
|
| 763 |
|
| 764 | Other OEM events have the following format:
|
| 765 |
|
| 766 | * Record ID (bytes 0-1): Set by the SEL.
|
| 767 | * Record type (byte 2): 0xf0 (OEM non-timestamped)
|
| 768 | * byte 3: The slave address of the card saving the panic
|
| 769 | * byte 4: A sequence number (starting at zero)
|
| 770 | The rest of the bytes (11 bytes) are the panic string. If the panic string
|
| 771 | is longer than 11 bytes, multiple messages will be sent with increasing
|
| 772 | sequence numbers.
|
| 773 |
|
| 774 | Because you cannot send OEM events using the standard interface, this
|
| 775 | function will attempt to find an SEL and add the events there. It
|
| 776 | will first query the capabilities of the local management controller.
|
| 777 | If it has an SEL, then they will be stored in the SEL of the local
|
| 778 | management controller. If not, and the local management controller is
|
| 779 | an event generator, the event receiver from the local management
|
| 780 | controller will be queried and the events sent to the SEL on that
|
| 781 | device. Otherwise, the events go nowhere since there is nowhere to
|
| 782 | send them.
|
| 783 |
|
| 784 |
|
| 785 | Poweroff
|
| 786 | --------
|
| 787 |
|
| 788 | If the poweroff capability is selected, the IPMI driver will install
|
| 789 | a shutdown function into the standard poweroff function pointer. This
|
| 790 | is in the ipmi_poweroff module. When the system requests a powerdown,
|
| 791 | it will send the proper IPMI commands to do this. This is supported on
|
| 792 | several platforms.
|
| 793 |
|
| 794 | There is a module parameter named "poweroff_powercycle" that may
|
| 795 | either be zero (do a power down) or non-zero (do a power cycle, power
|
| 796 | the system off, then power it on in a few seconds). Setting
|
| 797 | ipmi_poweroff.poweroff_control=x will do the same thing on the kernel
|
| 798 | command line. The parameter is also available via the proc filesystem
|
| 799 | in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system
|
| 800 | does not support power cycling, it will always do the power off.
|
| 801 |
|
| 802 | The "ifnum_to_use" parameter specifies which interface the poweroff
|
| 803 | code should use. The default is -1, which means to pick the first one
|
| 804 | registered.
|
| 805 |
|
| 806 | Note that if you have ACPI enabled, the system will prefer using ACPI to
|
| 807 | power off.
|