제거된 IBM CAPI CXL sysfs ABI | Linux 6.18.37

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

1. 요약·해설

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

공유 attribute와 device symlink

sysfs-class-cxl:1-6

여러 context가 공유하는 attribute는 device/ symlink가 가리키는 실제 device directory에 저장됩니다.

AFU slave context

sysfs-class-cxl:9-110

Error buffer, interrupt 수, MMIO 크기, AFU mode, prefault policy, reset과 kernel/user API version을 제공했습니다.

AFU configuration record

sysfs-class-cxl:113-150

AFU가 선택적으로 내보내는 PCIe형 record에서 vendor ID, device ID, class code와 raw configuration space를 읽었습니다.

AFU master context

sysfs-class-cxl:154-177

Master context는 전체 MMIO 크기와 process별 MMIO window의 길이·offset을 노출했습니다.

Card 정보와 PERST 제어

sysfs-class-cxl:180-272

CAIA·PSL revision, FPGA image, PERST image reload, reset, timebase 동기화와 tunneled operation 지원 여부를 제어·조회했습니다.

2. 영어 원문 전체

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

원문 전체 펼치기

1 The cxl driver was removed in 6.15.

3 Please note that attributes that are shared between devices are stored in

4 the directory pointed to by the symlink device/.

5 For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is

6 /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.

9 Slave contexts (eg. /sys/class/cxl/afu0.0s):

11 What: /sys/class/cxl/<afu>/afu_err_buf

12 Date: September 2014, removed February 2025

13 Contact: linuxppc-dev@lists.ozlabs.org

14 Description: read only

15 AFU Error Buffer contents. The contents of this file are

16 application specific and depends on the AFU being used.

17 Applications interacting with the AFU can use this attribute

18 to know about the current error condition and take appropriate

19 action like logging the event etc.

22 What: /sys/class/cxl/<afu>/irqs_max

23 Date: September 2014, removed February 2025

24 Contact: linuxppc-dev@lists.ozlabs.org

25 Description: read/write

26 Decimal value of maximum number of interrupts that can be

27 requested by userspace. The default on probe is the maximum

28 that hardware can support (eg. 2037). Write values will limit

29 userspace applications to that many userspace interrupts. Must

30 be >= irqs_min.

31 Users: https://github.com/ibm-capi/libcxl

33 What: /sys/class/cxl/<afu>/irqs_min

34 Date: September 2014, removed February 2025

35 Contact: linuxppc-dev@lists.ozlabs.org

36 Description: read only

37 Decimal value of the minimum number of interrupts that

38 userspace must request on a CXL_START_WORK ioctl. Userspace may

39 omit the num_interrupts field in the START_WORK IOCTL to get

40 this minimum automatically.

41 Users: https://github.com/ibm-capi/libcxl

43 What: /sys/class/cxl/<afu>/mmio_size

44 Date: September 2014, removed February 2025

45 Contact: linuxppc-dev@lists.ozlabs.org

46 Description: read only

47 Decimal value of the size of the MMIO space that may be mmapped

48 by userspace.

49 Users: https://github.com/ibm-capi/libcxl

51 What: /sys/class/cxl/<afu>/modes_supported

52 Date: September 2014, removed February 2025

53 Contact: linuxppc-dev@lists.ozlabs.org

54 Description: read only

55 List of the modes this AFU supports. One per line.

56 Valid entries are: "dedicated_process" and "afu_directed"

57 Users: https://github.com/ibm-capi/libcxl

59 What: /sys/class/cxl/<afu>/mode

60 Date: September 2014, removed February 2025

61 Contact: linuxppc-dev@lists.ozlabs.org

62 Description: read/write

63 The current mode the AFU is using. Will be one of the modes

64 given in modes_supported. Writing will change the mode

65 provided that no user contexts are attached.

66 Users: https://github.com/ibm-capi/libcxl

69 What: /sys/class/cxl/<afu>/prefault_mode

70 Date: September 2014, removed February 2025

71 Contact: linuxppc-dev@lists.ozlabs.org

72 Description: read/write

73 Set the mode for prefaulting in segments into the segment table

74 when performing the START_WORK ioctl. Only applicable when

75 running under hashed page table mmu.

76 Possible values:

78 ======================= ======================================

79 none No prefaulting (default)

80 work_element_descriptor Treat the work element

81 descriptor as an effective address and

82 prefault what it points to.

83 all all segments process calling

84 START_WORK maps.

85 ======================= ======================================

87 Users: https://github.com/ibm-capi/libcxl

89 What: /sys/class/cxl/<afu>/reset

90 Date: September 2014, removed February 2025

91 Contact: linuxppc-dev@lists.ozlabs.org

92 Description: write only

93 Writing 1 here will reset the AFU provided there are not

94 contexts active on the AFU.

95 Users: https://github.com/ibm-capi/libcxl

97 What: /sys/class/cxl/<afu>/api_version

98 Date: September 2014, removed February 2025

99 Contact: linuxppc-dev@lists.ozlabs.org

100 Description: read only

101 Decimal value of the current version of the kernel/user API.

102 Users: https://github.com/ibm-capi/libcxl

103

104 What: /sys/class/cxl/<afu>/api_version_compatible

105 Date: September 2014, removed February 2025

106 Contact: linuxppc-dev@lists.ozlabs.org

107 Description: read only

108 Decimal value of the lowest version of the userspace API

109 this kernel supports.

110 Users: https://github.com/ibm-capi/libcxl

111

112

113 AFU configuration records (eg. /sys/class/cxl/afu0.0/cr0):

114

115 An AFU may optionally export one or more PCIe like configuration records, known

116 as AFU configuration records, which will show up here (if present).

117

118 What: /sys/class/cxl/<afu>/cr<config num>/vendor

119 Date: February 2015, removed February 2025

120 Contact: linuxppc-dev@lists.ozlabs.org

121 Description: read only

122 Hexadecimal value of the vendor ID found in this AFU

123 configuration record.

124 Users: https://github.com/ibm-capi/libcxl

125

126 What: /sys/class/cxl/<afu>/cr<config num>/device

127 Date: February 2015, removed February 2025

128 Contact: linuxppc-dev@lists.ozlabs.org

129 Description: read only

130 Hexadecimal value of the device ID found in this AFU

131 configuration record.

132 Users: https://github.com/ibm-capi/libcxl

133

134 What: /sys/class/cxl/<afu>/cr<config num>/class

135 Date: February 2015, removed February 2025

136 Contact: linuxppc-dev@lists.ozlabs.org

137 Description: read only

138 Hexadecimal value of the class code found in this AFU

139 configuration record.

140 Users: https://github.com/ibm-capi/libcxl

141

142 What: /sys/class/cxl/<afu>/cr<config num>/config

143 Date: February 2015, removed February 2025

144 Contact: linuxppc-dev@lists.ozlabs.org

145 Description: read only

146 This binary file provides raw access to the AFU configuration

147 record. The format is expected to match the either the standard

148 or extended configuration space defined by the PCIe

149 specification.

150 Users: https://github.com/ibm-capi/libcxl

151

152

153

154 Master contexts (eg. /sys/class/cxl/afu0.0m)

155

156 What: /sys/class/cxl/<afu>m/mmio_size

157 Date: September 2014, removed February 2025

158 Contact: linuxppc-dev@lists.ozlabs.org

159 Description: read only

160 Decimal value of the size of the MMIO space that may be mmapped

161 by userspace. This includes all slave contexts space also.

162 Users: https://github.com/ibm-capi/libcxl

163

164 What: /sys/class/cxl/<afu>m/pp_mmio_len

165 Date: September 2014, removed February 2025

166 Contact: linuxppc-dev@lists.ozlabs.org

167 Description: read only

168 Decimal value of the Per Process MMIO space length.

169 Users: https://github.com/ibm-capi/libcxl

170

171 What: /sys/class/cxl/<afu>m/pp_mmio_off

172 Date: September 2014, removed February 2025

173 Contact: linuxppc-dev@lists.ozlabs.org

174 Description: read only

175 (not in a guest)

176 Decimal value of the Per Process MMIO space offset.

177 Users: https://github.com/ibm-capi/libcxl

178

179

180 Card info (eg. /sys/class/cxl/card0)

181

182 What: /sys/class/cxl/<card>/caia_version

183 Date: September 2014, removed February 2025

184 Contact: linuxppc-dev@lists.ozlabs.org

185 Description: read only

186 Identifies the CAIA Version the card implements.

187 Users: https://github.com/ibm-capi/libcxl

188

189 What: /sys/class/cxl/<card>/psl_revision

190 Date: September 2014, removed February 2025

191 Contact: linuxppc-dev@lists.ozlabs.org

192 Description: read only

193 Identifies the revision level of the PSL.

194 Users: https://github.com/ibm-capi/libcxl

195

196 What: /sys/class/cxl/<card>/base_image

197 Date: September 2014, removed February 2025

198 Contact: linuxppc-dev@lists.ozlabs.org

199 Description: read only

200 (not in a guest)

201 Identifies the revision level of the base image for devices

202 that support loadable PSLs. For FPGAs this field identifies

203 the image contained in the on-adapter flash which is loaded

204 during the initial program load.

205 Users: https://github.com/ibm-capi/libcxl

206

207 What: /sys/class/cxl/<card>/image_loaded

208 Date: September 2014, removed February 2025

209 Contact: linuxppc-dev@lists.ozlabs.org

210 Description: read only

211 (not in a guest)

212 Will return "user" or "factory" depending on the image loaded

213 onto the card.

214 Users: https://github.com/ibm-capi/libcxl

215

216 What: /sys/class/cxl/<card>/load_image_on_perst

217 Date: December 2014, removed February 2025

218 Contact: linuxppc-dev@lists.ozlabs.org

219 Description: read/write

220 (not in a guest)

221 Valid entries are "none", "user", and "factory".

222 "none" means PERST will not cause image to be loaded to the

223 card. A power cycle is required to load the image.

224 "none" could be useful for debugging because the trace arrays

225 are preserved.

226

227 "user" and "factory" means PERST will cause either the user or

228 user or factory image to be loaded.

229 Default is to reload on PERST whichever image the card has

230 loaded.

231 Users: https://github.com/ibm-capi/libcxl

232

233 What: /sys/class/cxl/<card>/reset

234 Date: October 2014, removed February 2025

235 Contact: linuxppc-dev@lists.ozlabs.org

236 Description: write only

237 Writing 1 will issue a PERST to card provided there are no

238 contexts active on any one of the card AFUs. This may cause

239 the card to reload the FPGA depending on load_image_on_perst.

240 Writing -1 will do a force PERST irrespective of any active

241 contexts on the card AFUs.

242 Users: https://github.com/ibm-capi/libcxl

243

244 What: /sys/class/cxl/<card>/perst_reloads_same_image

245 Date: July 2015, removed February 2025

246 Contact: linuxppc-dev@lists.ozlabs.org

247 Description: read/write

248 (not in a guest)

249 Trust that when an image is reloaded via PERST, it will not

250 have changed.

251

252 == =================================================

253 0 don't trust, the image may be different (default)

254 1 trust that the image will not change.

255 == =================================================

256 Users: https://github.com/ibm-capi/libcxl

257

258 What: /sys/class/cxl/<card>/psl_timebase_synced

259 Date: March 2016, removed February 2025

260 Contact: linuxppc-dev@lists.ozlabs.org

261 Description: read only

262 Returns 1 if the psl timebase register is synchronized

263 with the core timebase register, 0 otherwise.

264 Users: https://github.com/ibm-capi/libcxl

265

266 What: /sys/class/cxl/<card>/tunneled_ops_supported

267 Date: May 2018, removed February 2025

268 Contact: linuxppc-dev@lists.ozlabs.org

269 Description: read only

270 Returns 1 if tunneled operations are supported in capi mode,

271 0 otherwise.

272 Users: https://github.com/ibm-capi/libcxl

273

3. 한국어 전문 번역

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

Driver 제거와 sysfs 배치

1-6

이 문서의 cxl driver는 IBM CAPI(Coherent Accelerator Processor Interface) 계열 accelerator를 위한 기존 driver이며 Linux 6.15에서 제거됐다.

여러 device가 공유하는 attribute는 device/ symlink가 가리키는 directory에 저장된다. 예를 들어 /sys/class/cxl/afu0.0s/irqs_max의 실제 경로는 /sys/class/cxl/afu0.0s/device/irqs_max, 즉 /sys/class/cxl/afu0.0/irqs_max다.

Slave context

9-110

Slave context의 예시는 /sys/class/cxl/afu0.0s다. 아래 항목의 contact는 linuxppc-dev@lists.ozlabs.org이며 모두 2014년 9월에 작성되고 2025년 2월에 제거됐다. 별도로 표시하지 않은 Users는 https://github.com/ibm-capi/libcxl이다.

경로	접근	의미
/sys/class/cxl/<afu>/afu_err_buf	read-only	AFU Error Buffer의 내용이다. 내용은 application별로 다르며 사용하는 AFU에 따라 달라진다. AFU와 상호 작용하는 application은 현재 오류 상태를 파악하고 event 기록 같은 적절한 조치를 하는 데 이 attribute를 사용할 수 있다.
/sys/class/cxl/<afu>/irqs_max	read/write	user space가 요청할 수 있는 최대 interrupt 수의 10진수 값이다. Probe 직후 기본값은 hardware가 지원하는 최댓값이며 예시는 2037이다. 값을 쓰면 user space application이 사용할 수 있는 user space interrupt 수를 그 값으로 제한한다. irqs_min 이상이어야 한다.
/sys/class/cxl/<afu>/irqs_min	read-only	user space가 CXL_START_WORK ioctl에서 요청해야 하는 최소 interrupt 수의 10진수 값이다. START_WORK IOCTL에서 num_interrupts field를 생략하면 이 최솟값을 자동으로 사용할 수 있다.
/sys/class/cxl/<afu>/mmio_size	read-only	user space가 mmap할 수 있는 MMIO 공간 크기의 10진수 값이다.
/sys/class/cxl/<afu>/modes_supported	read-only	AFU가 지원하는 mode를 한 줄에 하나씩 나열한다. 유효한 값은 dedicated_process와 afu_directed다.
/sys/class/cxl/<afu>/mode	read/write	AFU가 현재 사용하는 mode이며 modes_supported에 나온 값 가운데 하나다. 연결된 user context가 없을 때 값을 쓰면 mode를 변경할 수 있다.

prefault_mode

/sys/class/cxl/<afu>/prefault_mode는 read/write attribute다. START_WORK ioctl을 수행할 때 segment table에 segment를 미리 fault-in하는 mode를 설정한다. Hashed page table MMU에서 실행할 때만 적용된다.

값	동작
none	Prefault를 수행하지 않는다. 기본값이다.
work_element_descriptor	work element descriptor를 effective address로 취급하고, 그 주소가 가리키는 대상을 prefault한다.
all	START_WORK를 호출한 process가 mapping한 모든 segment를 prefault한다.

경로	접근	의미
/sys/class/cxl/<afu>/reset	write-only	AFU에 활성 context가 없을 때 1을 쓰면 AFU를 reset한다.
/sys/class/cxl/<afu>/api_version	read-only	현재 kernel/user API version의 10진수 값이다.
/sys/class/cxl/<afu>/api_version_compatible	read-only	이 kernel이 지원하는 user space API 가운데 가장 낮은 version의 10진수 값이다.

AFU configuration record

113-150

AFU는 AFU configuration record라고 부르는 PCIe와 비슷한 configuration record를 하나 이상 선택적으로 내보낼 수 있다. Record가 존재하면 /sys/class/cxl/afu0.0/cr0 같은 위치에 나타난다. 아래 항목은 2015년 2월에 작성되고 2025년 2월에 제거됐으며 contact는 linuxppc-dev@lists.ozlabs.org, Users는 https://github.com/ibm-capi/libcxl이다.

경로	접근	의미
/sys/class/cxl/<afu>/cr<config num>/vendor	read-only	이 AFU configuration record에 있는 vendor ID의 16진수 값이다.
/sys/class/cxl/<afu>/cr<config num>/device	read-only	이 AFU configuration record에 있는 device ID의 16진수 값이다.
/sys/class/cxl/<afu>/cr<config num>/class	read-only	이 AFU configuration record에 있는 class code의 16진수 값이다.
/sys/class/cxl/<afu>/cr<config num>/config	read-only binary	AFU configuration record에 raw access를 제공하는 binary file이다. 형식은 PCIe specification이 정의한 standard 또는 extended configuration space와 일치할 것으로 예상한다.

Master context

154-177

Master context의 예시는 /sys/class/cxl/afu0.0m이다. 아래 read-only 항목은 2014년 9월에 작성되고 2025년 2월에 제거됐으며 contact는 linuxppc-dev@lists.ozlabs.org, Users는 https://github.com/ibm-capi/libcxl이다.

경로	의미
/sys/class/cxl/<afu>m/mmio_size	user space가 mmap할 수 있는 MMIO 공간 크기의 10진수 값이다. 모든 slave context의 공간도 포함한다.
/sys/class/cxl/<afu>m/pp_mmio_len	Per Process MMIO 공간 길이의 10진수 값이다.
/sys/class/cxl/<afu>m/pp_mmio_off	Per Process MMIO 공간 offset의 10진수 값이다. Guest에서는 제공되지 않는다.

Card 정보

180-214

Card 정보의 예시는 /sys/class/cxl/card0이다. 아래 항목의 contact는 linuxppc-dev@lists.ozlabs.org이고 Users는 https://github.com/ibm-capi/libcxl이며, 모두 2014년 9월에 작성되고 2025년 2월에 제거됐다.

경로	접근	의미
/sys/class/cxl/<card>/caia_version	read-only	card가 구현한 CAIA version을 식별한다.
/sys/class/cxl/<card>/psl_revision	read-only	PSL의 revision level을 식별한다.
/sys/class/cxl/<card>/base_image	read-only	Guest에서는 제공되지 않는다. Load 가능한 PSL을 지원하는 device의 base image revision level을 식별한다. FPGA에서는 initial program load 때 불러오는 on-adapter flash image를 식별한다.
/sys/class/cxl/<card>/image_loaded	read-only	Guest에서는 제공되지 않는다. Card에 load된 image에 따라 "user" 또는 "factory"를 반환한다.

Card image와 PERST 제어

216-272

아래 항목의 contact는 linuxppc-dev@lists.ozlabs.org이고 Users는 https://github.com/ibm-capi/libcxl이며, 모두 2025년 2월에 제거됐다.

load_image_on_perst

/sys/class/cxl/<card>/load_image_on_perst는 2014년 12월에 작성된 read/write attribute이며 guest에서는 제공되지 않는다. 유효한 값은 none, user, factory다.

값	PERST 동작
none	PERST가 card에 image를 load하지 않는다. Image를 load하려면 power cycle이 필요하다. Trace array가 보존되므로 debugging에 유용할 수 있다.
user	PERST가 user image를 load한다.
factory	PERST가 factory image를 load한다.

기본 동작은 card에 현재 load되어 있는 image가 무엇이든 PERST 때 같은 종류를 다시 load하는 것이다.

reset

/sys/class/cxl/<card>/reset은 2014년 10월에 작성된 write-only attribute다. Card의 어떤 AFU에도 활성 context가 없을 때 1을 쓰면 card에 PERST를 발생시킨다. load_image_on_perst 설정에 따라 FPGA를 다시 load할 수 있다. -1을 쓰면 card AFU의 활성 context 여부와 관계없이 강제로 PERST를 수행한다.

perst_reloads_same_image

/sys/class/cxl/<card>/perst_reloads_same_image는 2015년 7월에 작성된 read/write attribute이며 guest에서는 제공되지 않는다. PERST로 image를 다시 load할 때 image가 바뀌지 않는다고 신뢰할지를 지정한다.

값	의미
0	신뢰하지 않는다. Image가 달라질 수 있으며 기본값이다.
1	Image가 바뀌지 않는다고 신뢰한다.

경로	작성 시점	접근	의미
/sys/class/cxl/<card>/psl_timebase_synced	2016년 3월	read-only	PSL timebase register가 core timebase register와 동기화됐으면 1, 아니면 0을 반환한다.
/sys/class/cxl/<card>/tunneled_ops_supported	2018년 5월	read-only	CAPI mode에서 tunneled operation을 지원하면 1, 아니면 0을 반환한다.