diff options
Diffstat (limited to 'Documentation/IPMI.txt')
| -rw-r--r-- | Documentation/IPMI.txt | 133 |
1 files changed, 76 insertions, 57 deletions
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index c0d8788e75d3..aa77a25a0940 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -1,9 +1,8 @@ +===================== +The Linux IPMI Driver +===================== - The Linux IPMI Driver - --------------------- - Corey Minyard - <minyard@mvista.com> - <minyard@acm.org> +:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org> The Intelligent Platform Management Interface, or IPMI, is a standard for controlling intelligent devices that monitor a system. @@ -111,6 +110,8 @@ ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the I2C kernel driver's SMBus interfaces to send and receive IPMI messages over the SMBus. +ipmi_powernv - A driver for access BMCs on POWERNV systems. + ipmi_watchdog - IPMI requires systems to have a very capable watchdog timer. This driver implements the standard Linux watchdog timer interface on top of the IPMI message handler. @@ -118,17 +119,15 @@ interface on top of the IPMI message handler. ipmi_poweroff - Some systems support the ability to be turned off via IPMI commands. -These are all individually selectable via configuration options. +bt-bmc - This is not part of the main driver, but instead a driver for +accessing a BMC-side interface of a BT interface. It is used on BMCs +running Linux to provide an interface to the host. -Note that the KCS-only interface has been removed. The af_ipmi driver -is no longer supported and has been removed because it was impossible -to do 32 bit emulation on 64-bit kernels with it. +These are all individually selectable via configuration options. Much documentation for the interface is in the include files. The IPMI include files are: -net/af_ipmi.h - Contains the socket interface. - linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI. linux/ipmi_smi.h - Contains the interface for system management interfaces @@ -141,7 +140,7 @@ Addressing ---------- The IPMI addressing works much like IP addresses, you have an overlay -to handle the different address types. The overlay is: +to handle the different address types. The overlay is:: struct ipmi_addr { @@ -153,7 +152,7 @@ to handle the different address types. The overlay is: The addr_type determines what the address really is. The driver currently understands two different types of addresses. -"System Interface" addresses are defined as: +"System Interface" addresses are defined as:: struct ipmi_system_interface_addr { @@ -166,7 +165,7 @@ straight to the BMC on the current card. The channel must be IPMI_BMC_CHANNEL. Messages that are destined to go out on the IPMB bus use the -IPMI_IPMB_ADDR_TYPE address type. The format is +IPMI_IPMB_ADDR_TYPE address type. The format is:: struct ipmi_ipmb_addr { @@ -184,16 +183,16 @@ spec. Messages -------- -Messages are defined as: +Messages are defined as:: -struct ipmi_msg -{ + struct ipmi_msg + { unsigned char netfn; unsigned char lun; unsigned char cmd; unsigned char *data; int data_len; -}; + }; The driver takes care of adding/stripping the header information. The data portion is just the data to be send (do NOT put addressing info @@ -208,7 +207,7 @@ block of data, even when receiving messages. Otherwise the driver will have no place to put the message. Messages coming up from the message handler in kernelland will come in -as: +as:: struct ipmi_recv_msg { @@ -245,9 +244,21 @@ addressed (because some boards actually have multiple BMCs on them) and the user should not have to care what type of SMI is below them. +Watching For Interfaces +^^^^^^^^^^^^^^^^^^^^^^^ + +When your code comes up, the IPMI driver may or may not have detected +if IPMI devices exist. So you might have to defer your setup until +the device is detected, or you might be able to do it immediately. +To handle this, and to allow for discovery, you register an SMI +watcher with ipmi_smi_watcher_register() to iterate over interfaces +and tell you when they come and go. + + Creating the User +^^^^^^^^^^^^^^^^^ -To user the message handler, you must first create a user using +To use the message handler, you must first create a user using ipmi_create_user. The interface number specifies which SMI you want to connect to, and you must supply callback functions to be called when data comes in. The callback function can run at interrupt level, @@ -262,8 +273,9 @@ closing the device automatically destroys the user. Messaging +^^^^^^^^^ -To send a message from kernel-land, the ipmi_request() call does +To send a message from kernel-land, the ipmi_request_settime() call does pretty much all message handling. Most of the parameter are self-explanatory. However, it takes a "msgid" parameter. This is NOT the sequence number of messages. It is simply a long value that is @@ -311,6 +323,7 @@ though, since it is tricky to manage your own buffers. Events and Incoming Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The driver takes care of polling for IPMI events and receiving commands (commands are messages that are not responses, they are @@ -352,11 +365,12 @@ that for more details. The SI Driver ------------- -The SI driver allows up to 4 KCS or SMIC interfaces to be configured -in the system. By default, scan the ACPI tables for interfaces, and -if it doesn't find any the driver will attempt to register one KCS -interface at the spec-specified I/O port 0xca2 without interrupts. -You can change this at module load time (for a module) with: +The SI driver allows KCS, BT, and SMIC interfaces to be configured +in the system. It discovers interfaces through a host of different +methods, depending on the system. + +You can specify up to four interfaces on the module load line and +control some module parameters:: modprobe ipmi_si.o type=<type1>,<type2>.... ports=<port1>,<port2>... addrs=<addr1>,<addr2>... @@ -367,7 +381,7 @@ You can change this at module load time (for a module) with: force_kipmid=<enable1>,<enable2>,... kipmid_max_busy_us=<ustime1>,<ustime2>,... unload_when_empty=[0|1] - trydefaults=[0|1] trydmi=[0|1] tryacpi=[0|1] + trydmi=[0|1] tryacpi=[0|1] tryplatform=[0|1] trypci=[0|1] Each of these except try... items is a list, the first item for the @@ -386,10 +400,6 @@ use the I/O port given as the device address. If you specify irqs as non-zero for an interface, the driver will attempt to use the given interrupt for the device. -trydefaults sets whether the standard IPMI interface at 0xca2 and -any interfaces specified by ACPE are tried. By default, the driver -tries it, set this value to zero to turn this off. - The other try... items disable discovery by their corresponding names. These are all enabled by default, set them to zero to disable them. The tryplatform disables openfirmware. @@ -430,11 +440,11 @@ default is one. Setting to 0 is useful with the hotmod, but is obviously only useful for modules. When compiled into the kernel, the parameters can be specified on the -kernel command line as: +kernel command line as:: ipmi_si.type=<type1>,<type2>... ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>... - ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1] + ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.regspacings=<sp1>,<sp2>,... ipmi_si.regsizes=<size1>,<size2>,... ipmi_si.regshifts=<shift1>,<shift2>,... @@ -444,11 +454,6 @@ kernel command line as: It works the same as the module parameters of the same names. -By default, the driver will attempt to detect any device specified by -ACPI, and if none of those then a KCS device at the spec-specified -0xca2. If you want to turn this off, set the "trydefaults" option to -false. - If your IPMI interface does not support interrupts and is a KCS or SMIC interface, the IPMI driver will start a kernel thread for the interface to help speed things up. This is a low-priority kernel @@ -472,16 +477,22 @@ The driver supports a hot add and remove of interfaces. This way, interfaces can be added or removed after the kernel is up and running. This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a write-only parameter. You write a string to this interface. The string -has the format: +has the format:: + <op1>[:op2[:op3...]] -The "op"s are: + +The "op"s are:: + add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]] -You can specify more than one interface on the line. The "opt"s are: + +You can specify more than one interface on the line. The "opt"s are:: + rsp=<regspacing> rsi=<regsize> rsh=<regshift> irq=<irq> ipmb=<ipmb slave addr> + and these have the same meanings as discussed above. Note that you can also use this on the kernel command line for a more compact format for specifying an interface. Note that when removing an interface, @@ -494,13 +505,14 @@ The SMBus Driver (SSIF) The SMBus driver allows up to 4 SMBus devices to be configured in the system. By default, the driver will only register with something it finds in DMI or ACPI tables. You can change this -at module load time (for a module) with: +at module load time (for a module) with:: modprobe ipmi_ssif.o addr=<i2caddr1>[,<i2caddr2>[,...]] adapter=<adapter1>[,<adapter2>[...]] dbg=<flags1>,<flags2>... - slave_addrs=<addr1>,<addr2>,... + slave_addrs=<addr1>,<addr2>,... + tryacpi=[0|1] trydmi=[0|1] [dbg_probe=1] The addresses are normal I2C addresses. The adapter is the string @@ -513,6 +525,9 @@ spaces in kernel parameters. The debug flags are bit flags for each BMC found, they are: IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8 +The tryxxx parameters can be used to disable detecting interfaces +from various sources. + Setting dbg_probe to 1 will enable debugging of the probing and detection process for BMCs on the SMBusses. @@ -529,13 +544,14 @@ the smb_addr parameter unless you have DMI or ACPI data to tell the driver what to use. When compiled into the kernel, the addresses can be specified on the -kernel command line as: +kernel command line as:: ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]] ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]] ipmi_ssif.dbg=<flags1>[,<flags2>[...]] ipmi_ssif.dbg_probe=1 - ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + ipmi_ssif.tryacpi=[0|1] ipmi_ssif.trydmi=[0|1] These are the same options as on the module command line. @@ -558,9 +574,9 @@ Some users need more detailed information about a device, like where the address came from or the raw base device for the IPMI interface. You can use the IPMI smi_watcher to catch the IPMI interfaces as they come or go, and to grab the information, you can use the function -ipmi_get_smi_info(), which returns the following structure: +ipmi_get_smi_info(), which returns the following structure:: -struct ipmi_smi_info { + struct ipmi_smi_info { enum ipmi_addr_src addr_src; struct device *dev; union { @@ -568,7 +584,7 @@ struct ipmi_smi_info { void *acpi_handle; } acpi_info; } addr_info; -}; + }; Currently special info for only for SI_ACPI address sources is returned. Others may be added as necessary. @@ -583,7 +599,7 @@ Watchdog A watchdog timer is provided that implements the Linux-standard watchdog timer interface. It has three module parameters that can be -used to control it: +used to control it:: modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type> preaction=<preaction type> preop=<preop type> start_now=x @@ -628,7 +644,7 @@ watchdog device is closed. The default value of nowayout is true if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not. When compiled into the kernel, the kernel command line is available -for configuring the watchdog: +for configuring the watchdog:: ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t> ipmi_watchdog.action=<action type> @@ -668,6 +684,7 @@ also get a bunch of OEM events holding the panic string. The field settings of the events are: + * Generator ID: 0x21 (kernel) * EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) * Sensor Type: 0x20 (OS critical stop sensor) @@ -676,18 +693,20 @@ The field settings of the events are: * Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) * Event data 2: second byte of panic string * Event data 3: third byte of panic string + See the IPMI spec for the details of the event layout. This event is always sent to the local management controller. It will handle routing the message to the right place Other OEM events have the following format: -Record ID (bytes 0-1): Set by the SEL. -Record type (byte 2): 0xf0 (OEM non-timestamped) -byte 3: The slave address of the card saving the panic -byte 4: A sequence number (starting at zero) -The rest of the bytes (11 bytes) are the panic string. If the panic string -is longer than 11 bytes, multiple messages will be sent with increasing -sequence numbers. + +* Record ID (bytes 0-1): Set by the SEL. +* Record type (byte 2): 0xf0 (OEM non-timestamped) +* byte 3: The slave address of the card saving the panic +* byte 4: A sequence number (starting at zero) + The rest of the bytes (11 bytes) are the panic string. If the panic string + is longer than 11 bytes, multiple messages will be sent with increasing + sequence numbers. Because you cannot send OEM events using the standard interface, this function will attempt to find an SEL and add the events there. It |