8 This document describes how to use the IPMI driver for Linux. If you
9 are not familiar with IPMI itself, see the web site at
10 http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
11 subject and I can't cover it all here!
16 The Linux IPMI driver is designed to be very modular and flexible, you
17 only need to take the pieces you need and you can use it in many
18 different ways. Because of that, it's broken into many chunks of
19 code. These chunks are:
21 ipmi_msghandler - This is the central piece of software for the IPMI
22 system. It handles all messages, message timing, and responses. The
23 IPMI users tie into this, and the IPMI physical interfaces (called
24 System Management Interfaces, or SMIs) also tie in here. This
25 provides the kernelland interface for IPMI, but does not provide an
26 interface for use by application processes.
28 ipmi_devintf - This provides a userland IOCTL interface for the IPMI
29 driver, each open file for this device ties in to the message handler
32 ipmi_kcs_drv - A driver for the KCS SMI. Most system have a KCS
36 Much documentation for the interface is in the include files. The
37 IPMI include files are:
39 ipmi.h - Contains the user interface and IOCTL interface for IPMI.
41 ipmi_smi.h - Contains the interface for SMI drivers to use.
43 ipmi_msgdefs.h - General definitions for base IPMI messaging.
49 The IPMI addressing works much like IP addresses, you have an overlay
50 to handle the different address types. The overlay is:
56 char data[IPMI_MAX_ADDR_SIZE];
59 The addr_type determines what the address really is. The driver
60 currently understands two different types of addresses.
62 "System Interface" addresses are defined as:
64 struct ipmi_system_interface_addr
70 and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking
71 straight to the BMC on the current card. The channel must be
74 Messages that are destined to go out on the IPMB bus use the
75 IPMI_IPMB_ADDR_TYPE address type. The format is
81 unsigned char slave_addr;
85 The "channel" here is generally zero, but some devices support more
86 than one channel, it corresponds to the channel as defined in the IPMI
93 Messages are defined as:
104 The driver takes care of adding/stripping the header information. The
105 data portion is just the data to be send (do NOT put addressing info
106 here) or the response. Note that the completion code of a response is
107 the first item in "data", it is not stripped out because that is how
108 all the messages are defined in the spec (and thus makes counting the
109 offsets a little easier :-).
111 When using the IOCTL interface from userland, you must provide a block
112 of data for "data", fill it, and set data_len to the length of the
113 block of data, even when receiving messages. Otherwise the driver
114 will have no place to put the message.
116 Messages coming up from the message handler in kernelland will come in
121 struct list_head link;
123 /* The type of message as defined in the "Receive Types"
128 struct ipmi_addr addr;
132 /* Call this when done with the message. It will presumably free
133 the message and do any other necessary cleanup. */
134 void (*done)(struct ipmi_recv_msg *msg);
136 /* Place-holder for the data, don't make any assumptions about
137 the size or existence of this, since it may change. */
138 unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
141 You should look at the receive type and handle the message
145 The Upper Layer Interface (Message Handler)
146 -------------------------------------------
148 The upper layer of the interface provides the users with a consistent
149 view of the IPMI interfaces. It allows multiple SMI interfaces to be
150 addressed (because some boards actually have multiple BMCs on them)
151 and the user should not have to care what type of SMI is below them.
156 To user the message handler, you must first create a user using
157 ipmi_create_user. The interface number specifies which SMI you want
158 to connect to, and you must supply callback functions to be called
159 when data comes in. The callback function can run at interrupt level,
160 so be careful using the callbacks. This also allows to you pass in a
161 piece of data, the handler_data, that will be passed back to you on
164 Once you are done, call ipmi_destroy_user() to get rid of the user.
166 From userland, opening the device automatically creates a user, and
167 closing the device automatically destroys the user.
172 To send a message from kernel-land, the ipmi_request() call does
173 pretty much all message handling. Most of the parameter are
174 self-explanatory. However, it takes a "msgid" parameter. This is NOT
175 the sequence number of messages. It is simply a long value that is
176 passed back when the response for the message is returned. You may
177 use it for anything you like.
179 Responses come back in the function pointed to by the ipmi_recv_hndl
180 field of the "handler" that you passed in to ipmi_create_user().
181 Remember again, these may be running at interrupt level. Remember to
182 look at the receive type, too.
184 From userland, you fill out an ipmi_req_t structure and use the
185 IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select()
186 or poll() to wait for messages to come in. However, you cannot use
187 read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
188 ipmi_recv_t structure to actually get the message. Remember that you
189 must supply a pointer to a block of data in the msg.data field, and
190 you must fill in the msg.data_len field with the size of the data.
191 This gives the receiver a place to actually put the message.
193 If the message cannot fit into the data you provide, you will get an
194 EMSGSIZE error and the driver will leave the data in the receive
195 queue. If you want to get it and have it truncate the message, us
196 the IPMICTL_RECEIVE_MSG_TRUNC ioctl.
198 When you send a command (which is defined by the lowest-order bit of
199 the netfn per the IPMI spec) on the IPMB bus, the driver will
200 automatically assign the sequence number to the command and save the
201 command. If the response is not receive in the IPMI-specified 5
202 seconds, it will generate a response automatically saying the command
203 timed out. If an unsolicited response comes in (if it was after 5
204 seconds, for instance), that response will be ignored.
206 In kernelland, after you receive a message and are done with it, you
207 MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note
208 that you should NEVER mess with the "done" field of a message, that is
209 required to properly clean up the message.
211 Note that when sending, there is an ipmi_request_supply_msgs() call
212 that lets you supply the smi and receive message. This is useful for
213 pieces of code that need to work even if the system is out of buffers
214 (the watchdog timer uses this, for instance). You supply your own
215 buffer and own free routines. This is not recommended for normal use,
216 though, since it is tricky to manage your own buffers.
219 Events and Incoming Commands
221 The driver takes care of polling for IPMI events and receiving
222 commands (commands are messages that are not responses, they are
223 commands that other things on the IPMB bus have sent you). To receive
224 these, you must register for them, they will not automatically be sent
227 To receive events, you must call ipmi_set_gets_events() and set the
228 "val" to non-zero. Any events that have been received by the driver
229 since startup will immediately be delivered to the first user that
230 registers for events. After that, if multiple users are registered
231 for events, they will all receive all events that come in.
233 For receiving commands, you have to individually register commands you
234 want to receive. Call ipmi_register_for_cmd() and supply the netfn
235 and command name for each command you want to receive. Only one user
236 may be registered for each netfn/cmd, but different users may register
237 for different commands.
239 From userland, equivalent IOCTLs are provided to do these functions.
242 The Lower Layer (SMI) Interface
243 -------------------------------
245 As mentioned before, multiple SMI interfaces may be registered to the
246 message handler, each of these is assigned an interface number when
247 they register with the message handler. They are generally assigned
248 in the order they register, although if an SMI unregisters and then
249 another one registers, all bets are off.
251 The ipmi_smi.h defines the interface for SMIs, see that for more
258 The KCS driver allows up to 4 KCS interfaces to be configured in the
259 system. By default, the driver will register one KCS interface at the
260 spec-specified I/O port 0xca2 without interrupts. You can change this
261 at module load time (for a module) with:
263 insmod ipmi_kcs_drv.o kcs_ports=<port1>,<port2>... kcs_addrs=<addr1>,<addr2>
264 kcs_irqs=<irq1>,<irq2>... kcs_trydefaults=[0|1]
266 The KCS driver supports two types of interfaces, ports (for I/O port
267 based KCS interfaces) and memory addresses (for KCS interfaces in
268 memory). The driver will support both of them simultaneously, setting
269 the port to zero (or just not specifying it) will allow the memory
270 address to be used. The port will override the memory address if it
271 is specified and non-zero. kcs_trydefaults sets whether the standard
272 IPMI interface at 0xca2 and any interfaces specified by ACPE are
273 tried. By default, the driver tries it, set this value to zero to
276 When compiled into the kernel, the addresses can be specified on the
277 kernel command line as:
279 ipmi_kcs=<bmc1>:<irq1>,<bmc2>:<irq2>....,[nodefault]
281 The <bmcx> values is either "p<port>" or "m<addr>" for port or memory
282 addresses. So for instance, a KCS interface at port 0xca2 using
283 interrupt 9 and a memory interface at address 0xf9827341 with no
284 interrupt would be specified "ipmi_kcs=p0xca2:9,m0xf9827341".
285 If you specify zero for in irq or don't specify it, the driver will
286 run polled unless the software can detect the interrupt to use in the
289 By default, the driver will attempt to detect a KCS device at the
290 spec-specified 0xca2 address and any address specified by ACPI. If
291 you want to turn this off, use the "nodefault" option.
293 If you have high-res timers compiled into the kernel, the driver will
294 use them to provide much better performance. Note that if you do not
295 have high-res timers enabled in the kernel and you don't have
296 interrupts enabled, the driver will run VERY slowly. Don't blame me,
297 the KCS interface sucks.
305 A watchdog timer is provided that implements the Linux-standard
306 watchdog timer interface. It has three module parameters that can be
309 insmod ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
310 preaction=<preaction type>
312 The timeout is the number of seconds to the action, and the pretimeout
313 is the amount of seconds before the reset that the pre-timeout panic will
314 occur (if pretimeout is zero, then pretimeout will not be enabled).
316 The action may be "reset", "power_cycle", or "power_off", and
317 specifies what to do when the timer times out, and defaults to
320 The preaction may be "pre_smi" for an indication through the SMI
321 interface, "pre_int" for an indication through the SMI with an
322 interrupts, and "pre_nmi" for a NMI on a preaction.
324 When compiled into the kernel, the kernel command line is available
325 for configuring the watchdog:
327 ipmi_wdog=<timeout>[,<pretimeout>[,<option>[,<options>....]]]
329 The options are the actions and preaction above (if an option
330 controlling the same thing is specified twice, the last is taken). An
331 options "start_now" is also there, if included, the watchdog will
332 start running immediately when all the drivers are ready, it doesn't
333 have to have a user hooked up to start it.
335 The watchdog will panic and start a 120 second reset timeout if it
336 gets a pre-action. During a panic or a reboot, the watchdog will
337 start a 120 timer if it is running to make sure the reboot occurs.
339 Note that if you use the NMI preaction for the watchdog, you MUST
340 NOT use nmi watchdog mode 1. If you use the NMI watchdog, you