EISA bus support

EISA/sysfs API 개요

문서 제목은 `EISA bus support`이며 저자는 Marc Zyngier `<[email protected]>`입니다. 기존 EISA driver를 새 EISA/sysfs API로 porting할 때 필요한 여러 note를 모았습니다.

kernel 2.5.59부터 EISA bus는 PCI나 USB 같은 mainstream bus와 거의 같은 지위를 갖게 되었습니다. sysfs가 bus, device, driver를 관리하는 충분한 abstraction을 정의한 덕분입니다.

새 API 자체는 단순하지만 기존 driver 전환은 쉽지 않습니다. detection code를 ISA card probing에도 함께 사용하는 경우가 많고, EISA driver 대부분이 오래된 Linux driver라 누적된 legacy code가 많기 때문입니다.

EISA infrastructure는 세 부분으로 구성됩니다.

• `bus code`: EISA가 동작하는 모든 architecture가 공유하는 generic code입니다. bus probing으로 사용 가능한 EISA card를 검출하고, I/O resource를 할당하며, sysfs를 통한 이름 지정과 driver registration interface를 제공합니다.
• `bus root driver`: bus hardware와 generic bus code를 잇는 glue입니다. bus를 구현하는 device를 찾고 generic bus code가 나중에 probe할 수 있도록 setup합니다. x86의 단순한 I/O region reserve부터 hppa EISA의 복잡한 처리까지 platform마다 다르며, 새 platform에서 EISA를 지원하려면 이 부분을 구현합니다.
• `driver`: 자신이 관리하는 device 목록을 bus에 제공하고, 요청받을 때 device를 probe하고 release하는 callback을 구현합니다.

아래 모든 function과 structure는 `<linux/eisa.h>`에 있으며 이 header는 `<linux/device.h>`에 크게 의존합니다.

Bus root driver

`eisa_root_register()`는 device를 EISA bus의 root로 선언합니다.

int eisa_root_register (struct eisa_root_device *root);

`struct eisa_root_device`는 bridge/root device reference와 probing에 필요한 parameter를 보관합니다.

struct eisa_root_device {
        struct device   *dev;         /* Pointer to bridge device */
        struct resource *res;
        unsigned long    bus_base_addr;
        int                 slots;  /* Max slot number */
        int                 force_probe; /* Probe even when no slot 0 */
        u64                 dma_mask; /* from bridge device */
        int              bus_nr; /* Set by eisa_root_register */
        struct resource  eisa_root_res;        /* ditto */
};

원문의 field 설명 표는 다음과 같습니다. `node`는 `eisa_root_register` 내부 용도이고, `dev`는 root device pointer, `res`는 root I/O resource, `bus_base_addr`는 해당 bus의 slot 0 address입니다. `slots`는 probe할 최대 slot number, `force_probe`는 slot 0이 비어 있어 EISA mainboard가 보이지 않아도 probe할지 여부입니다. `dma_mask`는 보통 bridge device에서 가져온 기본 DMA mask이고 `bus_nr`는 register 함수가 설정하는 unique bus ID입니다.

============= ======================================================
node          used for eisa_root_register internal purpose
dev           pointer to the root device
res           root device I/O resource
bus_base_addr slot 0 address on this bus
slots              max slot number to probe
force_probe   Probe even when slot 0 is empty (no EISA mainboard)
dma_mask      Default DMA mask. Usually the bridge device dma_mask.
bus_nr              unique bus id, set by eisa_root_register
============= ======================================================

structure의 `eisa_root_res` 역시 `eisa_root_register()`가 설정하는 root resource입니다.

EISA driver 등록과 ID table

EISA driver는 다음 API로 등록하고 unregister합니다.

int eisa_driver_register (struct eisa_driver *edrv);
void eisa_driver_unregister (struct eisa_driver *edrv);

`struct eisa_device_id`는 길이 `EISA_SIG_LEN`인 signature와 driver-specific `driver_data`를 가집니다. `struct eisa_driver`는 ID table과 generic `struct device_driver`를 포함합니다.

struct eisa_device_id {
        char sig[EISA_SIG_LEN];
        unsigned long driver_data;
};

struct eisa_driver {
        const struct eisa_device_id *id_table;
        struct device_driver         driver;
};

`id_table`은 NULL-terminated EISA ID string array이며 마지막에는 empty string entry가 옵니다. 각 string에는 선택적으로 driver-dependent value인 `driver_data`를 짝지을 수 있습니다.

`driver`는 `Documentation/driver-api/driver-model/driver.rst`가 설명하는 generic driver입니다. `.name`, `.probe`, `.remove` member만 필수입니다.

=============== ====================================================
id_table        an array of NULL terminated EISA id strings,
                followed by an empty string. Each string can
                optionally be paired with a driver-dependent value
                (driver_data).

driver                a generic driver, such as described in
                Documentation/driver-api/driver-model/driver.rst. Only .name,
                .probe and .remove members are mandatory.
=============== ====================================================

3c59x driver 예제는 `TCM5920`, `TCM5970` ID를 offset 값과 연결하고 empty entry로 table을 끝낸 뒤 `3c59x`라는 generic driver name과 probe/remove callback을 설정합니다.

static struct eisa_device_id vortex_eisa_ids[] = {
        { "TCM5920", EISA_3C592_OFFSET },
        { "TCM5970", EISA_3C597_OFFSET },
        { "" }
};

static struct eisa_driver vortex_eisa_driver = {
        .id_table = vortex_eisa_ids,
        .driver   = {
                .name    = "3c59x",
                .probe   = vortex_eisa_probe,
                .remove  = vortex_eisa_remove
        }
};

EISA device 표현

sysfs framework는 device를 발견하거나 제거할 때 `.probe`와 `.remove`를 호출합니다. `.remove`는 driver를 module로 build한 경우에만 호출된다는 점에 유의해야 합니다.

두 callback은 `struct device` pointer를 받으며, 이 generic device는 다음 `struct eisa_device` 안에 포함됩니다.

struct eisa_device {
        struct eisa_device_id id;
        int                   slot;
        int                   state;
        unsigned long         base_addr;
        struct resource       res[EISA_MAX_RESOURCES];
        u64                   dma_mask;
        struct device         dev; /* generic device */
};

`id`는 device에서 읽은 EISA ID이고 `id.driver_data`는 matching driver의 EISA ID entry에서 설정됩니다. `slot`은 device를 발견한 slot number입니다. `state`는 device 상태 flag 집합이며 현재 `EISA_CONFIG_ENABLED`와 `EISA_CONFIG_FORCED`가 있습니다.

`res`는 device에 할당된 256byte I/O region 네 개의 집합이고 `dma_mask`는 parent device에서 가져옵니다. `dev`는 `Documentation/driver-api/driver-model/device.rst`가 설명하는 generic device입니다.

======== ============================================================
id         EISA id, as read from device. id.driver_data is set from the
         matching driver EISA id.
slot         slot number which the device was detected on
state    set of flags indicating the state of the device. Current
         flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
res         set of four 256 bytes I/O regions allocated to this device
dma_mask DMA mask set from the parent device.
dev         generic device (see Documentation/driver-api/driver-model/device.rst)
======== ============================================================

generic `struct device`에서 enclosing `struct eisa_device`를 얻을 때는 `to_eisa_device` macro를 사용합니다.

Driver data와 region helper

`eisa_set_drvdata()`는 device의 `driver_data` area에 caller data를 저장합니다.

void eisa_set_drvdata (struct eisa_device *edev, void *data);

`eisa_get_drvdata()`는 앞서 device의 `driver_data` area에 저장한 pointer를 반환합니다. 원문의 declaration 끝에 있는 colon 표기를 그대로 보존했습니다.

void *eisa_get_drvdata (struct eisa_device *edev):

`eisa_get_region_index()`는 주어진 address가 속한 region number를 반환하며 범위는 `0 <= x < EISA_MAX_RESOURCES`입니다.

int eisa_get_region_index (void *addr);

Kernel parameter

`eisa_bus.enable_dev`는 firmware가 disabled로 표시했어도 강제로 enable할 slot의 comma-separated list입니다. 이 조건에서도 driver가 device를 올바르게 initialize할 수 있어야 합니다.

`eisa_bus.disable_dev`는 firmware가 enabled로 표시했어도 disable할 slot의 comma-separated list입니다. 해당 device를 처리하도록 driver를 호출하지 않습니다.

`virtual_root.force_probe`는 EISA-compliant mainboard를 찾지 못해 slot 0에 아무것도 나타나지 않아도 EISA slot을 probe하도록 강제합니다. 기본값은 0으로 강제하지 않으며 `CONFIG_EISA_VLB_PRIMING`을 설정하면 1, 즉 force probing이 됩니다.

Driver porting과 probe 시점 주의

EISA driver를 새 API로 바꾸는 작업은 probing이 core EISA code로 이동했으므로 대체로 code를 삭제하는 일입니다. 하지만 대부분 driver가 ISA와 EISA 사이에 probing routine을 공유하므로 EISA code를 제거할 때 다른 bus 경로를 손상하지 않도록 특별히 주의해야 합니다.

`eisa_driver_register()`가 반환할 때 EISA device가 이미 검출되었을 것이라고 절대 기대하면 안 됩니다. bus가 아직 probe되지 않았을 가능성이 크고, bus root driver는 보통 boot process의 상당히 늦은 시점에 동작합니다.

기존 driver 대부분은 직접 probing하며 probe routine을 빠져나올 때 machine 전체를 탐색했다고 가정합니다. 이러한 전제를 버리고 EISA SCSI card 같은 device를 hotplug model로 전환하는 것이 올바른 방향입니다.

감사

저자는 도움을 준 다음 사람들에게 감사를 표합니다.

• 멋진 Alpha Jensen을 빌려준 Xavier Benigni
• 이 code를 kernel에 넣는 데 기여한 James Bottomley와 Jeff Garzik
• 많은 EISA ID를 제공한 Andries Brouwer
• 집의 너무 많은 machine을 감당한 Catrin Jones