Documentation/i2c/busses/i2c-piix4.rst

   1 =======================
   2 Kernel driver i2c-piix4
   3 =======================
   4
   5 Supported adapters:
   6   * Intel 82371AB PIIX4 and PIIX4E
   7   * Intel 82443MX (440MX)
   8     Datasheet: Publicly available at the Intel website
   9   * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges
  10     Datasheet: Only available via NDA from ServerWorks
  11   * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
  12     Datasheet: Not publicly available
  13     SB700 register reference available at:
  14     http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf
  15   * AMD SP5100 (SB700 derivative found on some server mainboards)
  16     Datasheet: Publicly available at the AMD website
  17     http://support.amd.com/us/Embedded_TechDocs/44413.pdf
  18   * AMD Hudson-2, ML, CZ
  19     Datasheet: Not publicly available
  20   * Hygon CZ
  21     Datasheet: Not publicly available
  22   * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
  23     Datasheet: Publicly available at the SMSC website http://www.smsc.com
  24
  25 Authors:
  26         - Frodo Looijaard <frodol@dds.nl>
  27         - Philip Edelbrock <phil@netroedge.com>
  28
  29
  30 Module Parameters
  31 -----------------
  32
  33 * force: int
  34   Forcibly enable the PIIX4. DANGEROUS!
  35 * force_addr: int
  36   Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!
  37
  38
  39 Description
  40 -----------
  41
  42 The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
  43 functionality. Among other things, it implements the PCI bus. One of its
  44 minor functions is implementing a System Management Bus. This is a true
  45 SMBus - you can not access it on I2C levels. The good news is that it
  46 natively understands SMBus commands and you do not have to worry about
  47 timing problems. The bad news is that non-SMBus devices connected to it can
  48 confuse it mightily. Yes, this is known to happen...
  49
  50 Do ``lspci -v`` and see whether it contains an entry like this::
  51
  52   0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
  53                Flags: medium devsel, IRQ 9
  54
  55 Bus and device numbers may differ, but the function number must be
  56 identical (like many PCI devices, the PIIX4 incorporates a number of
  57 different 'functions', which can be considered as separate devices). If you
  58 find such an entry, you have a PIIX4 SMBus controller.
  59
  60 On some computers (most notably, some Dells), the SMBus is disabled by
  61 default. If you use the insmod parameter 'force=1', the kernel module will
  62 try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
  63 correct address for this module, you could get in big trouble (read:
  64 crashes, data corruption, etc.). Try this only as a last resort (try BIOS
  65 updates first, for example), and backup first! An even more dangerous
  66 option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
  67 'force' does, but it will also set a new base I/O port address. The SMBus
  68 parts of the PIIX4 needs a range of 8 of these addresses to function
  69 correctly. If these addresses are already reserved by some other device,
  70 you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
  71 ABOUT WHAT YOU ARE DOING!
  72
  73 The PIIX4E is just an new version of the PIIX4; it is supported as well.
  74 The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
  75 this driver on those mainboards.
  76
  77 The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
  78 identical to the PIIX4 in I2C/SMBus support.
  79
  80 The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two
  81 PIIX4-compatible SMBus controllers. If your BIOS initializes the
  82 secondary controller, it will be detected by this driver as
  83 an "Auxiliary SMBus Host Controller".
  84
  85 If you own Force CPCI735 motherboard or other OSB4 based systems you may need
  86 to change the SMBus Interrupt Select register so the SMBus controller uses
  87 the SMI mode.
  88
  89 1) Use ``lspci`` command and locate the PCI device with the SMBus controller:
  90    00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
  91    The line may vary for different chipsets. Please consult the driver source
  92    for all possible PCI ids (and ``lspci -n`` to match them). Let's assume the
  93    device is located at 00:0f.0.
  94 2) Now you just need to change the value in 0xD2 register. Get it first with
  95    command: ``lspci -xxx -s 00:0f.0``
  96    If the value is 0x3 then you need to change it to 0x1:
  97    ``setpci  -s 00:0f.0 d2.b=1``
  98
  99 Please note that you don't need to do that in all cases, just when the SMBus is
 100 not working properly.
 101
 102
 103 Hardware-specific issues
 104 ------------------------
 105
 106 This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
 107 Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
 108 which can easily get corrupted due to a state machine bug. These are mostly
 109 Thinkpad laptops, but desktop systems may also be affected. We have no list
 110 of all affected systems, so the only safe solution was to prevent access to
 111 the SMBus on all IBM systems (detected using DMI data.)
 112
 113
 114 Description in the ACPI code
 115 ----------------------------
 116
 117 Device driver for the PIIX4 chip creates a separate I2C bus for each of its
 118 ports::
 119
 120     $ i2cdetect -l
 121     ...
 122     i2c-7   unknown         SMBus PIIX4 adapter port 0 at 0b00      N/A
 123     i2c-8   unknown         SMBus PIIX4 adapter port 2 at 0b00      N/A
 124     i2c-9   unknown         SMBus PIIX4 adapter port 1 at 0b20      N/A
 125     ...
 126
 127 Therefore if you want to access one of these busses in the ACPI code, port
 128 subdevices are needed to be declared inside the PIIX device::
 129
 130     Scope (\_SB_.PCI0.SMBS)
 131     {
 132         Name (_ADR, 0x00140000)
 133
 134         Device (SMB0) {
 135             Name (_ADR, 0)
 136         }
 137         Device (SMB1) {
 138             Name (_ADR, 1)
 139         }
 140         Device (SMB2) {
 141             Name (_ADR, 2)
 142         }
 143     }
 144
 145 If this is not the case for your UEFI firmware and you don't have access to the
 146 source code, you can use ACPI SSDT Overlays to provide the missing parts. Just
 147 keep in mind that in this case you would need to load your extra SSDT table
 148 before the piix4 driver starts, i.e. you should provide SSDT via initrd or EFI
 149 variable methods and not via configfs.
 150
 151 As an example of usage here is the ACPI snippet code that would assign jc42
 152 driver to the 0x1C device on the I2C bus created by the PIIX port 0::
 153
 154     Device (JC42) {
 155         Name (_HID, "PRP0001")
 156         Name (_DDN, "JC42 Temperature sensor")
 157         Name (_CRS, ResourceTemplate () {
 158             I2cSerialBusV2 (
 159                 0x001c,
 160                 ControllerInitiated,
 161                 100000,
 162                 AddressingMode7Bit,
 163                 "\\_SB.PCI0.SMBS.SMB0",
 164                 0
 165             )
 166         })
 167
 168         Name (_DSD, Package () {
 169             ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 170             Package () {
 171                 Package () { "compatible", Package() { "jedec,jc-42.4-temp" } },
 172             }
 173         })
 174     }