From: Daniel Vetter <daniel@ffwll.ch>
To: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>,
Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
Gerd Hoffmann <kraxel@redhat.com>,
DRI Development <dri-devel@lists.freedesktop.org>,
Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH 3/9] drm/doc: Some polish for shmem helpers
Date: Thu, 14 May 2020 22:05:59 +0200 [thread overview]
Message-ID: <20200514200559.GE206103@phenom.ffwll.local> (raw)
In-Reply-To: <d4088d21-8351-6afb-ae90-cab3e30f83e8@suse.de>
On Mon, May 11, 2020 at 01:12:49PM +0200, Thomas Zimmermann wrote:
>
>
> Am 11.05.20 um 11:35 schrieb Daniel Vetter:
> > - Move the shmem helper section to the drm-mm.rst file, next to the
> > vram helpers. Makes a lot more sense there with the now wider scope.
> > Also, that's where the all the other backing storage stuff resides.
> > It's just the framebuffer helpers that should be in the kms helper
> > section.
> >
> > - Try to clarify which functiosn are for implementing
> > drm_gem_object_funcs, and which for drivers to call directly. At
> > least one driver screwed that up a bit.
> >
> > Cc: Gerd Hoffmann <kraxel@redhat.com>
> > Cc: Rob Herring <robh@kernel.org>
> > Cc: Noralf Trønnes <noralf@tronnes.org>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
>
> Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>
>
> See below for a suggestion on the help text.
>
> > ---
> > Documentation/gpu/drm-kms-helpers.rst | 12 --------
> > Documentation/gpu/drm-mm.rst | 12 ++++++++
> > drivers/gpu/drm/drm_gem_shmem_helper.c | 39 +++++++++++++++++++++-----
> > 3 files changed, 44 insertions(+), 19 deletions(-)
> >
> > diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
> > index ee730457bf4e..b89ddd06dabb 100644
> > --- a/Documentation/gpu/drm-kms-helpers.rst
> > +++ b/Documentation/gpu/drm-kms-helpers.rst
> > @@ -411,15 +411,3 @@ Legacy CRTC/Modeset Helper Functions Reference
> >
> > .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
> > :export:
> > -
> > -SHMEM GEM Helper Reference
> > -==========================
> > -
> > -.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
> > - :doc: overview
> > -
> > -.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
> > - :internal:
> > -
> > -.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
> > - :export:
> > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > index 1839762044be..c01757b0ac25 100644
> > --- a/Documentation/gpu/drm-mm.rst
> > +++ b/Documentation/gpu/drm-mm.rst
> > @@ -373,6 +373,18 @@ GEM CMA Helper Functions Reference
> > .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
> > :export:
> >
> > +GEM SHMEM Helper Function Reference
> > +-----------------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
> > + :doc: overview
> > +
> > +.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
> > + :internal:
> > +
> > +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
> > + :export:
> > +
> > GEM VRAM Helper Functions Reference
> > -----------------------------------
> >
> > diff --git a/drivers/gpu/drm/drm_gem_shmem_helper.c b/drivers/gpu/drm/drm_gem_shmem_helper.c
> > index df31e5782eed..2a70159d50ef 100644
> > --- a/drivers/gpu/drm/drm_gem_shmem_helper.c
> > +++ b/drivers/gpu/drm/drm_gem_shmem_helper.c
> > @@ -103,7 +103,8 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_create);
> > * @obj: GEM object to free
> > *
> > * This function cleans up the GEM object state and frees the memory used to
> > - * store the object itself.
> > + * store the object itself. It should be used to implement
> > + * &drm_gem_object_funcs.free.
>
> It should 'only' be used? Or maybe you can say that it should be used by
> drivers that don't implement struct drm_driver.gem_create_object.
Just looked at this, and I'm not clear what you're aiming for. There
doesn't seem to be any misuse for this for other places than the free
hook. And I can't really come up with ideas where that would even work.
What kind of confusion are you trying to clarify with your suggestion?
Maybe I can then reword that into something that also makes sense for me.
Thanks, Daniel
>
> > */
> > void drm_gem_shmem_free_object(struct drm_gem_object *obj)
> > {
> > @@ -214,7 +215,8 @@ EXPORT_SYMBOL(drm_gem_shmem_put_pages);
> > * @obj: GEM object
> > *
> > * This function makes sure the backing pages are pinned in memory while the
> > - * buffer is exported.
> > + * buffer is exported. It should only be used to implement
> > + * &drm_gem_object_funcs.pin.
> > *
> > * Returns:
> > * 0 on success or a negative error code on failure.
> > @@ -232,7 +234,7 @@ EXPORT_SYMBOL(drm_gem_shmem_pin);
> > * @obj: GEM object
> > *
> > * This function removes the requirement that the backing pages are pinned in
> > - * memory.
> > + * memory. It should only be used to implement &drm_gem_object_funcs.unpin.
> > */
> > void drm_gem_shmem_unpin(struct drm_gem_object *obj)
> > {
> > @@ -285,8 +287,14 @@ static void *drm_gem_shmem_vmap_locked(struct drm_gem_shmem_object *shmem)
> > * drm_gem_shmem_vmap - Create a virtual mapping for a shmem GEM object
> > * @shmem: shmem GEM object
> > *
> > - * This function makes sure that a virtual address exists for the buffer backing
> > - * the shmem GEM object.
> > + * This function makes sure that a contiguous kernel virtual address mapping
> > + * exists for the buffer backing the shmem GEM object.
> > + *
> > + * This function can be used to implement &drm_gem_object_funcs.vmap. But it can
> > + * also be called by drivers directly, in which case it will hide the
> > + * differences between dma-buf imported and natively allocated objects.
> > + *
> > + * Acquired mappings should be cleaned up by calling drm_gem_shmem_vunmap().
> > *
> > * Returns:
> > * 0 on success or a negative error code on failure.
> > @@ -330,7 +338,13 @@ static void drm_gem_shmem_vunmap_locked(struct drm_gem_shmem_object *shmem)
> > * drm_gem_shmem_vunmap - Unmap a virtual mapping fo a shmem GEM object
> > * @shmem: shmem GEM object
> > *
> > - * This function removes the virtual address when use count drops to zero.
> > + * This function cleans up a kernel virtual address mapping acquired by
> > + * drm_gem_shmem_vmap(). The mapping is only removed when the use count drops to
> > + * zero.
> > + *
> > + * This function can be used to implement &drm_gem_object_funcs.vmap. But it can
> > + * also be called by drivers directly, in which case it will hide the
> > + * differences between dma-buf imported and natively allocated objects.
> > */
> > void drm_gem_shmem_vunmap(struct drm_gem_object *obj, void *vaddr)
> > {
> > @@ -559,6 +573,8 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_mmap);
> > * @p: DRM printer
> > * @indent: Tab indentation level
> > * @obj: GEM object
> > + *
> > + * This implements the &drm_gem_object_funcs.info callback.
> > */
> > void drm_gem_shmem_print_info(struct drm_printer *p, unsigned int indent,
> > const struct drm_gem_object *obj)
> > @@ -577,7 +593,12 @@ EXPORT_SYMBOL(drm_gem_shmem_print_info);
> > * @obj: GEM object
> > *
> > * This function exports a scatter/gather table suitable for PRIME usage by
> > - * calling the standard DMA mapping API.
> > + * calling the standard DMA mapping API. Drivers should not call this function
> > + * directly, instead it should only be used as an implementation for
> > + * &drm_gem_object_funcs.get_sg_table.
> > + *
> > + * Drivers who need to acquire an scatter/gather table for objects need to call
> > + * drm_gem_shmem_get_pages_sgt() instead.
> > *
> > * Returns:
> > * A pointer to the scatter/gather table of pinned pages or NULL on failure.
> > @@ -599,6 +620,10 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_get_sg_table);
> > * the sg table doesn't exist, the pages are pinned, dma-mapped, and a sg
> > * table created.
> > *
> > + * This is the main function for drivers to get at backing storage, and it hides
> > + * and difference between dma-buf imported and natively allocated objects.
> > + * drm_gem_shmem_get_sg_table() should not be directly called by drivers.
> > + *
> > * Returns:
> > * A pointer to the scatter/gather table of pinned pages or errno on failure.
> > */
> >
>
> --
> Thomas Zimmermann
> Graphics Driver Developer
> SUSE Software Solutions Germany GmbH
> Maxfeldstr. 5, 90409 Nürnberg, Germany
> (HRB 36809, AG Nürnberg)
> Geschäftsführer: Felix Imendörffer
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2020-05-14 20:06 UTC|newest]
Thread overview: 51+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-11 9:35 [PATCH 0/9] shmem helper untangling Daniel Vetter
2020-05-11 9:35 ` [PATCH 1/9] drm/msm: Don't call dma_buf_vunmap without _vmap Daniel Vetter
2020-05-11 15:24 ` Rob Clark
2020-05-11 15:28 ` Daniel Vetter
2020-05-11 20:36 ` Rob Clark
2020-05-14 20:11 ` [PATCH] " Daniel Vetter
2020-05-28 8:29 ` Daniel Vetter
2020-05-31 16:02 ` Rob Clark
2020-06-03 12:46 ` Daniel Vetter
2020-05-11 9:35 ` [PATCH 2/9] drm/gem: WARN if drm_gem_get_pages is called on a private obj Daniel Vetter
2020-05-14 7:45 ` Thomas Zimmermann
2020-05-11 9:35 ` [PATCH 3/9] drm/doc: Some polish for shmem helpers Daniel Vetter
2020-05-11 11:12 ` Thomas Zimmermann
2020-05-14 20:05 ` Daniel Vetter [this message]
2020-05-15 6:26 ` Thomas Zimmermann
2020-05-11 9:35 ` [PATCH 4/9] drm/virtio: Call the right " Daniel Vetter
2020-05-14 7:46 ` Thomas Zimmermann
2020-05-11 9:35 ` [PATCH 5/9] drm/udl: Don't call get/put_pages on imported dma-buf Daniel Vetter
2020-05-11 11:23 ` Thomas Zimmermann
2020-05-11 11:37 ` Daniel Vetter
2020-05-11 12:04 ` Thomas Zimmermann
2020-05-14 7:25 ` Thomas Zimmermann
2020-05-14 12:47 ` Daniel Vetter
2020-06-03 12:57 ` Daniel Vetter
2020-05-11 9:35 ` [PATCH 6/9] drm/shmem-helpers: Don't call get/put_pages on imported dma-buf in vmap Daniel Vetter
2020-05-14 7:16 ` Thomas Zimmermann
2020-05-14 12:49 ` Daniel Vetter
2020-05-14 20:22 ` [PATCH] " Daniel Vetter
2020-05-11 9:35 ` [PATCH 7/9] drm/shmem-helpers: Redirect mmap for imported dma-buf Daniel Vetter
2020-05-14 7:23 ` Thomas Zimmermann
2020-05-14 12:47 ` Daniel Vetter
2020-05-27 18:32 ` Thomas Zimmermann
2020-05-27 19:34 ` Daniel Vetter
2020-05-28 12:53 ` Thomas Zimmermann
2020-05-11 9:35 ` [PATCH 8/9] drm/shmem-helpers: Ensure get_pages is not called on " Daniel Vetter
2020-05-14 7:30 ` Thomas Zimmermann
2020-06-03 13:12 ` Daniel Vetter
2020-06-08 14:40 ` Thomas Zimmermann
2020-06-08 15:04 ` Daniel Vetter
2020-05-11 9:35 ` [PATCH 9/9] drm/shmem-helpers: Simplify dma-buf importing Daniel Vetter
2020-05-14 7:44 ` Thomas Zimmermann
2020-05-14 12:55 ` Daniel Vetter
2020-05-14 15:26 ` Thomas Zimmermann
2020-05-20 18:02 ` [PATCH] " Daniel Vetter
2020-05-29 13:34 ` Boris Brezillon
2020-05-29 13:35 ` Boris Brezillon
2020-05-29 13:49 ` Boris Brezillon
2020-05-29 14:05 ` Daniel Vetter
2020-05-29 14:36 ` Boris Brezillon
2020-06-15 8:23 ` [PATCH 9/9] " Thomas Zimmermann
2020-05-29 13:52 ` [PATCH 0/9] shmem helper untangling Boris Brezillon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200514200559.GE206103@phenom.ffwll.local \
--to=daniel@ffwll.ch \
--cc=daniel.vetter@ffwll.ch \
--cc=daniel.vetter@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
--cc=kraxel@redhat.com \
--cc=tzimmermann@suse.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).