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

Linux 6.18.37 · Devicetree Bindings

Common Pinctrl Bindings

Pin controller와 client state를 연결하는 공통 device tree binding입니다.

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

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

1. 요약·해설

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

요약과 해설

pinctrl-bindings.txt:1-109

연속 state ID, `pinctrl-n`, `pinctrl-names`, empty state의 계약과 예제를 정리합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 == Introduction ==
2
3 Hardware modules that control pin multiplexing or configuration parameters
4 such as pull-up/down, tri-state, drive-strength etc are designated as pin
5 controllers. Each pin controller must be represented as a node in device tree,
6 just like any other hardware module.
7
8 Hardware modules whose signals are affected by pin configuration are
9 designated client devices. Again, each client device must be represented as a
10 node in device tree, just like any other hardware module.
11
12 For a client device to operate correctly, certain pin controllers must
13 set up certain specific pin configurations. Some client devices need a
14 single static pin configuration, e.g. set up during initialization. Others
15 need to reconfigure pins at run-time, for example to tri-state pins when the
16 device is inactive. Hence, each client device can define a set of named
17 states. The number and names of those states is defined by the client device's
18 own binding.
19
20 The common pinctrl bindings defined in this file provide an infrastructure
21 for client device device tree nodes to map those state names to the pin
22 configuration used by those states.
23
24 Note that pin controllers themselves may also be client devices of themselves.
25 For example, a pin controller may set up its own "active" state when the
26 driver loads. This would allow representing a board's static pin configuration
27 in a single place, rather than splitting it across multiple client device
28 nodes. The decision to do this or not somewhat rests with the author of
29 individual board device tree files, and any requirements imposed by the
30 bindings for the individual client devices in use by that board, i.e. whether
31 they require certain specific named states for dynamic pin configuration.
32
33 == Pinctrl client devices ==
34
35 For each client device individually, every pin state is assigned an integer
36 ID. These numbers start at 0, and are contiguous. For each state ID, a unique
37 property exists to define the pin configuration. Each state may also be
38 assigned a name. When names are used, another property exists to map from
39 those names to the integer IDs.
40
41 Each client device's own binding determines the set of states that must be
42 defined in its device tree node, and whether to define the set of state
43 IDs that must be provided, or whether to define the set of state names that
44 must be provided.
45
46 Required properties:
47 pinctrl-0: List of phandles, each pointing at a pin configuration
48 node. These referenced pin configuration nodes must be child
49 nodes of the pin controller that they configure. Multiple
50 entries may exist in this list so that multiple pin
51 controllers may be configured, or so that a state may be built
52 from multiple nodes for a single pin controller, each
53 contributing part of the overall configuration. See the next
54 section of this document for details of the format of these
55 pin configuration nodes.
56
57 In some cases, it may be useful to define a state, but for it
58 to be empty. This may be required when a common IP block is
59 used in an SoC either without a pin controller, or where the
60 pin controller does not affect the HW module in question. If
61 the binding for that IP block requires certain pin states to
62 exist, they must still be defined, but may be left empty.
63
64 Optional properties:
65 pinctrl-1: List of phandles, each pointing at a pin configuration
66 node within a pin controller.
67 ...
68 pinctrl-n: List of phandles, each pointing at a pin configuration
69 node within a pin controller.
70 pinctrl-names: The list of names to assign states. List entry 0 defines the
71 name for integer state ID 0, list entry 1 for state ID 1, and
72 so on.
73
74 For example:
75
76 /* For a client device requiring named states */
77 device {
78 pinctrl-names = "active", "idle";
79 pinctrl-0 = <&state_0_node_a>;
80 pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;
81 };
82
83 /* For the same device if using state IDs */
84 device {
85 pinctrl-0 = <&state_0_node_a>;
86 pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;
87 };
88
89 /*
90 * For an IP block whose binding supports pin configuration,
91 * but in use on an SoC that doesn't have any pin control hardware
92 */
93 device {
94 pinctrl-names = "active", "idle";
95 pinctrl-0 = <>;
96 pinctrl-1 = <>;
97 };
98
99 == Pin controller devices ==
100
101 See pinctrl.yaml
102
103 == Generic pin multiplexing node content ==
104
105 See pinmux-node.yaml
106
107 == Generic pin configuration node content ==
108
109 See pincfg-node.yaml
110

3. 한국어 전문 번역

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

Pin controller와 client device

1-32

Pin multiplexing이나 pull-up/down, tri-state, drive-strength 같은 configuration parameter를 제어하는 hardware module을 pin controller라 하며 device tree node로 표현해야 합니다. Pin configuration의 영향을 받는 hardware module은 client device이고 역시 node로 표현합니다.

Client가 동작하려면 특정 pin controller가 특정 구성을 설정해야 합니다. 초기화 때 하나의 static configuration만 필요한 client도 있고, inactive 때 tri-state로 바꾸는 것처럼 runtime 재구성이 필요한 client도 있습니다. 따라서 각 client는 자체 binding이 정한 이름의 state 집합을 정의할 수 있습니다.

공통 pinctrl binding은 client node의 state 이름을 실제 pin configuration에 mapping하는 기반을 제공합니다. Pin controller 자신도 자신의 client가 되어 driver load 때 `active` state를 설정할 수 있으며, board의 static pin 구성을 한곳에 모을지는 board device tree 작성자와 client binding 요구사항에 달려 있습니다.

Client state ID와 필수 속성

33-63

각 client device의 pin state에는 0부터 연속된 integer ID가 할당됩니다. 각 ID에는 pin configuration을 정의하는 고유 property가 있고 선택적으로 이름을 붙일 수 있습니다. 이름을 쓰면 별도 property가 이름을 integer ID에 mapping합니다. 필요한 state ID 또는 state 이름 집합은 client 자체 binding이 결정합니다.

필수 `pinctrl-0`은 각각 pin configuration node를 가리키는 phandle 목록입니다. 참조 node는 자신이 구성하는 pin controller의 child여야 합니다. 여러 controller를 구성하거나 하나의 controller state를 여러 부분 node로 조합할 수 있으므로 목록에 여러 항목이 올 수 있습니다.

공통 IP block binding이 state 존재를 요구하지만 해당 SoC에 pin controller가 없거나 controller가 그 module에 영향을 주지 않는 경우에도 state는 정의해야 합니다. 이때 state는 비워 둘 수 있습니다.

추가 state와 이름

64-73

선택적 `pinctrl-1`부터 `pinctrl-n`까지는 각 integer state ID의 pin configuration phandle 목록입니다. `pinctrl-names`는 state 이름 목록이며 entry 0이 ID 0, entry 1이 ID 1에 대응하는 식으로 이어집니다.

Named state·ID·empty state 예제

74-98

이름이 있는 active·idle state, 같은 device를 integer state ID만으로 표현한 경우, pin control hardware가 없어 state를 빈 phandle list로 둔 경우를 차례로 보여 줍니다.

/* For a client device requiring named states */
device {
        pinctrl-names = "active", "idle";
        pinctrl-0 = <&state_0_node_a>;
        pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;
};

/* For the same device if using state IDs */
device {
        pinctrl-0 = <&state_0_node_a>;
        pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;
};

/*
 * For an IP block whose binding supports pin configuration,
 * but in use on an SoC that doesn't have any pin control hardware
 */
device {
        pinctrl-names = "active", "idle";
        pinctrl-0 = <>;
        pinctrl-1 = <>;
};

Controller·mux·configuration 참조

99-109

Pin controller device의 공통 정의는 `pinctrl.yaml`, generic pin multiplexing node content는 `pinmux-node.yaml`, generic pin configuration node content는 `pincfg-node.yaml`을 참조합니다.