Commit d2f4831e authored by Paul Cercueil's avatar Paul Cercueil Committed by Greg Kroah-Hartman
Browse files

Documentation: usb: Document FunctionFS DMABUF API 



Add documentation for the three ioctls used to attach or detach
externally-created DMABUFs, and to request transfers from/to previously
attached DMABUFs.

Signed-off-by: default avatarPaul Cercueil <paul@crapouillou.net>
Link: https://lore.kernel.org/r/20240130122340.54813-5-paul@crapouillou.net


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 7b07a2a7

Documentation/usb/functionfs.rst

+36 −0
Original line number Diff line number Diff line
@@ -2,6 +2,9 @@ 
How FunctionFS works

====================



Overview

========



From kernel point of view it is just a composite function with some

unique behaviour.  It may be added to an USB configuration only after

the user space driver has registered by writing descriptors and
@@ -66,3 +69,36 @@ have been written to their ep0's. 


Conversely, the gadget is unregistered after the first USB function

closes its endpoints.



DMABUF interface

================



FunctionFS additionally supports a DMABUF based interface, where the

userspace can attach DMABUF objects (externally created) to an endpoint,

and subsequently use them for data transfers.



A userspace application can then use this interface to share DMABUF

objects between several interfaces, allowing it to transfer data in a

zero-copy fashion, for instance between IIO and the USB stack.



As part of this interface, three new IOCTLs have been added. These three

IOCTLs have to be performed on a data endpoint (ie. not ep0). They are:



  ``FUNCTIONFS_DMABUF_ATTACH(int)``

    Attach the DMABUF object, identified by its file descriptor, to the

    data endpoint. Returns zero on success, and a negative errno value

    on error.



  ``FUNCTIONFS_DMABUF_DETACH(int)``

    Detach the given DMABUF object, identified by its file descriptor,

    from the data endpoint. Returns zero on success, and a negative

    errno value on error. Note that closing the endpoint's file

    descriptor will automatically detach all attached DMABUFs.



  ``FUNCTIONFS_DMABUF_TRANSFER(struct usb_ffs_dmabuf_transfer_req *)``

    Enqueue the previously attached DMABUF to the transfer queue.

    The argument is a structure that packs the DMABUF's file descriptor,

    the size in bytes to transfer (which should generally correspond to

    the size of the DMABUF), and a 'flags' field which is unused

    for now. Returns zero on success, and a negative errno value on

    error.