Generic MSI Controller Binding | Linux 6.18.37

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

1. 요약·해설

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

요약과 해설

msi.txt:1-135

msi-parent 목록과 controller별 specifier ID 예제를 설명합니다.

2. 영어 원문 전체

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

원문 전체 펼치기

1 This document describes the generic device tree binding for MSI controllers and

2 their master(s).

4 Message Signaled Interrupts (MSIs) are a class of interrupts generated by a

5 write to an MMIO address.

7 MSIs were originally specified by PCI (and are used with PCIe), but may also be

8 used with other busses, and hence a mechanism is required to relate devices on

9 those busses to the MSI controllers which they are capable of using,

10 potentially including additional information.

12 MSIs are distinguished by some combination of:

14 - The doorbell (the MMIO address written to).

16 Devices may be configured by software to write to arbitrary doorbells which

17 they can address. An MSI controller may feature a number of doorbells.

19 - The payload (the value written to the doorbell).

21 Devices may be configured to write an arbitrary payload chosen by software.

22 MSI controllers may have restrictions on permitted payloads.

24 - Sideband information accompanying the write.

26 Typically this is neither configurable nor probeable, and depends on the path

27 taken through the memory system (i.e. it is a property of the combination of

28 MSI controller and device rather than a property of either in isolation).

31 MSI controllers:

32 ================

34 An MSI controller signals interrupts to a CPU when a write is made to an MMIO

35 address by some master. An MSI controller may feature a number of doorbells.

37 Required properties:

38 --------------------

40 - msi-controller: Identifies the node as an MSI controller.

42 Optional properties:

43 --------------------

45 - #msi-cells: The number of cells in an msi-specifier, required if not zero.

47 Typically this will encode information related to sideband data, and will

48 not encode doorbells or payloads as these can be configured dynamically.

50 The meaning of the msi-specifier is defined by the device tree binding of

51 the specific MSI controller.

54 MSI clients

55 ===========

57 MSI clients are devices which generate MSIs. For each MSI they wish to

58 generate, the doorbell and payload may be configured, though sideband

59 information may not be configurable.

61 Required properties:

62 --------------------

64 - msi-parent: A list of phandle + msi-specifier pairs, one for each MSI

65 controller which the device is capable of using.

67 This property is unordered, and MSIs may be allocated from any combination of

68 MSI controllers listed in the msi-parent property.

70 If a device has restrictions on the allocation of MSIs, these restrictions

71 must be described with additional properties.

73 When #msi-cells is non-zero, busses with an msi-parent will require

74 additional properties to describe the relationship between devices on the bus

75 and the set of MSIs they can potentially generate.

78 Example

79 =======

81 / {

82 #address-cells = <1>;

83 #size-cells = <1>;

85 msi_a: msi-controller@a {

86 reg = <0xa 0xf00>;

87 compatible = "vendor-a,some-controller";

88 msi-controller;

89 /* No sideband data, so #msi-cells omitted */

90 };

92 msi_b: msi-controller@b {

93 reg = <0xb 0xf00>;

94 compatible = "vendor-b,another-controller";

95 msi-controller;

96 /* Each device has some unique ID */

97 #msi-cells = <1>;

98 };

100 msi_c: msi-controller@c {

101 reg = <0xc 0xf00>;

102 compatible = "vendor-b,another-controller";

103 msi-controller;

104 /* Each device has some unique ID */

105 #msi-cells = <1>;

106 };

107

108 dev@0 {

109 reg = <0x0 0xf00>;

110 compatible = "vendor-c,some-device";

111

112 /* Can only generate MSIs to msi_a */

113 msi-parent = <&msi_a>;

114 };

115

116 dev@1 {

117 reg = <0x1 0xf00>;

118 compatible = "vendor-c,some-device";

119

120 /*

121 * Can generate MSIs to either A or B.

122 */

123 msi-parent = <&msi_a>, <&msi_b 0x17>;

124 };

125

126 dev@2 {

127 reg = <0x2 0xf00>;

128 compatible = "vendor-c,some-device";

129 /*

130 * Has different IDs at each MSI controller.

131 * Can generate MSIs to all of the MSI controllers.

132 */

133 msi-parent = <&msi_a>, <&msi_b 0x17>, <&msi_c 0x53>;

134 };

135 };

136

3. 한국어 전문 번역

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

MSI 식별 요소

1-30

이 문서는 MSI controller와 그 master를 위한 일반 Device Tree 바인딩을 설명합니다. Message Signaled Interrupt(MSI)는 MMIO 주소에 값을 쓰면 생성되는 인터럽트입니다. 원래 PCI에서 규정되어 PCIe에도 쓰이지만 다른 bus에서도 사용할 수 있으므로, 각 bus의 장치와 사용할 수 있는 MSI controller를 추가 정보와 함께 연결하는 방법이 필요합니다.

MSI는 doorbell, payload, sideband 정보의 조합으로 구분됩니다. Doorbell은 쓰기 대상 MMIO 주소이며 장치는 접근 가능한 임의의 doorbell에 쓰도록 소프트웨어가 설정할 수 있고 controller는 여러 doorbell을 제공할 수 있습니다.

Payload는 doorbell에 쓰는 값입니다. 장치는 소프트웨어가 고른 임의의 payload를 쓰도록 설정할 수 있지만 controller가 허용 값에 제약을 둘 수 있습니다. Sideband 정보는 쓰기와 함께 전달되며 일반적으로 설정하거나 probe할 수 없습니다. 메모리 시스템에서 택한 경로에 따라 정해지므로 controller나 장치 하나만의 속성이 아니라 둘의 조합에 관한 속성입니다.

MSI 식별 요소

요소내용일반적인 구성 가능성

Doorbell쓰는 MMIO 주소소프트웨어 구성 가능

PayloadDoorbell에 쓰는 값구성 가능, controller 제약 가능

Sideband메모리 경로에 수반되는 정보대개 구성·probe 불가

MSI를 구분하는 세 정보와 구성 가능성을 비교합니다.

MSI controller

31-53

MSI controller는 master가 MMIO 주소에 쓰기를 수행할 때 CPU에 인터럽트를 알리며 여러 doorbell을 제공할 수 있습니다. 필수 불리언 `msi-controller`는 해당 노드를 MSI controller로 식별합니다.

선택 `#msi-cells`는 `msi-specifier`의 cell 수이며 0이 아니라면 필요합니다. 일반적으로 동적으로 구성 가능한 doorbell이나 payload가 아니라 sideband data와 관련된 정보를 인코딩합니다. Specifier의 의미는 특정 MSI controller의 Device Tree 바인딩이 정의합니다.

MSI controller 처리

MSI masterDoorbell + payload write

Memory pathSideband 정보

MSI controllerSpecifier 해석

CPUInterrupt signal

Master의 MMIO write가 controller를 거쳐 CPU interrupt가 됩니다.

MSI client와 msi-parent

54-77

MSI client는 MSI를 생성하는 장치입니다. 생성하려는 각 MSI의 doorbell과 payload는 구성할 수 있지만 sideband 정보는 구성하지 못할 수 있습니다.

필수 `msi-parent`는 장치가 사용할 수 있는 MSI controller마다 하나씩 phandle과 `msi-specifier` 쌍을 나열합니다. 목록 순서에는 의미가 없으며, MSI는 `msi-parent`에 나열된 controller의 어떤 조합에서든 할당할 수 있습니다.

장치의 MSI 할당에 제약이 있다면 추가 속성으로 그 제약을 기술해야 합니다. `#msi-cells`가 0이 아닌 경우 `msi-parent`를 가진 bus는 bus의 장치와 잠재적으로 생성할 수 있는 MSI 집합 사이의 관계를 설명하는 추가 속성이 필요합니다.

MSI client 선택

MSI clientmsi-parent 목록

Controller ASpecifier 선택

Controller B/CSpecifier와 sideband ID

Allocation허용 controller 조합

Client는 순서 없는 parent 목록에서 허용되는 controller 조합을 사용합니다.

세 MSI controller와 client 예제

78-135

예제의 controller A는 sideband data가 없어 `#msi-cells`를 생략합니다. Controller B와 C는 장치마다 고유 ID 하나가 필요하여 `#msi-cells = <1>`을 사용합니다.

`dev@0`은 A에만 MSI를 생성합니다. `dev@1`은 A 또는 B를 사용할 수 있고 B에서 ID `0x17`을 씁니다. `dev@2`는 A, B, C를 모두 사용할 수 있으며 B에서는 `0x17`, C에서는 `0x53`이라는 서로 다른 ID를 사용합니다.

/ {
        #address-cells = <1>;
        #size-cells = <1>;

        msi_a: msi-controller@a {
                reg = <0xa 0xf00>;
                compatible = "vendor-a,some-controller";
                msi-controller;
                /* No sideband data, so #msi-cells omitted */
        };

        msi_b: msi-controller@b {
                reg = <0xb 0xf00>;
                compatible = "vendor-b,another-controller";
                msi-controller;
                /* Each device has some unique ID */
                #msi-cells = <1>;
        };

        msi_c: msi-controller@c {
                reg = <0xc 0xf00>;
                compatible = "vendor-b,another-controller";
                msi-controller;
                /* Each device has some unique ID */
                #msi-cells = <1>;
        };

        dev@0 {
                reg = <0x0 0xf00>;
                compatible = "vendor-c,some-device";

                /* Can only generate MSIs to msi_a */
                msi-parent = <&msi_a>;
        };

        dev@1 {
                reg = <0x1 0xf00>;
                compatible = "vendor-c,some-device";

                /* 
                 * Can generate MSIs to either A or B.
                 */
                msi-parent = <&msi_a>, <&msi_b 0x17>;
        };

        dev@2 {
                reg = <0x2 0xf00>;
                compatible = "vendor-c,some-device";
                /*
                 * Has different IDs at each MSI controller.
                 * Can generate MSIs to all of the MSI controllers.
                 */
                msi-parent = <&msi_a>, <&msi_b 0x17>, <&msi_c 0x53>;
        };
};