cxlflash.rst 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433
  1. ================================
  2. Coherent Accelerator (CXL) Flash
  3. ================================
  4. Introduction
  5. ============
  6. The IBM Power architecture provides support for CAPI (Coherent
  7. Accelerator Power Interface), which is available to certain PCIe slots
  8. on Power 8 systems. CAPI can be thought of as a special tunneling
  9. protocol through PCIe that allow PCIe adapters to look like special
  10. purpose co-processors which can read or write an application's
  11. memory and generate page faults. As a result, the host interface to
  12. an adapter running in CAPI mode does not require the data buffers to
  13. be mapped to the device's memory (IOMMU bypass) nor does it require
  14. memory to be pinned.
  15. On Linux, Coherent Accelerator (CXL) kernel services present CAPI
  16. devices as a PCI device by implementing a virtual PCI host bridge.
  17. This abstraction simplifies the infrastructure and programming
  18. model, allowing for drivers to look similar to other native PCI
  19. device drivers.
  20. CXL provides a mechanism by which user space applications can
  21. directly talk to a device (network or storage) bypassing the typical
  22. kernel/device driver stack. The CXL Flash Adapter Driver enables a
  23. user space application direct access to Flash storage.
  24. The CXL Flash Adapter Driver is a kernel module that sits in the
  25. SCSI stack as a low level device driver (below the SCSI disk and
  26. protocol drivers) for the IBM CXL Flash Adapter. This driver is
  27. responsible for the initialization of the adapter, setting up the
  28. special path for user space access, and performing error recovery. It
  29. communicates directly the Flash Accelerator Functional Unit (AFU)
  30. as described in Documentation/powerpc/cxl.rst.
  31. The cxlflash driver supports two, mutually exclusive, modes of
  32. operation at the device (LUN) level:
  33. - Any flash device (LUN) can be configured to be accessed as a
  34. regular disk device (i.e.: /dev/sdc). This is the default mode.
  35. - Any flash device (LUN) can be configured to be accessed from
  36. user space with a special block library. This mode further
  37. specifies the means of accessing the device and provides for
  38. either raw access to the entire LUN (referred to as direct
  39. or physical LUN access) or access to a kernel/AFU-mediated
  40. partition of the LUN (referred to as virtual LUN access). The
  41. segmentation of a disk device into virtual LUNs is assisted
  42. by special translation services provided by the Flash AFU.
  43. Overview
  44. ========
  45. The Coherent Accelerator Interface Architecture (CAIA) introduces a
  46. concept of a master context. A master typically has special privileges
  47. granted to it by the kernel or hypervisor allowing it to perform AFU
  48. wide management and control. The master may or may not be involved
  49. directly in each user I/O, but at the minimum is involved in the
  50. initial setup before the user application is allowed to send requests
  51. directly to the AFU.
  52. The CXL Flash Adapter Driver establishes a master context with the
  53. AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
  54. Adapter Problem Space Memory Map looks like this::
  55. +-------------------------------+
  56. | 512 * 64 KB User MMIO |
  57. | (per context) |
  58. | User Accessible |
  59. +-------------------------------+
  60. | 512 * 128 B per context |
  61. | Provisioning and Control |
  62. | Trusted Process accessible |
  63. +-------------------------------+
  64. | 64 KB Global |
  65. | Trusted Process accessible |
  66. +-------------------------------+
  67. This driver configures itself into the SCSI software stack as an
  68. adapter driver. The driver is the only entity that is considered a
  69. Trusted Process to program the Provisioning and Control and Global
  70. areas in the MMIO Space shown above. The master context driver
  71. discovers all LUNs attached to the CXL Flash adapter and instantiates
  72. scsi block devices (/dev/sdb, /dev/sdc etc.) for each unique LUN
  73. seen from each path.
  74. Once these scsi block devices are instantiated, an application
  75. written to a specification provided by the block library may get
  76. access to the Flash from user space (without requiring a system call).
  77. This master context driver also provides a series of ioctls for this
  78. block library to enable this user space access. The driver supports
  79. two modes for accessing the block device.
  80. The first mode is called a virtual mode. In this mode a single scsi
  81. block device (/dev/sdb) may be carved up into any number of distinct
  82. virtual LUNs. The virtual LUNs may be resized as long as the sum of
  83. the sizes of all the virtual LUNs, along with the meta-data associated
  84. with it does not exceed the physical capacity.
  85. The second mode is called the physical mode. In this mode a single
  86. block device (/dev/sdb) may be opened directly by the block library
  87. and the entire space for the LUN is available to the application.
  88. Only the physical mode provides persistence of the data. i.e. The
  89. data written to the block device will survive application exit and
  90. restart and also reboot. The virtual LUNs do not persist (i.e. do
  91. not survive after the application terminates or the system reboots).
  92. Block library API
  93. =================
  94. Applications intending to get access to the CXL Flash from user
  95. space should use the block library, as it abstracts the details of
  96. interfacing directly with the cxlflash driver that are necessary for
  97. performing administrative actions (i.e.: setup, tear down, resize).
  98. The block library can be thought of as a 'user' of services,
  99. implemented as IOCTLs, that are provided by the cxlflash driver
  100. specifically for devices (LUNs) operating in user space access
  101. mode. While it is not a requirement that applications understand
  102. the interface between the block library and the cxlflash driver,
  103. a high-level overview of each supported service (IOCTL) is provided
  104. below.
  105. The block library can be found on GitHub:
  106. http://github.com/open-power/capiflash
  107. CXL Flash Driver LUN IOCTLs
  108. ===========================
  109. Users, such as the block library, that wish to interface with a flash
  110. device (LUN) via user space access need to use the services provided
  111. by the cxlflash driver. As these services are implemented as ioctls,
  112. a file descriptor handle must first be obtained in order to establish
  113. the communication channel between a user and the kernel. This file
  114. descriptor is obtained by opening the device special file associated
  115. with the scsi disk device (/dev/sdb) that was created during LUN
  116. discovery. As per the location of the cxlflash driver within the
  117. SCSI protocol stack, this open is actually not seen by the cxlflash
  118. driver. Upon successful open, the user receives a file descriptor
  119. (herein referred to as fd1) that should be used for issuing the
  120. subsequent ioctls listed below.
  121. The structure definitions for these IOCTLs are available in:
  122. uapi/scsi/cxlflash_ioctl.h
  123. DK_CXLFLASH_ATTACH
  124. ------------------
  125. This ioctl obtains, initializes, and starts a context using the CXL
  126. kernel services. These services specify a context id (u16) by which
  127. to uniquely identify the context and its allocated resources. The
  128. services additionally provide a second file descriptor (herein
  129. referred to as fd2) that is used by the block library to initiate
  130. memory mapped I/O (via mmap()) to the CXL flash device and poll for
  131. completion events. This file descriptor is intentionally installed by
  132. this driver and not the CXL kernel services to allow for intermediary
  133. notification and access in the event of a non-user-initiated close(),
  134. such as a killed process. This design point is described in further
  135. detail in the description for the DK_CXLFLASH_DETACH ioctl.
  136. There are a few important aspects regarding the "tokens" (context id
  137. and fd2) that are provided back to the user:
  138. - These tokens are only valid for the process under which they
  139. were created. The child of a forked process cannot continue
  140. to use the context id or file descriptor created by its parent
  141. (see DK_CXLFLASH_VLUN_CLONE for further details).
  142. - These tokens are only valid for the lifetime of the context and
  143. the process under which they were created. Once either is
  144. destroyed, the tokens are to be considered stale and subsequent
  145. usage will result in errors.
  146. - A valid adapter file descriptor (fd2 >= 0) is only returned on
  147. the initial attach for a context. Subsequent attaches to an
  148. existing context (DK_CXLFLASH_ATTACH_REUSE_CONTEXT flag present)
  149. do not provide the adapter file descriptor as it was previously
  150. made known to the application.
  151. - When a context is no longer needed, the user shall detach from
  152. the context via the DK_CXLFLASH_DETACH ioctl. When this ioctl
  153. returns with a valid adapter file descriptor and the return flag
  154. DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_
  155. close the adapter file descriptor following a successful detach.
  156. - When this ioctl returns with a valid fd2 and the return flag
  157. DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_
  158. close fd2 in the following circumstances:
  159. + Following a successful detach of the last user of the context
  160. + Following a successful recovery on the context's original fd2
  161. + In the child process of a fork(), following a clone ioctl,
  162. on the fd2 associated with the source context
  163. - At any time, a close on fd2 will invalidate the tokens. Applications
  164. should exercise caution to only close fd2 when appropriate (outlined
  165. in the previous bullet) to avoid premature loss of I/O.
  166. DK_CXLFLASH_USER_DIRECT
  167. -----------------------
  168. This ioctl is responsible for transitioning the LUN to direct
  169. (physical) mode access and configuring the AFU for direct access from
  170. user space on a per-context basis. Additionally, the block size and
  171. last logical block address (LBA) are returned to the user.
  172. As mentioned previously, when operating in user space access mode,
  173. LUNs may be accessed in whole or in part. Only one mode is allowed
  174. at a time and if one mode is active (outstanding references exist),
  175. requests to use the LUN in a different mode are denied.
  176. The AFU is configured for direct access from user space by adding an
  177. entry to the AFU's resource handle table. The index of the entry is
  178. treated as a resource handle that is returned to the user. The user
  179. is then able to use the handle to reference the LUN during I/O.
  180. DK_CXLFLASH_USER_VIRTUAL
  181. ------------------------
  182. This ioctl is responsible for transitioning the LUN to virtual mode
  183. of access and configuring the AFU for virtual access from user space
  184. on a per-context basis. Additionally, the block size and last logical
  185. block address (LBA) are returned to the user.
  186. As mentioned previously, when operating in user space access mode,
  187. LUNs may be accessed in whole or in part. Only one mode is allowed
  188. at a time and if one mode is active (outstanding references exist),
  189. requests to use the LUN in a different mode are denied.
  190. The AFU is configured for virtual access from user space by adding
  191. an entry to the AFU's resource handle table. The index of the entry
  192. is treated as a resource handle that is returned to the user. The
  193. user is then able to use the handle to reference the LUN during I/O.
  194. By default, the virtual LUN is created with a size of 0. The user
  195. would need to use the DK_CXLFLASH_VLUN_RESIZE ioctl to adjust the grow
  196. the virtual LUN to a desired size. To avoid having to perform this
  197. resize for the initial creation of the virtual LUN, the user has the
  198. option of specifying a size as part of the DK_CXLFLASH_USER_VIRTUAL
  199. ioctl, such that when success is returned to the user, the
  200. resource handle that is provided is already referencing provisioned
  201. storage. This is reflected by the last LBA being a non-zero value.
  202. When a LUN is accessible from more than one port, this ioctl will
  203. return with the DK_CXLFLASH_ALL_PORTS_ACTIVE return flag set. This
  204. provides the user with a hint that I/O can be retried in the event
  205. of an I/O error as the LUN can be reached over multiple paths.
  206. DK_CXLFLASH_VLUN_RESIZE
  207. -----------------------
  208. This ioctl is responsible for resizing a previously created virtual
  209. LUN and will fail if invoked upon a LUN that is not in virtual
  210. mode. Upon success, an updated last LBA is returned to the user
  211. indicating the new size of the virtual LUN associated with the
  212. resource handle.
  213. The partitioning of virtual LUNs is jointly mediated by the cxlflash
  214. driver and the AFU. An allocation table is kept for each LUN that is
  215. operating in the virtual mode and used to program a LUN translation
  216. table that the AFU references when provided with a resource handle.
  217. This ioctl can return -EAGAIN if an AFU sync operation takes too long.
  218. In addition to returning a failure to user, cxlflash will also schedule
  219. an asynchronous AFU reset. Should the user choose to retry the operation,
  220. it is expected to succeed. If this ioctl fails with -EAGAIN, the user
  221. can either retry the operation or treat it as a failure.
  222. DK_CXLFLASH_RELEASE
  223. -------------------
  224. This ioctl is responsible for releasing a previously obtained
  225. reference to either a physical or virtual LUN. This can be
  226. thought of as the inverse of the DK_CXLFLASH_USER_DIRECT or
  227. DK_CXLFLASH_USER_VIRTUAL ioctls. Upon success, the resource handle
  228. is no longer valid and the entry in the resource handle table is
  229. made available to be used again.
  230. As part of the release process for virtual LUNs, the virtual LUN
  231. is first resized to 0 to clear out and free the translation tables
  232. associated with the virtual LUN reference.
  233. DK_CXLFLASH_DETACH
  234. ------------------
  235. This ioctl is responsible for unregistering a context with the
  236. cxlflash driver and release outstanding resources that were
  237. not explicitly released via the DK_CXLFLASH_RELEASE ioctl. Upon
  238. success, all "tokens" which had been provided to the user from the
  239. DK_CXLFLASH_ATTACH onward are no longer valid.
  240. When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful
  241. attach, the application _must_ close the fd2 associated with the context
  242. following the detach of the final user of the context.
  243. DK_CXLFLASH_VLUN_CLONE
  244. ----------------------
  245. This ioctl is responsible for cloning a previously created
  246. context to a more recently created context. It exists solely to
  247. support maintaining user space access to storage after a process
  248. forks. Upon success, the child process (which invoked the ioctl)
  249. will have access to the same LUNs via the same resource handle(s)
  250. as the parent, but under a different context.
  251. Context sharing across processes is not supported with CXL and
  252. therefore each fork must be met with establishing a new context
  253. for the child process. This ioctl simplifies the state management
  254. and playback required by a user in such a scenario. When a process
  255. forks, child process can clone the parents context by first creating
  256. a context (via DK_CXLFLASH_ATTACH) and then using this ioctl to
  257. perform the clone from the parent to the child.
  258. The clone itself is fairly simple. The resource handle and lun
  259. translation tables are copied from the parent context to the child's
  260. and then synced with the AFU.
  261. When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful
  262. attach, the application _must_ close the fd2 associated with the source
  263. context (still resident/accessible in the parent process) following the
  264. clone. This is to avoid a stale entry in the file descriptor table of the
  265. child process.
  266. This ioctl can return -EAGAIN if an AFU sync operation takes too long.
  267. In addition to returning a failure to user, cxlflash will also schedule
  268. an asynchronous AFU reset. Should the user choose to retry the operation,
  269. it is expected to succeed. If this ioctl fails with -EAGAIN, the user
  270. can either retry the operation or treat it as a failure.
  271. DK_CXLFLASH_VERIFY
  272. ------------------
  273. This ioctl is used to detect various changes such as the capacity of
  274. the disk changing, the number of LUNs visible changing, etc. In cases
  275. where the changes affect the application (such as a LUN resize), the
  276. cxlflash driver will report the changed state to the application.
  277. The user calls in when they want to validate that a LUN hasn't been
  278. changed in response to a check condition. As the user is operating out
  279. of band from the kernel, they will see these types of events without
  280. the kernel's knowledge. When encountered, the user's architected
  281. behavior is to call in to this ioctl, indicating what they want to
  282. verify and passing along any appropriate information. For now, only
  283. verifying a LUN change (ie: size different) with sense data is
  284. supported.
  285. DK_CXLFLASH_RECOVER_AFU
  286. -----------------------
  287. This ioctl is used to drive recovery (if such an action is warranted)
  288. of a specified user context. Any state associated with the user context
  289. is re-established upon successful recovery.
  290. User contexts are put into an error condition when the device needs to
  291. be reset or is terminating. Users are notified of this error condition
  292. by seeing all 0xF's on an MMIO read. Upon encountering this, the
  293. architected behavior for a user is to call into this ioctl to recover
  294. their context. A user may also call into this ioctl at any time to
  295. check if the device is operating normally. If a failure is returned
  296. from this ioctl, the user is expected to gracefully clean up their
  297. context via release/detach ioctls. Until they do, the context they
  298. hold is not relinquished. The user may also optionally exit the process
  299. at which time the context/resources they held will be freed as part of
  300. the release fop.
  301. When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful
  302. attach, the application _must_ unmap and close the fd2 associated with the
  303. original context following this ioctl returning success and indicating that
  304. the context was recovered (DK_CXLFLASH_RECOVER_AFU_CONTEXT_RESET).
  305. DK_CXLFLASH_MANAGE_LUN
  306. ----------------------
  307. This ioctl is used to switch a LUN from a mode where it is available
  308. for file-system access (legacy), to a mode where it is set aside for
  309. exclusive user space access (superpipe). In case a LUN is visible
  310. across multiple ports and adapters, this ioctl is used to uniquely
  311. identify each LUN by its World Wide Node Name (WWNN).
  312. CXL Flash Driver Host IOCTLs
  313. ============================
  314. Each host adapter instance that is supported by the cxlflash driver
  315. has a special character device associated with it to enable a set of
  316. host management function. These character devices are hosted in a
  317. class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
  318. Applications can be written to perform various functions using the
  319. host ioctl APIs below.
  320. The structure definitions for these IOCTLs are available in:
  321. uapi/scsi/cxlflash_ioctl.h
  322. HT_CXLFLASH_LUN_PROVISION
  323. -------------------------
  324. This ioctl is used to create and delete persistent LUNs on cxlflash
  325. devices that lack an external LUN management interface. It is only
  326. valid when used with AFUs that support the LUN provision capability.
  327. When sufficient space is available, LUNs can be created by specifying
  328. the target port to host the LUN and a desired size in 4K blocks. Upon
  329. success, the LUN ID and WWID of the created LUN will be returned and
  330. the SCSI bus can be scanned to detect the change in LUN topology. Note
  331. that partial allocations are not supported. Should a creation fail due
  332. to a space issue, the target port can be queried for its current LUN
  333. geometry.
  334. To remove a LUN, the device must first be disassociated from the Linux
  335. SCSI subsystem. The LUN deletion can then be initiated by specifying a
  336. target port and LUN ID. Upon success, the LUN geometry associated with
  337. the port will be updated to reflect new number of provisioned LUNs and
  338. available capacity.
  339. To query the LUN geometry of a port, the target port is specified and
  340. upon success, the following information is presented:
  341. - Maximum number of provisioned LUNs allowed for the port
  342. - Current number of provisioned LUNs for the port
  343. - Maximum total capacity of provisioned LUNs for the port (4K blocks)
  344. - Current total capacity of provisioned LUNs for the port (4K blocks)
  345. With this information, the number of available LUNs and capacity can be
  346. can be calculated.
  347. HT_CXLFLASH_AFU_DEBUG
  348. ---------------------
  349. This ioctl is used to debug AFUs by supporting a command pass-through
  350. interface. It is only valid when used with AFUs that support the AFU
  351. debug capability.
  352. With exception of buffer management, AFU debug commands are opaque to
  353. cxlflash and treated as pass-through. For debug commands that do require
  354. data transfer, the user supplies an adequately sized data buffer and must
  355. specify the data transfer direction with respect to the host. There is a
  356. maximum transfer size of 256K imposed. Note that partial read completions
  357. are not supported - when errors are experienced with a host read data
  358. transfer, the data buffer is not copied back to the user.