Documentation/IPMI.txt

   1
   2                           The Linux IPMI Driver
   3                           ---------------------
   4                               Corey Minyard
   5                           <minyard@mvista.com>
   6                             <minyard@acm.org>
   7
   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!
  12
  13 Basic Design
  14 ------------
  15
  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:
  20
  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.
  27
  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
  30 as an IPMI user.
  31
  32 ipmi_kcs_drv - A driver for the KCS SMI.  Most system have a KCS
  33 interface for IPMI.
  34
  35
  36 Much documentation for the interface is in the include files.  The
  37 IPMI include files are:
  38
  39 ipmi.h - Contains the user interface and IOCTL interface for IPMI.
  40
  41 ipmi_smi.h - Contains the interface for SMI drivers to use.
  42
  43 ipmi_msgdefs.h - General definitions for base IPMI messaging.
  44
  45
  46 Addressing
  47 ----------
  48
  49 The IPMI addressing works much like IP addresses, you have an overlay
  50 to handle the different address types.  The overlay is:
  51
  52   struct ipmi_addr
  53   {
  54         int   addr_type;
  55         short channel;
  56         char  data[IPMI_MAX_ADDR_SIZE];
  57   };
  58
  59 The addr_type determines what the address really is.  The driver
  60 currently understands two different types of addresses.
  61
  62 "System Interface" addresses are defined as:
  63
  64   struct ipmi_system_interface_addr
  65   {
  66         int   addr_type;
  67         short channel;
  68   };
  69
  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
  72 IPMI_BMC_CHANNEL.
  73
  74 Messages that are destined to go out on the IPMB bus use the
  75 IPMI_IPMB_ADDR_TYPE address type.  The format is
  76
  77   struct ipmi_ipmb_addr
  78   {
  79         int           addr_type;
  80         short         channel;
  81         unsigned char slave_addr;
  82         unsigned char lun;
  83   };
  84
  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
  87 spec.
  88
  89
  90 Messages
  91 --------
  92
  93 Messages are defined as:
  94
  95 struct ipmi_msg
  96 {
  97         unsigned char netfn;
  98         unsigned char lun;
  99         unsigned char cmd;
 100         unsigned char *data;
 101         int           data_len;
 102 };
 103
 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 :-).
 110
 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.
 115
 116 Messages coming up from the message handler in kernelland will come in
 117 as:
 118
 119   struct ipmi_recv_msg
 120   {
 121         struct list_head link;
 122
 123         /* The type of message as defined in the "Receive Types"
 124            defines above. */
 125         int         recv_type;
 126
 127         ipmi_user_t      *user;
 128         struct ipmi_addr addr;
 129         long             msgid;
 130         struct ipmi_msg  msg;
 131
 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);
 135
 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];
 139   };
 140
 141 You should look at the receive type and handle the message
 142 appropriately.
 143
 144
 145 The Upper Layer Interface (Message Handler)
 146 -------------------------------------------
 147
 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.
 152
 153
 154 Creating the User
 155
 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
 162 all calls.
 163
 164 Once you are done, call ipmi_destroy_user() to get rid of the user.
 165
 166 From userland, opening the device automatically creates a user, and
 167 closing the device automatically destroys the user.
 168
 169
 170 Messaging
 171
 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.
 178
 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.
 183
 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.
 192
 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.
 197
 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.
 205
 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.
 210
 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.
 217
 218
 219 Events and Incoming Commands
 220
 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
 225 to you.
 226
 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.
 232
 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.
 238
 239 From userland, equivalent IOCTLs are provided to do these functions.
 240
 241
 242 The Lower Layer (SMI) Interface
 243 -------------------------------
 244
 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.
 250
 251 The ipmi_smi.h defines the interface for SMIs, see that for more
 252 details.
 253
 254
 255 The KCS Driver
 256 --------------
 257
 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:
 262
 263   insmod ipmi_kcs_drv.o kcs_ports=<port1>,<port2>... kcs_addrs=<addr1>,<addr2>
 264        kcs_irqs=<irq1>,<irq2>... kcs_trydefaults=[0|1]
 265
 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
 274 turn this off.
 275
 276 When compiled into the kernel, the addresses can be specified on the
 277 kernel command line as:
 278
 279   ipmi_kcs=<bmc1>:<irq1>,<bmc2>:<irq2>....,[nodefault]
 280
 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
 287 ACPI tables.
 288
 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.
 292
 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.
 298
 299
 300 Other Pieces
 301 ------------
 302
 303 Watchdog
 304
 305 A watchdog timer is provided that implements the Linux-standard
 306 watchdog timer interface.  It has three module parameters that can be
 307 used to control it:
 308
 309   insmod ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
 310       preaction=<preaction type>
 311
 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).
 315
 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
 318 "reset".
 319
 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.
 323
 324 When compiled into the kernel, the kernel command line is available
 325 for configuring the watchdog:
 326
 327   ipmi_wdog=<timeout>[,<pretimeout>[,<option>[,<options>....]]]
 328
 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.
 334
 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.
 338
 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
 341 must use mode 2.