811 lines · plain
1=====================2The Linux IPMI Driver3=====================4 5:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org>6 7The Intelligent Platform Management Interface, or IPMI, is a8standard for controlling intelligent devices that monitor a system.9It provides for dynamic discovery of sensors in the system and the10ability to monitor the sensors and be informed when the sensor's11values change or go outside certain boundaries. It also has a12standardized database for field-replaceable units (FRUs) and a watchdog13timer.14 15To use this, you need an interface to an IPMI controller in your16system (called a Baseboard Management Controller, or BMC) and17management software that can use the IPMI system.18 19This document describes how to use the IPMI driver for Linux. If you20are not familiar with IPMI itself, see the web site at21https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big22subject and I can't cover it all here!23 24Configuration25-------------26 27The Linux IPMI driver is modular, which means you have to pick several28things to have it work right depending on your hardware. Most of29these are available in the 'Character Devices' menu then the IPMI30menu.31 32No matter what, you must pick 'IPMI top-level message handler' to use33IPMI. What you do beyond that depends on your needs and hardware.34 35The message handler does not provide any user-level interfaces.36Kernel code (like the watchdog) can still use it. If you need access37from userland, you need to select 'Device interface for IPMI' if you38want access through a device driver.39 40The driver interface depends on your hardware. If your system41properly provides the SMBIOS info for IPMI, the driver will detect it42and just work. If you have a board with a standard interface (These43will generally be either "KCS", "SMIC", or "BT", consult your hardware44manual), choose the 'IPMI SI handler' option. A driver also exists45for direct I2C access to the IPMI management controller. Some boards46support this, but it is unknown if it will work on every board. For47this, choose 'IPMI SMBus handler', but be ready to try to do some48figuring to see if it will work on your system if the SMBIOS/APCI49information is wrong or not present. It is fairly safe to have both50these enabled and let the drivers auto-detect what is present.51 52You should generally enable ACPI on your system, as systems with IPMI53can have ACPI tables describing them.54 55If you have a standard interface and the board manufacturer has done56their job correctly, the IPMI controller should be automatically57detected (via ACPI or SMBIOS tables) and should just work. Sadly,58many boards do not have this information. The driver attempts59standard defaults, but they may not work. If you fall into this60situation, you need to read the section below named 'The SI Driver' or61"The SMBus Driver" on how to hand-configure your system.62 63IPMI defines a standard watchdog timer. You can enable this with the64'IPMI Watchdog Timer' config option. If you compile the driver into65the kernel, then via a kernel command-line option you can have the66watchdog timer start as soon as it initializes. It also have a lot67of other options, see the 'Watchdog' section below for more details.68Note that you can also have the watchdog continue to run if it is69closed (by default it is disabled on close). Go into the 'Watchdog70Cards' menu, enable 'Watchdog Timer Support', and enable the option71'Disable watchdog shutdown on close'.72 73IPMI systems can often be powered off using IPMI commands. Select74'IPMI Poweroff' to do this. The driver will auto-detect if the system75can be powered off by IPMI. It is safe to enable this even if your76system doesn't support this option. This works on ATCA systems, the77Radisys CPI1 card, and any IPMI system that supports standard chassis78management commands.79 80If you want the driver to put an event into the event log on a panic,81enable the 'Generate a panic event to all BMCs on a panic' option. If82you want the whole panic string put into the event log using OEM83events, enable the 'Generate OEM events containing the panic string'84option. You can also enable these dynamically by setting the module85parameter named "panic_op" in the ipmi_msghandler module to "event"86or "string". Setting that parameter to "none" disables this function.87 88Basic Design89------------90 91The Linux IPMI driver is designed to be very modular and flexible, you92only need to take the pieces you need and you can use it in many93different ways. Because of that, it's broken into many chunks of94code. These chunks (by module name) are:95 96ipmi_msghandler - This is the central piece of software for the IPMI97system. It handles all messages, message timing, and responses. The98IPMI users tie into this, and the IPMI physical interfaces (called99System Management Interfaces, or SMIs) also tie in here. This100provides the kernelland interface for IPMI, but does not provide an101interface for use by application processes.102 103ipmi_devintf - This provides a userland IOCTL interface for the IPMI104driver, each open file for this device ties in to the message handler105as an IPMI user.106 107ipmi_si - A driver for various system interfaces. This supports KCS,108SMIC, and BT interfaces. Unless you have an SMBus interface or your109own custom interface, you probably need to use this.110 111ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the112I2C kernel driver's SMBus interfaces to send and receive IPMI messages113over the SMBus.114 115ipmi_powernv - A driver for access BMCs on POWERNV systems.116 117ipmi_watchdog - IPMI requires systems to have a very capable watchdog118timer. This driver implements the standard Linux watchdog timer119interface on top of the IPMI message handler.120 121ipmi_poweroff - Some systems support the ability to be turned off via122IPMI commands.123 124bt-bmc - This is not part of the main driver, but instead a driver for125accessing a BMC-side interface of a BT interface. It is used on BMCs126running Linux to provide an interface to the host.127 128These are all individually selectable via configuration options.129 130Much documentation for the interface is in the include files. The131IPMI include files are:132 133linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.134 135linux/ipmi_smi.h - Contains the interface for system management interfaces136(things that interface to IPMI controllers) to use.137 138linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.139 140 141Addressing142----------143 144The IPMI addressing works much like IP addresses, you have an overlay145to handle the different address types. The overlay is::146 147 struct ipmi_addr148 {149 int addr_type;150 short channel;151 char data[IPMI_MAX_ADDR_SIZE];152 };153 154The addr_type determines what the address really is. The driver155currently understands two different types of addresses.156 157"System Interface" addresses are defined as::158 159 struct ipmi_system_interface_addr160 {161 int addr_type;162 short channel;163 };164 165and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking166straight to the BMC on the current card. The channel must be167IPMI_BMC_CHANNEL.168 169Messages that are destined to go out on the IPMB bus going through the170BMC use the IPMI_IPMB_ADDR_TYPE address type. The format is::171 172 struct ipmi_ipmb_addr173 {174 int addr_type;175 short channel;176 unsigned char slave_addr;177 unsigned char lun;178 };179 180The "channel" here is generally zero, but some devices support more181than one channel, it corresponds to the channel as defined in the IPMI182spec.183 184There is also an IPMB direct address for a situation where the sender185is directly on an IPMB bus and doesn't have to go through the BMC.186You can send messages to a specific management controller (MC) on the187IPMB using the IPMI_IPMB_DIRECT_ADDR_TYPE with the following format::188 189 struct ipmi_ipmb_direct_addr190 {191 int addr_type;192 short channel;193 unsigned char slave_addr;194 unsigned char rq_lun;195 unsigned char rs_lun;196 };197 198The channel is always zero. You can also receive commands from other199MCs that you have registered to handle and respond to them, so you can200use this to implement a management controller on a bus..201 202Messages203--------204 205Messages are defined as::206 207 struct ipmi_msg208 {209 unsigned char netfn;210 unsigned char lun;211 unsigned char cmd;212 unsigned char *data;213 int data_len;214 };215 216The driver takes care of adding/stripping the header information. The217data portion is just the data to be send (do NOT put addressing info218here) or the response. Note that the completion code of a response is219the first item in "data", it is not stripped out because that is how220all the messages are defined in the spec (and thus makes counting the221offsets a little easier :-).222 223When using the IOCTL interface from userland, you must provide a block224of data for "data", fill it, and set data_len to the length of the225block of data, even when receiving messages. Otherwise the driver226will have no place to put the message.227 228Messages coming up from the message handler in kernelland will come in229as::230 231 struct ipmi_recv_msg232 {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 free245 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 about249 the size or existence of this, since it may change. */250 unsigned char msg_data[IPMI_MAX_MSG_LENGTH];251 };252 253You should look at the receive type and handle the message254appropriately.255 256 257The Upper Layer Interface (Message Handler)258-------------------------------------------259 260The upper layer of the interface provides the users with a consistent261view of the IPMI interfaces. It allows multiple SMI interfaces to be262addressed (because some boards actually have multiple BMCs on them)263and the user should not have to care what type of SMI is below them.264 265 266Watching For Interfaces267^^^^^^^^^^^^^^^^^^^^^^^268 269When your code comes up, the IPMI driver may or may not have detected270if IPMI devices exist. So you might have to defer your setup until271the device is detected, or you might be able to do it immediately.272To handle this, and to allow for discovery, you register an SMI273watcher with ipmi_smi_watcher_register() to iterate over interfaces274and tell you when they come and go.275 276 277Creating the User278^^^^^^^^^^^^^^^^^279 280To use the message handler, you must first create a user using281ipmi_create_user. The interface number specifies which SMI you want282to connect to, and you must supply callback functions to be called283when data comes in. The callback function can run at interrupt level,284so be careful using the callbacks. This also allows to you pass in a285piece of data, the handler_data, that will be passed back to you on286all calls.287 288Once you are done, call ipmi_destroy_user() to get rid of the user.289 290From userland, opening the device automatically creates a user, and291closing the device automatically destroys the user.292 293 294Messaging295^^^^^^^^^296 297To send a message from kernel-land, the ipmi_request_settime() call does298pretty much all message handling. Most of the parameter are299self-explanatory. However, it takes a "msgid" parameter. This is NOT300the sequence number of messages. It is simply a long value that is301passed back when the response for the message is returned. You may302use it for anything you like.303 304Responses come back in the function pointed to by the ipmi_recv_hndl305field of the "handler" that you passed in to ipmi_create_user().306Remember again, these may be running at interrupt level. Remember to307look at the receive type, too.308 309From userland, you fill out an ipmi_req_t structure and use the310IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select()311or poll() to wait for messages to come in. However, you cannot use312read() to get them, you must call the IPMICTL_RECEIVE_MSG with the313ipmi_recv_t structure to actually get the message. Remember that you314must supply a pointer to a block of data in the msg.data field, and315you must fill in the msg.data_len field with the size of the data.316This gives the receiver a place to actually put the message.317 318If the message cannot fit into the data you provide, you will get an319EMSGSIZE error and the driver will leave the data in the receive320queue. If you want to get it and have it truncate the message, us321the IPMICTL_RECEIVE_MSG_TRUNC ioctl.322 323When you send a command (which is defined by the lowest-order bit of324the netfn per the IPMI spec) on the IPMB bus, the driver will325automatically assign the sequence number to the command and save the326command. If the response is not receive in the IPMI-specified 5327seconds, it will generate a response automatically saying the command328timed out. If an unsolicited response comes in (if it was after 5329seconds, for instance), that response will be ignored.330 331In kernelland, after you receive a message and are done with it, you332MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note333that you should NEVER mess with the "done" field of a message, that is334required to properly clean up the message.335 336Note that when sending, there is an ipmi_request_supply_msgs() call337that lets you supply the smi and receive message. This is useful for338pieces of code that need to work even if the system is out of buffers339(the watchdog timer uses this, for instance). You supply your own340buffer and own free routines. This is not recommended for normal use,341though, since it is tricky to manage your own buffers.342 343 344Events and Incoming Commands345^^^^^^^^^^^^^^^^^^^^^^^^^^^^346 347The driver takes care of polling for IPMI events and receiving348commands (commands are messages that are not responses, they are349commands that other things on the IPMB bus have sent you). To receive350these, you must register for them, they will not automatically be sent351to you.352 353To receive events, you must call ipmi_set_gets_events() and set the354"val" to non-zero. Any events that have been received by the driver355since startup will immediately be delivered to the first user that356registers for events. After that, if multiple users are registered357for events, they will all receive all events that come in.358 359For receiving commands, you have to individually register commands you360want to receive. Call ipmi_register_for_cmd() and supply the netfn361and command name for each command you want to receive. You also362specify a bitmask of the channels you want to receive the command from363(or use IPMI_CHAN_ALL for all channels if you don't care). Only one364user may be registered for each netfn/cmd/channel, but different users365may register for different commands, or the same command if the366channel bitmasks do not overlap.367 368To respond to a received command, set the response bit in the returned369netfn, use the address from the received message, and use the same370msgid that you got in the receive message.371 372From userland, equivalent IOCTLs are provided to do these functions.373 374 375The Lower Layer (SMI) Interface376-------------------------------377 378As mentioned before, multiple SMI interfaces may be registered to the379message handler, each of these is assigned an interface number when380they register with the message handler. They are generally assigned381in the order they register, although if an SMI unregisters and then382another one registers, all bets are off.383 384The ipmi_smi.h defines the interface for management interfaces, see385that for more details.386 387 388The SI Driver389-------------390 391The SI driver allows KCS, BT, and SMIC interfaces to be configured392in the system. It discovers interfaces through a host of different393methods, depending on the system.394 395You can specify up to four interfaces on the module load line and396control some module parameters::397 398 modprobe ipmi_si.o type=<type1>,<type2>....399 ports=<port1>,<port2>... addrs=<addr1>,<addr2>...400 irqs=<irq1>,<irq2>...401 regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,...402 regshifts=<shift1>,<shift2>,...403 slave_addrs=<addr1>,<addr2>,...404 force_kipmid=<enable1>,<enable2>,...405 kipmid_max_busy_us=<ustime1>,<ustime2>,...406 unload_when_empty=[0|1]407 trydmi=[0|1] tryacpi=[0|1]408 tryplatform=[0|1] trypci=[0|1]409 410Each of these except try... items is a list, the first item for the411first interface, second item for the second interface, etc.412 413The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it414defaults to "kcs".415 416If you specify addrs as non-zero for an interface, the driver will417use the memory address given as the address of the device. This418overrides si_ports.419 420If you specify ports as non-zero for an interface, the driver will421use the I/O port given as the device address.422 423If you specify irqs as non-zero for an interface, the driver will424attempt to use the given interrupt for the device.425 426The other try... items disable discovery by their corresponding427names. These are all enabled by default, set them to zero to disable428them. The tryplatform disables openfirmware.429 430The next three parameters have to do with register layout. The431registers used by the interfaces may not appear at successive432locations and they may not be in 8-bit registers. These parameters433allow the layout of the data in the registers to be more precisely434specified.435 436The regspacings parameter give the number of bytes between successive437register start addresses. For instance, if the regspacing is set to 4438and the start address is 0xca2, then the address for the second439register would be 0xca6. This defaults to 1.440 441The regsizes parameter gives the size of a register, in bytes. The442data used by IPMI is 8-bits wide, but it may be inside a larger443register. This parameter allows the read and write type to specified.444It may be 1, 2, 4, or 8. The default is 1.445 446Since the register size may be larger than 32 bits, the IPMI data may not447be in the lower 8 bits. The regshifts parameter give the amount to shift448the data to get to the actual IPMI data.449 450The slave_addrs specifies the IPMI address of the local BMC. This is451usually 0x20 and the driver defaults to that, but in case it's not, it452can be specified when the driver starts up.453 454The force_ipmid parameter forcefully enables (if set to 1) or disables455(if set to 0) the kernel IPMI daemon. Normally this is auto-detected456by the driver, but systems with broken interrupts might need an enable,457or users that don't want the daemon (don't need the performance, don't458want the CPU hit) can disable it.459 460If unload_when_empty is set to 1, the driver will be unloaded if it461doesn't find any interfaces or all the interfaces fail to work. The462default is one. Setting to 0 is useful with the hotmod, but is463obviously only useful for modules.464 465When compiled into the kernel, the parameters can be specified on the466kernel command line as::467 468 ipmi_si.type=<type1>,<type2>...469 ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...470 ipmi_si.irqs=<irq1>,<irq2>...471 ipmi_si.regspacings=<sp1>,<sp2>,...472 ipmi_si.regsizes=<size1>,<size2>,...473 ipmi_si.regshifts=<shift1>,<shift2>,...474 ipmi_si.slave_addrs=<addr1>,<addr2>,...475 ipmi_si.force_kipmid=<enable1>,<enable2>,...476 ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,...477 478It works the same as the module parameters of the same names.479 480If your IPMI interface does not support interrupts and is a KCS or481SMIC interface, the IPMI driver will start a kernel thread for the482interface to help speed things up. This is a low-priority kernel483thread that constantly polls the IPMI driver while an IPMI operation484is in progress. The force_kipmid module parameter will all the user to485force this thread on or off. If you force it off and don't have486interrupts, the driver will run VERY slowly. Don't blame me,487these interfaces suck.488 489Unfortunately, this thread can use a lot of CPU depending on the490interface's performance. This can waste a lot of CPU and cause491various issues with detecting idle CPU and using extra power. To492avoid this, the kipmid_max_busy_us sets the maximum amount of time, in493microseconds, that kipmid will spin before sleeping for a tick. This494value sets a balance between performance and CPU waste and needs to be495tuned to your needs. Maybe, someday, auto-tuning will be added, but496that's not a simple thing and even the auto-tuning would need to be497tuned to the user's desired performance.498 499The driver supports a hot add and remove of interfaces. This way,500interfaces can be added or removed after the kernel is up and running.501This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a502write-only parameter. You write a string to this interface. The string503has the format::504 505 <op1>[:op2[:op3...]]506 507The "op"s are::508 509 add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]]510 511You can specify more than one interface on the line. The "opt"s are::512 513 rsp=<regspacing>514 rsi=<regsize>515 rsh=<regshift>516 irq=<irq>517 ipmb=<ipmb slave addr>518 519and these have the same meanings as discussed above. Note that you520can also use this on the kernel command line for a more compact format521for specifying an interface. Note that when removing an interface,522only the first three parameters (si type, address type, and address)523are used for the comparison. Any options are ignored for removing.524 525The SMBus Driver (SSIF)526-----------------------527 528The SMBus driver allows up to 4 SMBus devices to be configured in the529system. By default, the driver will only register with something it530finds in DMI or ACPI tables. You can change this531at module load time (for a module) with::532 533 modprobe ipmi_ssif.o534 addr=<i2caddr1>[,<i2caddr2>[,...]]535 adapter=<adapter1>[,<adapter2>[...]]536 dbg=<flags1>,<flags2>...537 slave_addrs=<addr1>,<addr2>,...538 tryacpi=[0|1] trydmi=[0|1]539 [dbg_probe=1]540 alerts_broken541 542The addresses are normal I2C addresses. The adapter is the string543name of the adapter, as shown in /sys/bus/i2c/devices/i2c-<n>/name.544It is *NOT* i2c-<n> itself. Also, the comparison is done ignoring545spaces, so if the name is "This is an I2C chip" you can say546adapter_name=ThisisanI2cchip. This is because it's hard to pass in547spaces in kernel parameters.548 549The debug flags are bit flags for each BMC found, they are:550IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8551 552The tryxxx parameters can be used to disable detecting interfaces553from various sources.554 555Setting dbg_probe to 1 will enable debugging of the probing and556detection process for BMCs on the SMBusses.557 558The slave_addrs specifies the IPMI address of the local BMC. This is559usually 0x20 and the driver defaults to that, but in case it's not, it560can be specified when the driver starts up.561 562alerts_broken does not enable SMBus alert for SSIF. Otherwise SMBus563alert will be enabled on supported hardware.564 565Discovering the IPMI compliant BMC on the SMBus can cause devices on566the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI567message as a block write to the I2C bus and waits for a response.568This action can be detrimental to some I2C devices. It is highly569recommended that the known I2C address be given to the SMBus driver in570the smb_addr parameter unless you have DMI or ACPI data to tell the571driver what to use.572 573When compiled into the kernel, the addresses can be specified on the574kernel command line as::575 576 ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]]577 ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]578 ipmi_ssif.dbg=<flags1>[,<flags2>[...]]579 ipmi_ssif.dbg_probe=1580 ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]581 ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1]582 583These are the same options as on the module command line.584 585The I2C driver does not support non-blocking access or polling, so586this driver cannod to IPMI panic events, extend the watchdog at panic587time, or other panic-related IPMI functions without special kernel588patches and driver modifications. You can get those at the openipmi589web page.590 591The driver supports a hot add and remove of interfaces through the I2C592sysfs interface.593 594The IPMI IPMB Driver595--------------------596 597This driver is for supporting a system that sits on an IPMB bus; it598allows the interface to look like a normal IPMI interface. Sending599system interface addressed messages to it will cause the message to go600to the registered BMC on the system (default at IPMI address 0x20).601 602It also allows you to directly address other MCs on the bus using the603ipmb direct addressing. You can receive commands from other MCs on604the bus and they will be handled through the normal received command605mechanism described above.606 607Parameters are::608 609 ipmi_ipmb.bmcaddr=<address to use for system interface addresses messages>610 ipmi_ipmb.retry_time_ms=<Time between retries on IPMB>611 ipmi_ipmb.max_retries=<Number of times to retry a message>612 613Loading the module will not result in the driver automatcially614starting unless there is device tree information setting it up. If615you want to instantiate one of these by hand, do::616 617 echo ipmi-ipmb <addr> > /sys/class/i2c-dev/i2c-<n>/device/new_device618 619Note that the address you give here is the I2C address, not the IPMI620address. So if you want your MC address to be 0x60, you put 0x30621here. See the I2C driver info for more details.622 623Command bridging to other IPMB busses through this interface does not624work. The receive message queue is not implemented, by design. There625is only one receive message queue on a BMC, and that is meant for the626host drivers, not something on the IPMB bus.627 628A BMC may have multiple IPMB busses, which bus your device sits on629depends on how the system is wired. You can fetch the channels with630"ipmitool channel info <n>" where <n> is the channel, with the631channels being 0-7 and try the IPMB channels.632 633Other Pieces634------------635 636Get the detailed info related with the IPMI device637--------------------------------------------------638 639Some users need more detailed information about a device, like where640the address came from or the raw base device for the IPMI interface.641You can use the IPMI smi_watcher to catch the IPMI interfaces as they642come or go, and to grab the information, you can use the function643ipmi_get_smi_info(), which returns the following structure::644 645 struct ipmi_smi_info {646 enum ipmi_addr_src addr_src;647 struct device *dev;648 union {649 struct {650 void *acpi_handle;651 } acpi_info;652 } addr_info;653 };654 655Currently special info for only for SI_ACPI address sources is656returned. Others may be added as necessary.657 658Note that the dev pointer is included in the above structure, and659assuming ipmi_smi_get_info returns success, you must call put_device660on the dev pointer.661 662 663Watchdog664--------665 666A watchdog timer is provided that implements the Linux-standard667watchdog timer interface. It has three module parameters that can be668used to control it::669 670 modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>671 preaction=<preaction type> preop=<preop type> start_now=x672 nowayout=x ifnum_to_use=n panic_wdt_timeout=<t>673 674ifnum_to_use specifies which interface the watchdog timer should use.675The default is -1, which means to pick the first one registered.676 677The timeout is the number of seconds to the action, and the pretimeout678is the amount of seconds before the reset that the pre-timeout panic will679occur (if pretimeout is zero, then pretimeout will not be enabled). Note680that the pretimeout is the time before the final timeout. So if the681timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout682will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout683is the value of timeout which is set on kernel panic, in order to let actions684such as kdump to occur during panic.685 686The action may be "reset", "power_cycle", or "power_off", and687specifies what to do when the timer times out, and defaults to688"reset".689 690The preaction may be "pre_smi" for an indication through the SMI691interface, "pre_int" for an indication through the SMI with an692interrupts, and "pre_nmi" for a NMI on a preaction. This is how693the driver is informed of the pretimeout.694 695The preop may be set to "preop_none" for no operation on a pretimeout,696"preop_panic" to set the preoperation to panic, or "preop_give_data"697to provide data to read from the watchdog device when the pretimeout698occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data"699because you can't do data operations from an NMI.700 701When preop is set to "preop_give_data", one byte comes ready to read702on the device when the pretimeout occurs. Select and fasync work on703the device, as well.704 705If start_now is set to 1, the watchdog timer will start running as706soon as the driver is loaded.707 708If nowayout is set to 1, the watchdog timer will not stop when the709watchdog device is closed. The default value of nowayout is true710if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.711 712When compiled into the kernel, the kernel command line is available713for configuring the watchdog::714 715 ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>716 ipmi_watchdog.action=<action type>717 ipmi_watchdog.preaction=<preaction type>718 ipmi_watchdog.preop=<preop type>719 ipmi_watchdog.start_now=x720 ipmi_watchdog.nowayout=x721 ipmi_watchdog.panic_wdt_timeout=<t>722 723The options are the same as the module parameter options.724 725The watchdog will panic and start a 120 second reset timeout if it726gets a pre-action. During a panic or a reboot, the watchdog will727start a 120 timer if it is running to make sure the reboot occurs.728 729Note that if you use the NMI preaction for the watchdog, you MUST NOT730use the nmi watchdog. There is no reasonable way to tell if an NMI731comes from the IPMI controller, so it must assume that if it gets an732otherwise unhandled NMI, it must be from IPMI and it will panic733immediately.734 735Once you open the watchdog timer, you must write a 'V' character to the736device to close it, or the timer will not stop. This is a new semantic737for the driver, but makes it consistent with the rest of the watchdog738drivers in Linux.739 740 741Panic Timeouts742--------------743 744The OpenIPMI driver supports the ability to put semi-custom and custom745events in the system event log if a panic occurs. if you enable the746'Generate a panic event to all BMCs on a panic' option, you will get747one event on a panic in a standard IPMI event format. If you enable748the 'Generate OEM events containing the panic string' option, you will749also get a bunch of OEM events holding the panic string.750 751 752The field settings of the events are:753 754* Generator ID: 0x21 (kernel)755* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)756* Sensor Type: 0x20 (OS critical stop sensor)757* Sensor #: The first byte of the panic string (0 if no panic string)758* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info)759* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)760* Event data 2: second byte of panic string761* Event data 3: third byte of panic string762 763See the IPMI spec for the details of the event layout. This event is764always sent to the local management controller. It will handle routing765the message to the right place766 767Other OEM events have the following format:768 769* Record ID (bytes 0-1): Set by the SEL.770* Record type (byte 2): 0xf0 (OEM non-timestamped)771* byte 3: The slave address of the card saving the panic772* byte 4: A sequence number (starting at zero)773 The rest of the bytes (11 bytes) are the panic string. If the panic string774 is longer than 11 bytes, multiple messages will be sent with increasing775 sequence numbers.776 777Because you cannot send OEM events using the standard interface, this778function will attempt to find an SEL and add the events there. It779will first query the capabilities of the local management controller.780If it has an SEL, then they will be stored in the SEL of the local781management controller. If not, and the local management controller is782an event generator, the event receiver from the local management783controller will be queried and the events sent to the SEL on that784device. Otherwise, the events go nowhere since there is nowhere to785send them.786 787 788Poweroff789--------790 791If the poweroff capability is selected, the IPMI driver will install792a shutdown function into the standard poweroff function pointer. This793is in the ipmi_poweroff module. When the system requests a powerdown,794it will send the proper IPMI commands to do this. This is supported on795several platforms.796 797There is a module parameter named "poweroff_powercycle" that may798either be zero (do a power down) or non-zero (do a power cycle, power799the system off, then power it on in a few seconds). Setting800ipmi_poweroff.poweroff_control=x will do the same thing on the kernel801command line. The parameter is also available via the proc filesystem802in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system803does not support power cycling, it will always do the power off.804 805The "ifnum_to_use" parameter specifies which interface the poweroff806code should use. The default is -1, which means to pick the first one807registered.808 809Note that if you have ACPI enabled, the system will prefer using ACPI to810power off.811