리눅스 Device Tree dma-ranges 기준 정리

리눅스 Device Tree dma-ranges 기준 정리

Device Tree에서 DMA 설정을 볼 때 헷갈리기 쉬운 항목 중 하나가 dma-ranges다. 2026년 7월 23일 기준 Devicetree Specification과 Linux 커널 공식 문서를 보면, 이 속성은 장치 자체의 레지스터 주소를 적는 항목이 아니라 버스의 DMA 주소 공간과 부모 주소 공간 사이의 변환 관계를 설명하는 표준 속성이다.

핵심은 세 가지다. dma-ranges가 어느 노드에 붙는지, 값이 어떤 순서의 triplet으로 인코딩되는지, 그리고 일반 주소 변환용 ranges와 무엇이 다른지다. 이 글은 공식 문서 기준으로 그 차이와 확인 포인트만 정리한다.

dma-ranges는 무엇을 설명할까?

Devicetree Specification은 dma-ranges를 "해당 버스에서 시작한 DMA 연산이 접근하는 물리 주소 공간"과 "그 버스의 부모 주소 공간" 사이의 매핑을 설명하는 속성으로 정의한다. 즉 CPU가 MMIO 레지스터를 볼 때의 주소 번역이 아니라, 디바이스가 DMA로 메모리에 접근할 때 사용하는 주소 창을 설명하는 쪽에 가깝다.

따라서 어떤 장치 노드의 reg 값이 맞다고 해서 DMA 주소 해석까지 자동으로 맞는 것은 아니다. DMA 주소 창이 부모 버스나 시스템 물리 주소와 다르게 보이는 구조라면, 공식 명세 기준으로는 그 차이를 dma-ranges로 드러내야 한다.

어느 노드에 써야 할까?

명세는 dma-ranges를 "memory-mapped bus"의 DMA 구조를 설명하는 속성으로 다룬다. 그래서 보통은 개별 주변장치 노드보다, 그 장치들이 속한 버스 노드에 붙는 경우를 먼저 생각하는 편이 맞다. 어떤 버스 아래에 있는 여러 디바이스가 같은 DMA 주소 변환 규칙을 공유한다면 버스 수준에서 표현하는 방식이 자연스럽다.

Linux 커널의 Devicetree 바인딩 가이드도 보드와 SoC DTS에서는 장치를 버스 노드 아래에 두고, 자식 버스 범위를 ranges로 제한하라고 설명한다. 이 문맥을 같이 보면, 주소 창과 DMA 창은 개별 장치보다 버스 경계에서 먼저 설계하고 문서화하는 편이 안전하다.

값 형식은 어떻게 생겼을까?

공식 명세에서 dma-ranges의 값 형식은 비어 있거나, 또는 반복되는 (child-bus-address, parent-bus-address, length) triplet 배열이다. 각 항목의 셀 수는 고정 상수가 아니라 주소 공간 정의에 따라 달라진다.

• child-bus-address 셀 수는 현재 노드의 #address-cells를 따른다.
• parent-bus-address 셀 수는 부모 주소 공간을 정의하는 노드의 #address-cells를 따른다.
• length 셀 수는 현재 노드의 #size-cells를 따른다.

그래서 같은 dma-ranges라도 어떤 버스 아래에 두는지에 따라 셀 개수가 달라질 수 있다. 해석이 꼬일 때는 값만 보지 말고 현재 노드와 부모 노드의 #address-cells, #size-cells를 같이 읽어야 한다.

예시는 어떻게 읽어야 할까?

예를 들어 현재 버스가 #address-cells = <1>, #size-cells = <1>이고 부모도 주소 셀 1개를 쓴다고 가정하면, 다음처럼 3셀씩 한 묶음으로 읽는다.

bus@0 {
        #address-cells = <1>;
        #size-cells = <1>;
        dma-ranges = <0x00000000 0x40000000 0x10000000>;
};

이 경우 triplet 하나는 자식 버스의 DMA 주소 0x00000000부터 길이 0x10000000 범위가 부모 주소 공간의 0x40000000부터 시작하는 범위에 대응된다는 뜻으로 읽는다. 여러 연속 범위를 표현해야 하면 triplet을 이어서 추가하면 된다.

빈 dma-ranges도 가능할까?

가능하다. Devicetree Specification은 dma-ranges의 값 타입을 <empty> 또는 <prop-encoded-array>로 명시한다. 다만 공식 문서가 이 짧은 정의만으로 모든 플랫폼 해석 규칙까지 풀어 쓰는 것은 아니므로, 빈 값을 쓸 때는 해당 버스 바인딩이나 플랫폼 문서가 기대하는 의미를 함께 확인하는 편이 안전하다.

ranges와는 무엇이 다를까?

속성	대상 주소 공간	질문으로 바꾸면
ranges	버스 주소 공간과 부모 주소 공간	"이 버스의 일반 주소는 부모에서 어디로 보일까?"
dma-ranges	DMA용 버스 주소 공간과 부모 주소 공간	"이 버스에서 발생한 DMA 주소는 부모에서 어디로 번역될까?"

두 속성은 triplet 구조가 비슷해서 자주 혼동되지만, 공식 명세는 용도를 분리한다. ranges는 일반 주소 변환, dma-ranges는 DMA 주소 변환이다. MMIO 창과 DMA 창이 같은 하드웨어도 있지만, 항상 같다고 전제하면 안 된다.

Linux 커널은 무엇을 기준으로 볼까?

Linux 커널 Devicetree Kernel API 문서에는 of_translate_dma_region()이 "device tree address and size tuple"을 번역하는 함수로 문서화되어 있다. 반환값 설명도 변환된 DMA region 다음 셀을 가리키는 포인터라고 적혀 있다. 즉 커널 쪽에서도 DMA 범위를 별도 번역 대상으로 다룬다는 점은 분명하다.

실무에서는 DTS에서 dma-ranges를 읽을 때 커널이 단순 문자열로 보는 것이 아니라, 셀 수와 범위 단위로 해석한다는 점이 중요하다. 셀 개수나 범위 길이가 어긋나면 바인딩 검토와 디버깅 모두 어려워진다.

언제 특히 주의해야 할까?

• 버스 아래 여러 디바이스가 같은 DMA 주소 창을 공유하는데 개별 디바이스마다 따로 설명하려 할 때
• #address-cells, #size-cells를 바꿨는데 dma-ranges 셀 개수는 예전 형식을 그대로 둘 때
• ranges 값만 보고 DMA도 같은 번역이라고 가정할 때
• 빈 dma-ranges를 쓰면서 그 의미를 바인딩이나 플랫폼 문서로 보강하지 않을 때

자주 묻는 질문

Q. dma-ranges는 장치의 reg 주소를 설명하는 속성일까?

아니다. 공식 명세 기준으로 reg는 노드의 주소 가능 자원을 설명하고, dma-ranges는 DMA 연산에서 보이는 주소 공간과 부모 주소 공간 사이의 매핑을 설명한다. 같은 주소 체계라고 단정하면 안 된다.

Q. ranges만 있으면 dma-ranges는 없어도 될까?

그렇게 일반화할 수는 없다. 공식 문서는 두 속성을 별도로 정의한다. 하드웨어와 바인딩이 DMA 주소 변환을 따로 표현해야 하는 구조라면 ranges만으로는 의미가 부족할 수 있다.

Q. 셀 수는 어디를 기준으로 계산해야 할까?

현재 버스 노드의 #address-cells, #size-cells, 그리고 부모 주소 공간의 #address-cells를 같이 봐야 한다. dma-ranges 하나만 떼어 읽으면 셀 경계가 쉽게 틀어진다.

정리

dma-ranges는 Device Tree에서 DMA 주소 창을 부모 주소 공간으로 어떻게 번역할지 설명하는 표준 속성이다. 형식은 비어 있거나 반복되는 (child-bus-address, parent-bus-address, length) triplet이며, 각 항목의 셀 수는 현재 노드와 부모 노드의 셀 설정에 따라 결정된다.

2026년 7월 23일 기준 공식 문서를 기준으로 보면, 이 속성을 읽을 때 가장 중요한 기준은 "일반 주소 변환인지, DMA 주소 변환인지"를 먼저 분리하는 것이다. ranges와 dma-ranges를 같은 뜻으로 다루지 않는 것이 안전한 기본값이다.

참고 자료

• Devicetree Specification: The Devicetree
• Linux Kernel Documentation: DeviceTree Kernel API
• Linux Kernel Documentation: DOs and DON’Ts for designing and writing Devicetree bindings