annotate Documentation/IPMI.txt @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
rev   line source
ian@0 1
ian@0 2 The Linux IPMI Driver
ian@0 3 ---------------------
ian@0 4 Corey Minyard
ian@0 5 <minyard@mvista.com>
ian@0 6 <minyard@acm.org>
ian@0 7
ian@0 8 The Intelligent Platform Management Interface, or IPMI, is a
ian@0 9 standard for controlling intelligent devices that monitor a system.
ian@0 10 It provides for dynamic discovery of sensors in the system and the
ian@0 11 ability to monitor the sensors and be informed when the sensor's
ian@0 12 values change or go outside certain boundaries. It also has a
ian@0 13 standardized database for field-replaceable units (FRUs) and a watchdog
ian@0 14 timer.
ian@0 15
ian@0 16 To use this, you need an interface to an IPMI controller in your
ian@0 17 system (called a Baseboard Management Controller, or BMC) and
ian@0 18 management software that can use the IPMI system.
ian@0 19
ian@0 20 This document describes how to use the IPMI driver for Linux. If you
ian@0 21 are not familiar with IPMI itself, see the web site at
ian@0 22 http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
ian@0 23 subject and I can't cover it all here!
ian@0 24
ian@0 25 Configuration
ian@0 26 -------------
ian@0 27
ian@0 28 The Linux IPMI driver is modular, which means you have to pick several
ian@0 29 things to have it work right depending on your hardware. Most of
ian@0 30 these are available in the 'Character Devices' menu then the IPMI
ian@0 31 menu.
ian@0 32
ian@0 33 No matter what, you must pick 'IPMI top-level message handler' to use
ian@0 34 IPMI. What you do beyond that depends on your needs and hardware.
ian@0 35
ian@0 36 The message handler does not provide any user-level interfaces.
ian@0 37 Kernel code (like the watchdog) can still use it. If you need access
ian@0 38 from userland, you need to select 'Device interface for IPMI' if you
ian@0 39 want access through a device driver.
ian@0 40
ian@0 41 The driver interface depends on your hardware. If your system
ian@0 42 properly provides the SMBIOS info for IPMI, the driver will detect it
ian@0 43 and just work. If you have a board with a standard interface (These
ian@0 44 will generally be either "KCS", "SMIC", or "BT", consult your hardware
ian@0 45 manual), choose the 'IPMI SI handler' option. A driver also exists
ian@0 46 for direct I2C access to the IPMI management controller. Some boards
ian@0 47 support this, but it is unknown if it will work on every board. For
ian@0 48 this, choose 'IPMI SMBus handler', but be ready to try to do some
ian@0 49 figuring to see if it will work on your system if the SMBIOS/APCI
ian@0 50 information is wrong or not present. It is fairly safe to have both
ian@0 51 these enabled and let the drivers auto-detect what is present.
ian@0 52
ian@0 53 You should generally enable ACPI on your system, as systems with IPMI
ian@0 54 can have ACPI tables describing them.
ian@0 55
ian@0 56 If you have a standard interface and the board manufacturer has done
ian@0 57 their job correctly, the IPMI controller should be automatically
ian@0 58 detected (via ACPI or SMBIOS tables) and should just work. Sadly,
ian@0 59 many boards do not have this information. The driver attempts
ian@0 60 standard defaults, but they may not work. If you fall into this
ian@0 61 situation, you need to read the section below named 'The SI Driver' or
ian@0 62 "The SMBus Driver" on how to hand-configure your system.
ian@0 63
ian@0 64 IPMI defines a standard watchdog timer. You can enable this with the
ian@0 65 'IPMI Watchdog Timer' config option. If you compile the driver into
ian@0 66 the kernel, then via a kernel command-line option you can have the
ian@0 67 watchdog timer start as soon as it initializes. It also have a lot
ian@0 68 of other options, see the 'Watchdog' section below for more details.
ian@0 69 Note that you can also have the watchdog continue to run if it is
ian@0 70 closed (by default it is disabled on close). Go into the 'Watchdog
ian@0 71 Cards' menu, enable 'Watchdog Timer Support', and enable the option
ian@0 72 'Disable watchdog shutdown on close'.
ian@0 73
ian@0 74 IPMI systems can often be powered off using IPMI commands. Select
ian@0 75 'IPMI Poweroff' to do this. The driver will auto-detect if the system
ian@0 76 can be powered off by IPMI. It is safe to enable this even if your
ian@0 77 system doesn't support this option. This works on ATCA systems, the
ian@0 78 Radisys CPI1 card, and any IPMI system that supports standard chassis
ian@0 79 management commands.
ian@0 80
ian@0 81 If you want the driver to put an event into the event log on a panic,
ian@0 82 enable the 'Generate a panic event to all BMCs on a panic' option. If
ian@0 83 you want the whole panic string put into the event log using OEM
ian@0 84 events, enable the 'Generate OEM events containing the panic string'
ian@0 85 option.
ian@0 86
ian@0 87 Basic Design
ian@0 88 ------------
ian@0 89
ian@0 90 The Linux IPMI driver is designed to be very modular and flexible, you
ian@0 91 only need to take the pieces you need and you can use it in many
ian@0 92 different ways. Because of that, it's broken into many chunks of
ian@0 93 code. These chunks (by module name) are:
ian@0 94
ian@0 95 ipmi_msghandler - This is the central piece of software for the IPMI
ian@0 96 system. It handles all messages, message timing, and responses. The
ian@0 97 IPMI users tie into this, and the IPMI physical interfaces (called
ian@0 98 System Management Interfaces, or SMIs) also tie in here. This
ian@0 99 provides the kernelland interface for IPMI, but does not provide an
ian@0 100 interface for use by application processes.
ian@0 101
ian@0 102 ipmi_devintf - This provides a userland IOCTL interface for the IPMI
ian@0 103 driver, each open file for this device ties in to the message handler
ian@0 104 as an IPMI user.
ian@0 105
ian@0 106 ipmi_si - A driver for various system interfaces. This supports KCS,
ian@0 107 SMIC, and BT interfaces. Unless you have an SMBus interface or your
ian@0 108 own custom interface, you probably need to use this.
ian@0 109
ian@0 110 ipmi_smb - A driver for accessing BMCs on the SMBus. It uses the
ian@0 111 I2C kernel driver's SMBus interfaces to send and receive IPMI messages
ian@0 112 over the SMBus.
ian@0 113
ian@0 114 ipmi_watchdog - IPMI requires systems to have a very capable watchdog
ian@0 115 timer. This driver implements the standard Linux watchdog timer
ian@0 116 interface on top of the IPMI message handler.
ian@0 117
ian@0 118 ipmi_poweroff - Some systems support the ability to be turned off via
ian@0 119 IPMI commands.
ian@0 120
ian@0 121 These are all individually selectable via configuration options.
ian@0 122
ian@0 123 Note that the KCS-only interface has been removed. The af_ipmi driver
ian@0 124 is no longer supported and has been removed because it was impossible
ian@0 125 to do 32 bit emulation on 64-bit kernels with it.
ian@0 126
ian@0 127 Much documentation for the interface is in the include files. The
ian@0 128 IPMI include files are:
ian@0 129
ian@0 130 net/af_ipmi.h - Contains the socket interface.
ian@0 131
ian@0 132 linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
ian@0 133
ian@0 134 linux/ipmi_smi.h - Contains the interface for system management interfaces
ian@0 135 (things that interface to IPMI controllers) to use.
ian@0 136
ian@0 137 linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.
ian@0 138
ian@0 139
ian@0 140 Addressing
ian@0 141 ----------
ian@0 142
ian@0 143 The IPMI addressing works much like IP addresses, you have an overlay
ian@0 144 to handle the different address types. The overlay is:
ian@0 145
ian@0 146 struct ipmi_addr
ian@0 147 {
ian@0 148 int addr_type;
ian@0 149 short channel;
ian@0 150 char data[IPMI_MAX_ADDR_SIZE];
ian@0 151 };
ian@0 152
ian@0 153 The addr_type determines what the address really is. The driver
ian@0 154 currently understands two different types of addresses.
ian@0 155
ian@0 156 "System Interface" addresses are defined as:
ian@0 157
ian@0 158 struct ipmi_system_interface_addr
ian@0 159 {
ian@0 160 int addr_type;
ian@0 161 short channel;
ian@0 162 };
ian@0 163
ian@0 164 and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking
ian@0 165 straight to the BMC on the current card. The channel must be
ian@0 167
ian@0 168 Messages that are destined to go out on the IPMB bus use the
ian@0 169 IPMI_IPMB_ADDR_TYPE address type. The format is
ian@0 170
ian@0 171 struct ipmi_ipmb_addr
ian@0 172 {
ian@0 173 int addr_type;
ian@0 174 short channel;
ian@0 175 unsigned char slave_addr;
ian@0 176 unsigned char lun;
ian@0 177 };
ian@0 178
ian@0 179 The "channel" here is generally zero, but some devices support more
ian@0 180 than one channel, it corresponds to the channel as defined in the IPMI
ian@0 181 spec.
ian@0 182
ian@0 183
ian@0 184 Messages
ian@0 185 --------
ian@0 186
ian@0 187 Messages are defined as:
ian@0 188
ian@0 189 struct ipmi_msg
ian@0 190 {
ian@0 191 unsigned char netfn;
ian@0 192 unsigned char lun;
ian@0 193 unsigned char cmd;
ian@0 194 unsigned char *data;
ian@0 195 int data_len;
ian@0 196 };
ian@0 197
ian@0 198 The driver takes care of adding/stripping the header information. The
ian@0 199 data portion is just the data to be send (do NOT put addressing info
ian@0 200 here) or the response. Note that the completion code of a response is
ian@0 201 the first item in "data", it is not stripped out because that is how
ian@0 202 all the messages are defined in the spec (and thus makes counting the
ian@0 203 offsets a little easier :-).
ian@0 204
ian@0 205 When using the IOCTL interface from userland, you must provide a block
ian@0 206 of data for "data", fill it, and set data_len to the length of the
ian@0 207 block of data, even when receiving messages. Otherwise the driver
ian@0 208 will have no place to put the message.
ian@0 209
ian@0 210 Messages coming up from the message handler in kernelland will come in
ian@0 211 as:
ian@0 212
ian@0 213 struct ipmi_recv_msg
ian@0 214 {
ian@0 215 struct list_head link;
ian@0 216
ian@0 217 /* The type of message as defined in the "Receive Types"
ian@0 218 defines above. */
ian@0 219 int recv_type;
ian@0 220
ian@0 221 ipmi_user_t *user;
ian@0 222 struct ipmi_addr addr;
ian@0 223 long msgid;
ian@0 224 struct ipmi_msg msg;
ian@0 225
ian@0 226 /* Call this when done with the message. It will presumably free
ian@0 227 the message and do any other necessary cleanup. */
ian@0 228 void (*done)(struct ipmi_recv_msg *msg);
ian@0 229
ian@0 230 /* Place-holder for the data, don't make any assumptions about
ian@0 231 the size or existence of this, since it may change. */
ian@0 232 unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
ian@0 233 };
ian@0 234
ian@0 235 You should look at the receive type and handle the message
ian@0 236 appropriately.
ian@0 237
ian@0 238
ian@0 239 The Upper Layer Interface (Message Handler)
ian@0 240 -------------------------------------------
ian@0 241
ian@0 242 The upper layer of the interface provides the users with a consistent
ian@0 243 view of the IPMI interfaces. It allows multiple SMI interfaces to be
ian@0 244 addressed (because some boards actually have multiple BMCs on them)
ian@0 245 and the user should not have to care what type of SMI is below them.
ian@0 246
ian@0 247
ian@0 248 Creating the User
ian@0 249
ian@0 250 To user the message handler, you must first create a user using
ian@0 251 ipmi_create_user. The interface number specifies which SMI you want
ian@0 252 to connect to, and you must supply callback functions to be called
ian@0 253 when data comes in. The callback function can run at interrupt level,
ian@0 254 so be careful using the callbacks. This also allows to you pass in a
ian@0 255 piece of data, the handler_data, that will be passed back to you on
ian@0 256 all calls.
ian@0 257
ian@0 258 Once you are done, call ipmi_destroy_user() to get rid of the user.
ian@0 259
ian@0 260 From userland, opening the device automatically creates a user, and
ian@0 261 closing the device automatically destroys the user.
ian@0 262
ian@0 263
ian@0 264 Messaging
ian@0 265
ian@0 266 To send a message from kernel-land, the ipmi_request() call does
ian@0 267 pretty much all message handling. Most of the parameter are
ian@0 268 self-explanatory. However, it takes a "msgid" parameter. This is NOT
ian@0 269 the sequence number of messages. It is simply a long value that is
ian@0 270 passed back when the response for the message is returned. You may
ian@0 271 use it for anything you like.
ian@0 272
ian@0 273 Responses come back in the function pointed to by the ipmi_recv_hndl
ian@0 274 field of the "handler" that you passed in to ipmi_create_user().
ian@0 275 Remember again, these may be running at interrupt level. Remember to
ian@0 276 look at the receive type, too.
ian@0 277
ian@0 278 From userland, you fill out an ipmi_req_t structure and use the
ian@0 279 IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select()
ian@0 280 or poll() to wait for messages to come in. However, you cannot use
ian@0 281 read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
ian@0 282 ipmi_recv_t structure to actually get the message. Remember that you
ian@0 283 must supply a pointer to a block of data in the msg.data field, and
ian@0 284 you must fill in the msg.data_len field with the size of the data.
ian@0 285 This gives the receiver a place to actually put the message.
ian@0 286
ian@0 287 If the message cannot fit into the data you provide, you will get an
ian@0 288 EMSGSIZE error and the driver will leave the data in the receive
ian@0 289 queue. If you want to get it and have it truncate the message, us
ian@0 290 the IPMICTL_RECEIVE_MSG_TRUNC ioctl.
ian@0 291
ian@0 292 When you send a command (which is defined by the lowest-order bit of
ian@0 293 the netfn per the IPMI spec) on the IPMB bus, the driver will
ian@0 294 automatically assign the sequence number to the command and save the
ian@0 295 command. If the response is not receive in the IPMI-specified 5
ian@0 296 seconds, it will generate a response automatically saying the command
ian@0 297 timed out. If an unsolicited response comes in (if it was after 5
ian@0 298 seconds, for instance), that response will be ignored.
ian@0 299
ian@0 300 In kernelland, after you receive a message and are done with it, you
ian@0 301 MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note
ian@0 302 that you should NEVER mess with the "done" field of a message, that is
ian@0 303 required to properly clean up the message.
ian@0 304
ian@0 305 Note that when sending, there is an ipmi_request_supply_msgs() call
ian@0 306 that lets you supply the smi and receive message. This is useful for
ian@0 307 pieces of code that need to work even if the system is out of buffers
ian@0 308 (the watchdog timer uses this, for instance). You supply your own
ian@0 309 buffer and own free routines. This is not recommended for normal use,
ian@0 310 though, since it is tricky to manage your own buffers.
ian@0 311
ian@0 312
ian@0 313 Events and Incoming Commands
ian@0 314
ian@0 315 The driver takes care of polling for IPMI events and receiving
ian@0 316 commands (commands are messages that are not responses, they are
ian@0 317 commands that other things on the IPMB bus have sent you). To receive
ian@0 318 these, you must register for them, they will not automatically be sent
ian@0 319 to you.
ian@0 320
ian@0 321 To receive events, you must call ipmi_set_gets_events() and set the
ian@0 322 "val" to non-zero. Any events that have been received by the driver
ian@0 323 since startup will immediately be delivered to the first user that
ian@0 324 registers for events. After that, if multiple users are registered
ian@0 325 for events, they will all receive all events that come in.
ian@0 326
ian@0 327 For receiving commands, you have to individually register commands you
ian@0 328 want to receive. Call ipmi_register_for_cmd() and supply the netfn
ian@0 329 and command name for each command you want to receive. Only one user
ian@0 330 may be registered for each netfn/cmd, but different users may register
ian@0 331 for different commands.
ian@0 332
ian@0 333 From userland, equivalent IOCTLs are provided to do these functions.
ian@0 334
ian@0 335
ian@0 336 The Lower Layer (SMI) Interface
ian@0 337 -------------------------------
ian@0 338
ian@0 339 As mentioned before, multiple SMI interfaces may be registered to the
ian@0 340 message handler, each of these is assigned an interface number when
ian@0 341 they register with the message handler. They are generally assigned
ian@0 342 in the order they register, although if an SMI unregisters and then
ian@0 343 another one registers, all bets are off.
ian@0 344
ian@0 345 The ipmi_smi.h defines the interface for management interfaces, see
ian@0 346 that for more details.
ian@0 347
ian@0 348
ian@0 349 The SI Driver
ian@0 350 -------------
ian@0 351
ian@0 352 The SI driver allows up to 4 KCS or SMIC interfaces to be configured
ian@0 353 in the system. By default, scan the ACPI tables for interfaces, and
ian@0 354 if it doesn't find any the driver will attempt to register one KCS
ian@0 355 interface at the spec-specified I/O port 0xca2 without interrupts.
ian@0 356 You can change this at module load time (for a module) with:
ian@0 357
ian@0 358 modprobe ipmi_si.o type=<type1>,<type2>....
ian@0 359 ports=<port1>,<port2>... addrs=<addr1>,<addr2>...
ian@0 360 irqs=<irq1>,<irq2>... trydefaults=[0|1]
ian@0 361 regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,...
ian@0 362 regshifts=<shift1>,<shift2>,...
ian@0 363 slave_addrs=<addr1>,<addr2>,...
ian@0 364
ian@0 365 Each of these except si_trydefaults is a list, the first item for the
ian@0 366 first interface, second item for the second interface, etc.
ian@0 367
ian@0 368 The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it
ian@0 369 defaults to "kcs".
ian@0 370
ian@0 371 If you specify si_addrs as non-zero for an interface, the driver will
ian@0 372 use the memory address given as the address of the device. This
ian@0 373 overrides si_ports.
ian@0 374
ian@0 375 If you specify si_ports as non-zero for an interface, the driver will
ian@0 376 use the I/O port given as the device address.
ian@0 377
ian@0 378 If you specify si_irqs as non-zero for an interface, the driver will
ian@0 379 attempt to use the given interrupt for the device.
ian@0 380
ian@0 381 si_trydefaults sets whether the standard IPMI interface at 0xca2 and
ian@0 382 any interfaces specified by ACPE are tried. By default, the driver
ian@0 383 tries it, set this value to zero to turn this off.
ian@0 384
ian@0 385 The next three parameters have to do with register layout. The
ian@0 386 registers used by the interfaces may not appear at successive
ian@0 387 locations and they may not be in 8-bit registers. These parameters
ian@0 388 allow the layout of the data in the registers to be more precisely
ian@0 389 specified.
ian@0 390
ian@0 391 The regspacings parameter give the number of bytes between successive
ian@0 392 register start addresses. For instance, if the regspacing is set to 4
ian@0 393 and the start address is 0xca2, then the address for the second
ian@0 394 register would be 0xca6. This defaults to 1.
ian@0 395
ian@0 396 The regsizes parameter gives the size of a register, in bytes. The
ian@0 397 data used by IPMI is 8-bits wide, but it may be inside a larger
ian@0 398 register. This parameter allows the read and write type to specified.
ian@0 399 It may be 1, 2, 4, or 8. The default is 1.
ian@0 400
ian@0 401 Since the register size may be larger than 32 bits, the IPMI data may not
ian@0 402 be in the lower 8 bits. The regshifts parameter give the amount to shift
ian@0 403 the data to get to the actual IPMI data.
ian@0 404
ian@0 405 The slave_addrs specifies the IPMI address of the local BMC. This is
ian@0 406 usually 0x20 and the driver defaults to that, but in case it's not, it
ian@0 407 can be specified when the driver starts up.
ian@0 408
ian@0 409 When compiled into the kernel, the addresses can be specified on the
ian@0 410 kernel command line as:
ian@0 411
ian@0 412 ipmi_si.type=<type1>,<type2>...
ian@0 413 ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
ian@0 414 ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1]
ian@0 415 ipmi_si.regspacings=<sp1>,<sp2>,...
ian@0 416 ipmi_si.regsizes=<size1>,<size2>,...
ian@0 417 ipmi_si.regshifts=<shift1>,<shift2>,...
ian@0 418 ipmi_si.slave_addrs=<addr1>,<addr2>,...
ian@0 419
ian@0 420 It works the same as the module parameters of the same names.
ian@0 421
ian@0 422 By default, the driver will attempt to detect any device specified by
ian@0 423 ACPI, and if none of those then a KCS device at the spec-specified
ian@0 424 0xca2. If you want to turn this off, set the "trydefaults" option to
ian@0 425 false.
ian@0 426
ian@0 427 If you have high-res timers compiled into the kernel, the driver will
ian@0 428 use them to provide much better performance. Note that if you do not
ian@0 429 have high-res timers enabled in the kernel and you don't have
ian@0 430 interrupts enabled, the driver will run VERY slowly. Don't blame me,
ian@0 431 these interfaces suck.
ian@0 432
ian@0 433
ian@0 434 The SMBus Driver
ian@0 435 ----------------
ian@0 436
ian@0 437 The SMBus driver allows up to 4 SMBus devices to be configured in the
ian@0 438 system. By default, the driver will register any SMBus interfaces it finds
ian@0 439 in the I2C address range of 0x20 to 0x4f on any adapter. You can change this
ian@0 440 at module load time (for a module) with:
ian@0 441
ian@0 442 modprobe ipmi_smb.o
ian@0 443 addr=<adapter1>,<i2caddr1>[,<adapter2>,<i2caddr2>[,...]]
ian@0 444 dbg=<flags1>,<flags2>...
ian@0 445 [defaultprobe=1] [dbg_probe=1]
ian@0 446
ian@0 447 The addresses are specified in pairs, the first is the adapter ID and the
ian@0 448 second is the I2C address on that adapter.
ian@0 449
ian@0 450 The debug flags are bit flags for each BMC found, they are:
ian@0 451 IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8
ian@0 452
ian@0 453 Setting smb_defaultprobe to zero disabled the default probing of SMBus
ian@0 454 interfaces at address range 0x20 to 0x4f. This means that only the
ian@0 455 BMCs specified on the smb_addr line will be detected.
ian@0 456
ian@0 457 Setting smb_dbg_probe to 1 will enable debugging of the probing and
ian@0 458 detection process for BMCs on the SMBusses.
ian@0 459
ian@0 460 Discovering the IPMI compilant BMC on the SMBus can cause devices
ian@0 461 on the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI
ian@0 462 message as a block write to the I2C bus and waits for a response.
ian@0 463 This action can be detrimental to some I2C devices. It is highly recommended
ian@0 464 that the known I2c address be given to the SMBus driver in the smb_addr
ian@0 465 parameter. The default adrress range will not be used when a smb_addr
ian@0 466 parameter is provided.
ian@0 467
ian@0 468 When compiled into the kernel, the addresses can be specified on the
ian@0 469 kernel command line as:
ian@0 470
ian@0 471 ipmb_smb.addr=<adapter1>,<i2caddr1>[,<adapter2>,<i2caddr2>[,...]]
ian@0 472 ipmi_smb.dbg=<flags1>,<flags2>...
ian@0 473 ipmi_smb.defaultprobe=0 ipmi_smb.dbg_probe=1
ian@0 474
ian@0 475 These are the same options as on the module command line.
ian@0 476
ian@0 477 Note that you might need some I2C changes if CONFIG_IPMI_PANIC_EVENT
ian@0 478 is enabled along with this, so the I2C driver knows to run to
ian@0 479 completion during sending a panic event.
ian@0 480
ian@0 481
ian@0 482 Other Pieces
ian@0 483 ------------
ian@0 484
ian@0 485 Watchdog
ian@0 486 --------
ian@0 487
ian@0 488 A watchdog timer is provided that implements the Linux-standard
ian@0 489 watchdog timer interface. It has three module parameters that can be
ian@0 490 used to control it:
ian@0 491
ian@0 492 modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
ian@0 493 preaction=<preaction type> preop=<preop type> start_now=x
ian@0 494 nowayout=x
ian@0 495
ian@0 496 The timeout is the number of seconds to the action, and the pretimeout
ian@0 497 is the amount of seconds before the reset that the pre-timeout panic will
ian@0 498 occur (if pretimeout is zero, then pretimeout will not be enabled). Note
ian@0 499 that the pretimeout is the time before the final timeout. So if the
ian@0 500 timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout
ian@0 501 will occur in 40 second (10 seconds before the timeout).
ian@0 502
ian@0 503 The action may be "reset", "power_cycle", or "power_off", and
ian@0 504 specifies what to do when the timer times out, and defaults to
ian@0 505 "reset".
ian@0 506
ian@0 507 The preaction may be "pre_smi" for an indication through the SMI
ian@0 508 interface, "pre_int" for an indication through the SMI with an
ian@0 509 interrupts, and "pre_nmi" for a NMI on a preaction. This is how
ian@0 510 the driver is informed of the pretimeout.
ian@0 511
ian@0 512 The preop may be set to "preop_none" for no operation on a pretimeout,
ian@0 513 "preop_panic" to set the preoperation to panic, or "preop_give_data"
ian@0 514 to provide data to read from the watchdog device when the pretimeout
ian@0 515 occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data"
ian@0 516 because you can't do data operations from an NMI.
ian@0 517
ian@0 518 When preop is set to "preop_give_data", one byte comes ready to read
ian@0 519 on the device when the pretimeout occurs. Select and fasync work on
ian@0 520 the device, as well.
ian@0 521
ian@0 522 If start_now is set to 1, the watchdog timer will start running as
ian@0 523 soon as the driver is loaded.
ian@0 524
ian@0 525 If nowayout is set to 1, the watchdog timer will not stop when the
ian@0 526 watchdog device is closed. The default value of nowayout is true
ian@0 527 if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.
ian@0 528
ian@0 529 When compiled into the kernel, the kernel command line is available
ian@0 530 for configuring the watchdog:
ian@0 531
ian@0 532 ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>
ian@0 533 ipmi_watchdog.action=<action type>
ian@0 534 ipmi_watchdog.preaction=<preaction type>
ian@0 535 ipmi_watchdog.preop=<preop type>
ian@0 536 ipmi_watchdog.start_now=x
ian@0 537 ipmi_watchdog.nowayout=x
ian@0 538
ian@0 539 The options are the same as the module parameter options.
ian@0 540
ian@0 541 The watchdog will panic and start a 120 second reset timeout if it
ian@0 542 gets a pre-action. During a panic or a reboot, the watchdog will
ian@0 543 start a 120 timer if it is running to make sure the reboot occurs.
ian@0 544
ian@0 545 Note that if you use the NMI preaction for the watchdog, you MUST
ian@0 546 NOT use nmi watchdog mode 1. If you use the NMI watchdog, you
ian@0 547 must use mode 2.
ian@0 548
ian@0 549 Once you open the watchdog timer, you must write a 'V' character to the
ian@0 550 device to close it, or the timer will not stop. This is a new semantic
ian@0 551 for the driver, but makes it consistent with the rest of the watchdog
ian@0 552 drivers in Linux.
ian@0 553
ian@0 554
ian@0 555 Panic Timeouts
ian@0 556 --------------
ian@0 557
ian@0 558 The OpenIPMI driver supports the ability to put semi-custom and custom
ian@0 559 events in the system event log if a panic occurs. if you enable the
ian@0 560 'Generate a panic event to all BMCs on a panic' option, you will get
ian@0 561 one event on a panic in a standard IPMI event format. If you enable
ian@0 562 the 'Generate OEM events containing the panic string' option, you will
ian@0 563 also get a bunch of OEM events holding the panic string.
ian@0 564
ian@0 565
ian@0 566 The field settings of the events are:
ian@0 567 * Generator ID: 0x21 (kernel)
ian@0 568 * EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)
ian@0 569 * Sensor Type: 0x20 (OS critical stop sensor)
ian@0 570 * Sensor #: The first byte of the panic string (0 if no panic string)
ian@0 571 * Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info)
ian@0 572 * Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)
ian@0 573 * Event data 2: second byte of panic string
ian@0 574 * Event data 3: third byte of panic string
ian@0 575 See the IPMI spec for the details of the event layout. This event is
ian@0 576 always sent to the local management controller. It will handle routing
ian@0 577 the message to the right place
ian@0 578
ian@0 579 Other OEM events have the following format:
ian@0 580 Record ID (bytes 0-1): Set by the SEL.
ian@0 581 Record type (byte 2): 0xf0 (OEM non-timestamped)
ian@0 582 byte 3: The slave address of the card saving the panic
ian@0 583 byte 4: A sequence number (starting at zero)
ian@0 584 The rest of the bytes (11 bytes) are the panic string. If the panic string
ian@0 585 is longer than 11 bytes, multiple messages will be sent with increasing
ian@0 586 sequence numbers.
ian@0 587
ian@0 588 Because you cannot send OEM events using the standard interface, this
ian@0 589 function will attempt to find an SEL and add the events there. It
ian@0 590 will first query the capabilities of the local management controller.
ian@0 591 If it has an SEL, then they will be stored in the SEL of the local
ian@0 592 management controller. If not, and the local management controller is
ian@0 593 an event generator, the event receiver from the local management
ian@0 594 controller will be queried and the events sent to the SEL on that
ian@0 595 device. Otherwise, the events go nowhere since there is nowhere to
ian@0 596 send them.
ian@0 597
ian@0 598
ian@0 599 Poweroff
ian@0 600 --------
ian@0 601
ian@0 602 If the poweroff capability is selected, the IPMI driver will install
ian@0 603 a shutdown function into the standard poweroff function pointer. This
ian@0 604 is in the ipmi_poweroff module. When the system requests a powerdown,
ian@0 605 it will send the proper IPMI commands to do this. This is supported on
ian@0 606 several platforms.
ian@0 607
ian@0 608 There is a module parameter named "poweroff_powercycle" that may
ian@0 609 either be zero (do a power down) or non-zero (do a power cycle, power
ian@0 610 the system off, then power it on in a few seconds). Setting
ian@0 611 ipmi_poweroff.poweroff_control=x will do the same thing on the kernel
ian@0 612 command line. The parameter is also available via the proc filesystem
ian@0 613 in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system
ian@0 614 does not support power cycling, it will always do the power off.
ian@0 615
ian@0 616 Note that if you have ACPI enabled, the system will prefer using ACPI to
ian@0 617 power off.