arch/powerpc/cxlflash.rst

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
27     user space application direct access to Flash storage.
29     The CXL Flash Adapter Driver is a kernel module that sits in the
35     as described in Documentation/arch/powerpc/cxl.rst.
40         - Any flash device (LUN) can be configured to be accessed as a
43         - Any flash device (LUN) can be configured to be accessed from
47           or physical LUN access) or access to a kernel/AFU-mediated
59     directly in each user I/O, but at the minimum is involved in the
60     initial setup before the user application is allowed to send requests
67                      +-------------------------------+
71                      +-------------------------------+
75                      +-------------------------------+
78                      +-------------------------------+
83     areas in the MMIO Space shown above.  The master context driver
88     Once these scsi block devices are instantiated, an application
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
104     and the entire space for the LUN is available to the application.
107     data written to the block device will survive application exit and
109     not survive after the application terminates or the system reboots).
121     specifically for devices (LUNs) operating in user space access
124     a high-level overview of each supported service (IOCTL) is provided
128     http://github.com/open-power/capiflash
137     a file descriptor handle must first be obtained in order to establish
147     The structure definitions for these IOCTLs are available in:
151 ------------------
161     notification and access in the event of a non-user-initiated close(),
162     such as a killed process. This design point is described in further
163     detail in the description for the DK_CXLFLASH_DETACH ioctl.
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
176           usage will result in errors.
178 	- A valid adapter file descriptor (fd2 >= 0) is only returned on
182 	  made known to the application.
184         - When a context is no longer needed, the user shall detach from
187 	  DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_
190 	- When this ioctl returns with a valid fd2 and the return flag
191 	  DK_CXLFLASH_APP_CLOSE_ADAP_FD is present, the application _must_
192 	  close fd2 in the following circumstances:
196 		+ In the child process of a fork(), following a clone ioctl,
199         - At any time, a close on fd2 will invalidate the tokens. Applications
201 	  in the previous bullet) to avoid premature loss of I/O.
204 -----------------------
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
213     requests to use the LUN in a different mode are denied.
221 ------------------------
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
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.
248     provides the user with a hint that I/O can be retried in the event
252 -----------------------
254     LUN and will fail if invoked upon a LUN that is not in virtual
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.
265     In addition to returning a failure to user, cxlflash will also schedule
267     it is expected to succeed. If this ioctl fails with -EAGAIN, the user
271 -------------------
276     is no longer valid and the entry in the resource handle table is
284 ------------------
292     attach, the application _must_ close the fd2 associated with the context
296 ----------------------
307     and playback required by a user in such a scenario. When a process
317     attach, the application _must_ close the fd2 associated with the source
318     context (still resident/accessible in the parent process) following the
319     clone. This is to avoid a stale entry in the file descriptor table of the
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 schedule
325     it is expected to succeed. If this ioctl fails with -EAGAIN, the user
329 ------------------
331     the disk changing, the number of LUNs visible changing, etc. In cases
332     where the changes affect the application (such as a LUN resize), the
333     cxlflash driver will report the changed state to the application.
335     The user calls in when they want to validate that a LUN hasn't been
336     changed in response to a check condition. As the user is operating out
339     behavior is to call in to this ioctl, indicating what they want to
345 -----------------------
348     is re-established upon successful recovery.
363     attach, the application _must_ unmap and close the fd2 associated with the
368 ----------------------
370     for file-system access (legacy), to a mode where it is set aside for
371     exclusive user space access (superpipe). In case a LUN is visible
381     host management function. These character devices are hosted in a
387     The structure definitions for these IOCTLs are available in:
391 -------------------------
397     the target port to host the LUN and a desired size in 4K blocks. Upon
399     the SCSI bus can be scanned to detect the change in LUN topology. Note
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