Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 421242aa authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/cma-helpers: Use recommened kerneldoc for struct member refs 



I just learned that &struct_name.member_name works and looks pretty
even. It doesn't (yet) link to the member directly though, which would
be really good for big structures or vfunc tables (where the
per-member kerneldoc tends to be long).

Also some minor drive-by polish where it makes sense, I read a lot
of docs ...

v2: Review from Laurent:
- Move misplaced doc change to the right patch.
- Remove "DRM driver's", it's redundant.
- Spotted 3 more places where where we could add prose reference with
  a real one.

Cc: Laurent Pinchart <Laurent.pinchart@ideasonboard.com>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Reviewed-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1483044517-5770-14-git-send-email-daniel.vetter@ffwll.ch
parent b112481b

drivers/gpu/drm/drm_fb_cma_helper.c

+13 −13
Original line number Diff line number Diff line
@@ -48,14 +48,14 @@ struct drm_fbdev_cma { 
 * Provides helper functions for creating a cma (contiguous memory allocator)

 * backed framebuffer.

 *

 * drm_fb_cma_create() is used in the &drm_mode_config_funcs ->fb_create

 * drm_fb_cma_create() is used in the &drm_mode_config_funcs.fb_create

 * callback function to create a cma backed framebuffer.

 *

 * An fbdev framebuffer backed by cma is also available by calling

 * drm_fbdev_cma_init(). drm_fbdev_cma_fini() tears it down.

 * If the &drm_framebuffer_funcs ->dirty callback is set, fb_deferred_io

 * will be set up automatically. dirty() is called by

 * drm_fb_helper_deferred_io() in process context (struct delayed_work).

 * If the &drm_framebuffer_funcs.dirty callback is set, fb_deferred_io will be

 * set up automatically. &drm_framebuffer_funcs.dirty is called by

 * drm_fb_helper_deferred_io() in process context (&struct delayed_work).

 *

 * Example fbdev deferred io code::

 *
@@ -155,16 +155,16 @@ static struct drm_fb_cma *drm_fb_cma_alloc(struct drm_device *dev, 


/**

 * drm_fb_cma_create_with_funcs() - helper function for the

 *                                  &drm_mode_config_funcs ->fb_create

 *                                  callback function

 *                                  &drm_mode_config_funcs.fb_create

 *                                  callback

 * @dev: DRM device

 * @file_priv: drm file for the ioctl call

 * @mode_cmd: metadata from the userspace fb creation request

 * @funcs: vtable to be used for the new framebuffer object

 *

 * This can be used to set &drm_framebuffer_funcs for drivers that need the

 * dirty() callback. Use drm_fb_cma_create() if you don't need to change

 * &drm_framebuffer_funcs.

 * &drm_framebuffer_funcs.dirty callback. Use drm_fb_cma_create() if you don't

 * need to change &drm_framebuffer_funcs.

 */

struct drm_framebuffer *drm_fb_cma_create_with_funcs(struct drm_device *dev,

	struct drm_file *file_priv, const struct drm_mode_fb_cmd2 *mode_cmd,
@@ -221,14 +221,14 @@ struct drm_framebuffer *drm_fb_cma_create_with_funcs(struct drm_device *dev, 
EXPORT_SYMBOL_GPL(drm_fb_cma_create_with_funcs);



/**

 * drm_fb_cma_create() - &drm_mode_config_funcs ->fb_create callback function

 * drm_fb_cma_create() - &drm_mode_config_funcs.fb_create callback function

 * @dev: DRM device

 * @file_priv: drm file for the ioctl call

 * @mode_cmd: metadata from the userspace fb creation request

 *

 * If your hardware has special alignment or pitch requirements these should be

 * checked before calling this function. Use drm_fb_cma_create_with_funcs() if

 * you need to set &drm_framebuffer_funcs ->dirty.

 * you need to set &drm_framebuffer_funcs.dirty.

 */

struct drm_framebuffer *drm_fb_cma_create(struct drm_device *dev,

	struct drm_file *file_priv, const struct drm_mode_fb_cmd2 *mode_cmd)
@@ -264,7 +264,7 @@ EXPORT_SYMBOL_GPL(drm_fb_cma_get_gem_obj); 
 * @plane: Which plane

 * @state: Plane state attach fence to

 *

 * This should be put into prepare_fb hook of &struct drm_plane_helper_funcs .

 * This should be set as the &struct drm_plane_helper_funcs.prepare_fb hook.

 *

 * This function checks if the plane FB has an dma-buf attached, extracts

 * the exclusive fence and attaches it to plane state for the atomic helper
@@ -588,7 +588,7 @@ EXPORT_SYMBOL_GPL(drm_fbdev_cma_fini); 
 * drm_fbdev_cma_restore_mode() - Restores initial framebuffer mode

 * @fbdev_cma: The drm_fbdev_cma struct, may be NULL

 *

 * This function is usually called from the DRM drivers lastclose callback.

 * This function is usually called from the &drm_driver.lastclose callback.

 */

void drm_fbdev_cma_restore_mode(struct drm_fbdev_cma *fbdev_cma)

{
@@ -601,7 +601,7 @@ EXPORT_SYMBOL_GPL(drm_fbdev_cma_restore_mode); 
 * drm_fbdev_cma_hotplug_event() - Poll for hotpulug events

 * @fbdev_cma: The drm_fbdev_cma struct, may be NULL

 *

 * This function is usually called from the DRM drivers output_poll_changed

 * This function is usually called from the &drm_mode_config.output_poll_changed

 * callback.

 */

void drm_fbdev_cma_hotplug_event(struct drm_fbdev_cma *fbdev_cma)

drivers/gpu/drm/drm_gem_cma_helper.c

+11 −11
Original line number Diff line number Diff line
@@ -176,8 +176,8 @@ drm_gem_cma_create_with_handle(struct drm_file *file_priv, 
 *

 * This function frees the backing memory of the CMA GEM object, cleans up the

 * GEM object state and frees the memory used to store the object itself.

 * Drivers using the CMA helpers should set this as their DRM driver's

 * ->gem_free_object() callback.

 * Drivers using the CMA helpers should set this as their

 * &drm_driver.gem_free_object callback.

 */

void drm_gem_cma_free_object(struct drm_gem_object *gem_obj)

{
@@ -207,7 +207,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_free_object); 
 * This aligns the pitch and size arguments to the minimum required. This is

 * an internal helper that can be wrapped by a driver to account for hardware

 * with more specific alignment requirements. It should not be used directly

 * as the ->dumb_create() callback in a DRM driver.

 * as their &drm_driver.dumb_create callback.

 *

 * Returns:

 * 0 on success or a negative error code on failure.
@@ -240,7 +240,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_dumb_create_internal); 
 * This function computes the pitch of the dumb buffer and rounds it up to an

 * integer number of bytes per pixel. Drivers for hardware that doesn't have

 * any additional restrictions on the pitch can directly use this function as

 * their ->dumb_create() callback.

 * their &drm_driver.dumb_create callback.

 *

 * For hardware with additional restrictions, drivers can adjust the fields

 * set up by userspace and pass the IOCTL data along to the
@@ -274,7 +274,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_dumb_create); 
 *

 * This function look up an object by its handle and returns the fake mmap

 * offset associated with it. Drivers using the CMA helpers should set this

 * as their DRM driver's ->dumb_map_offset() callback.

 * as their &drm_driver.dumb_map_offset callback.

 *

 * Returns:

 * 0 on success or a negative error code on failure.
@@ -391,7 +391,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_describe); 
 *

 * This function exports a scatter/gather table suitable for PRIME usage by

 * calling the standard DMA mapping API. Drivers using the CMA helpers should

 * set this as their DRM driver's ->gem_prime_get_sg_table() callback.

 * set this as their &drm_driver.gem_prime_get_sg_table callback.

 *

 * Returns:

 * A pointer to the scatter/gather table of pinned pages or NULL on failure.
@@ -429,8 +429,8 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_prime_get_sg_table); 
 * This function imports a scatter/gather table exported via DMA-BUF by

 * another driver. Imported buffers must be physically contiguous in memory

 * (i.e. the scatter/gather table must contain a single entry). Drivers that

 * use the CMA helpers should set this as their DRM driver's

 * ->gem_prime_import_sg_table() callback.

 * use the CMA helpers should set this as their

 * &drm_driver.gem_prime_import_sg_table callback.

 *

 * Returns:

 * A pointer to a newly created GEM object or an ERR_PTR-encoded negative
@@ -467,7 +467,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_prime_import_sg_table); 
 *

 * This function maps a buffer imported via DRM PRIME into a userspace

 * process's address space. Drivers that use the CMA helpers should set this

 * as their DRM driver's ->gem_prime_mmap() callback.

 * as their &drm_driver.gem_prime_mmap callback.

 *

 * Returns:

 * 0 on success or a negative error code on failure.
@@ -496,7 +496,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_prime_mmap); 
 * virtual address space. Since the CMA buffers are already mapped into the

 * kernel virtual address space this simply returns the cached virtual

 * address. Drivers using the CMA helpers should set this as their DRM

 * driver's ->gem_prime_vmap() callback.

 * driver's &drm_driver.gem_prime_vmap callback.

 *

 * Returns:

 * The kernel virtual address of the CMA GEM object's backing store.
@@ -518,7 +518,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_prime_vmap); 
 * This function removes a buffer exported via DRM PRIME from the kernel's

 * virtual address space. This is a no-op because CMA buffers cannot be

 * unmapped from kernel space. Drivers using the CMA helpers should set this

 * as their DRM driver's ->gem_prime_vunmap() callback.

 * as their &drm_driver.gem_prime_vunmap callback.

 */

void drm_gem_cma_prime_vunmap(struct drm_gem_object *obj, void *vaddr)

{