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 > Cc: Rob Herring > Cc: Noralf Trønnes > Signed-off-by: Daniel Vetter Reviewed-by: Thomas Zimmermann 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. > */ > 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