2                          The Linux IPMI Driver
   3                          ---------------------
   4                              Corey Minyard
   5                          <>
   6                            <>
   8The Intelligent Platform Management Interface, or IPMI, is a
   9standard for controlling intelligent devices that monitor a system.
  10It provides for dynamic discovery of sensors in the system and the
  11ability to monitor the sensors and be informed when the sensor's
  12values change or go outside certain boundaries.  It also has a
  13standardized database for field-replaceable units (FRUs) and a watchdog
  16To use this, you need an interface to an IPMI controller in your
  17system (called a Baseboard Management Controller, or BMC) and
  18management software that can use the IPMI system.
  20This document describes how to use the IPMI driver for Linux.  If you
  21are not familiar with IPMI itself, see the web site at
  22  IPMI is a big
  23subject and I can't cover it all here!
  28The Linux IPMI driver is modular, which means you have to pick several
  29things to have it work right depending on your hardware.  Most of
  30these are available in the 'Character Devices' menu then the IPMI
  33No matter what, you must pick 'IPMI top-level message handler' to use
  34IPMI.  What you do beyond that depends on your needs and hardware.
  36The message handler does not provide any user-level interfaces.
  37Kernel code (like the watchdog) can still use it.  If you need access
  38from userland, you need to select 'Device interface for IPMI' if you
  39want access through a device driver.
  41The driver interface depends on your hardware.  If your system
  42properly provides the SMBIOS info for IPMI, the driver will detect it
  43and just work.  If you have a board with a standard interface (These
  44will generally be either "KCS", "SMIC", or "BT", consult your hardware
  45manual), choose the 'IPMI SI handler' option.
  47You should generally enable ACPI on your system, as systems with IPMI
  48can have ACPI tables describing them.
  50If you have a standard interface and the board manufacturer has done
  51their job correctly, the IPMI controller should be automatically
  52detected (via ACPI or SMBIOS tables) and should just work.  Sadly,
  53many boards do not have this information.  The driver attempts
  54standard defaults, but they may not work.  If you fall into this
  55situation, you need to read the section below named 'The SI Driver'.
  57IPMI defines a standard watchdog timer.  You can enable this with the
  58'IPMI Watchdog Timer' config option.  If you compile the driver into
  59the kernel, then via a kernel command-line option you can have the
  60watchdog timer start as soon as it initializes.  It also have a lot
  61of other options, see the 'Watchdog' section below for more details.
  62Note that you can also have the watchdog continue to run if it is
  63closed (by default it is disabled on close).  Go into the 'Watchdog
  64Cards' menu, enable 'Watchdog Timer Support', and enable the option
  65'Disable watchdog shutdown on close'.
  67IPMI systems can often be powered off using IPMI commands.  Select
  68'IPMI Poweroff' to do this.  The driver will auto-detect if the system
  69can be powered off by IPMI.  It is safe to enable this even if your
  70system doesn't support this option.  This works on ATCA systems, the
  71Radisys CPI1 card, and any IPMI system that supports standard chassis
  72management commands.
  74If you want the driver to put an event into the event log on a panic,
  75enable the 'Generate a panic event to all BMCs on a panic' option.  If
  76you want the whole panic string put into the event log using OEM
  77events, enable the 'Generate OEM events containing the panic string'
  80Basic Design
  83The Linux IPMI driver is designed to be very modular and flexible, you
  84only need to take the pieces you need and you can use it in many
  85different ways.  Because of that, it's broken into many chunks of
  86code.  These chunks (by module name) are:
  88ipmi_msghandler - This is the central piece of software for the IPMI
  89system.  It handles all messages, message timing, and responses.  The
  90IPMI users tie into this, and the IPMI physical interfaces (called
  91System Management Interfaces, or SMIs) also tie in here.  This
  92provides the kernelland interface for IPMI, but does not provide an
  93interface for use by application processes.
  95ipmi_devintf - This provides a userland IOCTL interface for the IPMI
  96driver, each open file for this device ties in to the message handler
  97as an IPMI user.
  99ipmi_si - A driver for various system interfaces.  This supports KCS,
 100SMIC, and BT interfaces.
 102ipmi_watchdog - IPMI requires systems to have a very capable watchdog
 103timer.  This driver implements the standard Linux watchdog timer
 104interface on top of the IPMI message handler.
 106ipmi_poweroff - Some systems support the ability to be turned off via
 107IPMI commands.
 109These are all individually selectable via configuration options.
 111Note that the KCS-only interface has been removed.  The af_ipmi driver
 112is no longer supported and has been removed because it was impossible
 113to do 32 bit emulation on 64-bit kernels with it.
 115Much documentation for the interface is in the include files.  The
 116IPMI include files are:
 118net/af_ipmi.h - Contains the socket interface.
 120linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
 122linux/ipmi_smi.h - Contains the interface for system management interfaces
 123(things that interface to IPMI controllers) to use.
 125linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.
 131The IPMI addressing works much like IP addresses, you have an overlay
 132to handle the different address types.  The overlay is:
 134  struct ipmi_addr
 135  {
 136        int   addr_type;
 137        short channel;
 138        char  data[IPMI_MAX_ADDR_SIZE];
 139  };
 141The addr_type determines what the address really is.  The driver
 142currently understands two different types of addresses.
 144"System Interface" addresses are defined as:
 146  struct ipmi_system_interface_addr
 147  {
 148        int   addr_type;
 149        short channel;
 150  };
 152and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE.  This is used for talking
 153straight to the BMC on the current card.  The channel must be
 156Messages that are destined to go out on the IPMB bus use the
 157IPMI_IPMB_ADDR_TYPE address type.  The format is
 159  struct ipmi_ipmb_addr
 160  {
 161        int           addr_type;
 162        short         channel;
 163        unsigned char slave_addr;
 164        unsigned char lun;
 165  };
 167The "channel" here is generally zero, but some devices support more
 168than one channel, it corresponds to the channel as defined in the IPMI
 175Messages are defined as:
 177struct ipmi_msg
 179        unsigned char netfn;
 180        unsigned char lun;
 181        unsigned char cmd;
 182        unsigned char *data;
 183        int           data_len;
 186The driver takes care of adding/stripping the header information.  The
 187data portion is just the data to be send (do NOT put addressing info
 188here) or the response.  Note that the completion code of a response is
 189the first item in "data", it is not stripped out because that is how
 190all the messages are defined in the spec (and thus makes counting the
 191offsets a little easier :-).
 193When using the IOCTL interface from userland, you must provide a block
 194of data for "data", fill it, and set data_len to the length of the
 195block of data, even when receiving messages.  Otherwise the driver
 196will have no place to put the message.
 198Messages coming up from the message handler in kernelland will come in
 201  struct ipmi_recv_msg
 202  {
 203        struct list_head link;
 205        /* The type of message as defined in the "Receive Types"
 206           defines above. */
 207        int         recv_type;
 209        ipmi_user_t      *user;
 210        struct ipmi_addr addr;
 211        long             msgid;
 212        struct ipmi_msg  msg;
 214        /* Call this when done with the message.  It will presumably free
 215           the message and do any other necessary cleanup. */
 216        void (*done)(struct ipmi_recv_msg *msg);
 218        /* Place-holder for the data, don't make any assumptions about
 219           the size or existence of this, since it may change. */
 220        unsigned char   msg_data[IPMI_MAX_MSG_LENGTH];
 221  };
 223You should look at the receive type and handle the message
 227The Upper Layer Interface (Message Handler)
 230The upper layer of the interface provides the users with a consistent
 231view of the IPMI interfaces.  It allows multiple SMI interfaces to be
 232addressed (because some boards actually have multiple BMCs on them)
 233and the user should not have to care what type of SMI is below them.
 236Creating the User
 238To user the message handler, you must first create a user using
 239ipmi_create_user.  The interface number specifies which SMI you want
 240to connect to, and you must supply callback functions to be called
 241when data comes in.  The callback function can run at interrupt level,
 242so be careful using the callbacks.  This also allows to you pass in a
 243piece of data, the handler_data, that will be passed back to you on
 244all calls.
 246Once you are done, call ipmi_destroy_user() to get rid of the user.
 248From userland, opening the device automatically creates a user, and
 249closing the device automatically destroys the user.
 254To send a message from kernel-land, the ipmi_request() call does
 255pretty much all message handling.  Most of the parameter are
 256self-explanatory.  However, it takes a "msgid" parameter.  This is NOT
 257the sequence number of messages.  It is simply a long value that is
 258passed back when the response for the message is returned.  You may
 259use it for anything you like.
 261Responses come back in the function pointed to by the ipmi_recv_hndl
 262field of the "handler" that you passed in to ipmi_create_user().
 263Remember again, these may be running at interrupt level.  Remember to
 264look at the receive type, too.
 266From userland, you fill out an ipmi_req_t structure and use the
 267IPMICTL_SEND_COMMAND ioctl.  For incoming stuff, you can use select()
 268or poll() to wait for messages to come in.  However, you cannot use
 269read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
 270ipmi_recv_t structure to actually get the message.  Remember that you
 271must supply a pointer to a block of data in the field, and
 272you must fill in the msg.data_len field with the  messaf the datae isceisat the receitor o place to actuallo put the message.

will tde an

Whef yoo send I comma (s whici as defineo by thl Host-orolde4-bis of
tar net pefor the IPer sp)ut on the IPMB bMI, the driver wiof
will geneeate e response automaticallsayusing the commahe

wille kof messages.  Noou
that yor shoulNEVERof meld with thr " doer"a>field oahe messa,oe that is
properly cleng ut the message.

Note thak whesependiMI, there it an ipmi_reque_t suppcv_msst() caa>

hrouis, since is isrickity tm manaln youow MB diff ge.

The driver takes care or poomine for IPEM event, and receaging
(thingt on the IPMB bud havsephat y)ed.Tohe receian
wils noe automaticallo be sant

events, you must calt ipmiet_gfse_a>even()t, and see the
wilicoedpriatelo bdeldrivneed to>the firso user aant
wil cale receivacalM events thao come ied

all channs n if ya, don's ca)ed.O-onl done

From userland reqvanerene IOCert aru provid9; to do thesk functioied

ThL_power Laye(SMI)er Interfaa>


th thoroldea tyeregnsisd,or>a>hrou i oanhe SMunregnsisdon, and tha>
albfsetscare fied

Thx/ipmi_smi.  definef the interfact for management interfac,nd ta>

ThSI D driver

ThSI e driveo allowg uto 4he Ks, or SCMI interfaces to ia configgna>
th tha>system.Blly fa mu,ndu cah thACPI ectabsrf For interfac,nmmahe

y mu pbThx/ipmii.ove ty=<e ty1>,<e ty2>....a>
     uppor=<uppo1>,<uppo2>...dr adr=<r ad1>,<r ad2>...a>
     e gspacthin=<sp1>,<sp2>, gsizen=<size1>,<size2>,...a>
     e gshifor=<shifo1>,<shifo2>,...a>
     s slave_adr=<r ad1>,<r ad2>,...a>
     t fce_kx/ipd=<enctab1>,<enctab2>,...a>
     kx/ipd_max_busroy_=<usg ti1>,<usg ti2>,...a>
     unload_k wh_stpay=[0|1]a>
     tryy fa mus=[0|1] tryymi=[0|1] tryacpi=[0|1]a>
     tryplatinfo=[0|1] trypci=[0|1]a>

the first iter for ta>
first interfa,nd cspost iter for tnd cspost interfa,netpec.

(ncr sndardhe IPMI interfaiatb0xca2emmahe

Thy othe>ry...diystemdisctabmdisce ovyeo by tirit correspoaging


The gspacthinhe parametegceito the number obyeatebetw beesucnececeian
and thr staof addreIt i0xca2,ny tnat the addresr for tnd cspoan

The gsizenhe parametegceisth the  messaaeregnsisd,oa ibyeatre.T ta>
dats useo be IPMIsi8-4-beld viem, bue it mabivd sovide largiver
The aa , anwritive typt ta>specifdied

tha32ebitbMI, the IPMa>date mas na>


use on is ner, a>

emtion.Nnforippln This ie au-damectgna>
systeld witbrokingt interruceeraighy nee caMnctabel,

aly the interfacefailed tt wore.T ta>

Whee coilssed t to thn kern,n, th; parametsou cabeer specifd t on ta>

x/ipmii.e ty=<e ty1>,<e ty2>...a>
     x/ipmii.uppor=<uppo1>,<uppo2>...dx/ipmii.r adr=<r ad1>,<r ad2>...a>
     x/ipmii.irqr=<irq1>,<irq2>...>x/ipmii.eryy fa mus=[0|1]a>
     x/ipmii.e gspacthin=<sp1>,<sp2>,...a>
     x/ipmii.e gsizen=<size1>,<size2>,...a>
     x/ipmii.e gshifor=<shifo1>,<shifo2>,...a>
     x/ipmii.s slave_adr=<r ad1>,<r ad2>,...a>
     x/ipmii.t fce_kx/ipd=<enctab1>,<enctab2>,...a>
     x/ipmii.kx/ipd_max_busroy_=<usg ti1>,<usg ti2>,...a>

wil calt the user to
tsthe interfacesuckied

This ie doll usin/sys/y modue/x/ipmii/; paramets/hotmodats whici an a
 r a|n movo,kcs|bt|i_sc,mem|i/o,<r addre>[,<opo1>[,<opo2>[,...]]]a>
tha dolI interfait on th="lils.  Thel&quooptta&quoiserias:
 rsp=<e gspacthi>s:
 rsi=<e gsize>s:
 rsh=<e gshifo>s:
 x/ib=<i/ibhs slaMe ad>s:
and tseou havn ths nanmeanthinhaemdiscupasseaboeied.a>Note tha, you
Note thak when movthisymis interfa,a>
the first  fr ; parametso(sive typee addrese typeefdke addret()



the addresc nane fro for tnraw b >use devicr for tne IPMI interfaube

the functia>
ipmgetmi_s_e f ()ats whics retu at then alloming structuas:

      enumhx/ipme ad_src e ad_src;s:
     ng struse devic*e d;s:
      a>     ng strus{a>
      a>     nnnnnnnnn  voi*acpi_e hand;s:
      a>     n} acpi_e f ;s:
     n} a ad_e f ;s:

Note thar the d a pointeThis cludssed in>theboeing structu,nmmahe


y mu pbThx/ipme watchdog tio o=<e>rprsg tio o=<e>rauncti=<rcmptierype>s:
    prsauncti=<prsaunctierype> prsop=<prsoperype> r sta_now=xs:
    nowayd o=x ifnum_to_s u=ia>

the firs dolregnsisdfdied

wils noy benctabd)es.  Noou

wiloccur d i40asecspo (10asecspon b r fe n thg tio o)ied

Thaunctiee may bta&quoe d gta"ta&quoa wsd_cycleta" for &quoa wsd_offta"mmahe

the driveThis f foedossaf thprsg tio oied

Thprsopee may bseant tta&quoprsop_n doer"a fonnMpropntatiMpn ahprsg tio o,a>

provihe data t fader frot the watchdoe devicw tnat thprsg tio oa>

the devi,oaiesellied

Whee coilssed t to thn kern,n, thn kernhe comma ="liei anvailctabng

x/ipme watchd.g tio o=<e>rx/ipme watchd.prsg tio o=<e>a>
     rx/ipme watchd.auncti=<rcmptierype>s:
     rx/ipme watchd.prsauncti=<prsaunctierype>s:
     rx/ipme watchd.prsop=<prsoperype>s:
     rx/ipme watchd.r sta_now=xs:
     rx/ipme watchd.nowayd o=xs:

Thoumptietscarr ths nane at thy modul; paramethoumptieied

Note than if yan uso>thNIPMprsaunctier for tne watchdts, yoMUST NOTa>
thn_sne watchded.  Triei an t fasonctabiwaeht toell i oanhNMIa>

thebiliayId ta butemi-c mufror d c mufra>
th tha>syst s evt lhdoi oalpanice ccurned.n if yaenctabtt ta>

tacr sndardhe IPMs evt f fortie.  If yoenctaba>

Thfieldtseteatisossaf ths evts erias:
thmecsageht to thrraighplavia>

tha11hbyeat, multiimeemecsagesnr wiabeessntee witinc fasati()

th thSELessaf thlocnl()
gs evt g genet f,af ths evterecedriver frot thlocnllommagecume()

syst requesseta p wsddown,a>
pperhe IPMo commasvn tdoe, isup.  This irupa pofd t a>

syst e f,ny tnap wsd it pn a>tacfewasecspon)ge.Seteatia>

t/a>pc/sys/e d/x/ip/a wsdoffmp wsdcyclels.a>Note than it tha>systa>

Thta&quoifnum_to_s uta" paramethr specifies whici interfait thp wsdoffa>
the firs doa>

Note than if yah havACPI enctabdt;t tha>syst r wilp hrer l usinACPI t he

Nor"> a>ThoriginaleLXR softwscaro by th> pjects/lxr">LXR e couniay5a0s="line" name=6L251"65211

<21x ws@l5L183nopnta.ftwscaroby th>
R24p/IPd=5L"65 ASpntatinat thp