Back to home page

LXR

 
 

    


0001 
0002                           The Linux IPMI Driver
0003                           ---------------------
0004                               Corey Minyard
0005                           <minyard@mvista.com>
0006                             <minyard@acm.org>
0007 
0008 The Intelligent Platform Management Interface, or IPMI, is a
0009 standard for controlling intelligent devices that monitor a system.
0010 It provides for dynamic discovery of sensors in the system and the
0011 ability to monitor the sensors and be informed when the sensor's
0012 values change or go outside certain boundaries.  It also has a
0013 standardized database for field-replaceable units (FRUs) and a watchdog
0014 timer.
0015 
0016 To use this, you need an interface to an IPMI controller in your
0017 system (called a Baseboard Management Controller, or BMC) and
0018 management software that can use the IPMI system.
0019 
0020 This document describes how to use the IPMI driver for Linux.  If you
0021 are not familiar with IPMI itself, see the web site at
0022 http://www.intel.com/design/servers/ipmi/index.htm.  IPMI is a big
0023 subject and I can't cover it all here!
0024 
0025 Configuration
0026 -------------
0027 
0028 The Linux IPMI driver is modular, which means you have to pick several
0029 things to have it work right depending on your hardware.  Most of
0030 these are available in the 'Character Devices' menu then the IPMI
0031 menu.
0032 
0033 No matter what, you must pick 'IPMI top-level message handler' to use
0034 IPMI.  What you do beyond that depends on your needs and hardware.
0035 
0036 The message handler does not provide any user-level interfaces.
0037 Kernel code (like the watchdog) can still use it.  If you need access
0038 from userland, you need to select 'Device interface for IPMI' if you
0039 want access through a device driver.
0040 
0041 The driver interface depends on your hardware.  If your system
0042 properly provides the SMBIOS info for IPMI, the driver will detect it
0043 and just work.  If you have a board with a standard interface (These
0044 will generally be either "KCS", "SMIC", or "BT", consult your hardware
0045 manual), choose the 'IPMI SI handler' option.  A driver also exists
0046 for direct I2C access to the IPMI management controller.  Some boards
0047 support this, but it is unknown if it will work on every board.  For
0048 this, choose 'IPMI SMBus handler', but be ready to try to do some
0049 figuring to see if it will work on your system if the SMBIOS/APCI
0050 information is wrong or not present.  It is fairly safe to have both
0051 these enabled and let the drivers auto-detect what is present.
0052 
0053 You should generally enable ACPI on your system, as systems with IPMI
0054 can have ACPI tables describing them.
0055 
0056 If you have a standard interface and the board manufacturer has done
0057 their job correctly, the IPMI controller should be automatically
0058 detected (via ACPI or SMBIOS tables) and should just work.  Sadly,
0059 many boards do not have this information.  The driver attempts
0060 standard defaults, but they may not work.  If you fall into this
0061 situation, you need to read the section below named 'The SI Driver' or
0062 "The SMBus Driver" on how to hand-configure your system.
0063 
0064 IPMI defines a standard watchdog timer.  You can enable this with the
0065 'IPMI Watchdog Timer' config option.  If you compile the driver into
0066 the kernel, then via a kernel command-line option you can have the
0067 watchdog timer start as soon as it initializes.  It also have a lot
0068 of other options, see the 'Watchdog' section below for more details.
0069 Note that you can also have the watchdog continue to run if it is
0070 closed (by default it is disabled on close).  Go into the 'Watchdog
0071 Cards' menu, enable 'Watchdog Timer Support', and enable the option
0072 'Disable watchdog shutdown on close'.
0073 
0074 IPMI systems can often be powered off using IPMI commands.  Select
0075 'IPMI Poweroff' to do this.  The driver will auto-detect if the system
0076 can be powered off by IPMI.  It is safe to enable this even if your
0077 system doesn't support this option.  This works on ATCA systems, the
0078 Radisys CPI1 card, and any IPMI system that supports standard chassis
0079 management commands.
0080 
0081 If you want the driver to put an event into the event log on a panic,
0082 enable the 'Generate a panic event to all BMCs on a panic' option.  If
0083 you want the whole panic string put into the event log using OEM
0084 events, enable the 'Generate OEM events containing the panic string'
0085 option.
0086 
0087 Basic Design
0088 ------------
0089 
0090 The Linux IPMI driver is designed to be very modular and flexible, you
0091 only need to take the pieces you need and you can use it in many
0092 different ways.  Because of that, it's broken into many chunks of
0093 code.  These chunks (by module name) are:
0094 
0095 ipmi_msghandler - This is the central piece of software for the IPMI
0096 system.  It handles all messages, message timing, and responses.  The
0097 IPMI users tie into this, and the IPMI physical interfaces (called
0098 System Management Interfaces, or SMIs) also tie in here.  This
0099 provides the kernelland interface for IPMI, but does not provide an
0100 interface for use by application processes.
0101 
0102 ipmi_devintf - This provides a userland IOCTL interface for the IPMI
0103 driver, each open file for this device ties in to the message handler
0104 as an IPMI user.
0105 
0106 ipmi_si - A driver for various system interfaces.  This supports KCS,
0107 SMIC, and BT interfaces.  Unless you have an SMBus interface or your
0108 own custom interface, you probably need to use this.
0109 
0110 ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the
0111 I2C kernel driver's SMBus interfaces to send and receive IPMI messages
0112 over the SMBus.
0113 
0114 ipmi_powernv - A driver for access BMCs on POWERNV systems.
0115 
0116 ipmi_watchdog - IPMI requires systems to have a very capable watchdog
0117 timer.  This driver implements the standard Linux watchdog timer
0118 interface on top of the IPMI message handler.
0119 
0120 ipmi_poweroff - Some systems support the ability to be turned off via
0121 IPMI commands.
0122 
0123 bt-bmc - This is not part of the main driver, but instead a driver for
0124 accessing a BMC-side interface of a BT interface.  It is used on BMCs
0125 running Linux to provide an interface to the host.
0126 
0127 These are all individually selectable via configuration options.
0128 
0129 Much documentation for the interface is in the include files.  The
0130 IPMI include files are:
0131 
0132 linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
0133 
0134 linux/ipmi_smi.h - Contains the interface for system management interfaces
0135 (things that interface to IPMI controllers) to use.
0136 
0137 linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.
0138 
0139 
0140 Addressing
0141 ----------
0142 
0143 The IPMI addressing works much like IP addresses, you have an overlay
0144 to handle the different address types.  The overlay is:
0145 
0146   struct ipmi_addr
0147   {
0148         int   addr_type;
0149         short channel;
0150         char  data[IPMI_MAX_ADDR_SIZE];
0151   };
0152 
0153 The addr_type determines what the address really is.  The driver
0154 currently understands two different types of addresses.
0155 
0156 "System Interface" addresses are defined as:
0157 
0158   struct ipmi_system_interface_addr
0159   {
0160         int   addr_type;
0161         short channel;
0162   };
0163 
0164 and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE.  This is used for talking
0165 straight to the BMC on the current card.  The channel must be
0166 IPMI_BMC_CHANNEL.
0167 
0168 Messages that are destined to go out on the IPMB bus use the
0169 IPMI_IPMB_ADDR_TYPE address type.  The format is
0170 
0171   struct ipmi_ipmb_addr
0172   {
0173         int           addr_type;
0174         short         channel;
0175         unsigned char slave_addr;
0176         unsigned char lun;
0177   };
0178 
0179 The "channel" here is generally zero, but some devices support more
0180 than one channel, it corresponds to the channel as defined in the IPMI
0181 spec.
0182 
0183 
0184 Messages
0185 --------
0186 
0187 Messages are defined as:
0188 
0189 struct ipmi_msg
0190 {
0191         unsigned char netfn;
0192         unsigned char lun;
0193         unsigned char cmd;
0194         unsigned char *data;
0195         int           data_len;
0196 };
0197 
0198 The driver takes care of adding/stripping the header information.  The
0199 data portion is just the data to be send (do NOT put addressing info
0200 here) or the response.  Note that the completion code of a response is
0201 the first item in "data", it is not stripped out because that is how
0202 all the messages are defined in the spec (and thus makes counting the
0203 offsets a little easier :-).
0204 
0205 When using the IOCTL interface from userland, you must provide a block
0206 of data for "data", fill it, and set data_len to the length of the
0207 block of data, even when receiving messages.  Otherwise the driver
0208 will have no place to put the message.
0209 
0210 Messages coming up from the message handler in kernelland will come in
0211 as:
0212 
0213   struct ipmi_recv_msg
0214   {
0215         struct list_head link;
0216 
0217         /* The type of message as defined in the "Receive Types"
0218            defines above. */
0219         int         recv_type;
0220 
0221         ipmi_user_t      *user;
0222         struct ipmi_addr addr;
0223         long             msgid;
0224         struct ipmi_msg  msg;
0225 
0226         /* Call this when done with the message.  It will presumably free
0227            the message and do any other necessary cleanup. */
0228         void (*done)(struct ipmi_recv_msg *msg);
0229 
0230         /* Place-holder for the data, don't make any assumptions about
0231            the size or existence of this, since it may change. */
0232         unsigned char   msg_data[IPMI_MAX_MSG_LENGTH];
0233   };
0234 
0235 You should look at the receive type and handle the message
0236 appropriately.
0237 
0238 
0239 The Upper Layer Interface (Message Handler)
0240 -------------------------------------------
0241 
0242 The upper layer of the interface provides the users with a consistent
0243 view of the IPMI interfaces.  It allows multiple SMI interfaces to be
0244 addressed (because some boards actually have multiple BMCs on them)
0245 and the user should not have to care what type of SMI is below them.
0246 
0247 
0248 Watching For Interfaces
0249 
0250 When your code comes up, the IPMI driver may or may not have detected
0251 if IPMI devices exist.  So you might have to defer your setup until
0252 the device is detected, or you might be able to do it immediately.
0253 To handle this, and to allow for discovery, you register an SMI
0254 watcher with ipmi_smi_watcher_register() to iterate over interfaces
0255 and tell you when they come and go.
0256 
0257 
0258 Creating the User
0259 
0260 To user the message handler, you must first create a user using
0261 ipmi_create_user.  The interface number specifies which SMI you want
0262 to connect to, and you must supply callback functions to be called
0263 when data comes in.  The callback function can run at interrupt level,
0264 so be careful using the callbacks.  This also allows to you pass in a
0265 piece of data, the handler_data, that will be passed back to you on
0266 all calls.
0267 
0268 Once you are done, call ipmi_destroy_user() to get rid of the user.
0269 
0270 From userland, opening the device automatically creates a user, and
0271 closing the device automatically destroys the user.
0272 
0273 
0274 Messaging
0275 
0276 To send a message from kernel-land, the ipmi_request_settime() call does
0277 pretty much all message handling.  Most of the parameter are
0278 self-explanatory.  However, it takes a "msgid" parameter.  This is NOT
0279 the sequence number of messages.  It is simply a long value that is
0280 passed back when the response for the message is returned.  You may
0281 use it for anything you like.
0282 
0283 Responses come back in the function pointed to by the ipmi_recv_hndl
0284 field of the "handler" that you passed in to ipmi_create_user().
0285 Remember again, these may be running at interrupt level.  Remember to
0286 look at the receive type, too.
0287 
0288 From userland, you fill out an ipmi_req_t structure and use the
0289 IPMICTL_SEND_COMMAND ioctl.  For incoming stuff, you can use select()
0290 or poll() to wait for messages to come in.  However, you cannot use
0291 read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
0292 ipmi_recv_t structure to actually get the message.  Remember that you
0293 must supply a pointer to a block of data in the msg.data field, and
0294 you must fill in the msg.data_len field with the size of the data.
0295 This gives the receiver a place to actually put the message.
0296 
0297 If the message cannot fit into the data you provide, you will get an
0298 EMSGSIZE error and the driver will leave the data in the receive
0299 queue.  If you want to get it and have it truncate the message, us
0300 the IPMICTL_RECEIVE_MSG_TRUNC ioctl.
0301 
0302 When you send a command (which is defined by the lowest-order bit of
0303 the netfn per the IPMI spec) on the IPMB bus, the driver will
0304 automatically assign the sequence number to the command and save the
0305 command.  If the response is not receive in the IPMI-specified 5
0306 seconds, it will generate a response automatically saying the command
0307 timed out.  If an unsolicited response comes in (if it was after 5
0308 seconds, for instance), that response will be ignored.
0309 
0310 In kernelland, after you receive a message and are done with it, you
0311 MUST call ipmi_free_recv_msg() on it, or you will leak messages.  Note
0312 that you should NEVER mess with the "done" field of a message, that is
0313 required to properly clean up the message.
0314 
0315 Note that when sending, there is an ipmi_request_supply_msgs() call
0316 that lets you supply the smi and receive message.  This is useful for
0317 pieces of code that need to work even if the system is out of buffers
0318 (the watchdog timer uses this, for instance).  You supply your own
0319 buffer and own free routines.  This is not recommended for normal use,
0320 though, since it is tricky to manage your own buffers.
0321 
0322 
0323 Events and Incoming Commands
0324 
0325 The driver takes care of polling for IPMI events and receiving
0326 commands (commands are messages that are not responses, they are
0327 commands that other things on the IPMB bus have sent you).  To receive
0328 these, you must register for them, they will not automatically be sent
0329 to you.
0330 
0331 To receive events, you must call ipmi_set_gets_events() and set the
0332 "val" to non-zero.  Any events that have been received by the driver
0333 since startup will immediately be delivered to the first user that
0334 registers for events.  After that, if multiple users are registered
0335 for events, they will all receive all events that come in.
0336 
0337 For receiving commands, you have to individually register commands you
0338 want to receive.  Call ipmi_register_for_cmd() and supply the netfn
0339 and command name for each command you want to receive.  You also
0340 specify a bitmask of the channels you want to receive the command from
0341 (or use IPMI_CHAN_ALL for all channels if you don't care).  Only one
0342 user may be registered for each netfn/cmd/channel, but different users
0343 may register for different commands, or the same command if the
0344 channel bitmasks do not overlap.
0345 
0346 From userland, equivalent IOCTLs are provided to do these functions.
0347 
0348 
0349 The Lower Layer (SMI) Interface
0350 -------------------------------
0351 
0352 As mentioned before, multiple SMI interfaces may be registered to the
0353 message handler, each of these is assigned an interface number when
0354 they register with the message handler.  They are generally assigned
0355 in the order they register, although if an SMI unregisters and then
0356 another one registers, all bets are off.
0357 
0358 The ipmi_smi.h defines the interface for management interfaces, see
0359 that for more details.
0360 
0361 
0362 The SI Driver
0363 -------------
0364 
0365 The SI driver allows KCS, BT, and SMIC interfaces to be configured
0366 in the system.  It discovers interfaces through a host of different
0367 methods, depending on the system.
0368 
0369 You can specify up to four interfaces on the module load line and
0370 control some module parameters:
0371 
0372   modprobe ipmi_si.o type=<type1>,<type2>....
0373        ports=<port1>,<port2>... addrs=<addr1>,<addr2>...
0374        irqs=<irq1>,<irq2>...
0375        regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,...
0376        regshifts=<shift1>,<shift2>,...
0377        slave_addrs=<addr1>,<addr2>,...
0378        force_kipmid=<enable1>,<enable2>,...
0379        kipmid_max_busy_us=<ustime1>,<ustime2>,...
0380        unload_when_empty=[0|1]
0381        trydmi=[0|1] tryacpi=[0|1]
0382        tryplatform=[0|1] trypci=[0|1]
0383 
0384 Each of these except try... items is a list, the first item for the
0385 first interface, second item for the second interface, etc.
0386 
0387 The si_type may be either "kcs", "smic", or "bt".  If you leave it blank, it
0388 defaults to "kcs".
0389 
0390 If you specify addrs as non-zero for an interface, the driver will
0391 use the memory address given as the address of the device.  This
0392 overrides si_ports.
0393 
0394 If you specify ports as non-zero for an interface, the driver will
0395 use the I/O port given as the device address.
0396 
0397 If you specify irqs as non-zero for an interface, the driver will
0398 attempt to use the given interrupt for the device.
0399 
0400 The other try... items disable discovery by their corresponding
0401 names.  These are all enabled by default, set them to zero to disable
0402 them.  The tryplatform disables openfirmware.
0403 
0404 The next three parameters have to do with register layout.  The
0405 registers used by the interfaces may not appear at successive
0406 locations and they may not be in 8-bit registers.  These parameters
0407 allow the layout of the data in the registers to be more precisely
0408 specified.
0409 
0410 The regspacings parameter give the number of bytes between successive
0411 register start addresses.  For instance, if the regspacing is set to 4
0412 and the start address is 0xca2, then the address for the second
0413 register would be 0xca6.  This defaults to 1.
0414 
0415 The regsizes parameter gives the size of a register, in bytes.  The
0416 data used by IPMI is 8-bits wide, but it may be inside a larger
0417 register.  This parameter allows the read and write type to specified.
0418 It may be 1, 2, 4, or 8.  The default is 1.
0419 
0420 Since the register size may be larger than 32 bits, the IPMI data may not
0421 be in the lower 8 bits.  The regshifts parameter give the amount to shift
0422 the data to get to the actual IPMI data.
0423 
0424 The slave_addrs specifies the IPMI address of the local BMC.  This is
0425 usually 0x20 and the driver defaults to that, but in case it's not, it
0426 can be specified when the driver starts up.
0427 
0428 The force_ipmid parameter forcefully enables (if set to 1) or disables
0429 (if set to 0) the kernel IPMI daemon.  Normally this is auto-detected
0430 by the driver, but systems with broken interrupts might need an enable,
0431 or users that don't want the daemon (don't need the performance, don't
0432 want the CPU hit) can disable it.
0433 
0434 If unload_when_empty is set to 1, the driver will be unloaded if it
0435 doesn't find any interfaces or all the interfaces fail to work.  The
0436 default is one.  Setting to 0 is useful with the hotmod, but is
0437 obviously only useful for modules.
0438 
0439 When compiled into the kernel, the parameters can be specified on the
0440 kernel command line as:
0441 
0442   ipmi_si.type=<type1>,<type2>...
0443        ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
0444        ipmi_si.irqs=<irq1>,<irq2>...
0445        ipmi_si.regspacings=<sp1>,<sp2>,...
0446        ipmi_si.regsizes=<size1>,<size2>,...
0447        ipmi_si.regshifts=<shift1>,<shift2>,...
0448        ipmi_si.slave_addrs=<addr1>,<addr2>,...
0449        ipmi_si.force_kipmid=<enable1>,<enable2>,...
0450        ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,...
0451 
0452 It works the same as the module parameters of the same names.
0453 
0454 If your IPMI interface does not support interrupts and is a KCS or
0455 SMIC interface, the IPMI driver will start a kernel thread for the
0456 interface to help speed things up.  This is a low-priority kernel
0457 thread that constantly polls the IPMI driver while an IPMI operation
0458 is in progress.  The force_kipmid module parameter will all the user to
0459 force this thread on or off.  If you force it off and don't have
0460 interrupts, the driver will run VERY slowly.  Don't blame me,
0461 these interfaces suck.
0462 
0463 Unfortunately, this thread can use a lot of CPU depending on the
0464 interface's performance.  This can waste a lot of CPU and cause
0465 various issues with detecting idle CPU and using extra power.  To
0466 avoid this, the kipmid_max_busy_us sets the maximum amount of time, in
0467 microseconds, that kipmid will spin before sleeping for a tick.  This
0468 value sets a balance between performance and CPU waste and needs to be
0469 tuned to your needs.  Maybe, someday, auto-tuning will be added, but
0470 that's not a simple thing and even the auto-tuning would need to be
0471 tuned to the user's desired performance.
0472 
0473 The driver supports a hot add and remove of interfaces.  This way,
0474 interfaces can be added or removed after the kernel is up and running.
0475 This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a
0476 write-only parameter.  You write a string to this interface.  The string
0477 has the format:
0478    <op1>[:op2[:op3...]]
0479 The "op"s are:
0480    add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]]
0481 You can specify more than one interface on the line.  The "opt"s are:
0482    rsp=<regspacing>
0483    rsi=<regsize>
0484    rsh=<regshift>
0485    irq=<irq>
0486    ipmb=<ipmb slave addr>
0487 and these have the same meanings as discussed above.  Note that you
0488 can also use this on the kernel command line for a more compact format
0489 for specifying an interface.  Note that when removing an interface,
0490 only the first three parameters (si type, address type, and address)
0491 are used for the comparison.  Any options are ignored for removing.
0492 
0493 The SMBus Driver (SSIF)
0494 -----------------------
0495 
0496 The SMBus driver allows up to 4 SMBus devices to be configured in the
0497 system.  By default, the driver will only register with something it
0498 finds in DMI or ACPI tables.  You can change this
0499 at module load time (for a module) with:
0500 
0501   modprobe ipmi_ssif.o
0502         addr=<i2caddr1>[,<i2caddr2>[,...]]
0503         adapter=<adapter1>[,<adapter2>[...]]
0504         dbg=<flags1>,<flags2>...
0505         slave_addrs=<addr1>,<addr2>,...
0506         tryacpi=[0|1] trydmi=[0|1]
0507         [dbg_probe=1]
0508 
0509 The addresses are normal I2C addresses.  The adapter is the string
0510 name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name.
0511 It is *NOT* i2c-<n> itself.  Also, the comparison is done ignoring
0512 spaces, so if the name is "This is an I2C chip" you can say
0513 adapter_name=ThisisanI2cchip.  This is because it's hard to pass in
0514 spaces in kernel parameters.
0515 
0516 The debug flags are bit flags for each BMC found, they are:
0517 IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8
0518 
0519 The tryxxx parameters can be used to disable detecting interfaces
0520 from various sources.
0521 
0522 Setting dbg_probe to 1 will enable debugging of the probing and
0523 detection process for BMCs on the SMBusses.
0524 
0525 The slave_addrs specifies the IPMI address of the local BMC.  This is
0526 usually 0x20 and the driver defaults to that, but in case it's not, it
0527 can be specified when the driver starts up.
0528 
0529 Discovering the IPMI compliant BMC on the SMBus can cause devices on
0530 the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI
0531 message as a block write to the I2C bus and waits for a response.
0532 This action can be detrimental to some I2C devices. It is highly
0533 recommended that the known I2C address be given to the SMBus driver in
0534 the smb_addr parameter unless you have DMI or ACPI data to tell the
0535 driver what to use.
0536 
0537 When compiled into the kernel, the addresses can be specified on the
0538 kernel command line as:
0539 
0540   ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]]
0541         ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]
0542         ipmi_ssif.dbg=<flags1>[,<flags2>[...]]
0543         ipmi_ssif.dbg_probe=1
0544         ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]
0545         ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1]
0546 
0547 These are the same options as on the module command line.
0548 
0549 The I2C driver does not support non-blocking access or polling, so
0550 this driver cannod to IPMI panic events, extend the watchdog at panic
0551 time, or other panic-related IPMI functions without special kernel
0552 patches and driver modifications.  You can get those at the openipmi
0553 web page.
0554 
0555 The driver supports a hot add and remove of interfaces through the I2C
0556 sysfs interface.
0557 
0558 Other Pieces
0559 ------------
0560 
0561 Get the detailed info related with the IPMI device
0562 --------------------------------------------------
0563 
0564 Some users need more detailed information about a device, like where
0565 the address came from or the raw base device for the IPMI interface.
0566 You can use the IPMI smi_watcher to catch the IPMI interfaces as they
0567 come or go, and to grab the information, you can use the function
0568 ipmi_get_smi_info(), which returns the following structure:
0569 
0570 struct ipmi_smi_info {
0571         enum ipmi_addr_src addr_src;
0572         struct device *dev;
0573         union {
0574                 struct {
0575                         void *acpi_handle;
0576                 } acpi_info;
0577         } addr_info;
0578 };
0579 
0580 Currently special info for only for SI_ACPI address sources is
0581 returned.  Others may be added as necessary.
0582 
0583 Note that the dev pointer is included in the above structure, and
0584 assuming ipmi_smi_get_info returns success, you must call put_device
0585 on the dev pointer.
0586 
0587 
0588 Watchdog
0589 --------
0590 
0591 A watchdog timer is provided that implements the Linux-standard
0592 watchdog timer interface.  It has three module parameters that can be
0593 used to control it:
0594 
0595   modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
0596       preaction=<preaction type> preop=<preop type> start_now=x
0597       nowayout=x ifnum_to_use=n panic_wdt_timeout=<t>
0598 
0599 ifnum_to_use specifies which interface the watchdog timer should use.
0600 The default is -1, which means to pick the first one registered.
0601 
0602 The timeout is the number of seconds to the action, and the pretimeout
0603 is the amount of seconds before the reset that the pre-timeout panic will
0604 occur (if pretimeout is zero, then pretimeout will not be enabled).  Note
0605 that the pretimeout is the time before the final timeout.  So if the
0606 timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout
0607 will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout
0608 is the value of timeout which is set on kernel panic, in order to let actions
0609 such as kdump to occur during panic.
0610 
0611 The action may be "reset", "power_cycle", or "power_off", and
0612 specifies what to do when the timer times out, and defaults to
0613 "reset".
0614 
0615 The preaction may be "pre_smi" for an indication through the SMI
0616 interface, "pre_int" for an indication through the SMI with an
0617 interrupts, and "pre_nmi" for a NMI on a preaction.  This is how
0618 the driver is informed of the pretimeout.
0619 
0620 The preop may be set to "preop_none" for no operation on a pretimeout,
0621 "preop_panic" to set the preoperation to panic, or "preop_give_data"
0622 to provide data to read from the watchdog device when the pretimeout
0623 occurs.  A "pre_nmi" setting CANNOT be used with "preop_give_data"
0624 because you can't do data operations from an NMI.
0625 
0626 When preop is set to "preop_give_data", one byte comes ready to read
0627 on the device when the pretimeout occurs.  Select and fasync work on
0628 the device, as well.
0629 
0630 If start_now is set to 1, the watchdog timer will start running as
0631 soon as the driver is loaded.
0632 
0633 If nowayout is set to 1, the watchdog timer will not stop when the
0634 watchdog device is closed.  The default value of nowayout is true
0635 if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.
0636 
0637 When compiled into the kernel, the kernel command line is available
0638 for configuring the watchdog:
0639 
0640   ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>
0641         ipmi_watchdog.action=<action type>
0642         ipmi_watchdog.preaction=<preaction type>
0643         ipmi_watchdog.preop=<preop type>
0644         ipmi_watchdog.start_now=x
0645         ipmi_watchdog.nowayout=x
0646         ipmi_watchdog.panic_wdt_timeout=<t>
0647 
0648 The options are the same as the module parameter options.
0649 
0650 The watchdog will panic and start a 120 second reset timeout if it
0651 gets a pre-action.  During a panic or a reboot, the watchdog will
0652 start a 120 timer if it is running to make sure the reboot occurs.
0653 
0654 Note that if you use the NMI preaction for the watchdog, you MUST NOT
0655 use the nmi watchdog.  There is no reasonable way to tell if an NMI
0656 comes from the IPMI controller, so it must assume that if it gets an
0657 otherwise unhandled NMI, it must be from IPMI and it will panic
0658 immediately.
0659 
0660 Once you open the watchdog timer, you must write a 'V' character to the
0661 device to close it, or the timer will not stop.  This is a new semantic
0662 for the driver, but makes it consistent with the rest of the watchdog
0663 drivers in Linux.
0664 
0665 
0666 Panic Timeouts
0667 --------------
0668 
0669 The OpenIPMI driver supports the ability to put semi-custom and custom
0670 events in the system event log if a panic occurs.  if you enable the
0671 'Generate a panic event to all BMCs on a panic' option, you will get
0672 one event on a panic in a standard IPMI event format.  If you enable
0673 the 'Generate OEM events containing the panic string' option, you will
0674 also get a bunch of OEM events holding the panic string.
0675 
0676 
0677 The field settings of the events are:
0678 * Generator ID: 0x21 (kernel)
0679 * EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)
0680 * Sensor Type: 0x20 (OS critical stop sensor)
0681 * Sensor #: The first byte of the panic string (0 if no panic string)
0682 * Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info)
0683 * Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)
0684 * Event data 2: second byte of panic string
0685 * Event data 3: third byte of panic string
0686 See the IPMI spec for the details of the event layout.  This event is
0687 always sent to the local management controller.  It will handle routing
0688 the message to the right place
0689 
0690 Other OEM events have the following format:
0691 Record ID (bytes 0-1): Set by the SEL.
0692 Record type (byte 2): 0xf0 (OEM non-timestamped)
0693 byte 3: The slave address of the card saving the panic
0694 byte 4: A sequence number (starting at zero)
0695 The rest of the bytes (11 bytes) are the panic string.  If the panic string
0696 is longer than 11 bytes, multiple messages will be sent with increasing
0697 sequence numbers.
0698 
0699 Because you cannot send OEM events using the standard interface, this
0700 function will attempt to find an SEL and add the events there.  It
0701 will first query the capabilities of the local management controller.
0702 If it has an SEL, then they will be stored in the SEL of the local
0703 management controller.  If not, and the local management controller is
0704 an event generator, the event receiver from the local management
0705 controller will be queried and the events sent to the SEL on that
0706 device.  Otherwise, the events go nowhere since there is nowhere to
0707 send them.
0708 
0709 
0710 Poweroff
0711 --------
0712 
0713 If the poweroff capability is selected, the IPMI driver will install
0714 a shutdown function into the standard poweroff function pointer.  This
0715 is in the ipmi_poweroff module.  When the system requests a powerdown,
0716 it will send the proper IPMI commands to do this.  This is supported on
0717 several platforms.
0718 
0719 There is a module parameter named "poweroff_powercycle" that may
0720 either be zero (do a power down) or non-zero (do a power cycle, power
0721 the system off, then power it on in a few seconds).  Setting
0722 ipmi_poweroff.poweroff_control=x will do the same thing on the kernel
0723 command line.  The parameter is also available via the proc filesystem
0724 in /proc/sys/dev/ipmi/poweroff_powercycle.  Note that if the system
0725 does not support power cycling, it will always do the power off.
0726 
0727 The "ifnum_to_use" parameter specifies which interface the poweroff
0728 code should use.  The default is -1, which means to pick the first one
0729 registered.
0730 
0731 Note that if you have ACPI enabled, the system will prefer using ACPI to
0732 power off.