1.\" $OpenBSD: ipmi.4,v 1.11 2007/05/31 19:19:50 jmc Exp $ 2.\" 3.\" Copyright (c) 2005 Marco Peereboom <marco@openbsd.org> 4.\" Text was heavily borrowed from the IPMI spec V1.5 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" TORTIOUS ACTION, ARISING OUT OF 16.\" PERFORMANCE OF THIS SOFTWARE. 17.Dd $Mdocdate: May 31 2007 $ 18.Dt IPMI 4 19.Os 20.Sh NAME 21.Nm ipmi 22.Nd Intelligent Platform Management Interface driver 23.Sh SYNOPSIS 24.Cd "ipmi0 at mainbus0" 25.Sh DESCRIPTION 26The 27.Nm 28term Intelligent Platform Management refers to autonomous monitoring and 29recovery features implemented directly in platform management hardware and 30firmware. 31The key characteristics of Intelligent Platform Management is that 32inventory, monitoring, logging, and recovery control functions are available 33independent of the main processor, BIOS, and operating system. 34.Pp 35Platform status information can be obtained and recovery actions initiated 36under situations where vendor "in-band" management mechanisms are unavailable. 37The independent monitoring, logging, and access functions available through IPMI 38provide a level of manageability built in to the platform hardware. 39This can support systems where there is no systems management software 40available for a particular operating system. 41.Pp 42At the heart of the IPMI architecture is a microcontroller called 43the Baseboard Management Controller (BMC). 44The BMC provides the intelligence behind Intelligent Platform Management. 45The BMC manages the interface between system management software 46and the platform management hardware, provides autonomous monitoring, 47event logging, and recovery control and serves as the gateway 48between systems management software and hardware. 49.Sh IPMI MESSAGING 50IPMI uses message-based interfaces for the different interfaces to the platform 51management subsystems. 52All IPMI messages share the same fields in the message "payload", 53regardless of the interface (transport) that they're transferred over. 54IPMI messaging uses a request/response protocol. 55IPMI request messages are commonly referred to as commands. 56The use of request/response protocol facilitates the transfer of 57IPMI messages over different transports. 58IPMI commands are grouped into functional command sets 59using a field called network function code. 60There are command sets for sensor and event related commands, 61chassis commands etc. 62This functional grouping makes it easier to organize and manage 63the assignment and allocation of command values. 64.Sh SENSOR MODEL 65Access to monitored information such as temperatures, voltages, fan status 66etc., is provided via the IPMI Sensor Model. 67Instead of providing direct access to the monitoring hardware, 68IPMI provides access by abstracted sensor commands 69such as the "Get Sensor Reading" command, 70implemented via a management controller. 71This approach isolates the software from changes in the 72platform management hardware implementation. 73.Pp 74Sensors are classified according to the type of readings they provide 75and/or the type of events they generate. 76A sensor can return either an analog or discrete reading. 77Sensor events can be discrete or threshold-based. 78.Sh SYSTEM EVENT LOG AND EVENT MESSAGES 79The BMC provides a centralized non-volatile System Event Log, or SEL. 80Having the SEL and logging functions managed by the BMC 81helps ensure that post-mortem logging information is available 82should a failure occur that disables the systems processor(s). 83.Pp 84A set of IPMI commands allows the SEL to be read and cleared 85and for events to be added to the SEL. 86The common request message (command) 87used for adding events to the SEL is referred to as an Event Message. 88.Sh SENSOR DATA RECORDS & CAPABILITIES COMMANDS 89IPMI's extensibility and scalability mean that 90each platform implementation can have 91a different population of management controllers and sensors and 92different event generation capabilities. 93The design of IPMI allows system 94management software to retrieve information from the platform 95and automatically configure itself to the platform's capabilities. 96.Pp 97Information that describes the platform management capabilities 98is provided via two mechanisms: 99Capabilities Commands and Sensor Data Records (SDRs). 100Capabilities commands are commands within the IPMI command sets that return 101fields that provide information on other commands and functions the controller 102can handle. 103.Sh SYSTEMS INTERFACES 104IPMI defines three standardized systems interfaces that systems software uses 105for transferring IPMI messages to the BMC. 106In order to support a variety of microcontrollers, 107IPMI offers a choice of systems interfaces. 108The system interfaces are similar enough so that 109a single driver can handle all IPMI system interfaces. 110.Bl -tag -width Ds 111.It Keyboard Controller Style (KCS) 112The bit definitions and operation of the registers follows that used in the 113Intel 8742 Universal Peripheral Interface microcontroller. 114The term "Keyboard Controller Style" reflects the fact that 115the 8742 interface was used as the legacy keyboard controller interface 116in PC architecture computer systems. 117This interface is available built in to several commercially available 118microcontrollers. 119Data is transferred across the KCS interface using a per-byte handshake. 120.It System Management Interface Chip (SMIC) 121The SMIC interface provides an alternative 122when the implementer wishes to use a microcontroller for the BMC 123that does not have the built-in hardware for a KCS interface. 124This interface is a three I/O port interface that can be 125implemented using a simple ASIC, FPGA, or discrete logic devices. 126It may also be built in to a custom-designed management controller. 127Like the KCS interface, 128a per-byte handshake is also used 129for transferring data across the SMIC interface. 130.It Block Transfer (BT) 131This interface provides a higher performance system interface option. 132Unlike the KCS and SMIC interfaces, 133a per-block handshake is used for transferring data across the interface. 134The BT interface also provides an alternative to using 135a controller with a built-in KCS interface. 136The BT interface has three I/O mapped ports. 137A typical implementation includes hardware buffers for holding 138upstream and downstream message blocks. 139The BT interface can be implemented using an ASIC or FPGA 140or may be built in to a custom-designed management controller. 141.El 142.Sh WATCHDOG 143IPMI provides 144.Xr watchdog 4 145timer functionality. 146Once configured, if the watchdog is not reset within 147a certain period of time, 148it will timeout and the server will reset. 149The reset will occur regardless of the recoverability of the hang or crash. 150.Pp 151Example of enabling a watchdog: 152.Pp 153.Dl # sysctl kern.watchdog.period=10 154.Pp 155In this case if the watchdog is not reset, 156it'll reboot the server after roughly 10 seconds. 157.Pp 158Example of disabling the watchdog: 159.Pp 160.Dl # sysctl kern.watchdog.period=0 161.Sh SEE ALSO 162.Xr watchdog 4 , 163.Xr sensorsd 8 , 164.Xr sysctl 8 165.Sh HISTORY 166The 167.Nm 168driver first appeared in 169.Ox 3.9 170and conforms to the IPMI 1.5 specification. 171.Sh AUTHORS 172The 173.Nm 174driver was written by 175.An Jordan Hargrave Aq jordan@openbsd.org . 176