arch/powerpc/cxlflash.rst

2 Coherent Accelerator (CXL) Flash
12     purpose co-processors which can read or write an application's
14     an adapter running in CAPI mode does not require the data buffers to
26     kernel/device driver stack. The CXL Flash Adapter Driver enables a
27     user space application direct access to Flash storage.
29     The CXL Flash Adapter Driver is a kernel module that sits in the
31     protocol drivers) for the IBM CXL Flash Adapter. This driver is
34     communicates directly the Flash Accelerator Functional Unit (AFU)
40         - Any flash device (LUN) can be configured to be accessed as a
41           regular disk device (i.e.: /dev/sdc). This is the default mode.
43         - Any flash device (LUN) can be configured to be accessed from
44           user space with a special block library. This mode further
47           or physical LUN access) or access to a kernel/AFU-mediated
50           by special translation services provided by the Flash AFU.
63     The CXL Flash Adapter Driver establishes a master context with the
67                      +-------------------------------+
71                      +-------------------------------+
75                      +-------------------------------+
78                      +-------------------------------+
84     discovers all LUNs attached to the CXL Flash adapter and instantiates
90     access to the Flash from user space (without requiring a system call).
96     The first mode is called a virtual mode. In this mode a single scsi
99     the sizes of all the virtual LUNs, along with the meta-data associated
102     The second mode is called the physical mode. In this mode a single
106     Only the physical mode provides persistence of the data.  i.e. The
115     Applications intending to get access to the CXL Flash from user
122     mode. While it is not a requirement that applications understand
124     a high-level overview of each supported service (IOCTL) is provided
128     http://github.com/open-power/capiflash
131 CXL Flash Driver LUN IOCTLs
134     Users, such as the block library, that wish to interface with a flash
151 ------------------
158     memory mapped I/O (via mmap()) to the CXL flash device and poll for
161     notification and access in the event of a non-user-initiated close(),
168         - These tokens are only valid for the process under which they
173         - These tokens are only valid for the lifetime of the context and
178 	- A valid adapter file descriptor (fd2 >= 0) is only returned on
184         - When a context is no longer needed, the user shall detach from
190 	- When this ioctl returns with a valid fd2 and the return flag
199         - At any time, a close on fd2 will invalidate the tokens. Applications
204 -----------------------
206     (physical) mode access and configuring the AFU for direct access from
207     user space on a per-context basis. Additionally, the block size and
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 allowed
212     at a time and if one mode is active (outstanding references exist),
213     requests to use the LUN in a different mode are denied.
221 ------------------------
222     This ioctl is responsible for transitioning the LUN to virtual mode
224     on a per-context basis. Additionally, the block size and last logical
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 allowed
229     at a time and if one mode is active (outstanding references exist),
230     requests to use the LUN in a different mode are denied.
244     storage. This is reflected by the last LBA being a non-zero value.
252 -----------------------
255     mode. Upon success, an updated last LBA is returned to the user
261     operating in the virtual mode and used to program a LUN translation
264     This ioctl can return -EAGAIN if an AFU sync operation takes too long.
267     it is expected to succeed. If this ioctl fails with -EAGAIN, the user
271 -------------------
284 ------------------
296 ----------------------
322     This ioctl can return -EAGAIN if an AFU sync operation takes too long.
325     it is expected to succeed. If this ioctl fails with -EAGAIN, the user
329 ------------------
345 -----------------------
348     is re-established upon successful recovery.
368 ----------------------
369     This ioctl is used to switch a LUN from a mode where it is available
370     for file-system access (legacy), to a mode where it is set aside for
376 CXL Flash Driver Host IOCTLs
391 -------------------------
413         - Maximum number of provisioned LUNs allowed for the port
414         - Current number of provisioned LUNs for the port
415         - Maximum total capacity of provisioned LUNs for the port (4K blocks)
416         - Current total capacity of provisioned LUNs for the port (4K blocks)
422 ---------------------
423     This ioctl is used to debug AFUs by supporting a command pass-through
428     cxlflash and treated as pass-through. For debug commands that do require
432     are not supported - when errors are experienced with a host read data