| Message ID | 20230216130934.156541-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] drm: document DRM_IOCTL_PRIME_HANDLE_TO_FD and PRIME_FD_TO_HANDLE | expand |
On Thu, Feb 16, 2023 at 01:09:41PM +0000, Simon Ser wrote: > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: Pekka Paalanen <ppaalanen@gmail.com> > Cc: Daniel Stone <daniel@fooishbar.org> > --- > include/uapi/drm/drm.h | 17 +++++++++++++++++ > 1 file changed, 17 insertions(+) > > diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h > index 4cb956a52aee..54b2313c8332 100644 > --- a/include/uapi/drm/drm.h > +++ b/include/uapi/drm/drm.h > @@ -1012,7 +1012,24 @@ extern "C" { > #define DRM_IOCTL_UNLOCK DRM_IOW( 0x2b, struct drm_lock) > #define DRM_IOCTL_FINISH DRM_IOW( 0x2c, struct drm_lock) > > +/** > + * DRM_IOCTL_PRIME_HANDLE_TO_FD - Convert a GEM handle to a DMA-BUF FD. > + * > + * User-space sets &drm_prime_handle.handle with the GEM handle to export and > + * &drm_prime_handle.flags, and gets back a DMA-BUF file descriptor in > + * &drm_prime_handle.fd. I think it'd be good to mention here that export could fail for any number of driver specific reason, e.g. because the driver doesn't support dma-buf export at all, or it's not supported for this specific gem handle because it's a special one. And therefore generic clients need to be able to cope with some kind of fallback path ideally. Also I think it'd be good to mention that export support is announced with the DRM_PRIME_CAP_EXPORT flag in the DRM_CAP_PRIME GETCAP ioctl capability. > + */ > #define DRM_IOCTL_PRIME_HANDLE_TO_FD DRM_IOWR(0x2d, struct drm_prime_handle) > +/** > + * DRM_IOCTL_PRIME_FD_TO_HANDLE - Convert a DMA-BUF FD to a GEM handle. > + * > + * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to > + * import, and gets back a GEM handle in &drm_prime_handle.handle. > + * &drm_prime_handle.flags is unused. Same here, some mention that import can fail for any reason (many drivers do not support importing to anything else than the exporting device). Also DRM_PRIME_CAP_IMPORT for querying. > + * > + * If an existing GEM handle refers to the memory object backing the DMA-BUF, > + * that GEM handle is returned. I think we need to state clearly that this means importers who get unknown buffers must have a userspace lookup structure to catch these handle deduplications and refcount objects properly. With these additions: Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch> > + */ > #define DRM_IOCTL_PRIME_FD_TO_HANDLE DRM_IOWR(0x2e, struct drm_prime_handle) > > #define DRM_IOCTL_AGP_ACQUIRE DRM_IO( 0x30) > -- > 2.39.1 > >
Hi Simon On Thu, 16 Feb 2023 at 13:09, Simon Ser <contact@emersion.fr> wrote: > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: Pekka Paalanen <ppaalanen@gmail.com> > Cc: Daniel Stone <daniel@fooishbar.org> > --- > include/uapi/drm/drm.h | 17 +++++++++++++++++ > 1 file changed, 17 insertions(+) > > diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h > index 4cb956a52aee..54b2313c8332 100644 > --- a/include/uapi/drm/drm.h > +++ b/include/uapi/drm/drm.h > @@ -1012,7 +1012,24 @@ extern "C" { > #define DRM_IOCTL_UNLOCK DRM_IOW( 0x2b, struct drm_lock) > #define DRM_IOCTL_FINISH DRM_IOW( 0x2c, struct drm_lock) > > +/** > + * DRM_IOCTL_PRIME_HANDLE_TO_FD - Convert a GEM handle to a DMA-BUF FD. > + * > + * User-space sets &drm_prime_handle.handle with the GEM handle to export and > + * &drm_prime_handle.flags, and gets back a DMA-BUF file descriptor in > + * &drm_prime_handle.fd. > + */ > #define DRM_IOCTL_PRIME_HANDLE_TO_FD DRM_IOWR(0x2d, struct drm_prime_handle) > +/** > + * DRM_IOCTL_PRIME_FD_TO_HANDLE - Convert a DMA-BUF FD to a GEM handle. > + * > + * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to > + * import, and gets back a GEM handle in &drm_prime_handle.handle. > + * &drm_prime_handle.flags is unused. Is it worth explicitly stating that the handle would be released via DRM_IOCTL_GEM_CLOSE? I've had userspace developers query how to release imported handles in the past. Dave > + * > + * If an existing GEM handle refers to the memory object backing the DMA-BUF, > + * that GEM handle is returned. > + */ > #define DRM_IOCTL_PRIME_FD_TO_HANDLE DRM_IOWR(0x2e, struct drm_prime_handle) > > #define DRM_IOCTL_AGP_ACQUIRE DRM_IO( 0x30) > -- > 2.39.1 > >
On Monday, February 20th, 2023 at 16:49, Dave Stevenson <dave.stevenson@raspberrypi.com> wrote: > > + * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to > > + * import, and gets back a GEM handle in &drm_prime_handle.handle. > > + * &drm_prime_handle.flags is unused. > > Is it worth explicitly stating that the handle would be released via > DRM_IOCTL_GEM_CLOSE? I've had userspace developers query how to > release imported handles in the past. v2 spells this out I think.
On Mon, 20 Feb 2023 at 15:57, Simon Ser <contact@emersion.fr> wrote: > > On Monday, February 20th, 2023 at 16:49, Dave Stevenson <dave.stevenson@raspberrypi.com> wrote: > > > > + * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to > > > + * import, and gets back a GEM handle in &drm_prime_handle.handle. > > > + * &drm_prime_handle.flags is unused. > > > > Is it worth explicitly stating that the handle would be released via > > DRM_IOCTL_GEM_CLOSE? I've had userspace developers query how to > > release imported handles in the past. > > v2 spells this out I think. It does - thanks. I was reading back through my emails from Friday and the weekend, and hadn't noticed v2 :-/ Sorry for the noise. Dave
diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h index 4cb956a52aee..54b2313c8332 100644 --- a/include/uapi/drm/drm.h +++ b/include/uapi/drm/drm.h @@ -1012,7 +1012,24 @@ extern "C" { #define DRM_IOCTL_UNLOCK DRM_IOW( 0x2b, struct drm_lock) #define DRM_IOCTL_FINISH DRM_IOW( 0x2c, struct drm_lock) +/** + * DRM_IOCTL_PRIME_HANDLE_TO_FD - Convert a GEM handle to a DMA-BUF FD. + * + * User-space sets &drm_prime_handle.handle with the GEM handle to export and + * &drm_prime_handle.flags, and gets back a DMA-BUF file descriptor in + * &drm_prime_handle.fd. + */ #define DRM_IOCTL_PRIME_HANDLE_TO_FD DRM_IOWR(0x2d, struct drm_prime_handle) +/** + * DRM_IOCTL_PRIME_FD_TO_HANDLE - Convert a DMA-BUF FD to a GEM handle. + * + * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to + * import, and gets back a GEM handle in &drm_prime_handle.handle. + * &drm_prime_handle.flags is unused. + * + * If an existing GEM handle refers to the memory object backing the DMA-BUF, + * that GEM handle is returned. + */ #define DRM_IOCTL_PRIME_FD_TO_HANDLE DRM_IOWR(0x2e, struct drm_prime_handle) #define DRM_IOCTL_AGP_ACQUIRE DRM_IO( 0x30)
Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Pekka Paalanen <ppaalanen@gmail.com> Cc: Daniel Stone <daniel@fooishbar.org> --- include/uapi/drm/drm.h | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)