Generic IOMMU Bindings

IOMMU device node

이 문서는 IOMMU와 그 master를 위한 일반 Device Tree 바인딩을 설명합니다. IOMMU는 장치가 원래 접근할 수 없는 물리 메모리 범위를 사용하도록 주소 공간을 재매핑할 수 있습니다. 예를 들어 32-bit DMA를 64-bit 물리 주소에 연결할 수 있습니다.

또한 장치가 직접 구현하지 않아도 되도록 page 단위 scatter-gather를 제공하고, 모든 접근을 IOMMU를 거치게 한 뒤 매핑되지 않은 주소 접근에서 fault를 발생시켜 rogue DMA로부터 시스템을 보호합니다. 여러 context 사이의 주소 공간 격리도 제공하며 virtualization이 대표 사례입니다.

이 바인딩과 호환되는 node는 위 기능 중 일부를 가진 하드웨어를 나타냅니다. IOMMU는 single-master 또는 multiple-master일 수 있습니다. Single-master 장치는 보통 master와 고정 연결되고, multiple-master 장치는 둘 이상의 master 접근을 변환할 수 있습니다.

IOMMU 장치의 부모 bus node에는 IOMMU의 물리 주소 공간이 메모리에 어떻게 매핑되는지 설명하는 유효한 `dma-ranges`가 있어야 합니다. 빈 `dma-ranges`는 IOMMU와 메모리 사이의 1:1 매핑을 뜻합니다.

필수 `#iommu-cells`는 주소를 인코딩하기 위해 IOMMU specifier에 필요한 cell 수입니다. 정확한 의미는 특정 IOMMU 바인딩이 정의합니다. `<0>`은 구성할 추가 정보가 없는 single-master 또는 master 연결을 구성할 수 없는 multiple-master 장치에 쓸 수 있습니다. 하드웨어가 multi-master여도 현재 구성에서 master 하나만 노출한다면 보통 다음 사례처럼 cell 수 1을 사용합니다.

`#iommu-cells = <1>`은 주어진 master의 변환을 활성화하기 위해 구성해야 하는 multiple-master 장치에 흔히 쓰며 단일 cell은 master ID입니다. 단일 master ID를 표현하는 데 cell이 둘 이상 필요할 수도 있습니다.

`#iommu-cells = <4>`는 master의 DMA window를 구성할 수 있는 사례입니다. 첫 cell은 master ID, 둘째 cell은 해당 장치 DMA window의 시작 주소가 될 수 있고 셋째와 넷째 cell이 window 길이를 나타냅니다. 이는 예시일 뿐이므로 실제 cell 의미는 언제나 개별 IOMMU 바인딩을 확인해야 합니다.

IOMMU master node

IOMMU를 통해 메모리에 접근하는 장치를 master라고 합니다. 장치 하나가 하나 이상의 IOMMU에 연결된 여러 master interface를 가질 수 있습니다. 필수 `iommus`는 phandle과 IOMMU specifier 쌍의 목록이며 항목 하나가 장치의 master interface 하나를 설명합니다.

Device Tree node에 `iommus`가 있으면 주소 변환에 IOMMU를 사용하고 부모 node의 `dma-ranges`는 무시합니다. 예외는 참조한 IOMMU가 disabled인 경우이며 이때 부모의 `dma-ranges`가 적용됩니다. 단, node를 disabled로 표시해도 하드웨어에 변환을 끄는 수단이 없다면 실제 IOMMU가 꺼진다는 보장은 없습니다. 이런 하드웨어에서 IOMMU node를 disabled로 두면 driver가 변환을 올바르게 설정할 수 없으므로 그 구성 자체가 유효하지 않습니다.

선택 `pasid-num-bits`는 master가 DMA transaction에 address-space identifier를 붙여 여러 주소 공간을 지원할 때 그 PASID bit 수입니다. 기본값 0은 장치에 주소 공간이 하나뿐임을 뜻합니다.

`dma-can-stall`이 있으면 master는 transaction 완료를 무기한 기다릴 수 있습니다. 일부 IOMMU는 translation fault에서 즉시 abort하지 않고 driver에 알린 뒤 transaction을 진행 중 상태로 유지합니다. OS는 fault를 조사하고 물리 page를 resident 상태로 만든 다음 mapping을 갱신하여 transaction을 완료할 수 있습니다.

IOMMU가 동시에 유지할 수 있는 stalled transaction 수에는 한계가 있으므로 한도를 넘으면 master에 back-pressure를 주거나 새 fault transaction을 abort해야 합니다. 대부분의 bus와 master는 stall을 지원하지 않기 때문에 firmware가 명시적으로 opt-in해야 합니다. 시간 제한 안에 transaction을 완료해야 하는 PCI와 호환되지 않으며, stall을 고려하지 않은 시스템에서는 사용할 수 없습니다. 예를 들어 OS가 stalled domain의 secondary storage에서 page를 읽으려 하면 deadlock이 생길 수 있습니다.

Bus-level 확장에 관한 주의

가능한 확장으로 PCI host bridge 같은 bus 장치 node에서 `iommus`와 `dma-ranges`를 함께 사용하여 Device Tree에 명시적으로 나열되지 않은 PCI 장치 등의 자식과 IOMMU의 관계를 설명할 수 있습니다. 그러나 이 사용 사례의 요구사항은 아직 완전히 결정되지 않았으므로 바인딩을 더 논의하고 확장하기 전에는 구현하지 않는 것이 좋습니다.

IOMMU master 구성 예제

Single-master 예제는 `#iommu-cells = <0>`인 IOMMU를 master가 specifier 없이 참조합니다.

iommu {
        #iommu-cells = <0>;
};

master {
        iommus = <&{/iommu}>;
};

고정 연결 multiple-master 예제에서도 `#iommu-cells = <0>`을 사용합니다. IOMMU가 master를 구별할 정보가 부족해 모든 master가 같은 주소 변환을 공유하며 변환은 어느 시점에나 전체 master에 대해 함께 켜지거나 꺼집니다. `master@1`과 `master@2`는 같은 IOMMU에 정적으로 연결됩니다.

/* multiple-master IOMMU */
iommu {
        /*
         * Masters are statically associated with this IOMMU and share
         * the same address translations because the IOMMU does not
         * have sufficient information to distinguish between masters.
         *
         * Consequently address translation is always on or off for
         * all masters at any given point in time.
         */
        #iommu-cells = <0>;
};

/* static association with IOMMU */
master@1 {
        reg = <1>;
        iommus = <&{/iommu}>;
};

/* static association with IOMMU */
master@2 {
        reg = <2>;
        iommus = <&{/iommu}>;
};

구성 가능한 multiple-master 예제는 `#iommu-cells = <1>`로 master ID를 specifier에 넣습니다. 첫 장치는 ID 42 하나를 사용하고 둘째 장치는 ID 23과 24인 두 master interface를 가집니다.

iommu {
        /* the specifier represents the ID of the master */
        #iommu-cells = <1>;
};

master@1 {
        /* device has master ID 42 in the IOMMU */
        iommus = <&{/iommu} 42>;
};

master@2 {
        /* device has master IDs 23 and 24 in the IOMMU */
        iommus = <&{/iommu} 23>, <&{/iommu} 24>;
};

DMA window 구성 예제는 master ID 한 cell, window 주소 한 cell, 길이 두 cell로 총 네 cell을 사용합니다. Master 42에 주소 0에서 시작하는 4 GiB DMA window, 즉 I/O virtual address 공간을 지정합니다.

/ {
        iommu {
                /*
                 * One cell for the master ID and one cell for the
                 * address of the DMA window. The length of the DMA
                 * window is encoded in two cells.
                 *
                 * The DMA window is the range addressable by the
                 * master (i.e. the I/O virtual address space).
                 */
                #iommu-cells = <4>;
        };

        master {
                /* master ID 42, 4 GiB DMA window starting at 0 */
                iommus = <&{/iommu}  42  0  0x1 0x0>;
        };
};