| Message ID | 20220526163033.341425-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | dma-buf: document how to find size, mention kernel versions | expand |
On Thu, 26 May 2022 at 18:30, Simon Ser <contact@emersion.fr> wrote: > > Document how to obtain the size of a DMA-BUF. This is what > Wayland compositors are doing. > > Mention the kernel version numbers from which DMA-BUF features are > available. > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel.vetter@ffwll.ch> > Cc: Jason Ekstrand <jason@jlekstrand.net> > --- > include/uapi/linux/dma-buf.h | 10 +++++++--- > 1 file changed, 7 insertions(+), 3 deletions(-) > > diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf.h > index 8e4a2ca0bcbf..c95f6d3457d2 100644 > --- a/include/uapi/linux/dma-buf.h > +++ b/include/uapi/linux/dma-buf.h > @@ -47,9 +47,13 @@ > * > * If the driver or API with which the client is interacting uses implicit > * synchronization, waiting for prior work to complete can be done via > - * poll() on the DMA buffer file descriptor. If the driver or API requires > - * explicit synchronization, the client may have to wait on a sync_file or > - * other synchronization primitive outside the scope of the DMA buffer API. > + * poll() on the DMA buffer file descriptor from kernel version 3.17. If the > + * driver or API requires explicit synchronization, the client may have to wait > + * on a sync_file or other synchronization primitive outside the scope of the > + * DMA buffer API. This looks good, but you missed the DOC: implicit fence polling in dma-buf.c. Probably good to update that too. > + * > + * From kernel version 3.12, user-space can use llseek(2) with the ``SEEK_END`` > + * whence to obtain the size of a DMA-BUF. This feels misplaced, especially since this ends up under the "DMA Buffer ioctls" heading. Maybe simplest to just put a "DMA Buffer misc uAPI" section directly into dma-buf.rst and put that section there? Also probably good to add that the size is invariant. Or if you don't want a new heading, put it somewhere sensible in the mmap section? Also just noticed that the DOC: cpu access section could perhaps link to the relevant ioctl docs here to connect things better. -Daniel > */ > struct dma_buf_sync { > /** > -- > 2.36.1 > >
diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf.h index 8e4a2ca0bcbf..c95f6d3457d2 100644 --- a/include/uapi/linux/dma-buf.h +++ b/include/uapi/linux/dma-buf.h @@ -47,9 +47,13 @@ * * If the driver or API with which the client is interacting uses implicit * synchronization, waiting for prior work to complete can be done via - * poll() on the DMA buffer file descriptor. If the driver or API requires - * explicit synchronization, the client may have to wait on a sync_file or - * other synchronization primitive outside the scope of the DMA buffer API. + * poll() on the DMA buffer file descriptor from kernel version 3.17. If the + * driver or API requires explicit synchronization, the client may have to wait + * on a sync_file or other synchronization primitive outside the scope of the + * DMA buffer API. + * + * From kernel version 3.12, user-space can use llseek(2) with the ``SEEK_END`` + * whence to obtain the size of a DMA-BUF. */ struct dma_buf_sync { /**
Document how to obtain the size of a DMA-BUF. This is what Wayland compositors are doing. Mention the kernel version numbers from which DMA-BUF features are available. Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Jason Ekstrand <jason@jlekstrand.net> --- include/uapi/linux/dma-buf.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)