Documentation/driver-api/ipmb.rst

   1 ==============================
   2 IPMB Driver for a Satellite MC
   3 ==============================
   4
   5 The Intelligent Platform Management Bus or IPMB, is an
   6 I2C bus that provides a standardized interconnection between
   7 different boards within a chassis. This interconnection is
   8 between the baseboard management (BMC) and chassis electronics.
   9 IPMB is also associated with the messaging protocol through the
  10 IPMB bus.
  11
  12 The devices using the IPMB are usually management
  13 controllers that perform management functions such as servicing
  14 the front panel interface, monitoring the baseboard,
  15 hot-swapping disk drivers in the system chassis, etc...
  16
  17 When an IPMB is implemented in the system, the BMC serves as
  18 a controller to give system software access to the IPMB. The BMC
  19 sends IPMI requests to a device (usually a Satellite Management
  20 Controller or Satellite MC) via IPMB and the device
  21 sends a response back to the BMC.
  22
  23 For more information on IPMB and the format of an IPMB message,
  24 refer to the IPMB and IPMI specifications.
  25
  26 IPMB driver for Satellite MC
  27 ----------------------------
  28
  29 ipmb-dev-int - This is the driver needed on a Satellite MC to
  30 receive IPMB messages from a BMC and send a response back.
  31 This driver works with the I2C driver and a userspace
  32 program such as OpenIPMI:
  33
  34 1) It is an I2C slave backend driver. So, it defines a callback
  35    function to set the Satellite MC as an I2C slave.
  36    This callback function handles the received IPMI requests.
  37
  38 2) It defines the read and write functions to enable a user
  39    space program (such as OpenIPMI) to communicate with the kernel.
  40
  41
  42 Load the IPMB driver
  43 --------------------
  44
  45 The driver needs to be loaded at boot time or manually first.
  46 First, make sure you have the following in your config file:
  47 CONFIG_IPMB_DEVICE_INTERFACE=y
  48
  49 1) If you want the driver to be loaded at boot time:
  50
  51 a) Add this entry to your ACPI table, under the appropriate SMBus::
  52
  53      Device (SMB0) // Example SMBus host controller
  54      {
  55      Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
  56      Name (_UID, 0) // Unique ID of particular host controller
  57      :
  58      :
  59        Device (IPMB)
  60        {
  61          Name (_HID, "IPMB0001") // IPMB device interface
  62          Name (_UID, 0) // Unique device identifier
  63        }
  64      }
  65
  66 b) Example for device tree::
  67
  68      &i2c2 {
  69             status = "okay";
  70
  71             ipmb@10 {
  72                     compatible = "ipmb-dev";
  73                     reg = <0x10>;
  74                     i2c-protocol;
  75             };
  76      };
  77
  78 If xmit of data to be done using raw i2c block vs smbus
  79 then "i2c-protocol" needs to be defined as above.
  80
  81 2) Manually from Linux::
  82
  83      modprobe ipmb-dev-int
  84
  85
  86 Instantiate the device
  87 ----------------------
  88
  89 After loading the driver, you can instantiate the device as
  90 described in 'Documentation/i2c/instantiating-devices.rst'.
  91 If you have multiple BMCs, each connected to your Satellite MC via
  92 a different I2C bus, you can instantiate a device for each of
  93 those BMCs.
  94
  95 The name of the instantiated device contains the I2C bus number
  96 associated with it as follows::
  97
  98   BMC1 ------ IPMB/I2C bus 1 ---------|   /dev/ipmb-1
  99                                 Satellite MC
 100   BMC1 ------ IPMB/I2C bus 2 ---------|   /dev/ipmb-2
 101
 102 For instance, you can instantiate the ipmb-dev-int device from
 103 user space at the 7 bit address 0x10 on bus 2::
 104
 105   # echo ipmb-dev 0x1010 > /sys/bus/i2c/devices/i2c-2/new_device
 106
 107 This will create the device file /dev/ipmb-2, which can be accessed
 108 by the user space program. The device needs to be instantiated
 109 before running the user space program.