Xilinx IP Core Device Tree Bindings | Linux 6.18.37

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

1. 요약·해설

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

요약과 해설

xilinx.txt:1-139

Xilinx FPGA IP 코어 매개변수를 Device Tree 속성으로 변환하는 규칙과 UARTLite, framebuffer, Ethernet, hwicap, USB 바인딩을 설명합니다. 읽을 수 있는 영어 원문 전체와 한국어 전문 번역을 함께 제공하며, 속성명, compatible 문자열, 주소, 값과 원문 줄 좌표를 그대로 보존합니다.

2. 영어 원문 전체

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

원문 전체 펼치기

1 d) Xilinx IP cores

3 The Xilinx EDK toolchain ships with a set of IP cores (devices) for use

4 in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range

5 of standard device types (network, serial, etc.) and miscellaneous

6 devices (gpio, LCD, spi, etc). Also, since these devices are

7 implemented within the fpga fabric every instance of the device can be

8 synthesised with different options that change the behaviour.

10 Each IP-core has a set of parameters which the FPGA designer can use to

11 control how the core is synthesized. Historically, the EDK tool would

12 extract the device parameters relevant to device drivers and copy them

13 into an 'xparameters.h' in the form of #define symbols. This tells the

14 device drivers how the IP cores are configured, but it requires the kernel

15 to be recompiled every time the FPGA bitstream is resynthesized.

17 The new approach is to export the parameters into the device tree and

18 generate a new device tree each time the FPGA bitstream changes. The

19 parameters which used to be exported as #defines will now become

20 properties of the device node. In general, device nodes for IP-cores

21 will take the following form:

23 (name): (generic-name)@(base-address) {

24 compatible = "xlnx,(ip-core-name)-(HW_VER)"

25 [, (list of compatible devices), ...];

26 reg = <(baseaddr) (size)>;

27 interrupt-parent = <&interrupt-controller-phandle>;

28 interrupts = < ... >;

29 xlnx,(parameter1) = "(string-value)";

30 xlnx,(parameter2) = <(int-value)>;

31 };

33 (generic-name): an open firmware-style name that describes the

34 generic class of device. Preferably, this is one word, such

35 as 'serial' or 'ethernet'.

36 (ip-core-name): the name of the ip block (given after the BEGIN

37 directive in system.mhs). Should be in lowercase

38 and all underscores '_' converted to dashes '-'.

39 (name): is derived from the "PARAMETER INSTANCE" value.

40 (parameter#): C_* parameters from system.mhs. The C_ prefix is

41 dropped from the parameter name, the name is converted

42 to lowercase and all underscore '_' characters are

43 converted to dashes '-'.

44 (baseaddr): the baseaddr parameter value (often named C_BASEADDR).

45 (HW_VER): from the HW_VER parameter.

46 (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1).

48 Typically, the compatible list will include the exact IP core version

49 followed by an older IP core version which implements the same

50 interface or any other device with the same interface.

52 'reg' and 'interrupts' are all optional properties.

54 For example, the following block from system.mhs:

56 BEGIN opb_uartlite

57 PARAMETER INSTANCE = opb_uartlite_0

58 PARAMETER HW_VER = 1.00.b

59 PARAMETER C_BAUDRATE = 115200

60 PARAMETER C_DATA_BITS = 8

61 PARAMETER C_ODD_PARITY = 0

62 PARAMETER C_USE_PARITY = 0

63 PARAMETER C_CLK_FREQ = 50000000

64 PARAMETER C_BASEADDR = 0xEC100000

65 PARAMETER C_HIGHADDR = 0xEC10FFFF

66 BUS_INTERFACE SOPB = opb_7

67 PORT OPB_Clk = CLK_50MHz

68 PORT Interrupt = opb_uartlite_0_Interrupt

69 PORT RX = opb_uartlite_0_RX

70 PORT TX = opb_uartlite_0_TX

71 PORT OPB_Rst = sys_bus_reset_0

72 END

74 becomes the following device tree node:

76 opb_uartlite_0: serial@ec100000 {

77 device_type = "serial";

78 compatible = "xlnx,opb-uartlite-1.00.b";

79 reg = <ec100000 10000>;

80 interrupt-parent = <&opb_intc_0>;

81 interrupts = <1 0>; // got this from the opb_intc parameters

82 current-speed = <d#115200>; // standard serial device prop

83 clock-frequency = <d#50000000>; // standard serial device prop

84 xlnx,data-bits = <8>;

85 xlnx,odd-parity = <0>;

86 xlnx,use-parity = <0>;

87 };

89 That covers the general approach to binding xilinx IP cores into the

90 device tree. The following are bindings for specific devices:

92 i) Xilinx ML300 Framebuffer

94 Simple framebuffer device from the ML300 reference design (also on the

95 ML403 reference design as well as others).

97 Optional properties:

98 - resolution = <xres yres> : pixel resolution of framebuffer. Some

99 implementations use a different resolution.

100 Default is <d#640 d#480>

101 - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.

102 Default is <d#1024 d#480>.

103 - rotate-display (empty) : rotate display 180 degrees.

104

105 iii) Xilinx EMAC and Xilinx TEMAC

106

107 Xilinx Ethernet devices. In addition to general xilinx properties

108 listed above, nodes for these devices should include a phy-handle

109 property, and may include other common network device properties

110 like local-mac-address.

111

112 v) Xilinx hwicap

113

114 Xilinx hwicap devices provide access to the configuration logic

115 of the FPGA through the Internal Configuration Access Port

116 (ICAP). The ICAP enables partial reconfiguration of the FPGA,

117 readback of the configuration information, and some control over

118 'warm boots' of the FPGA fabric.

119

120 Required properties:

121 - xlnx,family : The family of the FPGA, necessary since the

122 capabilities of the underlying ICAP hardware

123 differ between different families. May be

124 'virtex2p', 'virtex4', or 'virtex5'.

125 - compatible : should contain "xlnx,xps-hwicap-1.00.a" or

126 "xlnx,opb-hwicap-1.00.b".

127

128 vii) Xilinx USB Host controller

129

130 The Xilinx USB host controller is EHCI compatible but with a different

131 base address for the EHCI registers, and it is always a big-endian

132 USB Host controller. The hardware can be configured as high speed only,

133 or high speed/full speed hybrid.

134

135 Required properties:

136 - xlnx,support-usb-fs: A value 0 means the core is built as high speed

137 only. A value 1 means the core also supports

138 full speed devices.

139

140

3. 한국어 전문 번역

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

Xilinx FPGA의 IP 코어

1-8

Xilinx EDK 도구 모음에는 Xilinx Spartan 및 Virtex FPGA에서 사용할 IP 코어, 즉 장치 집합이 포함됩니다. 이 장치들은 네트워크와 직렬 통신 같은 표준 장치 유형 전체와 GPIO, LCD, SPI 같은 기타 장치를 포괄합니다.

이 장치들은 FPGA 패브릭 안에 구현되므로 장치의 각 인스턴스를 서로 다른 옵션으로 합성하여 동작을 바꿀 수 있습니다.

xparameters.h에서 Device Tree 속성으로

9-21

각 IP 코어에는 FPGA 설계자가 코어의 합성 방식을 제어하는 데 사용할 수 있는 매개변수 집합이 있습니다. 과거에는 EDK 도구가 장치 드라이버에 관련된 매개변수를 추출하여 `#define` 심볼 형식으로 `xparameters.h`에 복사했습니다.

이 방식은 IP 코어의 구성 방법을 장치 드라이버에 알려 주지만, FPGA 비트스트림을 다시 합성할 때마다 커널도 다시 컴파일해야 한다는 문제가 있습니다.

새 방식은 매개변수를 Device Tree로 내보내고 FPGA 비트스트림이 바뀔 때마다 새 Device Tree를 생성합니다. 이전에 `#define`으로 내보내던 매개변수는 이제 장치 노드의 속성이 됩니다. 일반적인 IP 코어 장치 노드는 다음 형식을 사용합니다.

IP 코어 노드 형식과 이름 변환 규칙

22-52

(name): (generic-name)@(base-address) {
        compatible = "xlnx,(ip-core-name)-(HW_VER)"
                     [, (list of compatible devices), ...];
        reg = <(baseaddr) (size)>;
        interrupt-parent = <&interrupt-controller-phandle>;
        interrupts = < ... >;
        xlnx,(parameter1) = "(string-value)";
        xlnx,(parameter2) = <(int-value)>;
};

`(generic-name)`은 장치의 일반 클래스를 설명하는 Open Firmware 스타일 이름입니다. `serial`이나 `ethernet`처럼 한 단어를 사용하는 것이 좋습니다.

`(ip-core-name)`은 `system.mhs`의 `BEGIN` 지시문 뒤에 나오는 IP 블록 이름입니다. 소문자로 바꾸고 밑줄 `_`은 모두 대시 `-`로 바꿉니다. `(name)`은 `PARAMETER INSTANCE` 값에서 가져옵니다.

`(parameter#)`은 `system.mhs`의 `C_*` 매개변수입니다. 이름에서 `C_` 접두사를 제거하고 소문자로 바꾼 뒤 모든 밑줄 `_`을 대시 `-`로 변환합니다.

`(baseaddr)`은 대개 `C_BASEADDR`라는 이름의 기본 주소 매개변수 값이고, `(HW_VER)`은 `HW_VER` 매개변수에서 가져옵니다. `(size)`는 주소 범위의 크기로, 보통 `C_HIGHADDR - C_BASEADDR + 1`입니다.

일반적으로 `compatible` 목록에는 정확한 IP 코어 버전을 먼저 넣고, 같은 인터페이스를 구현하는 이전 IP 코어 버전이나 같은 인터페이스를 가진 다른 장치를 뒤에 넣습니다. `reg`와 `interrupts` 속성은 모두 선택 사항입니다.

system.mhs에서 UARTLite 노드로 변환

53-90

다음 `system.mhs` 블록은 `opb_uartlite_0` 인스턴스의 하드웨어 버전, 직렬 통신 설정, 클록, 주소 범위, 버스 인터페이스와 포트를 정의합니다.

BEGIN opb_uartlite
        PARAMETER INSTANCE = opb_uartlite_0
        PARAMETER HW_VER = 1.00.b
        PARAMETER C_BAUDRATE = 115200
        PARAMETER C_DATA_BITS = 8
        PARAMETER C_ODD_PARITY = 0
        PARAMETER C_USE_PARITY = 0
        PARAMETER C_CLK_FREQ = 50000000
        PARAMETER C_BASEADDR = 0xEC100000
        PARAMETER C_HIGHADDR = 0xEC10FFFF
        BUS_INTERFACE SOPB = opb_7
        PORT OPB_Clk = CLK_50MHz
        PORT Interrupt = opb_uartlite_0_Interrupt
        PORT RX = opb_uartlite_0_RX
        PORT TX = opb_uartlite_0_TX
        PORT OPB_Rst = sys_bus_reset_0
END

이 블록은 다음 Device Tree 노드로 변환됩니다. `C_BASEADDR`와 `C_HIGHADDR`에서 `reg` 범위를 만들고, 인터럽트 컨트롤러 매개변수에서 `interrupts`를 가져옵니다. 표준 직렬 장치 속성은 `current-speed`와 `clock-frequency`로 표현하고, 나머지 코어별 매개변수에는 `xlnx,` 접두사를 붙입니다.

opb_uartlite_0: serial@ec100000 {
        device_type = "serial";
        compatible = "xlnx,opb-uartlite-1.00.b";
        reg = <ec100000 10000>;
        interrupt-parent = <&opb_intc_0>;
        interrupts = <1 0>; // got this from the opb_intc parameters
        current-speed = <d#115200>;        // standard serial device prop
        clock-frequency = <d#50000000>;        // standard serial device prop
        xlnx,data-bits = <8>;
        xlnx,odd-parity = <0>;
        xlnx,use-parity = <0>;
};

여기까지가 Xilinx IP 코어를 Device Tree에 바인딩하는 일반적인 방법입니다. 다음 절부터는 특정 장치에 대한 바인딩을 설명합니다.

Xilinx ML300 Framebuffer

91-104

Xilinx ML300 Framebuffer는 ML300 참조 설계의 단순 프레임버퍼 장치이며 ML403을 비롯한 다른 참조 설계에도 사용됩니다.

선택 속성 `resolution = <xres yres>`는 프레임버퍼의 픽셀 해상도를 지정합니다. 일부 구현은 다른 해상도를 사용하며 기본값은 `<d#640 d#480>`입니다.

`virt-resolution = <xvirt yvirt>`는 메모리 안의 프레임버퍼 크기를 지정하며 기본값은 `<d#1024 d#480>`입니다. 값이 없는 `rotate-display` 속성을 지정하면 화면을 180도 회전합니다.

Xilinx EMAC와 TEMAC

105-111

Xilinx EMAC와 Xilinx TEMAC은 이더넷 장치입니다. 이 장치의 노드에는 앞서 설명한 일반 Xilinx 속성뿐 아니라 `phy-handle` 속성도 포함해야 합니다. `local-mac-address` 같은 다른 공통 네트워크 장치 속성도 포함할 수 있습니다.

Xilinx hwicap

112-127

Xilinx hwicap 장치는 Internal Configuration Access Port(ICAP)를 통해 FPGA의 구성 로직에 접근합니다. ICAP는 FPGA의 부분 재구성, 구성 정보의 readback, FPGA 패브릭의 일부 warm boot 제어 기능을 제공합니다.

필수 `xlnx,family` 속성은 FPGA 제품군을 지정합니다. 기반 ICAP 하드웨어의 기능이 제품군마다 다르기 때문에 필요하며, 값은 `virtex2p`, `virtex4`, `virtex5` 중 하나입니다.

필수 `compatible` 속성에는 `xlnx,xps-hwicap-1.00.a` 또는 `xlnx,opb-hwicap-1.00.b`가 들어가야 합니다.

Xilinx USB Host controller

128-139

Xilinx USB 호스트 컨트롤러는 EHCI 호환이지만 EHCI 레지스터의 기본 주소가 다르며 항상 big-endian 방식으로 동작합니다. 하드웨어는 high speed 전용 또는 high speed와 full speed를 함께 지원하는 하이브리드 방식으로 구성할 수 있습니다.

필수 `xlnx,support-usb-fs` 속성의 값이 0이면 코어가 high speed 전용으로 빌드되었음을 뜻합니다. 값이 1이면 코어가 full speed 장치도 지원함을 뜻합니다.