434 lines · plain
1================================2Coherent Accelerator (CXL) Flash3================================4 5Introduction6============7 8 The IBM Power architecture provides support for CAPI (Coherent9 Accelerator Power Interface), which is available to certain PCIe slots10 on Power 8 systems. CAPI can be thought of as a special tunneling11 protocol through PCIe that allow PCIe adapters to look like special12 purpose co-processors which can read or write an application's13 memory and generate page faults. As a result, the host interface to14 an adapter running in CAPI mode does not require the data buffers to15 be mapped to the device's memory (IOMMU bypass) nor does it require16 memory to be pinned.17 18 On Linux, Coherent Accelerator (CXL) kernel services present CAPI19 devices as a PCI device by implementing a virtual PCI host bridge.20 This abstraction simplifies the infrastructure and programming21 model, allowing for drivers to look similar to other native PCI22 device drivers.23 24 CXL provides a mechanism by which user space applications can25 directly talk to a device (network or storage) bypassing the typical26 kernel/device driver stack. The CXL Flash Adapter Driver enables a27 user space application direct access to Flash storage.28 29 The CXL Flash Adapter Driver is a kernel module that sits in the30 SCSI stack as a low level device driver (below the SCSI disk and31 protocol drivers) for the IBM CXL Flash Adapter. This driver is32 responsible for the initialization of the adapter, setting up the33 special path for user space access, and performing error recovery. It34 communicates directly the Flash Accelerator Functional Unit (AFU)35 as described in Documentation/arch/powerpc/cxl.rst.36 37 The cxlflash driver supports two, mutually exclusive, modes of38 operation at the device (LUN) level:39 40 - Any flash device (LUN) can be configured to be accessed as a41 regular disk device (i.e.: /dev/sdc). This is the default mode.42 43 - Any flash device (LUN) can be configured to be accessed from44 user space with a special block library. This mode further45 specifies the means of accessing the device and provides for46 either raw access to the entire LUN (referred to as direct47 or physical LUN access) or access to a kernel/AFU-mediated48 partition of the LUN (referred to as virtual LUN access). The49 segmentation of a disk device into virtual LUNs is assisted50 by special translation services provided by the Flash AFU.51 52Overview53========54 55 The Coherent Accelerator Interface Architecture (CAIA) introduces a56 concept of a master context. A master typically has special privileges57 granted to it by the kernel or hypervisor allowing it to perform AFU58 wide management and control. The master may or may not be involved59 directly in each user I/O, but at the minimum is involved in the60 initial setup before the user application is allowed to send requests61 directly to the AFU.62 63 The CXL Flash Adapter Driver establishes a master context with the64 AFU. It uses memory mapped I/O (MMIO) for this control and setup. The65 Adapter Problem Space Memory Map looks like this::66 67 +-------------------------------+68 | 512 * 64 KB User MMIO |69 | (per context) |70 | User Accessible |71 +-------------------------------+72 | 512 * 128 B per context |73 | Provisioning and Control |74 | Trusted Process accessible |75 +-------------------------------+76 | 64 KB Global |77 | Trusted Process accessible |78 +-------------------------------+79 80 This driver configures itself into the SCSI software stack as an81 adapter driver. The driver is the only entity that is considered a82 Trusted Process to program the Provisioning and Control and Global83 areas in the MMIO Space shown above. The master context driver84 discovers all LUNs attached to the CXL Flash adapter and instantiates85 scsi block devices (/dev/sdb, /dev/sdc etc.) for each unique LUN86 seen from each path.87 88 Once these scsi block devices are instantiated, an application89 written to a specification provided by the block library may get90 access to the Flash from user space (without requiring a system call).91 92 This master context driver also provides a series of ioctls for this93 block library to enable this user space access. The driver supports94 two modes for accessing the block device.95 96 The first mode is called a virtual mode. In this mode a single scsi97 block device (/dev/sdb) may be carved up into any number of distinct98 virtual LUNs. The virtual LUNs may be resized as long as the sum of99 the sizes of all the virtual LUNs, along with the meta-data associated100 with it does not exceed the physical capacity.101 102 The second mode is called the physical mode. In this mode a single103 block device (/dev/sdb) may be opened directly by the block library104 and the entire space for the LUN is available to the application.105 106 Only the physical mode provides persistence of the data. i.e. The107 data written to the block device will survive application exit and108 restart and also reboot. The virtual LUNs do not persist (i.e. do109 not survive after the application terminates or the system reboots).110 111 112Block library API113=================114 115 Applications intending to get access to the CXL Flash from user116 space should use the block library, as it abstracts the details of117 interfacing directly with the cxlflash driver that are necessary for118 performing administrative actions (i.e.: setup, tear down, resize).119 The block library can be thought of as a 'user' of services,120 implemented as IOCTLs, that are provided by the cxlflash driver121 specifically for devices (LUNs) operating in user space access122 mode. While it is not a requirement that applications understand123 the interface between the block library and the cxlflash driver,124 a high-level overview of each supported service (IOCTL) is provided125 below.126 127 The block library can be found on GitHub:128 http://github.com/open-power/capiflash129 130 131CXL Flash Driver LUN IOCTLs132===========================133 134 Users, such as the block library, that wish to interface with a flash135 device (LUN) via user space access need to use the services provided136 by the cxlflash driver. As these services are implemented as ioctls,137 a file descriptor handle must first be obtained in order to establish138 the communication channel between a user and the kernel. This file139 descriptor is obtained by opening the device special file associated140 with the scsi disk device (/dev/sdb) that was created during LUN141 discovery. As per the location of the cxlflash driver within the142 SCSI protocol stack, this open is actually not seen by the cxlflash143 driver. Upon successful open, the user receives a file descriptor144 (herein referred to as fd1) that should be used for issuing the145 subsequent ioctls listed below.146 147 The structure definitions for these IOCTLs are available in:148 uapi/scsi/cxlflash_ioctl.h149 150DK_CXLFLASH_ATTACH151------------------152 153 This ioctl obtains, initializes, and starts a context using the CXL154 kernel services. These services specify a context id (u16) by which155 to uniquely identify the context and its allocated resources. The156 services additionally provide a second file descriptor (herein157 referred to as fd2) that is used by the block library to initiate158 memory mapped I/O (via mmap()) to the CXL flash device and poll for159 completion events. This file descriptor is intentionally installed by160 this driver and not the CXL kernel services to allow for intermediary161 notification and access in the event of a non-user-initiated close(),162 such as a killed process. This design point is described in further163 detail in the description for the DK_CXLFLASH_DETACH ioctl.164 165 There are a few important aspects regarding the "tokens" (context id166 and fd2) that are provided back to the user:167 168 - These tokens are only valid for the process under which they169 were created. The child of a forked process cannot continue170 to use the context id or file descriptor created by its parent171 (see DK_CXLFLASH_VLUN_CLONE for further details).172 173 - These tokens are only valid for the lifetime of the context and174 the process under which they were created. Once either is175 destroyed, the tokens are to be considered stale and subsequent176 usage will result in errors.177 178 - A valid adapter file descriptor (fd2 >= 0) is only returned on179 the initial attach for a context. Subsequent attaches to an180 existing context (DK_CXLFLASH_ATTACH_REUSE_CONTEXT flag present)181 do not provide the adapter file descriptor as it was previously182 made known to the application.183 184 - When a context is no longer needed, the user shall detach from185 the context via the DK_CXLFLASH_DETACH ioctl. When this ioctl186 returns with a valid adapter file descriptor and the return flag187 DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_188 close the adapter file descriptor following a successful detach.189 190 - When this ioctl returns with a valid fd2 and the return flag191 DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_192 close fd2 in the following circumstances:193 194 + Following a successful detach of the last user of the context195 + Following a successful recovery on the context's original fd2196 + In the child process of a fork(), following a clone ioctl,197 on the fd2 associated with the source context198 199 - At any time, a close on fd2 will invalidate the tokens. Applications200 should exercise caution to only close fd2 when appropriate (outlined201 in the previous bullet) to avoid premature loss of I/O.202 203DK_CXLFLASH_USER_DIRECT204-----------------------205 This ioctl is responsible for transitioning the LUN to direct206 (physical) mode access and configuring the AFU for direct access from207 user space on a per-context basis. Additionally, the block size and208 last logical block address (LBA) are returned to the user.209 210 As mentioned previously, when operating in user space access mode,211 LUNs may be accessed in whole or in part. Only one mode is allowed212 at a time and if one mode is active (outstanding references exist),213 requests to use the LUN in a different mode are denied.214 215 The AFU is configured for direct access from user space by adding an216 entry to the AFU's resource handle table. The index of the entry is217 treated as a resource handle that is returned to the user. The user218 is then able to use the handle to reference the LUN during I/O.219 220DK_CXLFLASH_USER_VIRTUAL221------------------------222 This ioctl is responsible for transitioning the LUN to virtual mode223 of access and configuring the AFU for virtual access from user space224 on a per-context basis. Additionally, the block size and last logical225 block address (LBA) are returned to the user.226 227 As mentioned previously, when operating in user space access mode,228 LUNs may be accessed in whole or in part. Only one mode is allowed229 at a time and if one mode is active (outstanding references exist),230 requests to use the LUN in a different mode are denied.231 232 The AFU is configured for virtual access from user space by adding233 an entry to the AFU's resource handle table. The index of the entry234 is treated as a resource handle that is returned to the user. The235 user is then able to use the handle to reference the LUN during I/O.236 237 By default, the virtual LUN is created with a size of 0. The user238 would need to use the DK_CXLFLASH_VLUN_RESIZE ioctl to adjust the grow239 the virtual LUN to a desired size. To avoid having to perform this240 resize for the initial creation of the virtual LUN, the user has the241 option of specifying a size as part of the DK_CXLFLASH_USER_VIRTUAL242 ioctl, such that when success is returned to the user, the243 resource handle that is provided is already referencing provisioned244 storage. This is reflected by the last LBA being a non-zero value.245 246 When a LUN is accessible from more than one port, this ioctl will247 return with the DK_CXLFLASH_ALL_PORTS_ACTIVE return flag set. This248 provides the user with a hint that I/O can be retried in the event249 of an I/O error as the LUN can be reached over multiple paths.250 251DK_CXLFLASH_VLUN_RESIZE252-----------------------253 This ioctl is responsible for resizing a previously created virtual254 LUN and will fail if invoked upon a LUN that is not in virtual255 mode. Upon success, an updated last LBA is returned to the user256 indicating the new size of the virtual LUN associated with the257 resource handle.258 259 The partitioning of virtual LUNs is jointly mediated by the cxlflash260 driver and the AFU. An allocation table is kept for each LUN that is261 operating in the virtual mode and used to program a LUN translation262 table that the AFU references when provided with a resource handle.263 264 This ioctl can return -EAGAIN if an AFU sync operation takes too long.265 In addition to returning a failure to user, cxlflash will also schedule266 an asynchronous AFU reset. Should the user choose to retry the operation,267 it is expected to succeed. If this ioctl fails with -EAGAIN, the user268 can either retry the operation or treat it as a failure.269 270DK_CXLFLASH_RELEASE271-------------------272 This ioctl is responsible for releasing a previously obtained273 reference to either a physical or virtual LUN. This can be274 thought of as the inverse of the DK_CXLFLASH_USER_DIRECT or275 DK_CXLFLASH_USER_VIRTUAL ioctls. Upon success, the resource handle276 is no longer valid and the entry in the resource handle table is277 made available to be used again.278 279 As part of the release process for virtual LUNs, the virtual LUN280 is first resized to 0 to clear out and free the translation tables281 associated with the virtual LUN reference.282 283DK_CXLFLASH_DETACH284------------------285 This ioctl is responsible for unregistering a context with the286 cxlflash driver and release outstanding resources that were287 not explicitly released via the DK_CXLFLASH_RELEASE ioctl. Upon288 success, all "tokens" which had been provided to the user from the289 DK_CXLFLASH_ATTACH onward are no longer valid.290 291 When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful292 attach, the application _must_ close the fd2 associated with the context293 following the detach of the final user of the context.294 295DK_CXLFLASH_VLUN_CLONE296----------------------297 This ioctl is responsible for cloning a previously created298 context to a more recently created context. It exists solely to299 support maintaining user space access to storage after a process300 forks. Upon success, the child process (which invoked the ioctl)301 will have access to the same LUNs via the same resource handle(s)302 as the parent, but under a different context.303 304 Context sharing across processes is not supported with CXL and305 therefore each fork must be met with establishing a new context306 for the child process. This ioctl simplifies the state management307 and playback required by a user in such a scenario. When a process308 forks, child process can clone the parents context by first creating309 a context (via DK_CXLFLASH_ATTACH) and then using this ioctl to310 perform the clone from the parent to the child.311 312 The clone itself is fairly simple. The resource handle and lun313 translation tables are copied from the parent context to the child's314 and then synced with the AFU.315 316 When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful317 attach, the application _must_ close the fd2 associated with the source318 context (still resident/accessible in the parent process) following the319 clone. This is to avoid a stale entry in the file descriptor table of the320 child process.321 322 This ioctl can return -EAGAIN if an AFU sync operation takes too long.323 In addition to returning a failure to user, cxlflash will also schedule324 an asynchronous AFU reset. Should the user choose to retry the operation,325 it is expected to succeed. If this ioctl fails with -EAGAIN, the user326 can either retry the operation or treat it as a failure.327 328DK_CXLFLASH_VERIFY329------------------330 This ioctl is used to detect various changes such as the capacity of331 the disk changing, the number of LUNs visible changing, etc. In cases332 where the changes affect the application (such as a LUN resize), the333 cxlflash driver will report the changed state to the application.334 335 The user calls in when they want to validate that a LUN hasn't been336 changed in response to a check condition. As the user is operating out337 of band from the kernel, they will see these types of events without338 the kernel's knowledge. When encountered, the user's architected339 behavior is to call in to this ioctl, indicating what they want to340 verify and passing along any appropriate information. For now, only341 verifying a LUN change (ie: size different) with sense data is342 supported.343 344DK_CXLFLASH_RECOVER_AFU345-----------------------346 This ioctl is used to drive recovery (if such an action is warranted)347 of a specified user context. Any state associated with the user context348 is re-established upon successful recovery.349 350 User contexts are put into an error condition when the device needs to351 be reset or is terminating. Users are notified of this error condition352 by seeing all 0xF's on an MMIO read. Upon encountering this, the353 architected behavior for a user is to call into this ioctl to recover354 their context. A user may also call into this ioctl at any time to355 check if the device is operating normally. If a failure is returned356 from this ioctl, the user is expected to gracefully clean up their357 context via release/detach ioctls. Until they do, the context they358 hold is not relinquished. The user may also optionally exit the process359 at which time the context/resources they held will be freed as part of360 the release fop.361 362 When the DK_CXLFLASH_APP_CLOSE_ADAP_FD flag was returned on a successful363 attach, the application _must_ unmap and close the fd2 associated with the364 original context following this ioctl returning success and indicating that365 the context was recovered (DK_CXLFLASH_RECOVER_AFU_CONTEXT_RESET).366 367DK_CXLFLASH_MANAGE_LUN368----------------------369 This ioctl is used to switch a LUN from a mode where it is available370 for file-system access (legacy), to a mode where it is set aside for371 exclusive user space access (superpipe). In case a LUN is visible372 across multiple ports and adapters, this ioctl is used to uniquely373 identify each LUN by its World Wide Node Name (WWNN).374 375 376CXL Flash Driver Host IOCTLs377============================378 379 Each host adapter instance that is supported by the cxlflash driver380 has a special character device associated with it to enable a set of381 host management function. These character devices are hosted in a382 class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.383 384 Applications can be written to perform various functions using the385 host ioctl APIs below.386 387 The structure definitions for these IOCTLs are available in:388 uapi/scsi/cxlflash_ioctl.h389 390HT_CXLFLASH_LUN_PROVISION391-------------------------392 This ioctl is used to create and delete persistent LUNs on cxlflash393 devices that lack an external LUN management interface. It is only394 valid when used with AFUs that support the LUN provision capability.395 396 When sufficient space is available, LUNs can be created by specifying397 the target port to host the LUN and a desired size in 4K blocks. Upon398 success, the LUN ID and WWID of the created LUN will be returned and399 the SCSI bus can be scanned to detect the change in LUN topology. Note400 that partial allocations are not supported. Should a creation fail due401 to a space issue, the target port can be queried for its current LUN402 geometry.403 404 To remove a LUN, the device must first be disassociated from the Linux405 SCSI subsystem. The LUN deletion can then be initiated by specifying a406 target port and LUN ID. Upon success, the LUN geometry associated with407 the port will be updated to reflect new number of provisioned LUNs and408 available capacity.409 410 To query the LUN geometry of a port, the target port is specified and411 upon success, the following information is presented:412 413 - Maximum number of provisioned LUNs allowed for the port414 - Current number of provisioned LUNs for the port415 - Maximum total capacity of provisioned LUNs for the port (4K blocks)416 - Current total capacity of provisioned LUNs for the port (4K blocks)417 418 With this information, the number of available LUNs and capacity can be419 can be calculated.420 421HT_CXLFLASH_AFU_DEBUG422---------------------423 This ioctl is used to debug AFUs by supporting a command pass-through424 interface. It is only valid when used with AFUs that support the AFU425 debug capability.426 427 With exception of buffer management, AFU debug commands are opaque to428 cxlflash and treated as pass-through. For debug commands that do require429 data transfer, the user supplies an adequately sized data buffer and must430 specify the data transfer direction with respect to the host. There is a431 maximum transfer size of 256K imposed. Note that partial read completions432 are not supported - when errors are experienced with a host read data433 transfer, the data buffer is not copied back to the user.434