Added some boilerplate for the structs, documented members where they are relevant and plenty of markup for hyperlinks all over. And a few small wording polish.

Note that the intro needs some more love after the DRM_MM_INSERT_* patch from Chris has landed.

v2: Spelling fixes (Chris).

v3: Use &struct foo instead of &foo structure (Chris).

Cc: Chris Wilson chris@chris-wilson.co.uk Cc: Joonas Lahtinen joonas.lahtinen@linux.intel.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- Documentation/gpu/drm-mm.rst | 2 +- drivers/gpu/drm/drm_mm.c | 41 +++++++++++---------- include/drm/drm_mm.h | 84 ++++++++++++++++++++++++++++++++++---------- 3 files changed, 89 insertions(+), 38 deletions(-)

diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index cb5daffcd6be..5355e5ad51a7 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -442,7 +442,7 @@ LRU Scan/Eviction Support -------------------------

.. kernel-doc:: drivers/gpu/drm/drm_mm.c - :doc: lru scan roaster + :doc: lru scan roster

DRM MM Range Allocator Function References ------------------------------------------ diff --git a/drivers/gpu/drm/drm_mm.c b/drivers/gpu/drm/drm_mm.c index e54aa3fa538f..229b3f525dee 100644 --- a/drivers/gpu/drm/drm_mm.c +++ b/drivers/gpu/drm/drm_mm.c @@ -59,8 +59,8 @@ * * The main data struct is &drm_mm, allocations are tracked in &drm_mm_node. * Drivers are free to embed either of them into their own suitable - * datastructures. drm_mm itself will not do any allocations of its own, so if - * drivers choose not to embed nodes they need to still allocate them + * datastructures. drm_mm itself will not do any memory allocations of its own, + * so if drivers choose not to embed nodes they need to still allocate them * themselves. * * The range allocator also supports reservation of preallocated blocks. This is @@ -78,7 +78,7 @@ * steep cliff not a real concern. Removing a node again is O(1). * * drm_mm supports a few features: Alignment and range restrictions can be - * supplied. Further more every &drm_mm_node has a color value (which is just an + * supplied. Furthermore every &drm_mm_node has a color value (which is just an * opaque unsigned long) which in conjunction with a driver callback can be used * to implement sophisticated placement restrictions. The i915 DRM driver uses * this to implement guard pages between incompatible caching domains in the @@ -296,11 +296,11 @@ static void drm_mm_insert_helper(struct drm_mm_node *hole_node, * @mm: drm_mm allocator to insert @node into * @node: drm_mm_node to insert * - * This functions inserts an already set-up drm_mm_node into the allocator, - * meaning that start, size and color must be set by the caller. This is useful - * to initialize the allocator with preallocated objects which must be set-up - * before the range allocator can be set-up, e.g. when taking over a firmware - * framebuffer. + * This functions inserts an already set-up &drm_mm_node into the allocator, + * meaning that start, size and color must be set by the caller. All other + * fields must be cleared to 0. This is useful to initialize the allocator with + * preallocated objects which must be set-up before the range allocator can be + * set-up, e.g. when taking over a firmware framebuffer. * * Returns: * 0 on success, -ENOSPC if there's no hole where @node is. @@ -375,7 +375,7 @@ EXPORT_SYMBOL(drm_mm_reserve_node); * @sflags: flags to fine-tune the allocation search * @aflags: flags to fine-tune the allocation behavior * - * The preallocated node must be cleared to 0. + * The preallocated @node must be cleared to 0. * * Returns: * 0 on success, -ENOSPC if there's no suitable hole. @@ -537,7 +537,7 @@ void drm_mm_replace_node(struct drm_mm_node *old, struct drm_mm_node *new) EXPORT_SYMBOL(drm_mm_replace_node);

/** - * DOC: lru scan roaster + * DOC: lru scan roster * * Very often GPUs need to have continuous allocations for a given object. When * evicting objects to make space for a new one it is therefore not most @@ -549,9 +549,11 @@ EXPORT_SYMBOL(drm_mm_replace_node); * The DRM range allocator supports this use-case through the scanning * interfaces. First a scan operation needs to be initialized with * drm_mm_scan_init() or drm_mm_scan_init_with_range(). The driver adds - * objects to the roster (probably by walking an LRU list, but this can be - * freely implemented) (using drm_mm_scan_add_block()) until a suitable hole - * is found or there are no further evictable objects. + * objects to the roster, probably by walking an LRU list, but this can be + * freely implemented. Eviction candiates are added using + * drm_mm_scan_add_block() until a suitable hole is found or there are no + * further evictable objects. Eviction roster metadata is tracked in struct + * &drm_mm_scan. * * The driver must walk through all objects again in exactly the reverse * order to restore the allocator state. Note that while the allocator is used @@ -559,7 +561,7 @@ EXPORT_SYMBOL(drm_mm_replace_node); * * Finally the driver evicts all objects selected (drm_mm_scan_remove_block() * reported true) in the scan, and any overlapping nodes after color adjustment - * (drm_mm_scan_evict_color()). Adding and removing an object is O(1), and + * (drm_mm_scan_color_evict()). Adding and removing an object is O(1), and * since freeing a node is also O(1) the overall complexity is * O(scanned_objects). So like the free stack which needs to be walked before a * scan operation even begins this is linear in the number of objects. It @@ -705,14 +707,15 @@ EXPORT_SYMBOL(drm_mm_scan_add_block); * @scan: the active drm_mm scanner * @node: drm_mm_node to remove * - * Nodes _must_ be removed in exactly the reverse order from the scan list as - * they have been added (e.g. using list_add as they are added and then - * list_for_each over that eviction list to remove), otherwise the internal + * Nodes **must** be removed in exactly the reverse order from the scan list as + * they have been added (e.g. using list_add() as they are added and then + * list_for_each() over that eviction list to remove), otherwise the internal * state of the memory manager will be corrupted. * * When the scan list is empty, the selected memory nodes can be freed. An - * immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then - * return the just freed block (because its at the top of the free_stack list). + * immediately following drm_mm_insert_node_in_range_generic() or one of the + * simpler versions of that function with !DRM_MM_SEARCH_BEST will then return + * the just freed block (because its at the top of the free_stack list). * * Returns: * True if this block should be evicted, false otherwise. Will always diff --git a/include/drm/drm_mm.h b/include/drm/drm_mm.h index 1383ac2328b8..3bddca8fd2b5 100644 --- a/include/drm/drm_mm.h +++ b/include/drm/drm_mm.h @@ -67,16 +67,29 @@ enum drm_mm_allocator_flags { #define DRM_MM_BOTTOMUP DRM_MM_SEARCH_DEFAULT, DRM_MM_CREATE_DEFAULT #define DRM_MM_TOPDOWN DRM_MM_SEARCH_BELOW, DRM_MM_CREATE_TOP

+/** + * struct drm_mm_node - allocated block in the DRM allocator + * + * This represents an allocated block in a &drm_mm allocator. Except for + * pre-reserved nodes inserted using drm_mm_reserve_node() the structure is + * entirely opaque and should only be accessed through the provided funcions. + * Since allocation of these nodes is entirely handled by the driver they can be + * embedded. + */ struct drm_mm_node { + /** @color: Opaque driver-private tag. */ + unsigned long color; + /** @start: Start address of the allocated block. */ + u64 start; + /** @size: Size of the allocated block. */ + u64 size; + /* private: */ struct list_head node_list; struct list_head hole_stack; struct rb_node rb; unsigned hole_follows : 1; unsigned allocated : 1; bool scanned_block : 1; - unsigned long color; - u64 start; - u64 size; u64 __subtree_last; struct drm_mm *mm; #ifdef CONFIG_DRM_DEBUG_MM @@ -84,7 +97,29 @@ struct drm_mm_node { #endif };

+/** + * struct drm_mm - DRM allocator + * + * DRM range allocator with a few special functions and features geared towards + * managing GPU memory. Except for the @color_adjust callback the structure is + * entirely opaque and should only be accessed through the provided functions + * and macros. This structure can be embedded into larger driver structures. + */ struct drm_mm { + /** + * @color_adjust: + * + * Optional driver callback to further apply restrictions on a hole. The + * node argument points at the node containing the hole from which the + * block would be allocated (see drm_mm_hole_follows() and friends). The + * other arguments are the size of the block to be allocated. The driver + * can adjust the start and end as needed to e.g. insert guard pages. + */ + void (*color_adjust)(const struct drm_mm_node *node, + unsigned long color, + u64 *start, u64 *end); + + /* private: */ /* List of all memory nodes that immediately precede a free hole. */ struct list_head hole_stack; /* head_node.node_list is the list of all memory nodes, ordered @@ -93,14 +128,20 @@ struct drm_mm { /* Keep an interval_tree for fast lookup of drm_mm_nodes by address. */ struct rb_root interval_tree;

- void (*color_adjust)(const struct drm_mm_node *node, - unsigned long color, - u64 *start, u64 *end); - unsigned long scan_active; };

+/** + * struct drm_mm_scan - DRM allocator eviction roaster data + * + * This structure tracks data needed for the eviction roaster set up using + * drm_mm_scan_init(), and used with drm_mm_scan_add_block() and + * drm_mm_scan_remove_block(). The structure is entirely opaque and should only + * be accessed through the provided functions and macros. It is meant to be + * allocated temporarily by the driver on the stack. + */ struct drm_mm_scan { + /* private: */ struct drm_mm *mm;

u64 size; @@ -159,7 +200,8 @@ static inline bool drm_mm_initialized(const struct drm_mm *mm) * * Holes are embedded into the drm_mm using the tail of a drm_mm_node. * If you wish to know whether a hole follows this particular node, - * query this function. + * query this function. See also drm_mm_hole_node_start() and + * drm_mm_hole_node_end(). * * Returns: * True if a hole follows the @node. @@ -228,23 +270,23 @@ static inline u64 drm_mm_hole_node_end(const struct drm_mm_node *hole_node)

/** * drm_mm_for_each_node - iterator to walk over all allocated nodes - * @entry: drm_mm_node structure to assign to in each iteration step - * @mm: drm_mm allocator to walk + * @entry: &struct drm_mm_node to assign to in each iteration step + * @mm: &drm_mm allocator to walk * * This iterator walks over all nodes in the range allocator. It is implemented - * with list_for_each, so not save against removal of elements. + * with list_for_each(), so not save against removal of elements. */ #define drm_mm_for_each_node(entry, mm) \ list_for_each_entry(entry, drm_mm_nodes(mm), node_list)

/** * drm_mm_for_each_node_safe - iterator to walk over all allocated nodes - * @entry: drm_mm_node structure to assign to in each iteration step - * @next: drm_mm_node structure to store the next step - * @mm: drm_mm allocator to walk + * @entry: &struct drm_mm_node to assign to in each iteration step + * @next: &struct drm_mm_node to store the next step + * @mm: &drm_mm allocator to walk * * This iterator walks over all nodes in the range allocator. It is implemented - * with list_for_each_safe, so save against removal of elements. + * with list_for_each_safe(), so save against removal of elements. */ #define drm_mm_for_each_node_safe(entry, next, mm) \ list_for_each_entry_safe(entry, next, drm_mm_nodes(mm), node_list) @@ -259,13 +301,13 @@ static inline u64 drm_mm_hole_node_end(const struct drm_mm_node *hole_node)

/** * drm_mm_for_each_hole - iterator to walk over all holes - * @entry: drm_mm_node used internally to track progress - * @mm: drm_mm allocator to walk + * @entry: &drm_mm_node used internally to track progress + * @mm: &drm_mm allocator to walk * @hole_start: ulong variable to assign the hole start to on each iteration * @hole_end: ulong variable to assign the hole end to on each iteration * * This iterator walks over all holes in the range allocator. It is implemented - * with list_for_each, so not save against removal of elements. @entry is used + * with list_for_each(), so not save against removal of elements. @entry is used * internally and will not reflect a real drm_mm_node for the very first hole. * Hence users of this iterator may not access it. * @@ -334,6 +376,9 @@ static inline int drm_mm_insert_node_in_range(struct drm_mm *mm, * @sflags: flags to fine-tune the allocation search * @aflags: flags to fine-tune the allocation behavior * + * This is a simplified version of drm_mm_insert_node_in_range_generic() with no + * range restrictions applied. + * * The preallocated node must be cleared to 0. * * Returns: @@ -434,6 +479,9 @@ void drm_mm_scan_init_with_range(struct drm_mm_scan *scan, * @color: opaque tag value to use for the allocation * @flags: flags to specify how the allocation will be performed afterwards * + * This is a simplified version of drm_mm_scan_init_with_range() with no range + * restrictions applied. + * * This simply sets up the scanning routines with the parameters for the desired * hole. *

sed -e 's/( * .*)struct &([_a-z]*)/\1&struct \2/' -i

Originally I wasnt a friend of this style because I thought a line-break between the "&struct" and "foo" part would break it. But a quick test shows that " * &struct \n * foo\n" works pefectly well with current kernel-doc. So time to mass-apply these changes!

Cc: Sumit Semwal sumit.semwal@linaro.org Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Chris Wilson chris@chris-wilson.co.uk Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/dma-buf/dma-buf.c | 6 +++--- include/linux/dma-buf.h | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c index 91aff74ed092..ab814aff0a5b 100644 --- a/drivers/dma-buf/dma-buf.c +++ b/drivers/dma-buf/dma-buf.c @@ -128,7 +128,7 @@ static loff_t dma_buf_llseek(struct file *file, loff_t offset, int whence) * DOC: fence polling * * To support cross-device and cross-driver synchronization of buffer access - * implicit fences (represented internally in the kernel with struct &fence) can + * implicit fences (represented internally in the kernel with &struct fence) can * be attached to a &dma_buf. The glue for that and a few related things are * provided in the &reservation_object structure. * @@ -373,7 +373,7 @@ static inline int is_dma_buf_file(struct file *file) * Additionally, provide a name string for exporter; useful in debugging. * * @exp_info: [in] holds all the export related information provided - * by the exporter. see struct &dma_buf_export_info + * by the exporter. see &struct dma_buf_export_info * for further details. * * Returns, on success, a newly created dma_buf object, which wraps the @@ -517,7 +517,7 @@ EXPORT_SYMBOL_GPL(dma_buf_get); * * If, as a result of this call, the refcount becomes 0, the 'release' file * operation related to this fd is called. It calls the release operation of - * struct &dma_buf_ops in turn, and frees the memory allocated for dmabuf when + * &struct dma_buf_ops in turn, and frees the memory allocated for dmabuf when * exported. */ void dma_buf_put(struct dma_buf *dmabuf) diff --git a/include/linux/dma-buf.h b/include/linux/dma-buf.h index 57828154e440..4d61fc55278b 100644 --- a/include/linux/dma-buf.h +++ b/include/linux/dma-buf.h @@ -278,7 +278,7 @@ struct dma_buf_ops { * Shared dma buffers are reference counted using dma_buf_put() and * get_dma_buf(). * - * Device DMA access is handled by the separate struct &dma_buf_attachment. + * Device DMA access is handled by the separate &struct dma_buf_attachment. */ struct dma_buf { size_t size; @@ -355,7 +355,7 @@ struct dma_buf_export_info { * DEFINE_DMA_BUF_EXPORT_INFO - helper macro for exporters * @name: export-info name * - * DEFINE_DMA_BUF_EXPORT_INFO macro defines the struct &dma_buf_export_info, + * DEFINE_DMA_BUF_EXPORT_INFO macro defines the &struct dma_buf_export_info, * zeroes it out and pre-populates exp_name in it. */ #define DEFINE_DMA_BUF_EXPORT_INFO(name) \

sed -e 's/( * .*)struct &([_a-z]*)/\1&struct \2/' -i

Originally I wasnt a friend of this style because I thought a line-break between the "&struct" and "foo" part would break it. But a quick test shows that " * &struct \n * foo\n" works pefectly well with current kernel-doc. So time to mass-apply these changes!

Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Chris Wilson chris@chris-wilson.co.uk Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_atomic.c | 6 +++--- drivers/gpu/drm/drm_atomic_helper.c | 8 ++++---- drivers/gpu/drm/drm_auth.c | 8 ++++---- drivers/gpu/drm/drm_bridge.c | 4 ++-- drivers/gpu/drm/drm_color_mgmt.c | 4 ++-- drivers/gpu/drm/drm_connector.c | 2 +- drivers/gpu/drm/drm_crtc_helper.c | 14 +++++++------- drivers/gpu/drm/drm_drv.c | 10 +++++----- drivers/gpu/drm/drm_dumb_buffers.c | 2 +- drivers/gpu/drm/drm_encoder.c | 4 ++-- drivers/gpu/drm/drm_fb_cma_helper.c | 2 +- drivers/gpu/drm/drm_framebuffer.c | 6 +++--- drivers/gpu/drm/drm_irq.c | 2 +- drivers/gpu/drm/drm_plane.c | 2 +- drivers/gpu/drm/drm_plane_helper.c | 2 +- drivers/gpu/drm/drm_probe_helper.c | 2 +- drivers/gpu/drm/drm_property.c | 2 +- drivers/gpu/drm/drm_simple_kms_helper.c | 2 +- include/drm/drm_atomic.h | 2 +- include/drm/drm_auth.h | 2 +- include/drm/drm_bridge.h | 8 ++++---- include/drm/drm_connector.h | 10 +++++----- include/drm/drm_crtc.h | 8 ++++---- include/drm/drm_fb_helper.h | 2 +- include/drm/drm_framebuffer.h | 6 +++--- include/drm/drm_irq.h | 4 ++-- include/drm/drm_mode_config.h | 10 +++++----- include/drm/drm_modeset_helper_vtables.h | 2 +- include/drm/drm_plane.h | 4 ++-- include/drm/drm_print.h | 4 ++-- include/drm/drm_simple_kms_helper.h | 8 ++++---- 31 files changed, 76 insertions(+), 76 deletions(-)

diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c index b1b54011a92c..681d5f97639d 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -1882,7 +1882,7 @@ EXPORT_SYMBOL(drm_atomic_clean_old_fb); * As a contrast, with implicit fencing the kernel keeps track of any * ongoing rendering, and automatically ensures that the atomic update waits * for any pending rendering to complete. For shared buffers represented with - * a struct &dma_buf this is tracked in &reservation_object structures. + * a &struct dma_buf this is tracked in &reservation_object structures. * Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org), * whereas explicit fencing is what Android wants. * @@ -1898,7 +1898,7 @@ EXPORT_SYMBOL(drm_atomic_clean_old_fb); * it will only check if the Sync File is a valid one. * * On the driver side the fence is stored on the @fence parameter of - * struct &drm_plane_state. Drivers which also support implicit fencing + * &struct drm_plane_state. Drivers which also support implicit fencing * should set the implicit fence using drm_atomic_set_fence_for_plane(), * to make sure there's consistent behaviour between drivers in precedence * of implicit vs. explicit fencing. @@ -1917,7 +1917,7 @@ EXPORT_SYMBOL(drm_atomic_clean_old_fb); * DRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1. * * Note that out-fences don't have a special interface to drivers and are - * internally represented by a struct &drm_pending_vblank_event in struct + * internally represented by a &struct drm_pending_vblank_event in struct * &drm_crtc_state, which is also used by the nonblocking atomic commit * helpers and for the DRM event handling for existing userspace. */ diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index 799c1564a4f8..8eab8944c736 100644 --- a/drivers/gpu/drm/drm_atomic_helper.c +++ b/drivers/gpu/drm/drm_atomic_helper.c @@ -56,9 +56,9 @@ * implement these functions themselves but must use the provided helpers. * * The atomic helper uses the same function table structures as all other - * modesetting helpers. See the documentation for struct &drm_crtc_helper_funcs, - * struct &drm_encoder_helper_funcs and struct &drm_connector_helper_funcs. It - * also shares the struct &drm_plane_helper_funcs function table with the plane + * modesetting helpers. See the documentation for &struct drm_crtc_helper_funcs, + * struct &drm_encoder_helper_funcs and &struct drm_connector_helper_funcs. It + * also shares the &struct drm_plane_helper_funcs function table with the plane * helpers. */ static void @@ -1369,7 +1369,7 @@ static int stall_checks(struct drm_crtc *crtc, bool nonblock) * actually committing the hardware state, and for nonblocking commits this call * must be placed in the async worker. See also drm_atomic_helper_swap_state() * and it's stall parameter, for when a driver's commit hooks look at the - * ->state pointers of struct &drm_crtc, &drm_plane or &drm_connector directly. + * ->state pointers of &struct drm_crtc, &drm_plane or &drm_connector directly. * * Completion of the hardware commit step must be signalled using * drm_atomic_helper_commit_hw_done(). After this step the driver is not allowed diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c index 6b143514a566..860cfe124c2a 100644 --- a/drivers/gpu/drm/drm_auth.c +++ b/drivers/gpu/drm/drm_auth.c @@ -35,8 +35,8 @@ /** * DOC: master and authentication * - * struct &drm_master is used to track groups of clients with open - * primary/legacy device nodes. For every struct &drm_file which has had at + * &struct drm_master is used to track groups of clients with open + * primary/legacy device nodes. For every &struct drm_file which has had at * least once successfully became the device master (either through the * SET_MASTER IOCTL, or implicitly through opening the primary device node when * no one else is the current master that time) there exists one &drm_master. @@ -294,7 +294,7 @@ EXPORT_SYMBOL(drm_is_current_master);

/** * drm_master_get - reference a master pointer - * @master: struct &drm_master + * @master: &struct drm_master * * Increments the reference count of @master and returns a pointer to @master. */ @@ -322,7 +322,7 @@ static void drm_master_destroy(struct kref *kref)

/** * drm_master_put - unreference and clear a master pointer - * @master: pointer to a pointer of struct &drm_master + * @master: pointer to a pointer of &struct drm_master * * This decrements the &drm_master behind @master and sets it to NULL. */ diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index cd10095e8d00..ae5e57ad718c 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -33,7 +33,7 @@ /** * DOC: overview * - * struct &drm_bridge represents a device that hangs on to an encoder. These are + * &struct drm_bridge represents a device that hangs on to an encoder. These are * handy when a regular &drm_encoder entity isn't enough to represent the entire * encoder chain. * @@ -55,7 +55,7 @@ * just provide additional hooks to get the desired output at the end of the * encoder chain. * - * Bridges can also be chained up using the next pointer in struct &drm_bridge. + * Bridges can also be chained up using the next pointer in &struct drm_bridge. * * Both legacy CRTC helpers and the new atomic modeset helpers support bridges. */ diff --git a/drivers/gpu/drm/drm_color_mgmt.c b/drivers/gpu/drm/drm_color_mgmt.c index 6543ebde501a..789b4c65cd69 100644 --- a/drivers/gpu/drm/drm_color_mgmt.c +++ b/drivers/gpu/drm/drm_color_mgmt.c @@ -36,7 +36,7 @@ * "DEGAMMA_LUT”: * Blob property to set the degamma lookup table (LUT) mapping pixel data * from the framebuffer before it is given to the transformation matrix. - * The data is interpreted as an array of struct &drm_color_lut elements. + * The data is interpreted as an array of &struct drm_color_lut elements. * Hardware might choose not to use the full precision of the LUT elements * nor use all the elements of the LUT (for example the hardware might * choose to interpolate between LUT[0] and LUT[4]). @@ -65,7 +65,7 @@ * “GAMMA_LUT”: * Blob property to set the gamma lookup table (LUT) mapping pixel data * after the transformation matrix to data sent to the connector. The - * data is interpreted as an array of struct &drm_color_lut elements. + * data is interpreted as an array of &struct drm_color_lut elements. * Hardware might choose not to use the full precision of the LUT elements * nor use all the elements of the LUT (for example the hardware might * choose to interpolate between LUT[0] and LUT[4]). diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c index 3115db2ae6b1..799edd0d308e 100644 --- a/drivers/gpu/drm/drm_connector.c +++ b/drivers/gpu/drm/drm_connector.c @@ -49,7 +49,7 @@ * Connectors must be attached to an encoder to be used. For devices that map * connectors to encoders 1:1, the connector should be attached at * initialization time with a call to drm_mode_connector_attach_encoder(). The - * driver must also set the struct &drm_connector encoder field to point to the + * driver must also set the &struct drm_connector encoder field to point to the * attached encoder. * * For connectors which are not fixed (like built-in panels) the driver needs to diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c index 923a17c05e01..1e281dd42e4b 100644 --- a/drivers/gpu/drm/drm_crtc_helper.c +++ b/drivers/gpu/drm/drm_crtc_helper.c @@ -71,7 +71,7 @@ * * These legacy modeset helpers use the same function table structures as * all other modesetting helpers. See the documentation for struct - * &drm_crtc_helper_funcs, struct &drm_encoder_helper_funcs and struct + * &drm_crtc_helper_funcs, &struct drm_encoder_helper_funcs and struct * &drm_connector_helper_funcs. */

@@ -478,10 +478,10 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) * @set: mode set configuration * * The drm_crtc_helper_set_config() helper function implements the set_config - * callback of struct &drm_crtc_funcs for drivers using the legacy CRTC helpers. + * callback of &struct drm_crtc_funcs for drivers using the legacy CRTC helpers. * * It first tries to locate the best encoder for each connector by calling the - * connector ->best_encoder() (struct &drm_connector_helper_funcs) helper + * connector ->best_encoder() (&struct drm_connector_helper_funcs) helper * operation. * * After locating the appropriate encoders, the helper function will call the @@ -493,7 +493,7 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) * * If the adjusted mode is identical to the current mode but changes to the * frame buffer need to be applied, the drm_crtc_helper_set_config() function - * will call the CRTC ->mode_set_base() (struct &drm_crtc_helper_funcs) helper + * will call the CRTC ->mode_set_base() (&struct drm_crtc_helper_funcs) helper * operation. * * If the adjusted mode differs from the current mode, or if the @@ -501,7 +501,7 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) * performs a full mode set sequence by calling the ->prepare(), ->mode_set() * and ->commit() CRTC and encoder helper operations, in that order. * Alternatively it can also use the dpms and disable helper operations. For - * details see struct &drm_crtc_helper_funcs and struct + * details see &struct drm_crtc_helper_funcs and struct * &drm_encoder_helper_funcs. * * This function is deprecated. New drivers must implement atomic modeset @@ -852,12 +852,12 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc) * @mode: DPMS mode * * The drm_helper_connector_dpms() helper function implements the ->dpms() - * callback of struct &drm_connector_funcs for drivers using the legacy CRTC helpers. + * callback of &struct drm_connector_funcs for drivers using the legacy CRTC helpers. * * This is the main helper function provided by the CRTC helper framework for * implementing the DPMS connector attribute. It computes the new desired DPMS * state for all encoders and CRTCs in the output mesh and calls the ->dpms() - * callbacks provided by the driver in struct &drm_crtc_helper_funcs and struct + * callbacks provided by the driver in &struct drm_crtc_helper_funcs and struct * &drm_encoder_helper_funcs appropriately. * * This function is deprecated. New drivers must implement atomic modeset diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c index 4a7b3e98d586..f8de5804c37c 100644 --- a/drivers/gpu/drm/drm_drv.c +++ b/drivers/gpu/drm/drm_drv.c @@ -298,7 +298,7 @@ void drm_minor_release(struct drm_minor *minor) /** * DOC: driver instance overview * - * A device instance for a drm driver is represented by struct &drm_device. This + * A device instance for a drm driver is represented by &struct drm_device. This * is allocated with drm_dev_alloc(), usually from bus-specific ->probe() * callbacks implemented by the driver. The driver then needs to initialize all * the various subsystems for the drm device like memory management, vblank @@ -323,7 +323,7 @@ void drm_minor_release(struct drm_minor *minor) * historical baggage. Hence use the reference counting provided by * drm_dev_ref() and drm_dev_unref() only carefully. * - * It is recommended that drivers embed struct &drm_device into their own device + * It is recommended that drivers embed &struct drm_device into their own device * structure, which is supported through drm_dev_init(). */

@@ -461,8 +461,8 @@ static void drm_fs_inode_free(struct inode *inode) * Note that for purely virtual devices @parent can be NULL. * * Drivers that do not want to allocate their own device struct - * embedding struct &drm_device can call drm_dev_alloc() instead. For drivers - * that do embed struct &drm_device it must be placed first in the overall + * embedding &struct drm_device can call drm_dev_alloc() instead. For drivers + * that do embed &struct drm_device it must be placed first in the overall * structure, and the overall structure must be allocated using kmalloc(): The * drm core's release function unconditionally calls kfree() on the @dev pointer * when the final reference is released. @@ -568,7 +568,7 @@ EXPORT_SYMBOL(drm_dev_init); * * Note that for purely virtual devices @parent can be NULL. * - * Drivers that wish to subclass or embed struct &drm_device into their + * Drivers that wish to subclass or embed &struct drm_device into their * own struct should look at using drm_dev_init() instead. * * RETURNS: diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c index 8ac5a1c1d811..e5c61cda4ae3 100644 --- a/drivers/gpu/drm/drm_dumb_buffers.c +++ b/drivers/gpu/drm/drm_dumb_buffers.c @@ -43,7 +43,7 @@ * KMS frame buffers. * * To support dumb objects drivers must implement the dumb_create, - * dumb_destroy and dumb_map_offset operations from struct &drm_driver. See + * dumb_destroy and dumb_map_offset operations from &struct drm_driver. See * there for further details. * * Note that dumb objects may not be used for gpu acceleration, as has been diff --git a/drivers/gpu/drm/drm_encoder.c b/drivers/gpu/drm/drm_encoder.c index 5f0598e4bf6f..487cfe3989e8 100644 --- a/drivers/gpu/drm/drm_encoder.c +++ b/drivers/gpu/drm/drm_encoder.c @@ -30,8 +30,8 @@ * DOC: overview * * Encoders represent the connecting element between the CRTC (as the overall - * pixel pipeline, represented by struct &drm_crtc) and the connectors (as the - * generic sink entity, represented by struct &drm_connector). An encoder takes + * pixel pipeline, represented by &struct drm_crtc) and the connectors (as the + * generic sink entity, represented by &struct drm_connector). An encoder takes * pixel data from a CRTC and converts it to a format suitable for any attached * connector. Encoders are objects exposed to userspace, originally to allow * userspace to infer cloning and connector/CRTC restrictions. Unfortunately diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 769a3b3236ee..76cb1aa1b089 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -273,7 +273,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 put into prepare_fb hook of &struct drm_plane_helper_funcs . * * 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 diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c index 94ddab41f24f..588ccc3a2218 100644 --- a/drivers/gpu/drm/drm_framebuffer.c +++ b/drivers/gpu/drm/drm_framebuffer.c @@ -39,13 +39,13 @@ * Frame buffers rely on the underlying memory manager for allocating backing * storage. When creating a frame buffer applications pass a memory handle * (or a list of memory handles for multi-planar formats) through the - * struct &drm_mode_fb_cmd2 argument. For drivers using GEM as their userspace + * &struct drm_mode_fb_cmd2 argument. For drivers using GEM as their userspace * buffer management interface this would be a GEM handle. Drivers are however * free to use their own backing storage object handles, e.g. vmwgfx directly * exposes special TTM handles to userspace and so expects TTM handles in the * create ioctl and not GEM handles. * - * Framebuffers are tracked with struct &drm_framebuffer. They are published + * Framebuffers are tracked with &struct drm_framebuffer. They are published * using drm_framebuffer_init() - after calling that function userspace can use * and access the framebuffer object. The helper function * drm_helper_mode_fill_fb_struct() can be used to pre-fill the required @@ -55,7 +55,7 @@ * drivers can grab additional references with drm_framebuffer_reference() and * drop them again with drm_framebuffer_unreference(). For driver-private * framebuffers for which the last reference is never dropped (e.g. for the - * fbdev framebuffer when the struct struct &drm_framebuffer is embedded into + * fbdev framebuffer when the struct &struct drm_framebuffer is embedded into * the fbdev helper struct) drivers can manually clean up a framebuffer at * module unload time with drm_framebuffer_unregister_private(). But doing this * is not recommended, and it's better to have a normal free-standing struct diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c index feb091310ffe..88c69e71102e 100644 --- a/drivers/gpu/drm/drm_irq.c +++ b/drivers/gpu/drm/drm_irq.c @@ -982,7 +982,7 @@ static void send_vblank_event(struct drm_device *dev, * period. This helper function implements exactly the required vblank arming * behaviour. * - * NOTE: Drivers using this to send out the event in struct &drm_crtc_state + * NOTE: Drivers using this to send out the event in &struct drm_crtc_state * as part of an atomic commit must ensure that the next vblank happens at * exactly the same time as the atomic commit is committed to the hardware. This * function itself does **not** protect again the next vblank interrupt racing diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c index 8ad20af88ed7..7b7275f0c2df 100644 --- a/drivers/gpu/drm/drm_plane.c +++ b/drivers/gpu/drm/drm_plane.c @@ -37,7 +37,7 @@ * rotation or Z-position. All these properties are stored in &drm_plane_state. * * To create a plane, a KMS drivers allocates and zeroes an instances of - * struct &drm_plane (possibly as part of a larger structure) and registers it + * &struct drm_plane (possibly as part of a larger structure) and registers it * with a call to drm_universal_plane_init(). * * Cursor and overlay planes are optional. All drivers should provide one diff --git a/drivers/gpu/drm/drm_plane_helper.c b/drivers/gpu/drm/drm_plane_helper.c index 8b042a193613..35d43607a47d 100644 --- a/drivers/gpu/drm/drm_plane_helper.c +++ b/drivers/gpu/drm/drm_plane_helper.c @@ -60,7 +60,7 @@ * Again drivers are strongly urged to switch to the new interfaces. * * The plane helpers share the function table structures with other helpers, - * specifically also the atomic helpers. See struct &drm_plane_helper_funcs for + * specifically also the atomic helpers. See &struct drm_plane_helper_funcs for * the details. */

diff --git a/drivers/gpu/drm/drm_probe_helper.c b/drivers/gpu/drm/drm_probe_helper.c index 7cff91e7497f..97a32898ef50 100644 --- a/drivers/gpu/drm/drm_probe_helper.c +++ b/drivers/gpu/drm/drm_probe_helper.c @@ -55,7 +55,7 @@ * handling code to avoid probing unrelated outputs. * * The probe helpers share the function table structures with other display - * helper libraries. See struct &drm_connector_helper_funcs for the details. + * helper libraries. See &struct drm_connector_helper_funcs for the details. */

static bool drm_kms_helper_poll = true; diff --git a/drivers/gpu/drm/drm_property.c b/drivers/gpu/drm/drm_property.c index 24be69d29964..0d0e5dc0ee23 100644 --- a/drivers/gpu/drm/drm_property.c +++ b/drivers/gpu/drm/drm_property.c @@ -34,7 +34,7 @@ * even the only way to transport metadata about the desired new modeset * configuration from userspace to the kernel. Properties have a well-defined * value range, which is enforced by the drm core. See the documentation of the - * flags member of struct &drm_property for an overview of the different + * flags member of &struct drm_property for an overview of the different * property types and ranges. * * Properties don't store the current value directly, but need to be diff --git a/drivers/gpu/drm/drm_simple_kms_helper.c b/drivers/gpu/drm/drm_simple_kms_helper.c index 3cc42f5dfba1..35c5d99296b9 100644 --- a/drivers/gpu/drm/drm_simple_kms_helper.c +++ b/drivers/gpu/drm/drm_simple_kms_helper.c @@ -23,7 +23,7 @@ * * drm_simple_display_pipe_init() initializes a simple display pipeline * which has only one full-screen scanout buffer feeding one output. The - * pipeline is represented by struct &drm_simple_display_pipe and binds + * pipeline is represented by &struct drm_simple_display_pipe and binds * together &drm_plane, &drm_crtc and &drm_encoder structures into one fixed * entity. Some flexibility for code reuse is provided through a separately * allocated &drm_connector object and supporting optional &drm_bridge diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index b0ebe0fafc41..fd2d971bca32 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -398,7 +398,7 @@ void drm_state_dump(struct drm_device *dev, struct drm_printer *p); * drm_atomic_crtc_needs_modeset - compute combined modeset need * @state: &drm_crtc_state for the CRTC * - * To give drivers flexibility struct &drm_crtc_state has 3 booleans to track + * To give drivers flexibility &struct drm_crtc_state has 3 booleans to track * whether the state CRTC changed enough to need a full modeset cycle: * connectors_changed, mode_changed and active_changed. This helper simply * combines these three to compute the overall need for a modeset for @state. diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h index 155588eb8ccf..eecbc2f43f55 100644 --- a/include/drm/drm_auth.h +++ b/include/drm/drm_auth.h @@ -48,7 +48,7 @@ struct drm_master { */ char *unique; /** - * @unique_len: Length of unique field. Protected by struct &drm_device + * @unique_len: Length of unique field. Protected by &struct drm_device * master_mutex. */ int unique_len; diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h index 435be20029f7..d3ca16f4da8f 100644 --- a/include/drm/drm_bridge.h +++ b/include/drm/drm_bridge.h @@ -98,7 +98,7 @@ struct drm_bridge_funcs { * preceding element is a bridge this means it's called before that * bridge's ->disable() function. If the preceding element is a * &drm_encoder it's called right before the encoder's ->disable(), - * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs. + * ->prepare() or ->dpms() hook from &struct drm_encoder_helper_funcs. * * The bridge can assume that the display pipe (i.e. clocks and timing * signals) feeding it is still running when this callback is called. @@ -115,7 +115,7 @@ struct drm_bridge_funcs { * preceding element is a bridge this means it's called after that * bridge's ->post_disable() function. If the preceding element is a * &drm_encoder it's called right after the encoder's ->disable(), - * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs. + * ->prepare() or ->dpms() hook from &struct drm_encoder_helper_funcs. * * The bridge must assume that the display pipe (i.e. clocks and timing * singals) feeding it is no longer running when this callback is @@ -144,7 +144,7 @@ struct drm_bridge_funcs { * preceding element is a bridge this means it's called before that * bridge's ->pre_enable() function. If the preceding element is a * &drm_encoder it's called right before the encoder's ->enable(), - * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs. + * ->commit() or ->dpms() hook from &struct drm_encoder_helper_funcs. * * The display pipe (i.e. clocks and timing signals) feeding this bridge * will not yet be running when this callback is called. The bridge must @@ -163,7 +163,7 @@ struct drm_bridge_funcs { * preceding element is a bridge this means it's called after that * bridge's ->enable() function. If the preceding element is a * &drm_encoder it's called right after the encoder's ->enable(), - * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs. + * ->commit() or ->dpms() hook from &struct drm_encoder_helper_funcs. * * The bridge can assume that the display pipe (i.e. clocks and timing * signals) feeding it is running when this callback is called. This diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h index 6e352a0b5c81..acb4241bff7d 100644 --- a/include/drm/drm_connector.h +++ b/include/drm/drm_connector.h @@ -94,7 +94,7 @@ enum subpixel_order { * * Describes a given display (e.g. CRT or flat panel) and its limitations. For * fixed display sinks like built-in panels there's not much difference between - * this and struct &drm_connector. But for sinks with a real cable this + * this and &struct drm_connector. But for sinks with a real cable this * structure is meant to describe all the things at the other end of the cable. * * For sinks which provide an EDID this can be filled out by calling @@ -422,7 +422,7 @@ struct drm_connector_funcs { * &drm_mode_config_funcs) will be cleaned up by calling the * @atomic_destroy_state hook in this structure. * - * Atomic drivers which don't subclass struct &drm_connector_state should use + * Atomic drivers which don't subclass &struct drm_connector_state should use * drm_atomic_helper_connector_duplicate_state(). Drivers that subclass the * state structure to extend it with driver-private state should use * __drm_atomic_helper_connector_duplicate_state() to make sure shared state is @@ -525,7 +525,7 @@ struct drm_connector_funcs { /** * @atomic_print_state: * - * If driver subclasses struct &drm_connector_state, it should implement + * If driver subclasses &struct drm_connector_state, it should implement * this optional hook for printing additional driver specific state. * * Do not call this directly, use drm_atomic_connector_print_state() @@ -904,8 +904,8 @@ void drm_connector_list_iter_put(struct drm_connector_list_iter *iter);

/** * drm_for_each_connector_iter - connector_list iterator macro - * @connector: struct &drm_connector pointer used as cursor - * @iter: struct &drm_connector_list_iter + * @connector: &struct drm_connector pointer used as cursor + * @iter: &struct drm_connector_list_iter * * Note that @connector is only valid within the list body, if you want to use * @connector after calling drm_connector_list_iter_put() then you need to grab diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h index 6920dee3a2d1..0b9ec7245c7e 100644 --- a/include/drm/drm_crtc.h +++ b/include/drm/drm_crtc.h @@ -315,7 +315,7 @@ struct drm_crtc_funcs { * * This is the main legacy entry point to change the modeset state on a * CRTC. All the details of the desired configuration are passed in a - * struct &drm_mode_set - see there for details. + * &struct drm_mode_set - see there for details. * * Drivers implementing atomic modeset should use * drm_atomic_helper_set_config() to implement this hook. @@ -346,7 +346,7 @@ struct drm_crtc_funcs { * shared dma-buf. * * An application can request to be notified when the page flip has - * completed. The drm core will supply a struct &drm_event in the event + * completed. The drm core will supply a &struct drm_event in the event * parameter in this case. This can be handled by the * drm_crtc_send_vblank_event() function, which the driver should call on * the provided event upon completion of the flip. Note that if @@ -431,7 +431,7 @@ struct drm_crtc_funcs { * &drm_mode_config_funcs) will be cleaned up by calling the * @atomic_destroy_state hook in this structure. * - * Atomic drivers which don't subclass struct &drm_crtc should use + * Atomic drivers which don't subclass &struct drm_crtc should use * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the * state structure to extend it with driver-private state should use * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is @@ -583,7 +583,7 @@ struct drm_crtc_funcs { /** * @atomic_print_state: * - * If driver subclasses struct &drm_crtc_state, it should implement + * If driver subclasses &struct drm_crtc_state, it should implement * this optional hook for printing additional driver specific state. * * Do not call this directly, use drm_atomic_crtc_print_state() diff --git a/include/drm/drm_fb_helper.h b/include/drm/drm_fb_helper.h index 975deedd593e..53687c5664b8 100644 --- a/include/drm/drm_fb_helper.h +++ b/include/drm/drm_fb_helper.h @@ -181,7 +181,7 @@ struct drm_fb_helper_connector { * * This is the main structure used by the fbdev helpers. Drivers supporting * fbdev emulation should embedded this into their overall driver structure. - * Drivers must also fill out a struct &drm_fb_helper_funcs with a few + * Drivers must also fill out a &struct drm_fb_helper_funcs with a few * operations. */ struct drm_fb_helper { diff --git a/include/drm/drm_framebuffer.h b/include/drm/drm_framebuffer.h index f0dde1d02be4..046c35e54099 100644 --- a/include/drm/drm_framebuffer.h +++ b/include/drm/drm_framebuffer.h @@ -51,7 +51,7 @@ struct drm_framebuffer_funcs { * @create_handle: * * Create a buffer handle in the driver-specific buffer manager (either - * GEM or TTM) valid for the passed-in struct &drm_file. This is used by + * GEM or TTM) valid for the passed-in &struct drm_file. This is used by * the core to implement the GETFB IOCTL, which returns (for * sufficiently priviledged user) also a native buffer handle. This can * be used for seamless transitions between modesetting clients by @@ -149,7 +149,7 @@ struct drm_framebuffer { * * This should not be used to specifiy x/y pixel offsets into the buffer * data (even for linear buffers). Specifying an x/y pixel offset is - * instead done through the source rectangle in struct &drm_plane_state. + * instead done through the source rectangle in &struct drm_plane_state. */ unsigned int offsets[4]; /** @@ -187,7 +187,7 @@ struct drm_framebuffer { */ int hot_y; /** - * @filp_head: Placed on struct &drm_file fbs list_head, protected by + * @filp_head: Placed on &struct drm_file fbs list_head, protected by * fbs_lock in the same structure. */ struct list_head filp_head; diff --git a/include/drm/drm_irq.h b/include/drm/drm_irq.h index 293d08caab60..18cfd11307e1 100644 --- a/include/drm/drm_irq.h +++ b/include/drm/drm_irq.h @@ -51,8 +51,8 @@ struct drm_pending_vblank_event { * * Note that for historical reasons - the vblank handling code is still shared * with legacy/non-kms drivers - this is a free-standing structure not directly - * connected to struct &drm_crtc. But all public interface functions are taking - * a struct &drm_crtc to hide this implementation detail. + * connected to &struct drm_crtc. But all public interface functions are taking + * a &struct drm_crtc to hide this implementation detail. */ struct drm_vblank_crtc { /** diff --git a/include/drm/drm_mode_config.h b/include/drm/drm_mode_config.h index 5b735549bd51..17942c0f32a8 100644 --- a/include/drm/drm_mode_config.h +++ b/include/drm/drm_mode_config.h @@ -47,7 +47,7 @@ struct drm_mode_config_funcs { * * Create a new framebuffer object. The core does basic checks on the * requested metadata, but most of that is left to the driver. See - * struct &drm_mode_fb_cmd2 for details. + * &struct drm_mode_fb_cmd2 for details. * * If the parameters are deemed valid and the backing storage objects in * the underlying memory manager all exist, then the driver allocates @@ -135,7 +135,7 @@ struct drm_mode_config_funcs { * error conditions which don't have to be checked at the * ->atomic_check() stage? * - * See the documentation for struct &drm_atomic_state for how exactly + * See the documentation for &struct drm_atomic_state for how exactly * an atomic modeset update is described. * * Drivers using the atomic helpers can implement this hook using @@ -171,7 +171,7 @@ struct drm_mode_config_funcs { * calling this function, and that nothing has been changed in the * interim. * - * See the documentation for struct &drm_atomic_state for how exactly + * See the documentation for &struct drm_atomic_state for how exactly * an atomic modeset update is described. * * Drivers using the atomic helpers can implement this hook using @@ -198,7 +198,7 @@ struct drm_mode_config_funcs { * completed. These events are per-CRTC and can be distinguished by the * CRTC index supplied in &drm_event to userspace. * - * The drm core will supply a struct &drm_event in the event + * The drm core will supply a &struct drm_event in the event * member of each CRTC's &drm_crtc_state structure. See the * documentation for &drm_crtc_state for more details about the precise * semantics of this event. @@ -381,7 +381,7 @@ struct drm_mode_config { /** * @connector_list: List of connector objects. Protected by * @connector_list_lock. Only use drm_for_each_connector_iter() and - * struct &drm_connector_list_iter to walk this list. + * &struct drm_connector_list_iter to walk this list. */ struct list_head connector_list; int num_encoder; diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_modeset_helper_vtables.h index 625c7475c5df..46f5b349f059 100644 --- a/include/drm/drm_modeset_helper_vtables.h +++ b/include/drm/drm_modeset_helper_vtables.h @@ -726,7 +726,7 @@ struct drm_connector_helper_funcs { * fixed panel can also manually add specific modes using * drm_mode_probed_add(). Drivers which manually add modes should also * make sure that the @display_info, @width_mm and @height_mm fields of the - * struct &drm_connector are filled in. + * &struct drm_connector are filled in. * * Virtual drivers that just want some standard VESA mode with a given * resolution can call drm_add_modes_noedid(), and mark the preferred diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h index db3bbdeb36d5..e049bc52fb07 100644 --- a/include/drm/drm_plane.h +++ b/include/drm/drm_plane.h @@ -253,7 +253,7 @@ struct drm_plane_funcs { * &drm_mode_config_funcs) will be cleaned up by calling the * @atomic_destroy_state hook in this structure. * - * Atomic drivers which don't subclass struct &drm_plane_state should use + * Atomic drivers which don't subclass &struct drm_plane_state should use * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the * state structure to extend it with driver-private state should use * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is @@ -381,7 +381,7 @@ struct drm_plane_funcs { /** * @atomic_print_state: * - * If driver subclasses struct &drm_plane_state, it should implement + * If driver subclasses &struct drm_plane_state, it should implement * this optional hook for printing additional driver specific state. * * Do not call this directly, use drm_atomic_plane_print_state() diff --git a/include/drm/drm_print.h b/include/drm/drm_print.h index e9d0ba20089c..7d98763c0444 100644 --- a/include/drm/drm_print.h +++ b/include/drm/drm_print.h @@ -80,7 +80,7 @@ void drm_printf(struct drm_printer *p, const char *f, ...);

/** * drm_seq_file_printer - construct a &drm_printer that outputs to &seq_file - * @f: the struct &seq_file to output to + * @f: the &struct seq_file to output to * * RETURNS: * The &drm_printer object @@ -96,7 +96,7 @@ static inline struct drm_printer drm_seq_file_printer(struct seq_file *f)

/** * drm_info_printer - construct a &drm_printer that outputs to dev_printk() - * @dev: the struct &device pointer + * @dev: the &struct device pointer * * RETURNS: * The &drm_printer object diff --git a/include/drm/drm_simple_kms_helper.h b/include/drm/drm_simple_kms_helper.h index 2bbc610ec3a2..fe8c4ba905ac 100644 --- a/include/drm/drm_simple_kms_helper.h +++ b/include/drm/drm_simple_kms_helper.h @@ -73,9 +73,9 @@ struct drm_simple_display_pipe_funcs { /** * @prepare_fb: * - * Optional, called by struct &drm_plane_helper_funcs ->prepare_fb . + * Optional, called by &struct drm_plane_helper_funcs ->prepare_fb . * Please read the documentation for the ->prepare_fb hook in - * struct &drm_plane_helper_funcs for more details. + * &struct drm_plane_helper_funcs for more details. */ int (*prepare_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state); @@ -83,9 +83,9 @@ struct drm_simple_display_pipe_funcs { /** * @cleanup_fb: * - * Optional, called by struct &drm_plane_helper_funcs ->cleanup_fb . + * Optional, called by &struct drm_plane_helper_funcs ->cleanup_fb . * Please read the documentation for the ->cleanup_fb hook in - * struct &drm_plane_helper_funcs for more details. + * &struct drm_plane_helper_funcs for more details. */ void (*cleanup_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state);

Drive-by polish.

Cc: Ville Syrjälä ville.syrjala@linux.intel.com Signed-off-by: Daniel Vetter daniel.vetter@ffwll.ch --- drivers/gpu/drm/drm_rect.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/drm_rect.c b/drivers/gpu/drm/drm_rect.c index e6057d8cdcd5..bc5575960ebc 100644 --- a/drivers/gpu/drm/drm_rect.c +++ b/drivers/gpu/drm/drm_rect.c @@ -371,10 +371,10 @@ EXPORT_SYMBOL(drm_rect_rotate); * to the vertical axis of the original untransformed * coordinate space, so that you never have to flip * them when doing a rotatation and its inverse. - * That is, if you do: + * That is, if you do :: * - * drm_rotate(&r, width, height, rotation); - * drm_rotate_inv(&r, width, height, rotation); + * drm_rotate(&r, width, height, rotation); + * drm_rotate_inv(&r, width, height, rotation); * * you will always get back the original rectangle. */

If we store the fb funcs pointer, we can remove a bit of boilerplate. Also remove the _fbdev_ in the example code, since the fb_funcs->dirty callback has nothing to do with fbdev. It's a KMS feature, only used by the fbdev deferred_io support to implement flushing/upload.

Cc: Noralf Trønnes noralf@tronnes.org Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_fb_cma_helper.c | 58 +++++++++++++------------------------ include/drm/drm_fb_cma_helper.h | 5 +--- 2 files changed, 21 insertions(+), 42 deletions(-)

diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index 76cb1aa1b089..ec081727cd5a 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -39,6 +39,7 @@ struct drm_fb_cma { struct drm_fbdev_cma { struct drm_fb_helper fb_helper; struct drm_fb_cma *fb; + const struct drm_framebuffer_funcs *fb_funcs; };

/** @@ -58,39 +59,29 @@ struct drm_fbdev_cma { * * Example fbdev deferred io code:: * - * static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb, - * struct drm_file *file_priv, - * unsigned flags, unsigned color, - * struct drm_clip_rect *clips, - * unsigned num_clips) + * static int driver_fb_dirty(struct drm_framebuffer *fb, + * struct drm_file *file_priv, + * unsigned flags, unsigned color, + * struct drm_clip_rect *clips, + * unsigned num_clips) * { * struct drm_gem_cma_object *cma = drm_fb_cma_get_gem_obj(fb, 0); * ... push changes ... * return 0; * } * - * static struct drm_framebuffer_funcs driver_fbdev_fb_funcs = { + * static struct drm_framebuffer_funcs driver_fb_funcs = { * .destroy = drm_fb_cma_destroy, * .create_handle = drm_fb_cma_create_handle, - * .dirty = driver_fbdev_fb_dirty, + * .dirty = driver_fb_dirty, * }; * - * static int driver_fbdev_create(struct drm_fb_helper *helper, - * struct drm_fb_helper_surface_size *sizes) - * { - * return drm_fbdev_cma_create_with_funcs(helper, sizes, - * &driver_fbdev_fb_funcs); - * } - * - * static const struct drm_fb_helper_funcs driver_fb_helper_funcs = { - * .fb_probe = driver_fbdev_create, - * }; + * Initialize:: * - * Initialize: * fbdev = drm_fbdev_cma_init_with_funcs(dev, 16, * dev->mode_config.num_crtc, * dev->mode_config.num_connector, - * &driver_fb_helper_funcs); + * &driver_fb_funcs); * */

@@ -408,13 +399,9 @@ static void drm_fbdev_cma_defio_fini(struct fb_info *fbi) kfree(fbi->fbops); }

-/* - * For use in a (struct drm_fb_helper_funcs *)->fb_probe callback function that - * needs custom struct drm_framebuffer_funcs, like dirty() for deferred_io use. - */ -int drm_fbdev_cma_create_with_funcs(struct drm_fb_helper *helper, - struct drm_fb_helper_surface_size *sizes, - const struct drm_framebuffer_funcs *funcs) +static int +drm_fbdev_cma_create(struct drm_fb_helper *helper, + struct drm_fb_helper_surface_size *sizes) { struct drm_fbdev_cma *fbdev_cma = to_fbdev_cma(helper); struct drm_mode_fb_cmd2 mode_cmd = { 0 }; @@ -450,7 +437,8 @@ int drm_fbdev_cma_create_with_funcs(struct drm_fb_helper *helper, goto err_gem_free_object; }

- fbdev_cma->fb = drm_fb_cma_alloc(dev, &mode_cmd, &obj, 1, funcs); + fbdev_cma->fb = drm_fb_cma_alloc(dev, &mode_cmd, &obj, 1, + fbdev_cma->fb_funcs); if (IS_ERR(fbdev_cma->fb)) { dev_err(dev->dev, "Failed to allocate DRM framebuffer.\n"); ret = PTR_ERR(fbdev_cma->fb); @@ -476,7 +464,7 @@ int drm_fbdev_cma_create_with_funcs(struct drm_fb_helper *helper, fbi->screen_size = size; fbi->fix.smem_len = size;

- if (funcs->dirty) { + if (fbdev_cma->fb_funcs->dirty) { ret = drm_fbdev_cma_defio_init(fbi, obj); if (ret) goto err_cma_destroy; @@ -492,13 +480,6 @@ int drm_fbdev_cma_create_with_funcs(struct drm_fb_helper *helper, drm_gem_object_unreference_unlocked(&obj->base); return ret; } -EXPORT_SYMBOL(drm_fbdev_cma_create_with_funcs); - -static int drm_fbdev_cma_create(struct drm_fb_helper *helper, - struct drm_fb_helper_surface_size *sizes) -{ - return drm_fbdev_cma_create_with_funcs(helper, sizes, &drm_fb_cma_funcs); -}

static const struct drm_fb_helper_funcs drm_fb_cma_helper_funcs = { .fb_probe = drm_fbdev_cma_create, @@ -516,7 +497,7 @@ static const struct drm_fb_helper_funcs drm_fb_cma_helper_funcs = { */ struct drm_fbdev_cma *drm_fbdev_cma_init_with_funcs(struct drm_device *dev, unsigned int preferred_bpp, unsigned int num_crtc, - unsigned int max_conn_count, const struct drm_fb_helper_funcs *funcs) + unsigned int max_conn_count, const struct drm_framebuffer_funcs *funcs) { struct drm_fbdev_cma *fbdev_cma; struct drm_fb_helper *helper; @@ -527,10 +508,11 @@ struct drm_fbdev_cma *drm_fbdev_cma_init_with_funcs(struct drm_device *dev, dev_err(dev->dev, "Failed to allocate drm fbdev.\n"); return ERR_PTR(-ENOMEM); } + fbdev_cma->fb_funcs = funcs;

helper = &fbdev_cma->fb_helper;

- drm_fb_helper_prepare(dev, helper, funcs); + drm_fb_helper_prepare(dev, helper, &drm_fb_cma_helper_funcs);

ret = drm_fb_helper_init(dev, helper, num_crtc, max_conn_count); if (ret < 0) { @@ -576,7 +558,7 @@ struct drm_fbdev_cma *drm_fbdev_cma_init(struct drm_device *dev, unsigned int max_conn_count) { return drm_fbdev_cma_init_with_funcs(dev, preferred_bpp, num_crtc, - max_conn_count, &drm_fb_cma_helper_funcs); + max_conn_count, &drm_fb_cma_funcs); } EXPORT_SYMBOL_GPL(drm_fbdev_cma_init);

diff --git a/include/drm/drm_fb_cma_helper.h b/include/drm/drm_fb_cma_helper.h index 3b00f6480b83..9f4e34ea99fd 100644 --- a/include/drm/drm_fb_cma_helper.h +++ b/include/drm/drm_fb_cma_helper.h @@ -17,7 +17,7 @@ struct drm_plane_state;

struct drm_fbdev_cma *drm_fbdev_cma_init_with_funcs(struct drm_device *dev, unsigned int preferred_bpp, unsigned int num_crtc, - unsigned int max_conn_count, const struct drm_fb_helper_funcs *funcs); + unsigned int max_conn_count, const struct drm_framebuffer_funcs *funcs); struct drm_fbdev_cma *drm_fbdev_cma_init(struct drm_device *dev, unsigned int preferred_bpp, unsigned int num_crtc, unsigned int max_conn_count); @@ -26,9 +26,6 @@ void drm_fbdev_cma_fini(struct drm_fbdev_cma *fbdev_cma); void drm_fbdev_cma_restore_mode(struct drm_fbdev_cma *fbdev_cma); void drm_fbdev_cma_hotplug_event(struct drm_fbdev_cma *fbdev_cma); void drm_fbdev_cma_set_suspend(struct drm_fbdev_cma *fbdev_cma, int state); -int drm_fbdev_cma_create_with_funcs(struct drm_fb_helper *helper, - struct drm_fb_helper_surface_size *sizes, - const struct drm_framebuffer_funcs *funcs);

void drm_fb_cma_destroy(struct drm_framebuffer *fb); int drm_fb_cma_create_handle(struct drm_framebuffer *fb,

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 ...

Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Chris Wilson chris@chris-wilson.co.uk Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_atomic_helper.c | 97 ++++++++++---------- drivers/gpu/drm/drm_crtc_helper.c | 28 +++--- drivers/gpu/drm/drm_dp_helper.c | 2 +- drivers/gpu/drm/drm_fb_helper.c | 48 +++++----- drivers/gpu/drm/drm_plane_helper.c | 9 +- drivers/gpu/drm/drm_probe_helper.c | 14 +-- include/drm/drm_atomic_helper.h | 13 +-- include/drm/drm_dp_mst_helper.h | 7 +- include/drm/drm_flip_work.h | 2 +- include/drm/drm_modeset_helper_vtables.h | 146 ++++++++++++++++--------------- include/drm/drm_simple_kms_helper.h | 12 +-- 11 files changed, 197 insertions(+), 181 deletions(-)

diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index 5e5224460042..8ef1f5923468 100644 --- a/drivers/gpu/drm/drm_atomic_helper.c +++ b/drivers/gpu/drm/drm_atomic_helper.c @@ -458,22 +458,25 @@ mode_fixup(struct drm_atomic_state *state) * Check the state object to see if the requested state is physically possible. * This does all the crtc and connector related computations for an atomic * update and adds any additional connectors needed for full modesets and calls - * down into ->mode_fixup functions of the driver backend. - * - * crtc_state->mode_changed is set when the input mode is changed. - * crtc_state->connectors_changed is set when a connector is added or - * removed from the crtc. - * crtc_state->active_changed is set when crtc_state->active changes, - * which is used for dpms. + * down into &drm_crtc_helper_funcs.mode_fixup and + * &drm_encoder_helper_funcs.mode_fixup or + * &drm_encoder_helper_funcs.atomic_check functions of the driver backend. + * + * &drm_crtc_state.mode_changed is set when the input mode is changed. + * &drm_crtc_state.connectors_changed is set when a connector is added or + * removed from the crtc. &drm_crtc_state.active_changed is set when + * &drm_crtc_state.active changes, which is used for DPMS. * See also: drm_atomic_crtc_needs_modeset() * * IMPORTANT: * - * Drivers which set ->mode_changed (e.g. in their ->atomic_check hooks if a - * plane update can't be done without a full modeset) _must_ call this function - * afterwards after that change. It is permitted to call this function multiple - * times for the same update, e.g. when the ->atomic_check functions depend upon - * the adjusted dotclock for fifo space allocation and watermark computation. + * Drivers which set &drm_crtc_state.mode_changed (e.g. in their + * &drm_plane_helper_funcs.atomic_check hooks if a plane update can't be done + * without a full modeset) _must_ call this function afterwards after that + * change. It is permitted to call this function multiple times for the same + * update, e.g. when the &drm_crtc_helper_funcs.atomic_check functions depend + * upon the adjusted dotclock for fifo space allocation and watermark + * computation. * * RETURNS: * Zero for success or -errno @@ -584,9 +587,10 @@ EXPORT_SYMBOL(drm_atomic_helper_check_modeset); * * Check the state object to see if the requested state is physically possible. * This does all the plane update related checks using by calling into the - * ->atomic_check hooks provided by the driver. + * &drm_crtc_helper_funcs.atomic_check and &drm_plane_helper_funcs.atomic_check + * hooks provided by the driver. * - * It also sets crtc_state->planes_changed to indicate that a crtc has + * It also sets &drm_crtc_state.planes_changed to indicate that a crtc has * updated planes. * * RETURNS: @@ -648,14 +652,15 @@ EXPORT_SYMBOL(drm_atomic_helper_check_planes); * Check the state object to see if the requested state is physically possible. * Only crtcs and planes have check callbacks, so for any additional (global) * checking that a driver needs it can simply wrap that around this function. - * Drivers without such needs can directly use this as their ->atomic_check() - * callback. + * Drivers without such needs can directly use this as their + * &drm_mode_config_funcs.atomic_check callback. * * This just wraps the two parts of the state checking for planes and modeset * state in the default order: First it calls drm_atomic_helper_check_modeset() * and then drm_atomic_helper_check_planes(). The assumption is that the - * ->atomic_check functions depend upon an updated adjusted_mode.clock to - * e.g. properly compute watermarks. + * @drm_plane_helper_funcs.atomic_check and @drm_crtc_helper_funcs.atomic_check + * functions depend upon an updated adjusted_mode.clock to e.g. properly compute + * watermarks. * * RETURNS: * Zero for success or -errno @@ -1125,8 +1130,8 @@ EXPORT_SYMBOL(drm_atomic_helper_wait_for_vblanks); * drm_atomic_helper_commit_tail - commit atomic update to hardware * @old_state: atomic state object with old state structures * - * This is the default implemenation for the ->atomic_commit_tail() hook of the - * &drm_mode_config_helper_funcs vtable. + * This is the default implemenation for the + * &drm_mode_config_helper_funcs.atomic_commit_tail hook. * * Note that the default ordering of how the various stages are called is to * match the legacy modeset helper library closest. One peculiarity of that is @@ -1203,8 +1208,8 @@ static void commit_work(struct work_struct *work) * drm_atomic_helper_setup_commit() and related functions. * * Committing the actual hardware state is done through the - * ->atomic_commit_tail() callback of the &drm_mode_config_helper_funcs vtable, - * or it's default implementation drm_atomic_helper_commit_tail(). + * &drm_mode_config_helper_funcs.atomic_commit_tail callback, or it's default + * implementation drm_atomic_helper_commit_tail(). * * RETURNS: * Zero for success or -errno. @@ -1362,14 +1367,15 @@ static int stall_checks(struct drm_crtc *crtc, bool nonblock) * * This function prepares @state to be used by the atomic helper's support for * nonblocking commits. Drivers using the nonblocking commit infrastructure - * should always call this function from their ->atomic_commit hook. + * should always call this function from their + * &drm_mode_config_funcs.atomic_commit hook. * * To be able to use this support drivers need to use a few more helper * functions. drm_atomic_helper_wait_for_dependencies() must be called before * actually committing the hardware state, and for nonblocking commits this call * must be placed in the async worker. See also drm_atomic_helper_swap_state() * and it's stall parameter, for when a driver's commit hooks look at the - * ->state pointers of &struct drm_crtc, &drm_plane or &drm_connector directly. + * &drm_crtc.state, &drm_plane.state or &drm_connector.state pointer directly. * * Completion of the hardware commit step must be signalled using * drm_atomic_helper_commit_hw_done(). After this step the driver is not allowed @@ -1476,8 +1482,7 @@ static struct drm_crtc_commit *preceeding_commit(struct drm_crtc *crtc) * This function waits for all preceeding commits that touch the same CRTC as * @old_state to both be committed to the hardware (as signalled by * drm_atomic_helper_commit_hw_done) and executed by the hardware (as signalled - * by calling drm_crtc_vblank_send_event on the event member of - * &drm_crtc_state). + * by calling drm_crtc_vblank_send_event on the &drm_crtc_state.event). * * This is part of the atomic helper support for nonblocking commits, see * drm_atomic_helper_setup_commit() for an overview. @@ -1614,8 +1619,9 @@ EXPORT_SYMBOL(drm_atomic_helper_commit_cleanup_done); * @state: atomic state object with new state structures * * This function prepares plane state, specifically framebuffers, for the new - * configuration. If any failure is encountered this function will call - * ->cleanup_fb on any already successfully prepared framebuffer. + * configuration, by calling &drm_plane_helper_funcs.prepare_fb. If any failure + * is encountered this function will call &drm_plane_helper_funcs.cleanup_fb on + * any already successfully prepared framebuffer. * * Returns: * 0 on success, negative error code on failure. @@ -1695,10 +1701,10 @@ static bool plane_crtc_active(const struct drm_plane_state *state) * * Drivers may set the NO_DISABLE_AFTER_MODESET flag in @flags if the relevant * display controllers require to disable a CRTC's planes when the CRTC is - * disabled. This function would skip the ->atomic_disable call for a plane if - * the CRTC of the old plane state needs a modesetting operation. Of course, - * the drivers need to disable the planes in their CRTC disable callbacks - * since no one else would do that. + * disabled. This function would skip the &drm_plane_helper_funcs.atomic_disable + * call for a plane if the CRTC of the old plane state needs a modesetting + * operation. Of course, the drivers need to disable the planes in their CRTC + * disable callbacks since no one else would do that. * * The drm_atomic_helper_commit() default implementation doesn't set the * ACTIVE_ONLY flag to most closely match the behaviour of the legacy helpers. @@ -1861,7 +1867,7 @@ EXPORT_SYMBOL(drm_atomic_helper_commit_planes_on_crtc); * planes. * * It is a bug to call this function without having implemented the - * ->atomic_disable() plane hook. + * &drm_plane_helper_funcs.atomic_disable plane hook. */ void drm_atomic_helper_disable_planes_on_crtc(struct drm_crtc_state *old_crtc_state, @@ -1948,8 +1954,8 @@ EXPORT_SYMBOL(drm_atomic_helper_cleanup_planes); * contains the old state. Also do any other cleanup required with that state. * * @stall must be set when nonblocking commits for this driver directly access - * the ->state pointer of &drm_plane, &drm_crtc or &drm_connector. With the - * current atomic helpers this is almost always the case, since the helpers + * the &drm_plane.state, &drm_crtc.state or &drm_connector.state pointer. With + * the current atomic helpers this is almost always the case, since the helpers * don't pass the right state structures to the callbacks. */ void drm_atomic_helper_swap_state(struct drm_atomic_state *state, @@ -2788,8 +2794,8 @@ EXPORT_SYMBOL(drm_atomic_helper_page_flip); * * This is the main helper function provided by the atomic helper framework for * implementing the legacy DPMS connector interface. It computes the new desired - * ->active state for the corresponding CRTC (if the connector is enabled) and - * updates it. + * &drm_crtc_state.active state for the corresponding CRTC (if the connector is + * enabled) and updates it. * * Returns: * Returns 0 on success, negative errno numbers on failure. @@ -2861,11 +2867,11 @@ int drm_atomic_helper_connector_dpms(struct drm_connector *connector, EXPORT_SYMBOL(drm_atomic_helper_connector_dpms);

/** - * drm_atomic_helper_best_encoder - Helper for &drm_connector_helper_funcs - * ->best_encoder callback + * drm_atomic_helper_best_encoder - Helper for + * &drm_connector_helper_funcs.best_encoder callback * @connector: Connector control structure * - * This is a &drm_connector_helper_funcs ->best_encoder callback helper for + * This is a &drm_connector_helper_funcs.best_encoder callback helper for * connectors that support exactly 1 encoder, statically determined at driver * init time. */ @@ -2899,7 +2905,7 @@ EXPORT_SYMBOL(drm_atomic_helper_best_encoder); */

/** - * drm_atomic_helper_crtc_reset - default ->reset hook for CRTCs + * drm_atomic_helper_crtc_reset - default &drm_crtc_funcs.reset hook for CRTCs * @crtc: drm CRTC * * Resets the atomic state for @crtc by freeing the state pointer (which might @@ -3006,7 +3012,7 @@ void drm_atomic_helper_crtc_destroy_state(struct drm_crtc *crtc, EXPORT_SYMBOL(drm_atomic_helper_crtc_destroy_state);

/** - * drm_atomic_helper_plane_reset - default ->reset hook for planes + * drm_atomic_helper_plane_reset - default &drm_plane_funcs.reset hook for planes * @plane: drm plane * * Resets the atomic state for @plane by freeing the state pointer (which might @@ -3110,8 +3116,9 @@ EXPORT_SYMBOL(drm_atomic_helper_plane_destroy_state); * @conn_state: connector state to assign * * Initializes the newly allocated @conn_state and assigns it to - * #connector ->state, usually required when initializing the drivers - * or when called from the ->reset hook. + * the &drm_conector->state pointer of @connector, usually required when + * initializing the drivers or when called from the &drm_connector_funcs.reset + * hook. * * This is useful for drivers that subclass the connector state. */ @@ -3127,7 +3134,7 @@ __drm_atomic_helper_connector_reset(struct drm_connector *connector, EXPORT_SYMBOL(__drm_atomic_helper_connector_reset);

/** - * drm_atomic_helper_connector_reset - default ->reset hook for connectors + * drm_atomic_helper_connector_reset - default &drm_connector_funcs.reset hook for connectors * @connector: drm connector * * Resets the atomic state for @connector by freeing the state pointer (which diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c index 1e281dd42e4b..8c1e4d93a4f4 100644 --- a/drivers/gpu/drm/drm_crtc_helper.c +++ b/drivers/gpu/drm/drm_crtc_helper.c @@ -53,9 +53,9 @@ * configuration on resume with drm_helper_resume_force_mode(). * * Note that this helper library doesn't track the current power state of CRTCs - * and encoders. It can call callbacks like ->dpms() even though the hardware is - * already in the desired state. This deficiency has been fixed in the atomic - * helpers. + * and encoders. It can call callbacks like &drm_encoder_helper_funcs.dpms even + * though the hardware is already in the desired state. This deficiency has been + * fixed in the atomic helpers. * * The driver callbacks are mostly compatible with the atomic modeset helpers, * except for the handling of the primary plane: Atomic helpers require that the @@ -477,12 +477,12 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) * drm_crtc_helper_set_config - set a new config from userspace * @set: mode set configuration * - * The drm_crtc_helper_set_config() helper function implements the set_config - * callback of &struct drm_crtc_funcs for drivers using the legacy CRTC helpers. + * The drm_crtc_helper_set_config() helper function implements the of + * &drm_crtc_funcs.set_config callback for drivers using the legacy CRTC + * helpers. * * It first tries to locate the best encoder for each connector by calling the - * connector ->best_encoder() (&struct drm_connector_helper_funcs) helper - * operation. + * connector @drm_connector_helper_funcs.best_encoder helper operation. * * After locating the appropriate encoders, the helper function will call the * mode_fixup encoder and CRTC helper operations to adjust the requested mode, @@ -493,8 +493,7 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) * * If the adjusted mode is identical to the current mode but changes to the * frame buffer need to be applied, the drm_crtc_helper_set_config() function - * will call the CRTC ->mode_set_base() (&struct drm_crtc_helper_funcs) helper - * operation. + * will call the CRTC &drm_crtc_helper_funcs.mode_set_base helper operation. * * If the adjusted mode differs from the current mode, or if the * ->mode_set_base() helper operation is not provided, the helper function @@ -851,14 +850,15 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc) * @connector: affected connector * @mode: DPMS mode * - * The drm_helper_connector_dpms() helper function implements the ->dpms() - * callback of &struct drm_connector_funcs for drivers using the legacy CRTC helpers. + * The drm_helper_connector_dpms() helper function implements the + * &drm_connector_funcs.dpms() callback for drivers using the legacy CRTC + * helpers. * * This is the main helper function provided by the CRTC helper framework for * implementing the DPMS connector attribute. It computes the new desired DPMS - * state for all encoders and CRTCs in the output mesh and calls the ->dpms() - * callbacks provided by the driver in &struct drm_crtc_helper_funcs and struct - * &drm_encoder_helper_funcs appropriately. + * state for all encoders and CRTCs in the output mesh and calls the + * &drm_crtc_helper_funcs.dpms and &drm_encoder_helper_funcs.dpms callbacks + * provided by the driver. * * This function is deprecated. New drivers must implement atomic modeset * support, for which this function is unsuitable. Instead drivers should use diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c index 3e6fe82c6d64..68908c1d5ca1 100644 --- a/drivers/gpu/drm/drm_dp_helper.c +++ b/drivers/gpu/drm/drm_dp_helper.c @@ -725,7 +725,7 @@ MODULE_PARM_DESC(dp_aux_i2c_speed_khz, /* * Transfer a single I2C-over-AUX message and handle various error conditions, * retrying the transaction as appropriate. It is assumed that the - * aux->transfer function does not modify anything in the msg other than the + * &drm_dp_aux.transfer function does not modify anything in the msg other than the * reply field. * * Returns bytes transferred on success, or a negative error code on failure. diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c index 730342cbe899..ff965ac3a7e9 100644 --- a/drivers/gpu/drm/drm_fb_helper.c +++ b/drivers/gpu/drm/drm_fb_helper.c @@ -66,11 +66,11 @@ static DEFINE_MUTEX(kernel_fb_helper_lock); * Teardown is done with drm_fb_helper_fini(). * * At runtime drivers should restore the fbdev console by calling - * drm_fb_helper_restore_fbdev_mode_unlocked() from their ->lastclose callback. - * They should also notify the fb helper code from updates to the output - * configuration by calling drm_fb_helper_hotplug_event(). For easier + * drm_fb_helper_restore_fbdev_mode_unlocked() from their &drm_driver.lastclose + * callback. They should also notify the fb helper code from updates to the + * output configuration by calling drm_fb_helper_hotplug_event(). For easier * integration with the output polling code in drm_crtc_helper.c the modeset - * code provides a ->output_poll_changed callback. + * code provides a &drm_mode_config_funcs.output_poll_changed callback. * * All other functions exported by the fb helper library can be used to * implement the fbdev driver interface by the driver. @@ -79,7 +79,7 @@ static DEFINE_MUTEX(kernel_fb_helper_lock); * hotplug detection using the fbdev helpers. The drm_fb_helper_prepare() * helper must be called first to initialize the minimum required to make * hotplug detection work. Drivers also need to make sure to properly set up - * the dev->mode_config.funcs member. After calling drm_kms_helper_poll_init() + * the &drm_mode_config.funcs member. After calling drm_kms_helper_poll_init() * it is safe to enable interrupts and start processing hotplug events. At the * same time, drivers should initialize all modeset objects such as CRTCs, * encoders and connectors. To finish up the fbdev helper initialization, the @@ -88,9 +88,9 @@ static DEFINE_MUTEX(kernel_fb_helper_lock); * should call drm_fb_helper_single_add_all_connectors() followed by * drm_fb_helper_initial_config(). * - * If &drm_framebuffer_funcs ->dirty is set, the + * If &drm_framebuffer_funcs.dirty is set, the * drm_fb_helper_{cfb,sys}_{write,fillrect,copyarea,imageblit} functions will - * accumulate changes and schedule &drm_fb_helper ->dirty_work to run right + * accumulate changes and schedule &drm_fb_helper.dirty_work to run right * away. This worker then calls the dirty() function ensuring that it will * always run in process context since the fb_*() function could be running in * atomic context. If drm_fb_helper_deferred_io() is used as the deferred_io @@ -247,7 +247,7 @@ static void drm_fb_helper_restore_lut_atomic(struct drm_crtc *crtc) }

/** - * drm_fb_helper_debug_enter - implementation for ->fb_debug_enter + * drm_fb_helper_debug_enter - implementation for &fb_ops.fb_debug_enter * @info: fbdev registered by the helper */ int drm_fb_helper_debug_enter(struct fb_info *info) @@ -296,7 +296,7 @@ static struct drm_framebuffer *drm_mode_config_fb(struct drm_crtc *crtc) }

/** - * drm_fb_helper_debug_leave - implementation for ->fb_debug_leave + * drm_fb_helper_debug_leave - implementation for &fb_ops.fb_debug_leave * @info: fbdev registered by the helper */ int drm_fb_helper_debug_leave(struct fb_info *info) @@ -445,7 +445,7 @@ static int restore_fbdev_mode(struct drm_fb_helper *fb_helper) * drm_fb_helper_restore_fbdev_mode_unlocked - restore fbdev configuration * @fb_helper: fbcon to restore * - * This should be called from driver's drm ->lastclose callback + * This should be called from driver's drm &drm_driver.lastclose callback * when implementing an fbcon on top of kms using this helper. This ensures that * the user isn't greeted with a black screen when e.g. X dies. * @@ -585,7 +585,7 @@ static void drm_fb_helper_dpms(struct fb_info *info, int dpms_mode) }

/** - * drm_fb_helper_blank - implementation for ->fb_blank + * drm_fb_helper_blank - implementation for &fb_ops.fb_blank * @blank: desired blanking state * @info: fbdev registered by the helper */ @@ -912,7 +912,7 @@ static void drm_fb_helper_dirty(struct fb_info *info, u32 x, u32 y, * @info: fb_info struct pointer * @pagelist: list of dirty mmap framebuffer pages * - * This function is used as the &fb_deferred_io ->deferred_io + * This function is used as the &fb_deferred_io.deferred_io * callback function for flushing the fbdev mmap writes. */ void drm_fb_helper_deferred_io(struct fb_info *info, @@ -1103,7 +1103,7 @@ EXPORT_SYMBOL(drm_fb_helper_set_suspend); * due to all the printk activity. * * This function can be called multiple times with the same state since - * &fb_info->state is checked to see if fbdev is running or not before locking. + * &fb_info.state is checked to see if fbdev is running or not before locking. * * Use drm_fb_helper_set_suspend() if you need to take the lock yourself. */ @@ -1181,7 +1181,7 @@ static int setcolreg(struct drm_crtc *crtc, u16 red, u16 green, }

/** - * drm_fb_helper_setcmap - implementation for ->fb_setcmap + * drm_fb_helper_setcmap - implementation for &fb_ops.fb_setcmap * @cmap: cmap to set * @info: fbdev registered by the helper */ @@ -1238,7 +1238,7 @@ int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info) EXPORT_SYMBOL(drm_fb_helper_setcmap);

/** - * drm_fb_helper_check_var - implementation for ->fb_check_var + * drm_fb_helper_check_var - implementation for &fb_ops.fb_check_var * @var: screeninfo to check * @info: fbdev registered by the helper */ @@ -1338,7 +1338,7 @@ int drm_fb_helper_check_var(struct fb_var_screeninfo *var, EXPORT_SYMBOL(drm_fb_helper_check_var);

/** - * drm_fb_helper_set_par - implementation for ->fb_set_par + * drm_fb_helper_set_par - implementation for &fb_ops.fb_set_par * @info: fbdev registered by the helper * * This will let fbcon do the mode init and is called at initialization time by @@ -1422,7 +1422,7 @@ static int pan_display_atomic(struct fb_var_screeninfo *var, }

/** - * drm_fb_helper_pan_display - implementation for ->fb_pan_display + * drm_fb_helper_pan_display - implementation for &fb_ops.fb_pan_display * @var: updated screen information * @info: fbdev registered by the helper */ @@ -1607,7 +1607,7 @@ static int drm_fb_helper_single_fb_probe(struct drm_fb_helper *fb_helper, * additional constraints need to set up their own limits. * * Drivers should call this (or their equivalent setup code) from their - * ->fb_probe callback. + * &drm_fb_helper_funcs.fb_probe callback. */ void drm_fb_helper_fill_fix(struct fb_info *info, uint32_t pitch, uint32_t depth) @@ -1636,11 +1636,11 @@ EXPORT_SYMBOL(drm_fb_helper_fill_fix); * @fb_height: desired fb height * * Sets up the variable fbdev metainformation from the given fb helper instance - * and the drm framebuffer allocated in fb_helper->fb. + * and the drm framebuffer allocated in &drm_fb_helper.fb. * * Drivers should call this (or their equivalent setup code) from their - * ->fb_probe callback after having allocated the fbdev backing - * storage framebuffer. + * &drm_fb_helper_funcs.fb_probe callback after having allocated the fbdev + * backing storage framebuffer. */ void drm_fb_helper_fill_var(struct fb_info *info, struct drm_fb_helper *fb_helper, uint32_t fb_width, uint32_t fb_height) @@ -2208,9 +2208,9 @@ static void drm_setup_crtcs(struct drm_fb_helper *fb_helper, * Note that this also registers the fbdev and so allows userspace to call into * the driver through the fbdev interfaces. * - * This function will call down into the ->fb_probe callback to let - * the driver allocate and initialize the fbdev info structure and the drm - * framebuffer used to back the fbdev. drm_fb_helper_fill_var() and + * This function will call down into the &drm_fb_helper_funcs.fb_probe callback + * to let the driver allocate and initialize the fbdev info structure and the + * drm framebuffer used to back the fbdev. drm_fb_helper_fill_var() and * drm_fb_helper_fill_fix() are provided as helpers to setup simple default * values for the fbdev info structure. * diff --git a/drivers/gpu/drm/drm_plane_helper.c b/drivers/gpu/drm/drm_plane_helper.c index 35d43607a47d..148688fb920a 100644 --- a/drivers/gpu/drm/drm_plane_helper.c +++ b/drivers/gpu/drm/drm_plane_helper.c @@ -39,9 +39,9 @@ * * This helper library has two parts. The first part has support to implement * primary plane support on top of the normal CRTC configuration interface. - * Since the legacy ->set_config interface ties the primary plane together with - * the CRTC state this does not allow userspace to disable the primary plane - * itself. To avoid too much duplicated code use + * Since the legacy &drm_mode_config_funcs.set_config interface ties the primary + * plane together with the CRTC state this does not allow userspace to disable + * the primary plane itself. To avoid too much duplicated code use * drm_plane_helper_check_update() which can be used to enforce the same * restrictions as primary planes had thus. The default primary plane only * expose XRBG8888 and ARGB8888 as valid pixel formats for the attached @@ -384,7 +384,8 @@ EXPORT_SYMBOL(drm_primary_helper_update); * is called in response to a userspace SetPlane operation on the plane with a * NULL framebuffer parameter. It unconditionally fails the disable call with * -EINVAL the only way to disable the primary plane without driver support is - * to disable the entier CRTC. Which does not match the plane ->disable hook. + * to disable the entire CRTC. Which does not match the plane + * &drm_plane_funcs.disable_plane hook. * * Note that some hardware may be able to disable the primary plane without * disabling the whole CRTC. Drivers for such hardware should provide their diff --git a/drivers/gpu/drm/drm_probe_helper.c b/drivers/gpu/drm/drm_probe_helper.c index 97a32898ef50..060211ac74a1 100644 --- a/drivers/gpu/drm/drm_probe_helper.c +++ b/drivers/gpu/drm/drm_probe_helper.c @@ -43,7 +43,7 @@ * DOC: output probing helper overview * * This library provides some helper code for output probing. It provides an - * implementation of the core connector->fill_modes interface with + * implementation of the core &drm_connector_funcs.fill_modes interface with * drm_helper_probe_single_connector_modes. * * It also provides support for polling connectors with a work item and for @@ -174,9 +174,9 @@ drm_connector_detect(struct drm_connector *connector, bool force) * be added to the connector's probed_modes list, then culled (based on validity * and the @maxX, @maxY parameters) and put into the normal modes list. * - * Intended to be used as a generic implementation of the ->fill_modes() - * @connector vfunc for drivers that use the CRTC helpers for output mode - * filtering and detection. + * Intended to be used as a generic implementation of the + * &drm_connector_funcs.fill_modes() vfunc for drivers that use the CRTC helpers + * for output mode filtering and detection. * * The basic procedure is as follows * @@ -188,7 +188,7 @@ drm_connector_detect(struct drm_connector *connector, bool force) * * - debugfs 'override_edid' (used for testing only) * - firmware EDID (drm_load_edid_firmware()) - * - connector helper ->get_modes() vfunc + * - &drm_connector_helper_funcs.get_modes vfunc * - if the connector status is connector_status_connected, standard * VESA DMT modes up to 1024x768 are automatically added * (drm_add_modes_noedid()) @@ -209,8 +209,8 @@ drm_connector_detect(struct drm_connector *connector, bool force) * (if specified) * - drm_mode_validate_flag() checks the modes againt basic connector * capabilites (interlace_allowed,doublescan_allowed,stereo_allowed) - * - the optional connector ->mode_valid() helper can perform driver and/or - * hardware specific checks + * - the optional &drm_connector_helper_funcs.mode_valid helper can perform + * driver and/or hardware specific checks * * 5. Any mode whose status is not OK is pruned from the connector's modes list, * accompanied by a debug message indicating the reason for the mode's diff --git a/include/drm/drm_atomic_helper.h b/include/drm/drm_atomic_helper.h index 4b2353dc34ba..5a351258d5fe 100644 --- a/include/drm/drm_atomic_helper.h +++ b/include/drm/drm_atomic_helper.h @@ -171,7 +171,8 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc, * * This iterates over the current state, useful (for example) when applying * atomic state after it has been checked and swapped. To iterate over the - * planes which *will* be attached (for ->atomic_check()) see + * planes which *will* be attached (more useful in code called from + * &drm_mode_config_funcs.atomic_check) see * drm_atomic_crtc_state_for_each_plane(). */ #define drm_atomic_crtc_for_each_plane(plane, crtc) \ @@ -183,8 +184,9 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc, * @crtc_state: the incoming crtc-state * * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be - * attached if the specified state is applied. Useful during (for example) - * ->atomic_check() operations, to validate the incoming state. + * attached if the specified state is applied. Useful during for example + * in code called from &drm_mode_config_funcs.atomic_check operations, to + * validate the incoming state. */ #define drm_atomic_crtc_state_for_each_plane(plane, crtc_state) \ drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask) @@ -196,8 +198,9 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc, * @crtc_state: the incoming crtc-state * * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be - * attached if the specified state is applied. Useful during (for example) - * ->atomic_check() operations, to validate the incoming state. + * attached if the specified state is applied. Useful during for example + * in code called from &drm_mode_config_funcs.atomic_check operations, to + * validate the incoming state. * * Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a * const plane_state. This is useful when a driver just wants to peek at other diff --git a/include/drm/drm_dp_mst_helper.h b/include/drm/drm_dp_mst_helper.h index 003207670597..551f519d84a3 100644 --- a/include/drm/drm_dp_mst_helper.h +++ b/include/drm/drm_dp_mst_helper.h @@ -493,8 +493,8 @@ struct drm_dp_mst_topology_mgr { int total_pbn;

/** - * @qlock: protects @tx_msg_downq, the tx_slots in struct - * &drm_dp_mst_branch and txmsg->state once they are queued + * @qlock: protects @tx_msg_downq, the &drm_dp_mst_branch.txslost and + * &drm_dp_sideband_msg_tx.state once they are queued */ struct mutex qlock; /** @@ -508,8 +508,7 @@ struct drm_dp_mst_topology_mgr { struct mutex payload_lock; /** * @proposed_vcpis: Array of pointers for the new VCPI allocation. The - * VCPI structure itself is embedded into the corresponding - * &drm_dp_mst_port structure. + * VCPI structure itself is &drm_dp_mst_port.vcpi. */ struct drm_dp_vcpi **proposed_vcpis; /** diff --git a/include/drm/drm_flip_work.h b/include/drm/drm_flip_work.h index d387cf06ae05..21c3d512d25c 100644 --- a/include/drm/drm_flip_work.h +++ b/include/drm/drm_flip_work.h @@ -54,7 +54,7 @@ typedef void (*drm_flip_func_t)(struct drm_flip_work *work, void *val); /** * struct drm_flip_task - flip work task * @node: list entry element - * @data: data to pass to work->func + * @data: data to pass to &drm_flip_work.func */ struct drm_flip_task { struct list_head node; diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_modeset_helper_vtables.h index 46f5b349f059..091c42205667 100644 --- a/include/drm/drm_modeset_helper_vtables.h +++ b/include/drm/drm_modeset_helper_vtables.h @@ -111,9 +111,9 @@ struct drm_crtc_helper_funcs { * This callback is used to validate a mode. The parameter mode is the * display mode that userspace requested, adjusted_mode is the mode the * encoders need to be fed with. Note that this is the inverse semantics - * of the meaning for the &drm_encoder and &drm_bridge - * ->mode_fixup() functions. If the CRTC cannot support the requested - * conversion from mode to adjusted_mode it should reject the modeset. + * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup + * vfunc. If the CRTC cannot support the requested conversion from mode + * to adjusted_mode it should reject the modeset. * * This function is used by both legacy CRTC helpers and atomic helpers. * With atomic helpers it is optional. @@ -134,17 +134,18 @@ struct drm_crtc_helper_funcs { * * Also beware that neither core nor helpers filter modes before * passing them to the driver: While the list of modes that is - * advertised to userspace is filtered using the connector's - * ->mode_valid() callback, neither the core nor the helpers do any - * filtering on modes passed in from userspace when setting a mode. It - * is therefore possible for userspace to pass in a mode that was - * previously filtered out using ->mode_valid() or add a custom mode - * that wasn't probed from EDID or similar to begin with. Even though - * this is an advanced feature and rarely used nowadays, some users rely - * on being able to specify modes manually so drivers must be prepared - * to deal with it. Specifically this means that all drivers need not - * only validate modes in ->mode_valid() but also in ->mode_fixup() to - * make sure invalid modes passed in from userspace are rejected. + * advertised to userspace is filtered using the + * &drm_connector.mode_valid callback, neither the core nor the helpers + * do any filtering on modes passed in from userspace when setting a + * mode. It is therefore possible for userspace to pass in a mode that + * was previously filtered out using &drm_connector.mode_valid or add a + * custom mode that wasn't probed from EDID or similar to begin with. + * Even though this is an advanced feature and rarely used nowadays, + * some users rely on being able to specify modes manually so drivers + * must be prepared to deal with it. Specifically this means that all + * drivers need not only validate modes in &drm_connector.mode_valid but + * also in this or in the &drm_encoder_helper_funcs.mode_fixup callback + * to make sure invalid modes passed in from userspace are rejected. * * RETURNS: * @@ -205,7 +206,7 @@ struct drm_crtc_helper_funcs { * optimized fast-path instead of a full mode set operation with all the * resulting flickering. If it is not present * drm_crtc_helper_set_config() will fall back to a full modeset, using - * the ->mode_set() callback. Since it can't update other planes it's + * the @mode_set callback. Since it can't update other planes it's * incompatible with atomic modeset support. * * This callback is only used by the CRTC helpers and deprecated. @@ -238,8 +239,7 @@ struct drm_crtc_helper_funcs { /** * @load_lut: * - * Load a LUT prepared with the @gamma_set functions from - * &drm_fb_helper_funcs. + * Load a LUT prepared with the &drm_fb_helper_funcs.gamma_set vfunc. * * This callback is optional and is only used by the fbdev emulation * helpers. @@ -257,10 +257,11 @@ struct drm_crtc_helper_funcs { * * This callback should be used to disable the CRTC. With the atomic * drivers it is called after all encoders connected to this CRTC have - * been shut off already using their own ->disable hook. If that - * sequence is too simple drivers can just add their own hooks and call - * it from this CRTC callback here by looping over all encoders - * connected to it using for_each_encoder_on_crtc(). + * been shut off already using their own + * &drm_encoder_helper_funcs.disable hook. If that sequence is too + * simple drivers can just add their own hooks and call it from this + * CRTC callback here by looping over all encoders connected to it using + * for_each_encoder_on_crtc(). * * This hook is used both by legacy CRTC helpers and atomic helpers. * Atomic drivers don't need to implement it if there's no need to @@ -289,10 +290,10 @@ struct drm_crtc_helper_funcs { * * This callback should be used to enable the CRTC. With the atomic * drivers it is called before all encoders connected to this CRTC are - * enabled through the encoder's own ->enable hook. If that sequence is - * too simple drivers can just add their own hooks and call it from this - * CRTC callback here by looping over all encoders connected to it using - * for_each_encoder_on_crtc(). + * enabled through the encoder's own &drm_encoder_helper_funcs.enable + * hook. If that sequence is too simple drivers can just add their own + * hooks and call it from this CRTC callback here by looping over all + * encoders connected to it using for_each_encoder_on_crtc(). * * This hook is used only by atomic helpers, for symmetry with @disable. * Atomic drivers don't need to implement it if there's no need to @@ -316,16 +317,16 @@ struct drm_crtc_helper_funcs { * beforehand. This is calling order used by the default helper * implementation in drm_atomic_helper_check(). * - * When using drm_atomic_helper_check_planes() CRTCs' ->atomic_check() - * hooks are called after the ones for planes, which allows drivers to - * assign shared resources requested by planes in the CRTC callback - * here. For more complicated dependencies the driver can call the provided - * check helpers multiple times until the computed state has a final - * configuration and everything has been checked. + * When using drm_atomic_helper_check_planes() this hook is called + * after the &drm_plane_helper_funcs.atomc_check hook for planes, which + * allows drivers to assign shared resources requested by planes in this + * callback here. For more complicated dependencies the driver can call + * the provided check helpers multiple times until the computed state + * has a final configuration and everything has been checked. * * This function is also allowed to inspect any other object's state and * can add more state objects to the atomic commit if needed. Care must - * be taken though to ensure that state check&compute functions for + * be taken though to ensure that state check and compute functions for * these added states are all called, and derived state in other objects * all updated. Again the recommendation is to just call check helpers * until a maximal configuration is reached. @@ -400,10 +401,11 @@ struct drm_crtc_helper_funcs { * * This callback should be used to disable the CRTC. With the atomic * drivers it is called after all encoders connected to this CRTC have - * been shut off already using their own ->disable hook. If that - * sequence is too simple drivers can just add their own hooks and call - * it from this CRTC callback here by looping over all encoders - * connected to it using for_each_encoder_on_crtc(). + * been shut off already using their own + * &drm_encoder_helper_funcs.disable hook. If that sequence is too + * simple drivers can just add their own hooks and call it from this + * CRTC callback here by looping over all encoders connected to it using + * for_each_encoder_on_crtc(). * * This hook is used only by atomic helpers. Atomic drivers don't * need to implement it if there's no need to disable anything at the @@ -483,16 +485,18 @@ struct drm_encoder_helper_funcs { * Also beware that neither core nor helpers filter modes before * passing them to the driver: While the list of modes that is * advertised to userspace is filtered using the connector's - * ->mode_valid() callback, neither the core nor the helpers do any - * filtering on modes passed in from userspace when setting a mode. It - * is therefore possible for userspace to pass in a mode that was - * previously filtered out using ->mode_valid() or add a custom mode - * that wasn't probed from EDID or similar to begin with. Even though - * this is an advanced feature and rarely used nowadays, some users rely - * on being able to specify modes manually so drivers must be prepared - * to deal with it. Specifically this means that all drivers need not - * only validate modes in ->mode_valid() but also in ->mode_fixup() to - * make sure invalid modes passed in from userspace are rejected. + * &drm_connector_helper_funcs.mode_valid callback, neither the core nor + * the helpers do any filtering on modes passed in from userspace when + * setting a mode. It is therefore possible for userspace to pass in a + * mode that was previously filtered out using + * &drm_connector_helper_funcs.mode_valid or add a custom mode that + * wasn't probed from EDID or similar to begin with. Even though this + * is an advanced feature and rarely used nowadays, some users rely on + * being able to specify modes manually so drivers must be prepared to + * deal with it. Specifically this means that all drivers need not only + * validate modes in &drm_connector.mode_valid but also in this or in + * the &drm_crtc_helper_funcs.mode_fixup callback to make sure + * invalid modes passed in from userspace are rejected. * * RETURNS: * @@ -544,7 +548,7 @@ struct drm_encoder_helper_funcs { * use this hook, because the helper library calls it only once and not * every time the display pipeline is suspend using either DPMS or the * new "ACTIVE" property. Such drivers should instead move all their - * encoder setup into the ->enable() callback. + * encoder setup into the @enable callback. * * This callback is used both by the legacy CRTC helpers and the atomic * modeset helpers. It is optional in the atomic helpers. @@ -570,7 +574,7 @@ struct drm_encoder_helper_funcs { * use this hook, because the helper library calls it only once and not * every time the display pipeline is suspended using either DPMS or the * new "ACTIVE" property. Such drivers should instead move all their - * encoder setup into the ->enable() callback. + * encoder setup into the @enable callback. * * This callback is used by the atomic modeset helpers in place of the * @mode_set callback, if set by the driver. It is optional and should @@ -621,10 +625,10 @@ struct drm_encoder_helper_funcs { * * This callback should be used to disable the encoder. With the atomic * drivers it is called before this encoder's CRTC has been shut off - * using the CRTC's own ->disable hook. If that sequence is too simple - * drivers can just add their own driver private encoder hooks and call - * them from CRTC's callback by looping over all encoders connected to - * it using for_each_encoder_on_crtc(). + * using their own &drm_crtc_helper_funcs.disable hook. If that + * sequence is too simple drivers can just add their own driver private + * encoder hooks and call them from CRTC's callback by looping over all + * encoders connected to it using for_each_encoder_on_crtc(). * * This hook is used both by legacy CRTC helpers and atomic helpers. * Atomic drivers don't need to implement it if there's no need to @@ -651,10 +655,10 @@ struct drm_encoder_helper_funcs { * * This callback should be used to enable the encoder. With the atomic * drivers it is called after this encoder's CRTC has been enabled using - * the CRTC's own ->enable hook. If that sequence is too simple drivers - * can just add their own driver private encoder hooks and call them - * from CRTC's callback by looping over all encoders connected to it - * using for_each_encoder_on_crtc(). + * their own &drm_crtc_helper_funcs.enable hook. If that sequence is + * too simple drivers can just add their own driver private encoder + * hooks and call them from CRTC's callback by looping over all encoders + * connected to it using for_each_encoder_on_crtc(). * * This hook is used only by atomic helpers, for symmetry with @disable. * Atomic drivers don't need to implement it if there's no need to @@ -716,7 +720,7 @@ struct drm_connector_helper_funcs { * @get_modes: * * This function should fill in all modes currently valid for the sink - * into the connector->probed_modes list. It should also update the + * into the &drm_connector.probed_modes list. It should also update the * EDID property by calling drm_mode_connector_update_edid_property(). * * The usual way to implement this is to cache the EDID retrieved in the @@ -725,8 +729,9 @@ struct drm_connector_helper_funcs { * them by calling drm_add_edid_modes(). But connectors that driver a * fixed panel can also manually add specific modes using * drm_mode_probed_add(). Drivers which manually add modes should also - * make sure that the @display_info, @width_mm and @height_mm fields of the - * &struct drm_connector are filled in. + * make sure that the &drm_connector.display_info, + * &drm_connector.width_mm and &drm_connector.height_mm fields are + * filled in. * * Virtual drivers that just want some standard VESA mode with a given * resolution can call drm_add_modes_noedid(), and mark the preferred @@ -735,7 +740,7 @@ struct drm_connector_helper_funcs { * Finally drivers that support audio probably want to update the ELD * data, too, using drm_edid_to_eld(). * - * This function is only called after the ->detect() hook has indicated + * This function is only called after the @detect hook has indicated * that a sink is connected and when the EDID isn't overridden through * sysfs or the kernel commandline. * @@ -768,8 +773,8 @@ struct drm_connector_helper_funcs { * * RETURNS: * - * Either MODE_OK or one of the failure reasons in enum - * &drm_mode_status. + * Either &drm_mode_status.MODE_OK or one of the failure reasons in &enum + * drm_mode_status. */ enum drm_mode_status (*mode_valid)(struct drm_connector *connector, struct drm_display_mode *mode); @@ -875,7 +880,7 @@ struct drm_plane_helper_funcs { * RETURNS: * * 0 on success or one of the following negative error codes allowed by - * the atomic_commit hook in &drm_mode_config_funcs. When using helpers + * the &drm_mode_config_funcs.atomic_commit vfunc. When using helpers * this callback is the only one which can fail an atomic commit, * everything else must complete successfully. */ @@ -898,7 +903,7 @@ struct drm_plane_helper_funcs { * * Drivers should check plane specific constraints in this hook. * - * When using drm_atomic_helper_check_planes() plane's ->atomic_check() + * When using drm_atomic_helper_check_planes() plane's @atomic_check * hooks are called before the ones for CRTCs, which allows drivers to * request shared resources that the CRTC controls here. For more * complicated dependencies the driver can call the provided check helpers @@ -907,7 +912,7 @@ struct drm_plane_helper_funcs { * * This function is also allowed to inspect any other object's state and * can add more state objects to the atomic commit if needed. Care must - * be taken though to ensure that state check&compute functions for + * be taken though to ensure that state check and compute functions for * these added states are all called, and derived state in other objects * all updated. Again the recommendation is to just call check helpers * until a maximal configuration is reached. @@ -936,8 +941,8 @@ struct drm_plane_helper_funcs { * @atomic_update: * * Drivers should use this function to update the plane state. This - * hook is called in-between the ->atomic_begin() and - * ->atomic_flush() of &drm_crtc_helper_funcs. + * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and + * drm_crtc_helper_funcs.atomic_flush callbacks. * * Note that the power state of the display pipe when this function is * called depends upon the exact helpers and calling sequence the driver @@ -953,14 +958,15 @@ struct drm_plane_helper_funcs { * @atomic_disable: * * Drivers should use this function to unconditionally disable a plane. - * This hook is called in-between the ->atomic_begin() and - * ->atomic_flush() of &drm_crtc_helper_funcs. It is an alternative to + * This hook is called in-between the + * &drm_crtc_helper_funcs.atomic_begin and + * drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to * @atomic_update, which will be called for disabling planes, too, if * the @atomic_disable hook isn't implemented. * * This hook is also useful to disable planes in preparation of a modeset, * by calling drm_atomic_helper_disable_planes_on_crtc() from the - * ->disable() hook in &drm_crtc_helper_funcs. + * &drm_crtc_helper_funcs.disable hook. * * Note that the power state of the display pipe when this function is * called depends upon the exact helpers and calling sequence the driver diff --git a/include/drm/drm_simple_kms_helper.h b/include/drm/drm_simple_kms_helper.h index fe8c4ba905ac..ad8cb5ff460a 100644 --- a/include/drm/drm_simple_kms_helper.h +++ b/include/drm/drm_simple_kms_helper.h @@ -73,9 +73,9 @@ struct drm_simple_display_pipe_funcs { /** * @prepare_fb: * - * Optional, called by &struct drm_plane_helper_funcs ->prepare_fb . - * Please read the documentation for the ->prepare_fb hook in - * &struct drm_plane_helper_funcs for more details. + * Optional, called by &drm_plane_helper_funcs.prepare_fb. Please read + * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for + * more details. */ int (*prepare_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state); @@ -83,9 +83,9 @@ struct drm_simple_display_pipe_funcs { /** * @cleanup_fb: * - * Optional, called by &struct drm_plane_helper_funcs ->cleanup_fb . - * Please read the documentation for the ->cleanup_fb hook in - * &struct drm_plane_helper_funcs for more details. + * Optional, called by &drm_plane_helper_funcs.cleanup_fb. Please read + * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for + * more details. */ void (*cleanup_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state);

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 ...

Cc: Laurent Pinchart Laurent.pinchart@ideasonboard.com Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Chris Wilson chris@chris-wilson.co.uk Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_fb_cma_helper.c | 24 ++++++++++++------------ drivers/gpu/drm/drm_gem_cma_helper.c | 16 ++++++++-------- 2 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c index ec081727cd5a..0a0ac77b464b 100644 --- a/drivers/gpu/drm/drm_fb_cma_helper.c +++ b/drivers/gpu/drm/drm_fb_cma_helper.c @@ -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 @@ -491,7 +491,7 @@ static const struct drm_fb_helper_funcs drm_fb_cma_helper_funcs = { * @preferred_bpp: Preferred bits per pixel for the device * @num_crtc: Number of CRTCs * @max_conn_count: Maximum number of connectors - * @funcs: fb helper functions, in particular fb_probe() + * @funcs: fb helper functions, in particular a custom dirty() callback * * Returns a newly allocated drm_fbdev_cma struct or a ERR_PTR. */ diff --git a/drivers/gpu/drm/drm_gem_cma_helper.c b/drivers/gpu/drm/drm_gem_cma_helper.c index 1d6c335584ec..6ec2d8096b2c 100644 --- a/drivers/gpu/drm/drm_gem_cma_helper.c +++ b/drivers/gpu/drm/drm_gem_cma_helper.c @@ -177,7 +177,7 @@ 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. + * &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 the &drm_driver.dumb_create callback in a DRM driver. * * 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's &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's &drm_driver.gem_prime_get_sg_table callback. * * Returns: * A pointer to the scatter/gather table of pinned pages or NULL on failure. @@ -430,7 +430,7 @@ EXPORT_SYMBOL_GPL(drm_gem_cma_prime_get_sg_table); * 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. + * &drm_driver.gem_prime_import_sg_table callback. * * Returns: * A pointer to a newly created GEM object or an ERR_PTR-encoded negative @@ -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's &drm_driver.gem_prime_vunmap callback. */ void drm_gem_cma_prime_vunmap(struct drm_gem_object *obj, void *vaddr) {

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 ...

Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Chris Wilson chris@chris-wilson.co.uk Signed-off-by: Daniel Vetter daniel.vetter@intel.com --- drivers/gpu/drm/drm_gem.c | 24 ++++++++++++------------ drivers/gpu/drm/drm_mm.c | 4 ++-- drivers/gpu/drm/drm_prime.c | 2 +- include/drm/drm_gem.h | 16 ++++++++-------- 4 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c index 465bacd0a630..bc93de308673 100644 --- a/drivers/gpu/drm/drm_gem.c +++ b/drivers/gpu/drm/drm_gem.c @@ -316,8 +316,8 @@ EXPORT_SYMBOL(drm_gem_handle_delete); * @dev: corresponding drm_device * @handle: the dumb handle to remove * - * This implements the ->dumb_destroy kms driver callback for drivers which use - * gem to manage their backing storage. + * This implements the &drm_driver.dumb_destroy kms driver callback for drivers + * which use gem to manage their backing storage. */ int drm_gem_dumb_destroy(struct drm_file *file, struct drm_device *dev, @@ -333,9 +333,9 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy); * @obj: object to register * @handlep: pointer to return the created handle to the caller * - * This expects the dev->object_name_lock to be held already and will drop it - * before returning. Used to avoid races in establishing new handles when - * importing an object from either an flink name or a dma-buf. + * This expects the &drm_device.object_name_lock to be held already and will + * drop it before returning. Used to avoid races in establishing new handles + * when importing an object from either an flink name or a dma-buf. * * Handles must be release again through drm_gem_handle_delete(). This is done * when userspace closes @file_priv for all attached handles, or through the @@ -447,8 +447,8 @@ EXPORT_SYMBOL(drm_gem_free_mmap_offset); * structures. * * This routine allocates and attaches a fake offset for @obj, in cases where - * the virtual size differs from the physical size (ie. obj->size). Otherwise - * just use drm_gem_create_mmap_offset(). + * the virtual size differs from the physical size (ie. &drm_gem_object.size). + * Otherwise just use drm_gem_create_mmap_offset(). * * This function is idempotent and handles an already allocated mmap offset * transparently. Drivers do not need to check for this case. @@ -787,7 +787,7 @@ EXPORT_SYMBOL(drm_gem_object_release); * @kref: kref of the object to free * * Called after the last reference to the object has been lost. - * Must be called holding &drm_device->struct_mutex. + * Must be called holding &drm_device.struct_mutex. * * Frees the object */ @@ -813,7 +813,7 @@ EXPORT_SYMBOL(drm_gem_object_free); * @obj: GEM buffer object * * This releases a reference to @obj. Callers must not hold the - * dev->struct_mutex lock when calling this function. + * &drm_device.struct_mutex lock when calling this function. * * See also __drm_gem_object_unreference(). */ @@ -840,9 +840,9 @@ EXPORT_SYMBOL(drm_gem_object_unreference_unlocked); * drm_gem_object_unreference - release a GEM BO reference * @obj: GEM buffer object * - * This releases a reference to @obj. Callers must hold the dev->struct_mutex - * lock when calling this function, even when the driver doesn't use - * dev->struct_mutex for anything. + * This releases a reference to @obj. Callers must hold the + * &drm_device.struct_mutex lock when calling this function, even when the + * driver doesn't use &drm_device.struct_mutex for anything. * * For drivers not encumbered with legacy locking use * drm_gem_object_unreference_unlocked() instead. diff --git a/drivers/gpu/drm/drm_mm.c b/drivers/gpu/drm/drm_mm.c index 229b3f525dee..e51876e588d6 100644 --- a/drivers/gpu/drm/drm_mm.c +++ b/drivers/gpu/drm/drm_mm.c @@ -552,8 +552,8 @@ EXPORT_SYMBOL(drm_mm_replace_node); * objects to the roster, probably by walking an LRU list, but this can be * freely implemented. Eviction candiates are added using * drm_mm_scan_add_block() until a suitable hole is found or there are no - * further evictable objects. Eviction roster metadata is tracked in struct - * &drm_mm_scan. + * further evictable objects. Eviction roster metadata is tracked in &struct + * drm_mm_scan. * * The driver must walk through all objects again in exactly the reverse * order to restore the allocator state. Note that while the allocator is used diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c index 8d77b2462594..485e558d6661 100644 --- a/drivers/gpu/drm/drm_prime.c +++ b/drivers/gpu/drm/drm_prime.c @@ -291,7 +291,7 @@ static void drm_gem_unmap_dma_buf(struct dma_buf_attachment *attach, * This wraps dma_buf_export() for use by generic GEM drivers that are using * drm_gem_dmabuf_release(). In addition to calling dma_buf_export(), we take * a reference to the &drm_device and the exported &drm_gem_object (stored in - * exp_info->priv) which is released by drm_gem_dmabuf_release(). + * &dma_buf_export_info.priv) which is released by drm_gem_dmabuf_release(). * * Returns the new dmabuf. */ diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h index 9f63736e6163..449a41b56ffc 100644 --- a/include/drm/drm_gem.h +++ b/include/drm/drm_gem.h @@ -63,7 +63,7 @@ struct drm_gem_object { * drops to 0 any global names (e.g. the id in the flink namespace) will * be cleared. * - * Protected by dev->object_name_lock. + * Protected by &drm_device.object_name_lock. */ unsigned handle_count;

@@ -106,8 +106,8 @@ struct drm_gem_object { * @name: * * Global name for this object, starts at 1. 0 means unnamed. - * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK - * and GEM_OPEN ioctls. + * Access is covered by &drm_device.object_name_lock. This is used by + * the GEM_FLINK and GEM_OPEN ioctls. */ int name;

@@ -150,7 +150,7 @@ struct drm_gem_object { * through importing or exporting). We break the resulting reference * loop when the last gem handle for this object is released. * - * Protected by obj->object_name_lock. + * Protected by &drm_device.object_name_lock. */ struct dma_buf *dma_buf;

@@ -163,7 +163,7 @@ struct drm_gem_object { * attachment point for the device. This is invariant over the lifetime * of a gem object. * - * The driver's ->gem_free_object callback is responsible for cleaning + * The &drm_driver.gem_free_object callback is responsible for cleaning * up the dma_buf attachment and references acquired at import time. * * Note that the drm gem/prime core does not depend upon drivers setting @@ -204,7 +204,7 @@ drm_gem_object_reference(struct drm_gem_object *obj) * @obj: GEM buffer object * * This function is meant to be used by drivers which are not encumbered with - * dev->struct_mutex legacy locking and which are using the + * &drm_device.struct_mutex legacy locking and which are using the * gem_free_object_unlocked callback. It avoids all the locking checks and * locking overhead of drm_gem_object_unreference() and * drm_gem_object_unreference_unlocked(). @@ -212,8 +212,8 @@ drm_gem_object_reference(struct drm_gem_object *obj) * Drivers should never call this directly in their code. Instead they should * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object * *obj)`` wrapper function, and use that. Shared code should never call this, to - * avoid breaking drivers by accident which still depend upon dev->struct_mutex - * locking. + * avoid breaking drivers by accident which still depend upon + * &drm_device.struct_mutex locking. */ static inline void __drm_gem_object_unreference(struct drm_gem_object *obj)

Hi

On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter daniel.vetter@ffwll.ch wrote:

• Remove the outdated hunk about driver documentation which somehow got misplaced here in the split-up.

• Collect all the testing&validation stuff together and give the CRC section a heading for prettier output.

Cc: Tomeu Vizoso tomeu.vizoso@collabora.com Cc: Jani Nikula jani.nikula@intel.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com

---

Documentation/gpu/drm-uapi.rst | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-)

Reviewed-by: David Herrmann dh.herrmann@gmail.com

Thanks David

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index de3ac9f90f8f..fcc228ef5bc4 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -156,8 +156,12 @@ other hand, a driver requires shared state between clients which is visible to user-space and accessible beyond open-file boundaries, they cannot support render nodes.

+Testing and validation +======================

Validating changes with IGT

+---------------------------

There's a collection of tests that aims to cover the whole functionality of DRM drivers and that can be used to check that changes to DRM drivers or the @@ -193,6 +197,12 @@ run-tests.sh is a wrapper around piglit that will execute the tests matching the -t options. A report in HTML format will be available in ./results/html/index.html. Results can be compared with piglit.

+Display CRC Support +-------------------

+.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c

• :doc: CRC ABI

VBlank event handling

@@ -209,16 +219,3 @@ DRM_IOCTL_MODESET_CTL mode setting, since on many devices the vertical blank counter is reset to 0 at some point during modeset. Modern drivers should not call this any more since with kernel mode setting it is a no-op.

-This second part of the GPU Driver Developer's Guide documents driver -code, implementation details and also all the driver-specific userspace -interfaces. Especially since all hardware-acceleration interfaces to -userspace are driver specific for efficiency and other reasons these -interfaces can be rather substantial. Hence every driver has its own -chapter.

-Testing and validation

-.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c

• :doc: CRC ABI

-- 2.7.4

---

dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel