← Documents Documentation/devicetree/bindings/common-properties.txt GitHub 원문 ↗

Linux 6.18.37 · Devicetree Bindings

Devicetree common properties

Register endianness와 daisy-chain device 수를 기술하는 공통 속성입니다.

Source pathDocumentation/devicetree/bindings/common-properties.txt
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

common-properties.txt:1-85

BE/LE/native register access 선택과 daisy-chain cardinality를 설명합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 Common properties
2 =================
3
4 Endianness
5 ----------
6
7 The Devicetree Specification does not define any properties related to hardware
8 byte swapping, but endianness issues show up frequently in porting drivers to
9 different machine types. This document attempts to provide a consistent
10 way of handling byte swapping across drivers.
11
12 Optional properties:
13 - big-endian: Boolean; force big endian register accesses
14 unconditionally (e.g. ioread32be/iowrite32be). Use this if you
15 know the peripheral always needs to be accessed in big endian (BE) mode.
16 - little-endian: Boolean; force little endian register accesses
17 unconditionally (e.g. readl/writel). Use this if you know the
18 peripheral always needs to be accessed in little endian (LE) mode.
19 - native-endian: Boolean; always use register accesses matched to the
20 endianness of the kernel binary (e.g. LE vmlinux -> readl/writel,
21 BE vmlinux -> ioread32be/iowrite32be). In this case no byte swaps
22 will ever be performed. Use this if the hardware "self-adjusts"
23 register endianness based on the CPU's configured endianness.
24
25 If a binding supports these properties, then the binding should also
26 specify the default behavior if none of these properties are present.
27 In such cases, little-endian is the preferred default, but it is not
28 a requirement. Some implementations assume that little-endian is
29 the default, because most existing (PCI-based) drivers implicitly
30 default to LE for their MMIO accesses.
31
32 Examples:
33 Scenario 1 : CPU in LE mode & device in LE mode.
34 dev: dev@40031000 {
35 compatible = "name";
36 reg = <0x40031000 0x1000>;
37 ...
38 native-endian;
39 };
40
41 Scenario 2 : CPU in LE mode & device in BE mode.
42 dev: dev@40031000 {
43 compatible = "name";
44 reg = <0x40031000 0x1000>;
45 ...
46 big-endian;
47 };
48
49 Scenario 3 : CPU in BE mode & device in BE mode.
50 dev: dev@40031000 {
51 compatible = "name";
52 reg = <0x40031000 0x1000>;
53 ...
54 native-endian;
55 };
56
57 Scenario 4 : CPU in BE mode & device in LE mode.
58 dev: dev@40031000 {
59 compatible = "name";
60 reg = <0x40031000 0x1000>;
61 ...
62 little-endian;
63 };
64
65 Daisy-chained devices
66 ---------------------
67
68 Many serially-attached GPIO and IIO devices are daisy-chainable. To the
69 host controller, a daisy-chain appears as a single device, but the number
70 of inputs and outputs it provides is the sum of inputs and outputs provided
71 by all of its devices. The driver needs to know how many devices the
72 daisy-chain comprises to determine the amount of data exchanged, how many
73 inputs and outputs to register and so on.
74
75 Optional properties:
76 - #daisy-chained-devices: Number of devices in the daisy-chain (default is 1).
77
78 Example:
79 gpio@0 {
80 compatible = "name";
81 reg = <0>;
82 gpio-controller;
83 #gpio-cells = <2>;
84 #daisy-chained-devices = <3>;
85 };
86

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Register access endianness

1-31

Devicetree Specification은 hardware byte swapping 관련 속성을 정의하지 않지만 서로 다른 machine type으로 driver를 port할 때 endianness 문제가 자주 발생합니다. 이 문서는 driver 전반에서 byte swapping을 일관되게 처리하는 공통 속성을 정의합니다.

Boolean `big-endian`은 `ioread32be`와 `iowrite32be` 같은 big-endian register access를 항상 강제합니다. Peripheral이 언제나 BE mode로 접근되어야 할 때 사용합니다.

Boolean `little-endian`은 `readl`과 `writel` 같은 little-endian register access를 항상 강제합니다. Peripheral이 언제나 LE mode로 접근되어야 할 때 사용합니다.

Boolean `native-endian`은 kernel binary의 endianness와 일치하는 access를 사용합니다. LE vmlinux에는 `readl`/`writel`, BE vmlinux에는 `ioread32be`/`iowrite32be`를 사용하므로 byte swap을 수행하지 않습니다. CPU 설정에 따라 hardware가 register endianness를 자체 조정할 때 적합합니다.

Binding이 이 속성들을 지원한다면 셋 중 아무것도 없을 때의 default도 명시해야 합니다. Preferred default는 little-endian이지만 필수는 아닙니다. 기존 PCI 기반 driver 대부분이 MMIO access를 암묵적으로 LE로 가정하기 때문입니다.

Devicetree endianness selection
PropertyAccessor policy사용 조건
big-endianioread32be / iowrite32bePeripheral이 항상 BE
little-endianreadl / writelPeripheral이 항상 LE
native-endianKernel binary endianness와 일치Hardware가 CPU endianness에 맞춤
NoneBinding-defined default, LE 권장명시적 default 필요

속성별 register accessor와 byte-swap 정책을 정리합니다.

CPU/device endianness 조합 예제

32-64

CPU와 device가 모두 LE인 scenario 1, 모두 BE인 scenario 3은 `native-endian`을 사용합니다. CPU가 LE이고 device가 BE인 scenario 2는 `big-endian`, CPU가 BE이고 device가 LE인 scenario 4는 `little-endian`을 사용합니다.

dev: dev@40031000 {
              compatible = "name";
              reg = <0x40031000 0x1000>;
              ...
              native-endian;
};

Scenario 2 : CPU in LE mode & device in BE mode.
dev: dev@40031000 {
              compatible = "name";
              reg = <0x40031000 0x1000>;
              ...
              big-endian;
};

Scenario 3 : CPU in BE mode & device in BE mode.
dev: dev@40031000 {
              compatible = "name";
              reg = <0x40031000 0x1000>;
              ...
              native-endian;
};

Scenario 4 : CPU in BE mode & device in LE mode.
dev: dev@40031000 {
              compatible = "name";
              reg = <0x40031000 0x1000>;
              ...
              little-endian;
};
CPU와 device 조합
CPUDeviceProperty
LELEnative-endian
LEBEbig-endian
BEBEnative-endian
BELElittle-endian

네 조합에서 선택할 속성을 한눈에 보여 줍니다.

Daisy-chained devices

65-85

Serial 방식으로 연결되는 GPIO와 IIO device 중에는 daisy chain을 구성할 수 있는 장치가 많습니다. Host controller에는 chain 전체가 단일 device처럼 보이지만 input/output 수는 모든 device의 합입니다.

Driver는 교환할 data 양과 등록할 input/output 수를 결정하기 위해 chain의 device 수를 알아야 합니다. 선택 속성 `#daisy-chained-devices`에 device 수를 지정하며 default는 1입니다.

예제 GPIO controller는 `#daisy-chained-devices = <3>`으로 세 device가 연결된 chain을 선언합니다.

gpio@0 {
              compatible = "name";
              reg = <0>;
              gpio-controller;
              #gpio-cells = <2>;
              #daisy-chained-devices = <3>;
};