Kernel driver i2c-piix4

지원 PIIX4 호환 사우스브리지

`i2c-piix4`는 Intel 82371AB PIIX4/PIIX4E와 82443MX(440MX), ServerWorks OSB4·CSB5·CSB6·HT-1000·HT-1100, ATI IXP200·IXP300·IXP400·SB600·SB700·SB800을 지원합니다.

또한 AMD SP5100, Hudson-2·ML·CZ, Hygon CZ, Standard Microsystems(SMSC) SLC90E66(Victory66) 사우스브리지를 지원합니다.

Intel 데이터시트는 공개되어 있고 ServerWorks 자료는 NDA로만 제공됩니다. ATI 자료는 공개되지 않았지만 SB700 레지스터 참조는 `http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf`에 있습니다.

AMD SP5100 데이터시트는 `http://support.amd.com/us/Embedded_TechDocs/44413.pdf`에 공개되어 있습니다. AMD Hudson-2·ML·CZ와 Hygon CZ 자료는 공개되지 않았습니다. SMSC SLC90E66 자료는 `http://www.smsc.com`에서 공개됩니다.

작성자는 Frodo Looijaard <frodol@dds.nl>와 Philip Edelbrock <phil@netroedge.com>입니다.

=======================
Kernel driver i2c-piix4
=======================

Supported adapters:
  * Intel 82371AB PIIX4 and PIIX4E
  * Intel 82443MX (440MX)
    Datasheet: Publicly available at the Intel website
  * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges
    Datasheet: Only available via NDA from ServerWorks
  * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
    Datasheet: Not publicly available
    SB700 register reference available at:
    http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf
  * AMD SP5100 (SB700 derivative found on some server mainboards)
    Datasheet: Publicly available at the AMD website
    http://support.amd.com/us/Embedded_TechDocs/44413.pdf
  * AMD Hudson-2, ML, CZ
    Datasheet: Not publicly available
  * Hygon CZ
    Datasheet: Not publicly available
  * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
    Datasheet: Publicly available at the SMSC website http://www.smsc.com

Authors:
        - Frodo Looijaard <frodol@dds.nl>
        - Philip Edelbrock <phil@netroedge.com>

위험한 강제 활성화 매개변수

정수형 `force`는 PIIX4를 강제로 활성화합니다. 위험합니다.

정수형 `force_addr`는 지정한 주소에서 PIIX4를 강제로 활성화합니다. 극도로 위험합니다.

Module Parameters
-----------------

* force: int
  Forcibly enable the PIIX4. DANGEROUS!
* force_addr: int
  Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!

PIIX4 SMBus 특성과 안전 경고

PIIX4의 정식 명칭은 82371AB이며 PCI 버스 등 많은 기능을 구현한 Intel 칩입니다. 부기능 가운데 하나가 System Management Bus입니다.

이는 진정한 SMBus이므로 I2C 계층으로 접근할 수 없습니다. SMBus 명령을 하드웨어가 직접 이해해 타이밍 문제를 걱정할 필요가 없다는 장점이 있지만, SMBus가 아닌 장치가 연결되면 컨트롤러가 크게 혼란스러울 수 있으며 실제 사례가 알려져 있습니다.

`lspci -v`에서 `0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)`와 IRQ 9 같은 항목을 찾으십시오. 버스와 장치 번호는 다를 수 있지만 기능 번호는 같아야 합니다. PIIX4는 여러 독립 기능을 포함하기 때문입니다. 이런 항목이 있으면 PIIX4 SMBus 컨트롤러가 있습니다.

일부 컴퓨터, 특히 일부 Dell 시스템은 기본적으로 SMBus가 비활성화되어 있습니다. `force=1`을 사용하면 커널 모듈이 활성화를 시도하지만 매우 위험합니다. BIOS가 올바른 주소를 설정하지 않았다면 충돌이나 데이터 손상 등이 생길 수 있습니다. BIOS 업데이트 같은 방법을 먼저 시도하고 반드시 백업한 뒤 최후 수단으로만 사용하십시오.

`force_addr=<IOPORT>`는 `force`처럼 PIIX4를 켤 뿐 아니라 새 기본 I/O 포트 주소도 설정하므로 더 위험합니다. PIIX4 SMBus가 정상 동작하려면 연속된 주소 8개가 필요합니다. 다른 장치가 이미 예약한 주소와 겹치면 심각한 문제가 발생합니다. 수행 내용을 매우 확실히 이해하지 못한다면 사용하지 마십시오.

PIIX4E는 PIIX4의 새 버전으로 역시 지원합니다. PIIX와 PIIX3에는 SMBus나 I2C 버스가 없으므로 해당 메인보드에서는 이 드라이버를 사용할 수 없습니다.

ServerWorks 사우스브리지, Intel 440MX, Victory66은 I2C/SMBus 지원 면에서 PIIX4와 동일합니다.

Description
-----------

The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
functionality. Among other things, it implements the PCI bus. One of its
minor functions is implementing a System Management Bus. This is a true
SMBus - you can not access it on I2C levels. The good news is that it
natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...

Do ``lspci -v`` and see whether it contains an entry like this::

  0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
               Flags: medium devsel, IRQ 9

Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
different 'functions', which can be considered as separate devices). If you
find such an entry, you have a PIIX4 SMBus controller.

On some computers (most notably, some Dells), the SMBus is disabled by
default. If you use the insmod parameter 'force=1', the kernel module will
try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
correct address for this module, you could get in big trouble (read:
crashes, data corruption, etc.). Try this only as a last resort (try BIOS
updates first, for example), and backup first! An even more dangerous
option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
'force' does, but it will also set a new base I/O port address. The SMBus
parts of the PIIX4 needs a range of 8 of these addresses to function
correctly. If these addresses are already reserved by some other device,
you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
ABOUT WHAT YOU ARE DOING!

The PIIX4E is just an new version of the PIIX4; it is supported as well.
The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
this driver on those mainboards.

The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
identical to the PIIX4 in I2C/SMBus support.

보조 컨트롤러와 OSB4 SMI 설정

AMD SB700, SB800, SP5100, Hudson-2 칩셋은 PIIX4 호환 SMBus 컨트롤러 두 개를 구현합니다. BIOS가 보조 컨트롤러를 초기화하면 이 드라이버가 `Auxiliary SMBus Host Controller`로 감지합니다.

Force CPCI735 메인보드나 다른 OSB4 기반 시스템에서는 SMBus 컨트롤러가 SMI 모드를 사용하도록 SMBus Interrupt Select 레지스터를 바꿔야 할 수 있습니다.

먼저 `lspci`에서 SMBus 컨트롤러가 있는 PCI 장치를 찾습니다. 예시는 `00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)`입니다. 칩셋에 따라 줄은 다를 수 있으므로 드라이버 소스의 가능한 PCI ID와 `lspci -n` 출력을 대조합니다.

장치가 `00:0f.0`에 있다고 가정하면 `lspci -xxx -s 00:0f.0`으로 레지스터 `0xD2` 값을 읽습니다. 값이 `0x3`이면 `setpci -s 00:0f.0 d2.b=1`로 `0x1`로 바꿉니다.

이 변경은 모든 경우에 필요한 것이 아니라 SMBus가 제대로 동작하지 않을 때만 필요합니다.

The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two
PIIX4-compatible SMBus controllers. If your BIOS initializes the
secondary controller, it will be detected by this driver as
an "Auxiliary SMBus Host Controller".

If you own Force CPCI735 motherboard or other OSB4 based systems you may need
to change the SMBus Interrupt Select register so the SMBus controller uses
the SMI mode.

1) Use ``lspci`` command and locate the PCI device with the SMBus controller:
   00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
   The line may vary for different chipsets. Please consult the driver source
   for all possible PCI ids (and ``lspci -n`` to match them). Let's assume the
   device is located at 00:0f.0.
2) Now you just need to change the value in 0xD2 register. Get it first with
   command: ``lspci -xxx -s 00:0f.0``
   If the value is 0x3 then you need to change it to 0x1:
   ``setpci  -s 00:0f.0 d2.b=1``

Please note that you don't need to do that in all cases, just when the SMBus is
not working properly.

IBM 24RF08 손상 방지

이 드라이버는 Intel PIIX4 SMBus를 탑재한 IBM 시스템에서 로드를 거부합니다.

일부 시스템에는 SMBus에 연결된 RFID EEPROM `24RF08`이 있으며 상태 머신 버그 때문에 쉽게 손상될 수 있습니다. 주로 ThinkPad 노트북이지만 데스크톱도 영향을 받을 수 있습니다.

영향받는 모든 시스템 목록이 없으므로, DMI 데이터로 감지한 모든 IBM 시스템에서 SMBus 접근을 막는 것이 유일하게 안전한 해결책이었습니다.

Hardware-specific issues
------------------------

This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
which can easily get corrupted due to a state machine bug. These are mostly
Thinkpad laptops, but desktop systems may also be affected. We have no list
of all affected systems, so the only safe solution was to prevent access to
the SMBus on all IBM systems (detected using DMI data.)

ACPI에서 PIIX4 포트 버스 기술

PIIX4 드라이버는 각 포트마다 별도의 I2C 버스를 만듭니다. 예시 `i2cdetect -l` 출력은 `i2c-7`을 주소 `0b00`의 PIIX4 포트 0, `i2c-8`을 같은 주소의 포트 2, `i2c-9`를 주소 `0b20`의 포트 1로 표시합니다.

ACPI 코드에서 이 버스 가운데 하나에 접근하려면 PIIX 장치 안에 포트 하위 장치를 선언해야 합니다. 예시 `Scope (\_SB_.PCI0.SMBS)`는 `_ADR = 0x00140000`을 갖고, `SMB0`, `SMB1`, `SMB2` 장치에 각각 `_ADR` 0, 1, 2를 지정합니다.

UEFI 펌웨어에 이 선언이 없고 소스 코드에도 접근할 수 없다면 ACPI SSDT Overlay로 누락 부분을 제공할 수 있습니다. 추가 SSDT 표는 piix4 드라이버보다 먼저 로드되어야 하므로 configfs가 아니라 initrd 또는 EFI 변수 방식으로 제공해야 합니다.

사용 예제는 PIIX 포트 0이 만든 I2C 버스의 주소 `0x1C` 장치에 `jc42` 드라이버를 할당합니다. `Device (JC42)`는 `_HID`를 `PRP0001`, `_DDN`을 `JC42 Temperature sensor`로 선언합니다.

`_CRS`의 `I2cSerialBusV2`는 주소 `0x001c`, `ControllerInitiated`, 속도 `100000`, `AddressingMode7Bit`, 컨트롤러 경로 `\_SB.PCI0.SMBS.SMB0`, 인덱스 0을 지정합니다.

`_DSD`는 UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301` 아래 `compatible` 속성을 `jedec,jc-42.4-temp`로 지정합니다.

Description in the ACPI code
----------------------------

Device driver for the PIIX4 chip creates a separate I2C bus for each of its
ports::

    $ i2cdetect -l
    ...
    i2c-7   unknown         SMBus PIIX4 adapter port 0 at 0b00      N/A
    i2c-8   unknown         SMBus PIIX4 adapter port 2 at 0b00      N/A
    i2c-9   unknown         SMBus PIIX4 adapter port 1 at 0b20      N/A
    ...

Therefore if you want to access one of these busses in the ACPI code, port
subdevices are needed to be declared inside the PIIX device::

    Scope (\_SB_.PCI0.SMBS)
    {
        Name (_ADR, 0x00140000)

        Device (SMB0) {
            Name (_ADR, 0)
        }
        Device (SMB1) {
            Name (_ADR, 1)
        }
        Device (SMB2) {
            Name (_ADR, 2)
        }
    }

If this is not the case for your UEFI firmware and you don't have access to the
source code, you can use ACPI SSDT Overlays to provide the missing parts. Just
keep in mind that in this case you would need to load your extra SSDT table
before the piix4 driver starts, i.e. you should provide SSDT via initrd or EFI
variable methods and not via configfs.

As an example of usage here is the ACPI snippet code that would assign jc42
driver to the 0x1C device on the I2C bus created by the PIIX port 0::

    Device (JC42) {
        Name (_HID, "PRP0001")
        Name (_DDN, "JC42 Temperature sensor")
        Name (_CRS, ResourceTemplate () {
            I2cSerialBusV2 (
                0x001c,
                ControllerInitiated,
                100000,
                AddressingMode7Bit,
                "\\_SB.PCI0.SMBS.SMB0",
                0
            )
        })

        Name (_DSD, Package () {
            ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
            Package () {
                Package () { "compatible", Package() { "jedec,jc-42.4-temp" } },
            }
        })
    }