[PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst

[PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst

[Daniel Vetter]

- 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(-)

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

[PATCH 02/17] drm/doc: link style-guide to doc-guide

[Daniel Vetter]

Our style guide should only be the delta compared to the overall one.

Cc: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/gpu/introduction.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
index 1903595b5310..6960e31f71e1 100644
--- a/Documentation/gpu/introduction.rst
+++ b/Documentation/gpu/introduction.rst
@@ -49,3 +49,5 @@ section name should be all upper-case or not, and whether it should end
 in a colon or not. Go with the file-local style. Other common section
 names are "Notes" with information for dangerous or tricky corner cases,
 and "FIXME" where the interface could be cleaned up.
+
+Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
-- 
2.7.4

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

[PATCH 03/17] drm/mm: Some doc polish

[Daniel Vetter]

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

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc

[Daniel Vetter]

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)	\
-- 
2.7.4

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

[PATCH 05/17] dma-buf: Use recommended structure member reference

[Daniel Vetter]

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

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 | 5 ++---
 include/linux/dma-buf.h   | 6 +++---
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c
index ab814aff0a5b..718f832a5c71 100644
--- a/drivers/dma-buf/dma-buf.c
+++ b/drivers/dma-buf/dma-buf.c
@@ -516,9 +516,8 @@ EXPORT_SYMBOL_GPL(dma_buf_get);
  * Uses file's refcounting done implicitly by fput().
  *
  * 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
- * exported.
+ * operation related to this fd is called. It calls &dma_buf_ops.release vfunc
+ * 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 4d61fc55278b..bfb3704fc6fc 100644
--- a/include/linux/dma-buf.h
+++ b/include/linux/dma-buf.h
@@ -66,8 +66,8 @@ struct dma_buf_ops {
 	 * is not the case, and the allocation cannot be moved, it should also
 	 * fail the attach operation.
 	 *
-	 * Any exporter-private housekeeping data can be stored in the priv
-	 * pointer of &dma_buf_attachment structure.
+	 * Any exporter-private housekeeping data can be stored in the
+	 * &dma_buf_attachment.priv pointer.
 	 *
 	 * This callback is optional.
 	 *
@@ -106,7 +106,7 @@ struct dma_buf_ops {
 	 *
 	 * Note that any specific buffer attributes required for this function
 	 * should get added to device_dma_parameters accessible via
-	 * device->dma_params from the &dma_buf_attachment. The @attach callback
+	 * &device.dma_params from the &dma_buf_attachment. The @attach callback
 	 * should also check these constraints.
 	 *
 	 * If this is being called for the first time, the exporter can now
-- 
2.7.4

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

[PATCH 06/17] drm/doc: use preferred struct reference in kernel-doc

[Daniel Vetter]

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);
-- 
2.7.4

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

[PATCH 07/17] drm: Nuke connector_list locking assert

[Daniel Vetter]

I've forgotten to remove this when revamping the
connector_list locking.

Cc: seanpaul@chromium.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 include/drm/drm_connector.h |  6 +-----
 include/drm/drm_crtc.h      | 14 --------------
 2 files changed, 1 insertion(+), 19 deletions(-)

diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index acb4241bff7d..d489cc003b7e 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -875,11 +875,7 @@ void drm_mode_put_tile_group(struct drm_device *dev,
  * deprecated. Use drm_for_each_connector_iter() instead.
  */
 #define drm_for_each_connector(connector, dev) \
-	for (assert_drm_connector_list_read_locked(&(dev)->mode_config),	\
-	     connector = list_first_entry(&(dev)->mode_config.connector_list,	\
-					  struct drm_connector, head);		\
-	     &connector->head != (&(dev)->mode_config.connector_list);		\
-	     connector = list_next_entry(connector, head))
+	list_for_each_entry(connector, &(dev)->mode_config.connector_list, head)
 
 /**
  * struct drm_connector_list_iter - connector_list iterator
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 0b9ec7245c7e..c0817fa205d4 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -835,18 +835,4 @@ static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
 #define drm_for_each_crtc(crtc, dev) \
 	list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)
 
-static inline void
-assert_drm_connector_list_read_locked(struct drm_mode_config *mode_config)
-{
-	/*
-	 * The connector hotadd/remove code currently grabs both locks when
-	 * updating lists. Hence readers need only hold either of them to be
-	 * safe and the check amounts to
-	 *
-	 * WARN_ON(not_holding(A) && not_holding(B)).
-	 */
-	WARN_ON(!mutex_is_locked(&mode_config->mutex) &&
-		!drm_modeset_is_locked(&mode_config->connection_mutex));
-}
-
 #endif /* __DRM_CRTC_H__ */
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 08/17] drm/doc: Update styleguide

[Daniel Vetter]

The new cool is &struct foo (kernel-doc now copes with linebreaks),
and structure members should be referenced using &foo.bar.

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/gpu/introduction.rst | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
index 6960e31f71e1..eb284eb748ba 100644
--- a/Documentation/gpu/introduction.rst
+++ b/Documentation/gpu/introduction.rst
@@ -23,13 +23,12 @@ For consistency this documentation uses American English. Abbreviations
 are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
 on. To aid in reading, documentations make full use of the markup
 characters kerneldoc provides: @parameter for function parameters,
-@member for structure members, &structure to reference structures and
-function() for functions. These all get automatically hyperlinked if
-kerneldoc for the referenced objects exists. When referencing entries in
-function vtables please use ->vfunc(). Note that kerneldoc does not
-support referencing struct members directly, so please add a reference
-to the vtable struct somewhere in the same paragraph or at least
-section.
+@member for structure members (within the same structure), &struct structure to
+reference structures and function() for functions. These all get automatically
+hyperlinked if kerneldoc for the referenced objects exists. When referencing
+entries in function vtables (and structure members in general) please use
+&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the
+member, only the structure.
 
 Except in special situations (to separate locked from unlocked variants)
 locking requirements for functions aren't documented in the kerneldoc.
-- 
2.7.4

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

[PATCH 09/17] drm/rect: Fix formatting of example code

[Daniel Vetter]

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.
  */
-- 
2.7.4

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

[PATCH 10/17] drm/atomic-helpers: Remove outdated comment

[Daniel Vetter]

We forgot to clean this up when adding connector refcounting.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/drm_atomic_helper.c | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c
index 8eab8944c736..5e5224460042 100644
--- a/drivers/gpu/drm/drm_atomic_helper.c
+++ b/drivers/gpu/drm/drm_atomic_helper.c
@@ -3286,11 +3286,6 @@ EXPORT_SYMBOL(drm_atomic_helper_duplicate_state);
 void
 __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
 {
-	/*
-	 * This is currently a placeholder so that drivers that subclass the
-	 * state will automatically do the right thing if code is ever added
-	 * to this function.
-	 */
 	if (state->crtc)
 		drm_connector_unreference(state->connector);
 }
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks

[Daniel Vetter]

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,
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 12/17] drm/kms-helpers: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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);
-- 
2.7.4

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

[PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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: Archit Taneja <architt@codeaurora.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/gpu/drm/drm_bridge.c | 27 +++++++++++--------------
 include/drm/drm_bridge.h     | 48 +++++++++++++++++++++++++-------------------
 2 files changed, 39 insertions(+), 36 deletions(-)

diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
index ae5e57ad718c..86a7637ba344 100644
--- a/drivers/gpu/drm/drm_bridge.c
+++ b/drivers/gpu/drm/drm_bridge.c
@@ -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 &drm_bridge.next pointer.
  *
  * Both legacy CRTC helpers and the new atomic modeset helpers support bridges.
  */
@@ -179,7 +179,7 @@ void drm_bridge_detach(struct drm_bridge *bridge)
  * @mode: desired mode to be set for the bridge
  * @adjusted_mode: updated mode that works for this bridge
  *
- * Calls ->mode_fixup() &drm_bridge_funcs op for all the bridges in the
+ * Calls &drm_bridge_funcs.mode_fixup for all the bridges in the
  * encoder chain, starting from the first bridge to the last.
  *
  * Note: the bridge passed should be the one closest to the encoder
@@ -206,11 +206,10 @@ bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
 EXPORT_SYMBOL(drm_bridge_mode_fixup);
 
 /**
- * drm_bridge_disable - calls ->disable() &drm_bridge_funcs op for all
- *			bridges in the encoder chain.
+ * drm_bridge_disable - disables all bridges in the encoder chain
  * @bridge: bridge control structure
  *
- * Calls ->disable() &drm_bridge_funcs op for all the bridges in the encoder
+ * Calls &drm_bridge_funcs.disable op for all the bridges in the encoder
  * chain, starting from the last bridge to the first. These are called before
  * calling the encoder's prepare op.
  *
@@ -229,11 +228,10 @@ void drm_bridge_disable(struct drm_bridge *bridge)
 EXPORT_SYMBOL(drm_bridge_disable);
 
 /**
- * drm_bridge_post_disable - calls ->post_disable() &drm_bridge_funcs op for
- *			     all bridges in the encoder chain.
+ * drm_bridge_post_disable - cleans up after disabling all bridges in the encoder chain
  * @bridge: bridge control structure
  *
- * Calls ->post_disable() &drm_bridge_funcs op for all the bridges in the
+ * Calls &drm_bridge_funcs.post_disable op for all the bridges in the
  * encoder chain, starting from the first bridge to the last. These are called
  * after completing the encoder's prepare op.
  *
@@ -258,7 +256,7 @@ EXPORT_SYMBOL(drm_bridge_post_disable);
  * @mode: desired mode to be set for the bridge
  * @adjusted_mode: updated mode that works for this bridge
  *
- * Calls ->mode_set() &drm_bridge_funcs op for all the bridges in the
+ * Calls &drm_bridge_funcs.mode_set op for all the bridges in the
  * encoder chain, starting from the first bridge to the last.
  *
  * Note: the bridge passed should be the one closest to the encoder
@@ -278,11 +276,11 @@ void drm_bridge_mode_set(struct drm_bridge *bridge,
 EXPORT_SYMBOL(drm_bridge_mode_set);
 
 /**
- * drm_bridge_pre_enable - calls ->pre_enable() &drm_bridge_funcs op for all
- *			   bridges in the encoder chain.
+ * drm_bridge_pre_enable - prepares for enabling all
+ *			   bridges in the encoder chain
  * @bridge: bridge control structure
  *
- * Calls ->pre_enable() &drm_bridge_funcs op for all the bridges in the encoder
+ * Calls &drm_bridge_funcs.pre_enable op for all the bridges in the encoder
  * chain, starting from the last bridge to the first. These are called
  * before calling the encoder's commit op.
  *
@@ -301,11 +299,10 @@ void drm_bridge_pre_enable(struct drm_bridge *bridge)
 EXPORT_SYMBOL(drm_bridge_pre_enable);
 
 /**
- * drm_bridge_enable - calls ->enable() &drm_bridge_funcs op for all bridges
- *		       in the encoder chain.
+ * drm_bridge_enable - enables all bridges in the encoder chain
  * @bridge: bridge control structure
  *
- * Calls ->enable() &drm_bridge_funcs op for all the bridges in the encoder
+ * Calls &drm_bridge_funcs.enable op for all the bridges in the encoder
  * chain, starting from the first bridge to the last. These are called
  * after completing the encoder's commit op.
  *
diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
index d3ca16f4da8f..1595a57dfbf2 100644
--- a/include/drm/drm_bridge.h
+++ b/include/drm/drm_bridge.h
@@ -87,18 +87,19 @@ struct drm_bridge_funcs {
 	 * True if an acceptable configuration is possible, false if the modeset
 	 * operation should be rejected.
 	 */
-	bool (*mode_fixup)(struct drm_bridge *bridge,
-			   const struct drm_display_mode *mode,
-			   struct drm_display_mode *adjusted_mode);
+	bool (*mode_fixup)(struct drm_bridge *bridge, const struct
+			   drm_display_mode *mode, struct drm_display_mode
+			   *adjusted_mode);
 	/**
 	 * @disable:
 	 *
 	 * This callback should disable the bridge. It is called right before
 	 * the preceding element in the display pipe is disabled. If the
 	 * 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.
+	 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
+	 * it's called right before the &drm_encoder_helper_funcs.disable,
+	 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
+	 * hook.
 	 *
 	 * The bridge can assume that the display pipe (i.e. clocks and timing
 	 * signals) feeding it is still running when this callback is called.
@@ -110,12 +111,13 @@ struct drm_bridge_funcs {
 	/**
 	 * @post_disable:
 	 *
-	 * This callback should disable the bridge. It is called right after
-	 * the preceding element in the display pipe is disabled. If the
-	 * 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.
+	 * This callback should disable the bridge. It is called right after the
+	 * preceding element in the display pipe is disabled. If the 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
+	 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
+	 * or &drm_encoder_helper_funcs.dpms hook.
 	 *
 	 * The bridge must assume that the display pipe (i.e. clocks and timing
 	 * singals) feeding it is no longer running when this callback is
@@ -129,9 +131,11 @@ struct drm_bridge_funcs {
 	 * @mode_set:
 	 *
 	 * This callback should set the given mode on the bridge. It is called
-	 * after the ->mode_set() callback for the preceding element in the
-	 * display pipeline has been called already. The display pipe (i.e.
-	 * clocks and timing signals) is off when this function is called.
+	 * after the @mode_set callback for the preceding element in the display
+	 * pipeline has been called already. If the bridge is the first element
+	 * then this would be &drm_encoder_helper_funcs.mode_set. The display
+	 * pipe (i.e.  clocks and timing signals) is off when this function is
+	 * called.
 	 */
 	void (*mode_set)(struct drm_bridge *bridge,
 			 struct drm_display_mode *mode,
@@ -142,9 +146,10 @@ struct drm_bridge_funcs {
 	 * This callback should enable the bridge. It is called right before
 	 * the preceding element in the display pipe is enabled. If the
 	 * 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.
+	 * bridge's @pre_enable function. If the preceding element is a
+	 * &drm_encoder it's called right before the encoder's
+	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
+	 * &drm_encoder_helper_funcs.dpms hook.
 	 *
 	 * 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
@@ -161,9 +166,10 @@ struct drm_bridge_funcs {
 	 * This callback should enable the bridge. It is called right after
 	 * the preceding element in the display pipe is enabled. If the
 	 * 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.
+	 * bridge's @enable function. If the preceding element is a
+	 * &drm_encoder it's called right after the encoder's
+	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
+	 * &drm_encoder_helper_funcs.dpms hook.
 	 *
 	 * The bridge can assume that the display pipe (i.e. clocks and timing
 	 * signals) feeding it is running when this callback is called. This
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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)
 {
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 15/17] drm/kms-core: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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.c        | 71 ++++++++++++++++++-------------------
 drivers/gpu/drm/drm_blend.c         | 11 +++---
 drivers/gpu/drm/drm_connector.c     | 12 +++----
 drivers/gpu/drm/drm_crtc.c          |  7 ++--
 drivers/gpu/drm/drm_dumb_buffers.c  |  4 +--
 drivers/gpu/drm/drm_encoder.c       |  2 +-
 drivers/gpu/drm/drm_encoder_slave.c |  2 +-
 drivers/gpu/drm/drm_framebuffer.c   | 10 +++---
 drivers/gpu/drm/drm_modeset_lock.c  | 10 +++---
 drivers/gpu/drm/drm_plane.c         |  2 +-
 drivers/gpu/drm/drm_property.c      |  2 +-
 include/drm/drm_atomic.h            |  6 ++--
 include/drm/drm_color_mgmt.h        |  2 +-
 include/drm/drm_connector.h         | 40 ++++++++++-----------
 include/drm/drm_crtc.h              | 29 +++++++--------
 include/drm/drm_framebuffer.h       | 15 ++++----
 include/drm/drm_mode_config.h       | 12 +++----
 include/drm/drm_mode_object.h       | 13 ++++---
 include/drm/drm_modeset_lock.h      |  2 +-
 include/drm/drm_plane.h             | 18 +++++-----
 include/drm/drm_property.h          |  8 ++---
 21 files changed, 141 insertions(+), 137 deletions(-)

diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
index 681d5f97639d..eea7e15bb1cf 100644
--- a/drivers/gpu/drm/drm_atomic.c
+++ b/drivers/gpu/drm/drm_atomic.c
@@ -200,8 +200,8 @@ EXPORT_SYMBOL(drm_atomic_state_default_clear);
  * all locks. So someone else could sneak in and change the current modeset
  * configuration. Which means that all the state assembled in @state is no
  * longer an atomic update to the current state, but to some arbitrary earlier
- * state. Which could break assumptions the driver's ->atomic_check likely
- * relies on.
+ * state. Which could break assumptions the driver's
+ * &drm_mode_config_funcs.atomic_check likely relies on.
  *
  * Hence we must clear all cached state and completely start over, using this
  * function.
@@ -461,11 +461,10 @@ drm_atomic_replace_property_blob_from_id(struct drm_crtc *crtc,
  * @property: the property to set
  * @val: the new property value
  *
- * Use this instead of calling crtc->atomic_set_property directly.
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_set_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_crtc_funcs.atomic_set_property for driver properties. To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -537,10 +536,10 @@ EXPORT_SYMBOL(drm_atomic_crtc_set_property);
  * @property: the property to set
  * @val: return location for the property value
  *
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_get_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_crtc_funcs.atomic_get_property for driver properties. To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -721,11 +720,10 @@ EXPORT_SYMBOL(drm_atomic_get_plane_state);
  * @property: the property to set
  * @val: the new property value
  *
- * Use this instead of calling plane->atomic_set_property directly.
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_set_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_plane_funcs.atomic_set_property for driver properties.  To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -796,10 +794,10 @@ EXPORT_SYMBOL(drm_atomic_plane_set_property);
  * @property: the property to set
  * @val: return location for the property value
  *
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_get_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_plane_funcs.atomic_get_property for driver properties.  To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -1062,11 +1060,10 @@ EXPORT_SYMBOL(drm_atomic_get_connector_state);
  * @property: the property to set
  * @val: the new property value
  *
- * Use this instead of calling connector->atomic_set_property directly.
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_set_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_connector_funcs.atomic_set_property for driver properties.  To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -1141,10 +1138,10 @@ static void drm_atomic_connector_print_state(struct drm_printer *p,
  * @property: the property to set
  * @val: return location for the property value
  *
- * This function handles generic/core properties and calls out to
- * driver's ->atomic_get_property() for driver properties.  To ensure
- * consistent behavior you must call this function rather than the
- * driver hook directly.
+ * This function handles generic/core properties and calls out to driver's
+ * &drm_connector_funcs.atomic_get_property for driver properties.  To ensure
+ * consistent behavior you must call this function rather than the driver hook
+ * directly.
  *
  * RETURNS:
  * Zero on success, error code on failure
@@ -1321,8 +1318,8 @@ EXPORT_SYMBOL(drm_atomic_set_fb_for_plane);
  * all drope the reference to the fence as we not storing it
  * anywhere.
  *
- * Otherwise, if plane_state->fence is not set this function we
- * just set it with the received implict fence.
+ * Otherwise, if &drm_plane_state.fence is not set this function we just set it
+ * with the received implict fence.
  */
 void
 drm_atomic_set_fence_for_plane(struct drm_plane_state *plane_state,
@@ -1623,7 +1620,7 @@ int drm_atomic_commit(struct drm_atomic_state *state)
 EXPORT_SYMBOL(drm_atomic_commit);
 
 /**
- * drm_atomic_nonblocking_commit - atomic&nonblocking configuration commit
+ * drm_atomic_nonblocking_commit - atomic nonblocking commit
  * @state: atomic configuration to check
  *
  * Note that this function can return -EDEADLK if the driver needed to acquire
@@ -1838,10 +1835,10 @@ static int atomic_set_prop(struct drm_atomic_state *state,
  * @plane_mask: plane mask for planes that were updated.
  * @ret: return value, can be -EDEADLK for a retry.
  *
- * Before doing an update plane->old_fb is set to plane->fb,
- * but before dropping the locks old_fb needs to be set to NULL
- * and plane->fb updated. This is a common operation for each
- * atomic update, so this call is split off as a helper.
+ * Before doing an update &drm_plane.old_fb is set to &drm_plane.fb, but before
+ * dropping the locks old_fb needs to be set to NULL and plane->fb updated. This
+ * is a common operation for each atomic update, so this call is split off as a
+ * helper.
  */
 void drm_atomic_clean_old_fb(struct drm_device *dev,
 			     unsigned plane_mask,
@@ -1882,7 +1879,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 &struct reservation_object.
  * Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org),
  * whereas explicit fencing is what Android wants.
  *
diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
index 1f2412c7ccfd..665aafc6ad68 100644
--- a/drivers/gpu/drm/drm_blend.c
+++ b/drivers/gpu/drm/drm_blend.c
@@ -40,9 +40,8 @@
  * sub-pixel accuracy, which is scaled up to a pixel-aligned destination
  * rectangle in the visible area of a &drm_crtc. The visible area of a CRTC is
  * defined by the horizontal and vertical visible pixels (stored in @hdisplay
- * and @vdisplay) of the requested mode (stored in @mode in the
- * &drm_crtc_state). These two rectangles are both stored in the
- * &drm_plane_state.
+ * and @vdisplay) of the requested mode (stored in &drm_crtc_state.mode). These
+ * two rectangles are both stored in the &drm_plane_state.
  *
  * For the atomic ioctl the following standard (atomic) properties on the plane object
  * encode the basic plane composition model:
@@ -215,7 +214,7 @@ EXPORT_SYMBOL(drm_rotation_simplify);
  * for it in drm core. Drivers can then attach this property to planes to enable
  * support for configurable planes arrangement during blending operation.
  * Once mutable zpos property has been enabled, the DRM core will automatically
- * calculate drm_plane_state->normalized_zpos values. Usually min should be set
+ * calculate &drm_plane_state.normalized_zpos values. Usually min should be set
  * to 0 and max to maximal number of planes for given crtc - 1.
  *
  * If zpos of some planes cannot be changed (like fixed background or
@@ -367,8 +366,8 @@ static int drm_atomic_helper_crtc_normalize_zpos(struct drm_crtc *crtc,
  * For every CRTC this function checks new states of all planes assigned to
  * it and calculates normalized zpos value for these planes. Planes are compared
  * first by their zpos values, then by plane id (if zpos is equal). The plane
- * with lowest zpos value is at the bottom. The plane_state->normalized_zpos is
- * then filled with unique values from 0 to number of active planes in crtc
+ * with lowest zpos value is at the bottom. The &drm_plane_state.normalized_zpos
+ * is then filled with unique values from 0 to number of active planes in crtc
  * minus one.
  *
  * RETURNS
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 799edd0d308e..dd720d4cb4f7 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -38,8 +38,8 @@
  * Hence they are reference-counted using drm_connector_reference() and
  * drm_connector_unreference().
  *
- * KMS driver must create, initialize, register and attach at a struct
- * &drm_connector for each such sink. The instance is created as other KMS
+ * KMS driver must create, initialize, register and attach at a &struct
+ * drm_connector for each such sink. The instance is created as other KMS
  * objects and initialized by setting the following fields.
  *
  * The connector is then registered with a call to drm_connector_init() with a
@@ -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 &drm_connector.encoder field to point to the
  * attached encoder.
  *
  * For connectors which are not fixed (like built-in panels) the driver needs to
@@ -497,7 +497,7 @@ static struct lockdep_map connector_list_iter_dep_map = {
  * @dev: DRM device
  * @iter: connector_list iterator
  *
- * Sets @iter up to walk the connector list in &drm_mode_config of @dev. @iter
+ * Sets @iter up to walk the &drm_mode_config.connector_list of @dev. @iter
  * must always be cleaned up again by calling drm_connector_list_iter_put().
  * Iteration itself happens using drm_connector_list_iter_next() or
  * drm_for_each_connector_iter().
@@ -696,8 +696,8 @@ DRM_ENUM_NAME_FN(drm_get_tv_subconnector_name,
  * 	drivers this is only provided for backwards compatibility with existing
  * 	drivers, it remaps to controlling the "ACTIVE" property on the CRTC the
  * 	connector is linked to. Drivers should never set this property directly,
- * 	it is handled by the DRM core by calling the ->dpms() callback in
- * 	&drm_connector_funcs. Atomic drivers should implement this hook using
+ * 	it is handled by the DRM core by calling the &drm_connector_funcs.dpms
+ * 	callback. Atomic drivers should implement this hook using
  * 	drm_atomic_helper_connector_dpms(). This is the only property standard
  * 	connector property that userspace can change.
  * PATH:
diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index 080c8d361f1f..3dfbb1befae1 100644
--- a/drivers/gpu/drm/drm_crtc.c
+++ b/drivers/gpu/drm/drm_crtc.c
@@ -392,11 +392,12 @@ int drm_mode_getcrtc(struct drm_device *dev,
 }
 
 /**
- * drm_mode_set_config_internal - helper to call ->set_config
+ * drm_mode_set_config_internal - helper to call &drm_mode_config_funcs.set_config
  * @set: modeset config to set
  *
- * This is a little helper to wrap internal calls to the ->set_config driver
- * interface. The only thing it adds is correct refcounting dance.
+ * This is a little helper to wrap internal calls to the
+ * &drm_mode_config_funcs.set_config driver interface. The only thing it adds is
+ * correct refcounting dance.
  *
  * Returns:
  * Zero on success, negative errno on failure.
diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
index e5c61cda4ae3..10307cc16d75 100644
--- a/drivers/gpu/drm/drm_dumb_buffers.c
+++ b/drivers/gpu/drm/drm_dumb_buffers.c
@@ -42,8 +42,8 @@
  * create dumb buffers suitable for scanout, which can then be used to create
  * 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
+ * To support dumb objects drivers must implement the &drm_driver.dumb_create,
+ * &drm_driver.dumb_destroy and &drm_driver.dumb_map_offset operations. 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 487cfe3989e8..129450713bb7 100644
--- a/drivers/gpu/drm/drm_encoder.c
+++ b/drivers/gpu/drm/drm_encoder.c
@@ -98,7 +98,7 @@ void drm_encoder_unregister_all(struct drm_device *dev)
  *
  * Initialises a preallocated encoder. Encoder should be subclassed as part of
  * driver encoder objects. At driver unload time drm_encoder_cleanup() should be
- * called from the driver's destroy hook in &drm_encoder_funcs.
+ * called from the driver's &drm_encoder_funcs.destroy hook.
  *
  * Returns:
  * Zero on success, error code on failure.
diff --git a/drivers/gpu/drm/drm_encoder_slave.c b/drivers/gpu/drm/drm_encoder_slave.c
index 4484785cd9ac..cf804389f5ec 100644
--- a/drivers/gpu/drm/drm_encoder_slave.c
+++ b/drivers/gpu/drm/drm_encoder_slave.c
@@ -43,7 +43,7 @@
  * &drm_encoder_slave. The @slave_funcs field will be initialized with
  * the hooks provided by the slave driver.
  *
- * If @info->platform_data is non-NULL it will be used as the initial
+ * If @info.platform_data is non-NULL it will be used as the initial
  * slave config.
  *
  * Returns 0 on success or a negative errno on failure, in particular,
diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
index 588ccc3a2218..ca9cff09cad1 100644
--- a/drivers/gpu/drm/drm_framebuffer.c
+++ b/drivers/gpu/drm/drm_framebuffer.c
@@ -58,8 +58,8 @@
  * 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
- * &drm_framebuffer.
+ * is not recommended, and it's better to have a normal free-standing &struct
+ * drm_framebuffer.
  */
 
 int drm_framebuffer_check_src_coords(uint32_t src_x, uint32_t src_y,
@@ -470,7 +470,7 @@ int drm_mode_getfb(struct drm_device *dev,
  * usb display-link, mipi manual update panels or edp panel self refresh modes.
  *
  * Modesetting drivers which always update the frontbuffer do not need to
- * implement the corresponding ->dirty framebuffer callback.
+ * implement the corresponding &drm_framebuffer_funcs.dirty callback.
  *
  * Called by the user via ioctl.
  *
@@ -709,8 +709,8 @@ EXPORT_SYMBOL(drm_framebuffer_unregister_private);
  * @fb: framebuffer to remove
  *
  * Cleanup framebuffer. This function is intended to be used from the drivers
- * ->destroy callback. It can also be used to clean up driver private
- * framebuffers embedded into a larger structure.
+ * &drm_framebuffer_funcs.destroy callback. It can also be used to clean up
+ * driver private framebuffers embedded into a larger structure.
  *
  * Note that this function does not remove the fb from active usuage - if it is
  * still used anywhere, hilarity can ensue since userspace could call getfb on
diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c
index 3551ae31f143..bf60f2645e55 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -33,7 +33,7 @@
  * to use &ww_mutex and acquire-contexts to avoid deadlocks.  But because
  * the locking is more distributed around the driver code, we want a bit
  * of extra utility/tracking out of our acquire-ctx.  This is provided
- * by drm_modeset_lock / drm_modeset_acquire_ctx.
+ * by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx.
  *
  * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
  *
@@ -53,7 +53,7 @@
  *     drm_modeset_acquire_fini(&ctx);
  *
  * On top of of these per-object locks using &ww_mutex there's also an overall
- * dev->mode_config.lock, for protecting everything else. Mostly this means
+ * &drm_mode_config.mutex, for protecting everything else. Mostly this means
  * probe state of connectors, and preventing hotplug add/removal of connectors.
  *
  * Finally there's a bunch of dedicated locks to protect drm core internal
@@ -71,7 +71,7 @@ static DEFINE_WW_CLASS(crtc_ww_class);
  * drm_modeset_unlock_all() function.
  *
  * This function is deprecated. It allocates a lock acquisition context and
- * stores it in the DRM device's ->mode_config. This facilitate conversion of
+ * stores it in &drm_device.mode_config. This facilitate conversion of
  * existing code because it removes the need to manually deal with the
  * acquisition context, but it is also brittle because the context is global
  * and care must be taken not to nest calls. New code should use the
@@ -124,7 +124,7 @@ EXPORT_SYMBOL(drm_modeset_lock_all);
  * drm_modeset_lock_all() function.
  *
  * This function is deprecated. It uses the lock acquisition context stored
- * in the DRM device's ->mode_config. This facilitates conversion of existing
+ * in &drm_device.mode_config. This facilitates conversion of existing
  * code because it removes the need to manually deal with the acquisition
  * context, but it is also brittle because the context is global and care must
  * be taken not to nest calls. New code should pass the acquisition context
@@ -468,7 +468,7 @@ EXPORT_SYMBOL(drm_modeset_unlock);
  * This function takes all modeset locks, suitable where a more fine-grained
  * scheme isn't (yet) implemented.
  *
- * Unlike drm_modeset_lock_all(), it doesn't take the dev->mode_config.mutex
+ * Unlike drm_modeset_lock_all(), it doesn't take the &drm_mode_config.mutex
  * since that lock isn't required for modeset state changes. Callers which
  * need to grab that lock too need to do so outside of the acquire context
  * @ctx.
diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c
index 7b7275f0c2df..541abd85b45d 100644
--- a/drivers/gpu/drm/drm_plane.c
+++ b/drivers/gpu/drm/drm_plane.c
@@ -42,7 +42,7 @@
  *
  * Cursor and overlay planes are optional. All drivers should provide one
  * primary plane per CRTC to avoid surprising userspace too much. See enum
- * &drm_plane_type for a more in-depth discussion of these special uapi-relevant
+ * drm_plane_type for a more in-depth discussion of these special uapi-relevant
  * plane types. Special planes are associated with their CRTC by calling
  * drm_crtc_init_with_planes().
  *
diff --git a/drivers/gpu/drm/drm_property.c b/drivers/gpu/drm/drm_property.c
index 0d0e5dc0ee23..0cb2a39fe059 100644
--- a/drivers/gpu/drm/drm_property.c
+++ b/drivers/gpu/drm/drm_property.c
@@ -43,7 +43,7 @@
  *
  * Property values are only 64bit. To support bigger piles of data (like gamma
  * tables, color correction matrizes or large structures) a property can instead
- * point at a &drm_property_blob with that additional data
+ * point at a &drm_property_blob with that additional data.
  *
  * Properties are defined by their symbolic name, userspace must keep a
  * per-object mapping from those names to the property ID used in the atomic
diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
index fd2d971bca32..04971469967f 100644
--- a/include/drm/drm_atomic.h
+++ b/include/drm/drm_atomic.h
@@ -123,7 +123,8 @@ struct drm_crtc_commit {
 	/**
 	 * @commit_entry:
 	 *
-	 * Entry on the per-CRTC commit_list. Protected by crtc->commit_lock.
+	 * Entry on the per-CRTC &drm_crtc.commit_list. Protected by
+	 * $drm_crtc.commit_lock.
 	 */
 	struct list_head commit_entry;
 
@@ -410,7 +411,8 @@ void drm_state_dump(struct drm_device *dev, struct drm_printer *p);
  *
  * For example if the CRTC mode has changed, and the hardware is able to enact
  * the requested mode change without going through a full modeset, the driver
- * should clear mode_changed during its ->atomic_check.
+ * should clear mode_changed in its &drm_mode_config_funcs.atomic_check
+ * implementation.
  */
 static inline bool
 drm_atomic_crtc_needs_modeset(const struct drm_crtc_state *state)
diff --git a/include/drm/drm_color_mgmt.h b/include/drm/drm_color_mgmt.h
index c767238ac9d5..d9c2f680f5ae 100644
--- a/include/drm/drm_color_mgmt.h
+++ b/include/drm/drm_color_mgmt.h
@@ -34,7 +34,7 @@ int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
 				 int gamma_size);
 
 /**
- * drm_color_lut_extract - clamp&round LUT entries
+ * drm_color_lut_extract - clamp and round LUT entries
  * @user_input: input value
  * @bit_precision: number of bits the hw LUT supports
  *
diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index d489cc003b7e..4f7d3b49995a 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -331,15 +331,15 @@ struct drm_connector_funcs {
 	 *
 	 * Entry point for output detection and basic mode validation. The
 	 * driver should reprobe the output if needed (e.g. when hotplug
-	 * handling is unreliable), add all detected modes to connector->modes
+	 * handling is unreliable), add all detected modes to &drm_connector.modes
 	 * and filter out any the device can't support in any configuration. It
 	 * also needs to filter out any modes wider or higher than the
 	 * parameters max_width and max_height indicate.
 	 *
 	 * The drivers must also prune any modes no longer valid from
-	 * connector->modes. Furthermore it must update connector->status and
-	 * connector->edid.  If no EDID has been received for this output
-	 * connector->edid must be NULL.
+	 * &drm_connector.modes. Furthermore it must update
+	 * &drm_connector.status and &drm_connector.edid.  If no EDID has been
+	 * received for this output connector->edid must be NULL.
 	 *
 	 * Drivers using the probe helpers should use
 	 * drm_helper_probe_single_connector_modes() or
@@ -348,7 +348,7 @@ struct drm_connector_funcs {
 	 *
 	 * RETURNS:
 	 *
-	 * The number of modes detected and filled into connector->modes.
+	 * The number of modes detected and filled into &drm_connector.modes.
 	 */
 	int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
 
@@ -381,7 +381,7 @@ struct drm_connector_funcs {
 	 * core drm connector interfaces. Everything added from this callback
 	 * should be unregistered in the early_unregister callback.
 	 *
-	 * This is called while holding drm_connector->mutex.
+	 * This is called while holding &drm_connector.mutex.
 	 *
 	 * Returns:
 	 *
@@ -398,7 +398,7 @@ struct drm_connector_funcs {
 	 * early in the driver unload sequence to disable userspace access
 	 * before data structures are torndown.
 	 *
-	 * This is called while holding drm_connector->mutex.
+	 * This is called while holding &drm_connector.mutex.
 	 */
 	void (*early_unregister)(struct drm_connector *connector);
 
@@ -418,9 +418,9 @@ struct drm_connector_funcs {
 	 * Duplicate the current atomic state for this connector and return it.
 	 * The core and helpers guarantee that any atomic state duplicated with
 	 * this hook and still owned by the caller (i.e. not transferred to the
-	 * driver by calling ->atomic_commit() from struct
-	 * &drm_mode_config_funcs) will be cleaned up by calling the
-	 * @atomic_destroy_state hook in this structure.
+	 * driver by calling &drm_mode_config_funcs.atomic_commit) 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
 	 * drm_atomic_helper_connector_duplicate_state(). Drivers that subclass the
@@ -428,7 +428,7 @@ struct drm_connector_funcs {
 	 * __drm_atomic_helper_connector_duplicate_state() to make sure shared state is
 	 * duplicated in a consistent fashion across drivers.
 	 *
-	 * It is an error to call this hook before connector->state has been
+	 * It is an error to call this hook before &drm_connector.state has been
 	 * initialized correctly.
 	 *
 	 * NOTE:
@@ -609,8 +609,8 @@ struct drm_connector {
 
 	/**
 	 * @mutex: Lock for general connector state, but currently only protects
-	 * @registered. Most of the connector state is still protected by the
-	 * mutex in &drm_mode_config.
+	 * @registered. Most of the connector state is still protected by
+	 * &drm_mode_config.mutex.
 	 */
 	struct mutex mutex;
 
@@ -636,14 +636,14 @@ struct drm_connector {
 	/**
 	 * @modes:
 	 * Modes available on this connector (from fill_modes() + user).
-	 * Protected by dev->mode_config.mutex.
+	 * Protected by &drm_mode_config.mutex.
 	 */
-	struct list_head modes; /* list of modes on this connector */
+	struct list_head modes;
 
 	/**
 	 * @status:
 	 * One of the drm_connector_status enums (connected, not, or unknown).
-	 * Protected by dev->mode_config.mutex.
+	 * Protected by &drm_mode_config.mutex.
 	 */
 	enum drm_connector_status status;
 
@@ -651,7 +651,7 @@ struct drm_connector {
 	 * @probed_modes:
 	 * These are modes added by probing with DDC or the BIOS, before
 	 * filtering is applied. Used by the probe helpers.Protected by
-	 * dev->mode_config.mutex.
+	 * &drm_mode_config.mutex.
 	 */
 	struct list_head probed_modes;
 
@@ -659,10 +659,10 @@ struct drm_connector {
 	 * @display_info: Display information is filled from EDID information
 	 * when a display is detected. For non hot-pluggable displays such as
 	 * flat panels in embedded systems, the driver should initialize the
-	 * display_info.width_mm and display_info.height_mm fields with the
-	 * physical size of the display.
+	 * &drm_display_info.width_mm and &drm_display_info.height_mm fields
+	 * with the physical size of the display.
 	 *
-	 * Protected by dev->mode_config.mutex.
+	 * Protected by &drm_mode_config.mutex.
 	 */
 	struct drm_display_info display_info;
 	const struct drm_connector_funcs *funcs;
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index c0817fa205d4..818ce4774169 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -81,8 +81,8 @@ struct drm_plane_helper_funcs;
  * @enable: whether the CRTC should be enabled, gates all other state
  * @active: whether the CRTC is actively displaying (used for DPMS)
  * @planes_changed: planes on this crtc are updated
- * @mode_changed: crtc_state->mode or crtc_state->enable has been changed
- * @active_changed: crtc_state->active has been toggled.
+ * @mode_changed: @mode or @enable has been changed
+ * @active_changed: @active has been toggled.
  * @connectors_changed: connectors to this crtc have been updated
  * @zpos_changed: zpos values of planes on this crtc have been updated
  * @color_mgmt_changed: color management properties have changed (degamma or
@@ -102,9 +102,10 @@ struct drm_plane_helper_funcs;
  *
  * Note that the distinction between @enable and @active is rather subtile:
  * Flipping @active while @enable is set without changing anything else may
- * never return in a failure from the ->atomic_check callback. Userspace assumes
- * that a DPMS On will always succeed. In other words: @enable controls resource
- * assignment, @active controls the actual hardware state.
+ * never return in a failure from the &drm_mode_config_funcs.atomic_check
+ * callback. Userspace assumes that a DPMS On will always succeed. In other
+ * words: @enable controls resource assignment, @active controls the actual
+ * hardware state.
  *
  * The three booleans active_changed, connectors_changed and mode_changed are
  * intended to indicate whether a full modeset is needed, rather than strictly
@@ -337,8 +338,8 @@ struct drm_crtc_funcs {
 	 * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application
 	 * requests a page flip the DRM core verifies that the new frame buffer
 	 * is large enough to be scanned out by the CRTC in the currently
-	 * configured mode and then calls the CRTC ->page_flip() operation with a
-	 * pointer to the new frame buffer.
+	 * configured mode and then calls this hook with a pointer to the new
+	 * frame buffer.
 	 *
 	 * The driver must wait for any pending rendering to the new framebuffer
 	 * to complete before executing the flip. It should also wait for any
@@ -373,7 +374,7 @@ struct drm_crtc_funcs {
 	 * RETURNS:
 	 *
 	 * 0 on success or a negative error code on failure. Note that if a
-	 * ->page_flip() operation is already pending the callback should return
+	 * page flip operation is already pending the callback should return
 	 * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode
 	 * or just runtime disabled through DPMS respectively the new atomic
 	 * "ACTIVE" state) should result in an -EINVAL error code. Note that
@@ -427,17 +428,17 @@ struct drm_crtc_funcs {
 	 * Duplicate the current atomic state for this CRTC and return it.
 	 * The core and helpers gurantee that any atomic state duplicated with
 	 * this hook and still owned by the caller (i.e. not transferred to the
-	 * driver by calling ->atomic_commit() from struct
-	 * &drm_mode_config_funcs) will be cleaned up by calling the
-	 * @atomic_destroy_state hook in this structure.
+	 * driver by calling &drm_mode_config_funcs.atomic_commit) 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_state 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
 	 * duplicated in a consistent fashion across drivers.
 	 *
-	 * It is an error to call this hook before crtc->state has been
+	 * It is an error to call this hook before &drm_crtc.state has been
 	 * initialized correctly.
 	 *
 	 * NOTE:
@@ -632,7 +633,7 @@ struct drm_crtc {
 	 * This provides a read lock for the overall crtc state (mode, dpms
 	 * state, ...) and a write lock for everything which can be update
 	 * without a full modeset (fb, cursor data, crtc properties ...). Full
-	 * modeset also need to grab dev->mode_config.connection_mutex.
+	 * modeset also need to grab &drm_mode_config.connection_mutex.
 	 */
 	struct drm_modeset_lock mutex;
 
diff --git a/include/drm/drm_framebuffer.h b/include/drm/drm_framebuffer.h
index 046c35e54099..04c77eee9c20 100644
--- a/include/drm/drm_framebuffer.h
+++ b/include/drm/drm_framebuffer.h
@@ -40,8 +40,8 @@ struct drm_framebuffer_funcs {
 	 *
 	 * Clean up framebuffer resources, specifically also unreference the
 	 * backing storage. The core guarantees to call this function for every
-	 * framebuffer successfully created by ->fb_create() in
-	 * &drm_mode_config_funcs. Drivers must also call
+	 * framebuffer successfully created by calling
+	 * &drm_mode_config_funcs.fb_create. Drivers must also call
 	 * drm_framebuffer_cleanup() to release DRM core resources for this
 	 * framebuffer.
 	 */
@@ -112,8 +112,8 @@ struct drm_framebuffer {
 	 */
 	struct drm_device *dev;
 	/**
-	 * @head: Place on the dev->mode_config.fb_list, access protected by
-	 * dev->mode_config.fb_lock.
+	 * @head: Place on the &drm_mode_config.fb_list, access protected by
+	 * &drm_mode_config.fb_lock.
 	 */
 	struct list_head head;
 
@@ -187,8 +187,7 @@ struct drm_framebuffer {
 	 */
 	int hot_y;
 	/**
-	 * @filp_head: Placed on &struct drm_file fbs list_head, protected by
-	 * fbs_lock in the same structure.
+	 * @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock.
 	 */
 	struct list_head filp_head;
 };
@@ -260,8 +259,8 @@ static inline void drm_framebuffer_assign(struct drm_framebuffer **p,
  * @fb: the loop cursor
  * @dev: the DRM device
  *
- * Iterate over all framebuffers of @dev. User must hold the fb_lock from
- * &drm_mode_config.
+ * Iterate over all framebuffers of @dev. User must hold
+ * &drm_mode_config.fb_lock.
  */
 #define drm_for_each_fb(fb, dev) \
 	for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)),		\
diff --git a/include/drm/drm_mode_config.h b/include/drm/drm_mode_config.h
index 17942c0f32a8..5a29978062d3 100644
--- a/include/drm/drm_mode_config.h
+++ b/include/drm/drm_mode_config.h
@@ -132,8 +132,8 @@ struct drm_mode_config_funcs {
 	 *    that before calling this hook.
 	 *
 	 * See the documentation of @atomic_commit for an exhaustive list of
-	 * error conditions which don't have to be checked at the
-	 * ->atomic_check() stage?
+	 * error conditions which don't have to be checked at the in this
+	 * callback.
 	 *
 	 * See the documentation for &struct drm_atomic_state for how exactly
 	 * an atomic modeset update is described.
@@ -198,10 +198,10 @@ 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
-	 * 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.
+	 * The drm core will supply a &struct drm_event in each CRTC's
+	 * &drm_crtc_state.event. See the documentation for
+	 * &drm_crtc_state.event for more details about the precise semantics of
+	 * this event.
 	 *
 	 * NOTE:
 	 *
diff --git a/include/drm/drm_mode_object.h b/include/drm/drm_mode_object.h
index 43460b21d112..2c017adf6d74 100644
--- a/include/drm/drm_mode_object.h
+++ b/include/drm/drm_mode_object.h
@@ -86,10 +86,15 @@ struct drm_object_properties {
 	 *
 	 * Note that atomic drivers do not store mutable properties in this
 	 * array, but only the decoded values in the corresponding state
-	 * structure. The decoding is done using the ->atomic_get_property and
-	 * ->atomic_set_property hooks of the corresponding object. Hence atomic
-	 * drivers should not use drm_object_property_set_value() and
-	 * drm_object_property_get_value() on mutable objects, i.e. those
+	 * structure. The decoding is done using the &drm_crtc.atomic_get_property and
+	 * &drm_crtc.atomic_set_property hooks for &struct drm_crtc. For
+	 * &struct drm_plane the hooks are &drm_plane_funcs.atomic_get_property and
+	 * &drm_plane_funcs.atomic_set_property. And for &struct drm_connector
+	 * the hooks are &drm_connector_funcs.atomic_get_property and
+	 * &drm_connector_funcs.atomic_set_property .
+	 *
+	 * Hence atomic drivers should not use drm_object_property_set_value()
+	 * and drm_object_property_get_value() on mutable objects, i.e. those
 	 * without the DRM_MODE_PROP_IMMUTABLE flag set.
 	 */
 	uint64_t values[DRM_OBJECT_MAX_PROPERTY];
diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index d918ce45ec2c..96d39fbd12ca 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -64,7 +64,7 @@ struct drm_modeset_acquire_ctx {
 /**
  * struct drm_modeset_lock - used for locking modeset resources.
  * @mutex: resource locking
- * @head: used to hold it's place on state->locked list when
+ * @head: used to hold it's place on &drm_atomi_state.locked list when
  *    part of an atomic update
  *
  * Used for locking CRTCs and other modeset resources.
diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index e049bc52fb07..525a3340c1b2 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -249,9 +249,9 @@ struct drm_plane_funcs {
 	 * Duplicate the current atomic state for this plane and return it.
 	 * The core and helpers gurantee that any atomic state duplicated with
 	 * this hook and still owned by the caller (i.e. not transferred to the
-	 * driver by calling ->atomic_commit() from struct
-	 * &drm_mode_config_funcs) will be cleaned up by calling the
-	 * @atomic_destroy_state hook in this structure.
+	 * driver by calling &drm_mode_config_funcs.atomic_commit) 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
 	 * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
@@ -259,7 +259,7 @@ struct drm_plane_funcs {
 	 * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is
 	 * duplicated in a consistent fashion across drivers.
 	 *
-	 * It is an error to call this hook before plane->state has been
+	 * It is an error to call this hook before &drm_plane.state has been
 	 * initialized correctly.
 	 *
 	 * NOTE:
@@ -423,8 +423,8 @@ enum drm_plane_type {
 	 *
 	 * Primary planes represent a "main" plane for a CRTC.  Primary planes
 	 * are the planes operated upon by CRTC modesetting and flipping
-	 * operations described in the page_flip and set_config hooks in struct
-	 * &drm_crtc_funcs.
+	 * operations described in the &drm_crtc_funcs.page_flip and
+	 * &drm_crtc_funcs.set_config hooks.
 	 */
 	DRM_PLANE_TYPE_PRIMARY,
 
@@ -470,8 +470,8 @@ struct drm_plane {
 	/**
 	 * @mutex:
 	 *
-	 * Protects modeset plane state, together with the mutex of &drm_crtc
-	 * this plane is linked to (when active, getting actived or getting
+	 * Protects modeset plane state, together with the &drm_crtc.mutex of
+	 * CRTC this plane is linked to (when active, getting actived or getting
 	 * disabled).
 	 */
 	struct drm_modeset_lock mutex;
@@ -580,7 +580,7 @@ static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
  *
  * Iterate over all legacy planes of @dev, excluding primary and cursor planes.
  * This is useful for implementing userspace apis when userspace is not
- * universal plane aware. See also enum &drm_plane_type.
+ * universal plane aware. See also &enum drm_plane_type.
  */
 #define drm_for_each_legacy_plane(plane, dev) \
 	list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
diff --git a/include/drm/drm_property.h b/include/drm/drm_property.h
index 43c4b6a2046d..f66fdb47551c 100644
--- a/include/drm/drm_property.h
+++ b/include/drm/drm_property.h
@@ -30,7 +30,7 @@
 /**
  * struct drm_property_enum - symbolic values for enumerations
  * @value: numeric property value for this enum entry
- * @head: list of enum values, linked to enum_list in &drm_property
+ * @head: list of enum values, linked to &drm_property.enum_list
  * @name: symbolic name for the enum
  *
  * For enumeration and bitmask properties this structure stores the symbolic
@@ -191,9 +191,9 @@ struct drm_property {
  * struct drm_property_blob - Blob data for &drm_property
  * @base: base KMS object
  * @dev: DRM device
- * @head_global: entry on the global blob list in &drm_mode_config
- *	property_blob_list.
- * @head_file: entry on the per-file blob list in &drm_file blobs list.
+ * @head_global: entry on the global blob list in
+ * 	&drm_mode_config.property_blob_list.
+ * @head_file: entry on the per-file blob list in &drm_file.blobs list.
  * @length: size of the blob in bytes, invariant over the lifetime of the object
  * @data: actual data, embedded at the end of this structure
  *
-- 
2.7.4

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

[PATCH 16/17] drm/gem|prime|mm: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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)
-- 
2.7.4

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

[PATCH 17/17] drm/core: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

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_auth.c     |  4 ++--
 drivers/gpu/drm/drm_drv.c      |  8 ++++----
 drivers/gpu/drm/drm_fops.c     | 11 ++++++-----
 drivers/gpu/drm/drm_irq.c      | 10 +++++-----
 drivers/gpu/drm/drm_pci.c      |  2 +-
 drivers/gpu/drm/drm_platform.c |  2 +-
 drivers/gpu/drm/drm_sysfs.c    |  2 +-
 include/drm/drm_auth.h         | 12 ++++++------
 include/drm/drm_drv.h          |  2 +-
 include/drm/drm_irq.h          |  4 ++--
 10 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
index 860cfe124c2a..7ff697389d74 100644
--- a/drivers/gpu/drm/drm_auth.c
+++ b/drivers/gpu/drm/drm_auth.c
@@ -40,8 +40,8 @@
  * 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.
- * This is noted in the is_master member of &drm_file. All other clients have
- * just a pointer to the &drm_master they are associated with.
+ * This is noted in &drm_file.is_master. All other clients have just a pointer
+ * to the &drm_master they are associated with.
  *
  * In addition only one &drm_master can be the current master for a &drm_device.
  * It can be switched through the DROP_MASTER and SET_MASTER IOCTL, or
diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
index f8de5804c37c..720427aad1d4 100644
--- a/drivers/gpu/drm/drm_drv.c
+++ b/drivers/gpu/drm/drm_drv.c
@@ -309,7 +309,7 @@ void drm_minor_release(struct drm_minor *minor)
  * userspace the device instance can be published using drm_dev_register().
  *
  * There is also deprecated support for initalizing device instances using
- * bus-specific helpers and the ->load() callback. But due to
+ * bus-specific helpers and the &drm_driver.load callback. But due to
  * backwards-compatibility needs the device instance have to be published too
  * early, which requires unpretty global locking to make safe and is therefore
  * only support for existing drivers not yet converted to the new scheme.
@@ -718,9 +718,9 @@ static void remove_compat_control_link(struct drm_device *dev)
  * Never call this twice on any device!
  *
  * NOTE: To ensure backward compatibility with existing drivers method this
- * function calls the ->load() method after registering the device nodes,
- * creating race conditions. Usage of the ->load() methods is therefore
- * deprecated, drivers must perform all initialization before calling
+ * function calls the &drm_driver.load method after registering the device
+ * nodes, creating race conditions. Usage of the &drm_driver.load methods is
+ * therefore deprecated, drivers must perform all initialization before calling
  * drm_dev_register().
  *
  * RETURNS:
diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c
index 48e106557c92..c9383ff36b61 100644
--- a/drivers/gpu/drm/drm_fops.c
+++ b/drivers/gpu/drm/drm_fops.c
@@ -580,7 +580,7 @@ EXPORT_SYMBOL(drm_poll);
  * kmalloc and @p must be the first member element.
  *
  * This is the locked version of drm_event_reserve_init() for callers which
- * already hold dev->event_lock.
+ * already hold &drm_device.event_lock.
  *
  * RETURNS:
  *
@@ -621,7 +621,7 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
  * If callers embedded @p into a larger structure it must be allocated with
  * kmalloc and @p must be the first member element.
  *
- * Callers which already hold dev->event_lock should use
+ * Callers which already hold &drm_device.event_lock should use
  * drm_event_reserve_init_locked() instead.
  *
  * RETURNS:
@@ -677,7 +677,7 @@ EXPORT_SYMBOL(drm_event_cancel_free);
  *
  * This function sends the event @e, initialized with drm_event_reserve_init(),
  * to its associated userspace DRM file. Callers must already hold
- * dev->event_lock, see drm_send_event() for the unlocked version.
+ * &drm_device.event_lock, see drm_send_event() for the unlocked version.
  *
  * Note that the core will take care of unlinking and disarming events when the
  * corresponding DRM file is closed. Drivers need not worry about whether the
@@ -717,8 +717,9 @@ EXPORT_SYMBOL(drm_send_event_locked);
  * @e: DRM event to deliver
  *
  * This function sends the event @e, initialized with drm_event_reserve_init(),
- * to its associated userspace DRM file. This function acquires dev->event_lock,
- * see drm_send_event_locked() for callers which already hold this lock.
+ * to its associated userspace DRM file. This function acquires
+ * &drm_device.event_lock, see drm_send_event_locked() for callers which already
+ * hold this lock.
  *
  * Note that the core will take care of unlinking and disarming events when the
  * corresponding DRM file is closed. Drivers need not worry about whether the
diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
index 88c69e71102e..1c4da043eeda 100644
--- a/drivers/gpu/drm/drm_irq.c
+++ b/drivers/gpu/drm/drm_irq.c
@@ -95,7 +95,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe,
  *
  * Only to be called from drm_crtc_vblank_on().
  *
- * Note: caller must hold dev->vbl_lock since this reads & writes
+ * Note: caller must hold &drm_device.vbl_lock since this reads & writes
  * device vblank fields.
  */
 static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe)
@@ -142,7 +142,7 @@ static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe
  * Only necessary when going from off->on, to account for frames we
  * didn't get an interrupt for.
  *
- * Note: caller must hold dev->vbl_lock since this reads & writes
+ * Note: caller must hold &drm_device.vbl_lock since this reads & writes
  * device vblank fields.
  */
 static void drm_update_vblank_count(struct drm_device *dev, unsigned int pipe,
@@ -449,7 +449,7 @@ static void drm_irq_vgaarb_nokms(void *cookie, bool state)
  *
  * This is the simplified helper interface provided for drivers with no special
  * needs. Drivers which need to install interrupt handlers for multiple
- * interrupts must instead set drm_device->irq_enabled to signal the DRM core
+ * interrupts must instead set &drm_device.irq_enabled to signal the DRM core
  * that vblank interrupts are available.
  *
  * Returns:
@@ -519,7 +519,7 @@ EXPORT_SYMBOL(drm_irq_install);
  * Calls the driver's irq_uninstall() function and unregisters the IRQ handler.
  * This should only be called by drivers which used drm_irq_install() to set up
  * their interrupt handler. Other drivers must only reset
- * drm_device->irq_enabled to false.
+ * &drm_device.irq_enabled to false.
  *
  * Note that for kernel modesetting drivers it is a bug if this function fails.
  * The sanity checks are only to catch buggy user modesetting drivers which call
@@ -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 &struct drm_crtc_state.event
  * 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_pci.c b/drivers/gpu/drm/drm_pci.c
index 3ceea9cb9d3e..062422143f05 100644
--- a/drivers/gpu/drm/drm_pci.c
+++ b/drivers/gpu/drm/drm_pci.c
@@ -223,7 +223,7 @@ void drm_pci_agp_destroy(struct drm_device *dev)
  * Try and register, if we fail to register, backout previous work.
  *
  * NOTE: This function is deprecated, please use drm_dev_alloc() and
- * drm_dev_register() instead and remove your ->load() callback.
+ * drm_dev_register() instead and remove your &drm_driver.load() callback.
  *
  * Return: 0 on success or a negative error code on failure.
  */
diff --git a/drivers/gpu/drm/drm_platform.c b/drivers/gpu/drm/drm_platform.c
index 026269851ce9..e52d87dd93e0 100644
--- a/drivers/gpu/drm/drm_platform.c
+++ b/drivers/gpu/drm/drm_platform.c
@@ -78,7 +78,7 @@ static int drm_get_platform_dev(struct platform_device *platdev,
  * .load() function.
  *
  * NOTE: This function is deprecated, please use drm_dev_alloc() and
- * drm_dev_register() instead and remove your ->load() callback.
+ * drm_dev_register() instead and remove your &drm_driver.load() callback.
  *
  * Return: 0 on success or a negative error code on failure.
  */
diff --git a/drivers/gpu/drm/drm_sysfs.c b/drivers/gpu/drm/drm_sysfs.c
index 9a37196c1bf1..513288b5c2f6 100644
--- a/drivers/gpu/drm/drm_sysfs.c
+++ b/drivers/gpu/drm/drm_sysfs.c
@@ -255,7 +255,7 @@ static const struct attribute_group *connector_dev_groups[] = {
  * @connector: connector to add
  *
  * Create a connector device in sysfs, along with its associated connector
- * properties (so far, connection status, dpms, mode list & edid) and
+ * properties (so far, connection status, dpms, mode list and edid) and
  * generate a hotplug event so userspace knows there's a new connector
  * available.
  */
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
index eecbc2f43f55..1eb4a52cad8d 100644
--- a/include/drm/drm_auth.h
+++ b/include/drm/drm_auth.h
@@ -43,18 +43,18 @@ struct drm_master {
 	struct kref refcount;
 	struct drm_device *dev;
 	/**
-	 * @unique: Unique identifier: e.g. busid. Protected by struct
-	 * &drm_device master_mutex.
+	 * @unique: Unique identifier: e.g. busid. Protected by
+	 * &drm_device.master_mutex.
 	 */
 	char *unique;
 	/**
-	 * @unique_len: Length of unique field. Protected by &struct drm_device
-	 * master_mutex.
+	 * @unique_len: Length of unique field. Protected by
+	 * &drm_device.master_mutex.
 	 */
 	int unique_len;
 	/**
-	 * @magic_map: Map of used authentication tokens. Protected by struct
-	 * &drm_device master_mutex.
+	 * @magic_map: Map of used authentication tokens. Protected by
+	 * &drm_device.master_mutex.
 	 */
 	struct idr magic_map;
 	struct drm_lock_data lock;
diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index c4fc49583dc0..cd764fa267fc 100644
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -282,7 +282,7 @@ struct drm_driver {
 	/**
 	 * @gem_free_object_unlocked: deconstructor for drm_gem_objects
 	 *
-	 * This is for drivers which are not encumbered with dev->struct_mutex
+	 * This is for drivers which are not encumbered with &drm_device.struct_mutex
 	 * legacy locking schemes. Use this hook instead of @gem_free_object.
 	 */
 	void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
diff --git a/include/drm/drm_irq.h b/include/drm/drm_irq.h
index 18cfd11307e1..2fb880462a57 100644
--- a/include/drm/drm_irq.h
+++ b/include/drm/drm_irq.h
@@ -67,7 +67,7 @@ struct drm_vblank_crtc {
 	 * @disable_timer: Disable timer for the delayed vblank disabling
 	 * hysteresis logic. Vblank disabling is controlled through the
 	 * drm_vblank_offdelay module option and the setting of the
-	 * max_vblank_count value in the &drm_device structure.
+	 * &drm_device.max_vblank_count value.
 	 */
 	struct timer_list disable_timer;
 
@@ -92,7 +92,7 @@ struct drm_vblank_crtc {
 	 */
 	atomic_t refcount;		/* number of users of vblank interruptsper crtc */
 	/**
-	 * @last: Protected by dev->vbl_lock, used for wraparound handling.
+	 * @last: Protected by &drm_device.vbl_lock, used for wraparound handling.
 	 */
 	u32 last;
 	/**
-- 
2.7.4

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

✗ Fi.CI.BAT: failure for series starting with [01/17] drm/docs: Small cleanup in drm-uapi.rst

[Patchwork]

== Series Details ==

Series: series starting with [01/17] drm/docs: Small cleanup in drm-uapi.rst
URL   : https://patchwork.freedesktop.org/series/17280/
State : failure

== Summary ==

Series 17280v1 Series without cover letter
https://patchwork.freedesktop.org/api/1.0/series/17280/revisions/1/mbox/

Test gem_busy:
        Subgroup basic-hang-default:
                pass       -> FAIL       (fi-hsw-4770r)
Test kms_force_connector_basic:
        Subgroup force-connector-state:
                pass       -> SKIP       (fi-snb-2520m)
Test pm_rpm:
        Subgroup basic-pci-d3-state:
                incomplete -> PASS       (fi-byt-n2820)

fi-bdw-5557u     total:246  pass:232  dwarn:0   dfail:0   fail:0   skip:14 
fi-bsw-n3050     total:246  pass:207  dwarn:0   dfail:0   fail:0   skip:39 
fi-bxt-j4205     total:246  pass:224  dwarn:0   dfail:0   fail:0   skip:22 
fi-bxt-t5700     total:82   pass:69   dwarn:0   dfail:0   fail:0   skip:12 
fi-byt-j1900     total:246  pass:219  dwarn:0   dfail:0   fail:0   skip:27 
fi-byt-n2820     total:246  pass:215  dwarn:0   dfail:0   fail:0   skip:31 
fi-hsw-4770      total:246  pass:227  dwarn:0   dfail:0   fail:0   skip:19 
fi-hsw-4770r     total:246  pass:226  dwarn:0   dfail:0   fail:1   skip:19 
fi-ivb-3520m     total:246  pass:225  dwarn:0   dfail:0   fail:0   skip:21 
fi-ivb-3770      total:246  pass:225  dwarn:0   dfail:0   fail:0   skip:21 
fi-kbl-7500u     total:246  pass:225  dwarn:0   dfail:0   fail:0   skip:21 
fi-skl-6260u     total:246  pass:233  dwarn:0   dfail:0   fail:0   skip:13 
fi-skl-6700hq    total:246  pass:226  dwarn:0   dfail:0   fail:0   skip:20 
fi-skl-6700k     total:246  pass:222  dwarn:3   dfail:0   fail:0   skip:21 
fi-skl-6770hq    total:246  pass:233  dwarn:0   dfail:0   fail:0   skip:13 
fi-snb-2520m     total:246  pass:214  dwarn:0   dfail:0   fail:0   skip:32 
fi-snb-2600      total:246  pass:214  dwarn:0   dfail:0   fail:0   skip:32 

584adc8f6687d7f6832ce060c3f6022282119f18 drm-tip: 2016y-12m-28d-13h-55m-14s UTC integration manifest
af82ef6 drm/core: Use recommened kerneldoc for struct member refs
d634e8f drm/gem|prime|mm: Use recommened kerneldoc for struct member refs
ff5204b drm/kms-core: Use recommened kerneldoc for struct member refs
9a415fa drm/cma-helpers: Use recommened kerneldoc for struct member refs
e79e7b5 drm/bridge: Use recommened kerneldoc for struct member refs
8691c35 drm/kms-helpers: Use recommened kerneldoc for struct member refs
9b6a09f drm/cma-helper: simplify setup for drivers with ->dirty callbacks
3d08675 drm/atomic-helpers: Remove outdated comment
f7bc5ea drm/rect: Fix formatting of example code
a0cde21 drm/doc: Update styleguide
c75289d drm: Nuke connector_list locking assert
97396f5 drm/doc: use preferred struct reference in kernel-doc
c213cc7 dma-buf: Use recommended structure member reference
f72696e dma-buf: use preferred struct reference in kernel-doc
effd65b drm/mm: Some doc polish
ad5c521 drm/doc: link style-guide to doc-guide
00dccc7 drm/docs: Small cleanup in drm-uapi.rst

== Logs ==

For more details see: https://intel-gfx-ci.01.org/CI/Patchwork_3404/
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 07/17] drm: Nuke connector_list locking assert

[Sean Paul]

On Thu, Dec 29, 2016 at 3:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> I've forgotten to remove this when revamping the
> connector_list locking.
>
> Cc: seanpaul@chromium.org

Reviewed-by: Sean Paul <seanpaul@chromium.org>

> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  include/drm/drm_connector.h |  6 +-----
>  include/drm/drm_crtc.h      | 14 --------------
>  2 files changed, 1 insertion(+), 19 deletions(-)
>
> diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
> index acb4241bff7d..d489cc003b7e 100644
> --- a/include/drm/drm_connector.h
> +++ b/include/drm/drm_connector.h
> @@ -875,11 +875,7 @@ void drm_mode_put_tile_group(struct drm_device *dev,
>   * deprecated. Use drm_for_each_connector_iter() instead.
>   */
>  #define drm_for_each_connector(connector, dev) \
> -       for (assert_drm_connector_list_read_locked(&(dev)->mode_config),        \
> -            connector = list_first_entry(&(dev)->mode_config.connector_list,   \
> -                                         struct drm_connector, head);          \
> -            &connector->head != (&(dev)->mode_config.connector_list);          \
> -            connector = list_next_entry(connector, head))
> +       list_for_each_entry(connector, &(dev)->mode_config.connector_list, head)
>
>  /**
>   * struct drm_connector_list_iter - connector_list iterator
> diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> index 0b9ec7245c7e..c0817fa205d4 100644
> --- a/include/drm/drm_crtc.h
> +++ b/include/drm/drm_crtc.h
> @@ -835,18 +835,4 @@ static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
>  #define drm_for_each_crtc(crtc, dev) \
>         list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)
>
> -static inline void
> -assert_drm_connector_list_read_locked(struct drm_mode_config *mode_config)
> -{
> -       /*
> -        * The connector hotadd/remove code currently grabs both locks when
> -        * updating lists. Hence readers need only hold either of them to be
> -        * safe and the check amounts to
> -        *
> -        * WARN_ON(not_holding(A) && not_holding(B)).
> -        */
> -       WARN_ON(!mutex_is_locked(&mode_config->mutex) &&
> -               !drm_modeset_is_locked(&mode_config->connection_mutex));
> -}
> -
>  #endif /* __DRM_CRTC_H__ */
> --
> 2.7.4
>



-- 
Sean Paul, Software Engineer, Google / Chromium OS
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst

[David Herrmann]

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
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 03/17] drm/mm: Some doc polish

[David Herrmann]

Hi

On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 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(-)

I liked the "DRM Roaster" more than the "Roster"!

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

Thanks
David

> 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.
>   *
> --
> 2.7.4
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc

[David Herrmann]

Hi

On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 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(-)

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

Thanks
David

> 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)       \
> --
> 2.7.4
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 10/17] drm/atomic-helpers: Remove outdated comment

[David Herrmann]

Hi

On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> We forgot to clean this up when adding connector refcounting.
>
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
>  drivers/gpu/drm/drm_atomic_helper.c | 5 -----
>  1 file changed, 5 deletions(-)

Patch 1-10 all:

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

Thanks
David

> diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c
> index 8eab8944c736..5e5224460042 100644
> --- a/drivers/gpu/drm/drm_atomic_helper.c
> +++ b/drivers/gpu/drm/drm_atomic_helper.c
> @@ -3286,11 +3286,6 @@ EXPORT_SYMBOL(drm_atomic_helper_duplicate_state);
>  void
>  __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
>  {
> -       /*
> -        * This is currently a placeholder so that drivers that subclass the
> -        * state will automatically do the right thing if code is ever added
> -        * to this function.
> -        */
>         if (state->crtc)
>                 drm_connector_unreference(state->connector);
>  }
> --
> 2.7.4
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc

[Daniel Vetter]

On Fri, Dec 30, 2016 at 12:16:17PM +0100, David Herrmann wrote:
> Hi
> 
> On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > 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(-)
> 
> Reviewed-by: David Herrmann <dh.herrmann@gmail.com>

Merged up to this patch, thanks for the review.

Now, lunch!
-Daniel

> 
> Thanks
> David
> 
> > 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)       \
> > --
> > 2.7.4
> >
> > _______________________________________________
> > dri-devel mailing list
> > dri-devel@lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 10/17] drm/atomic-helpers: Remove outdated comment

[Daniel Vetter]

On Fri, Dec 30, 2016 at 12:18:33PM +0100, David Herrmann wrote:
> Hi
> 
> On Thu, Dec 29, 2016 at 9:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > We forgot to clean this up when adding connector refcounting.
> >
> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > ---
> >  drivers/gpu/drm/drm_atomic_helper.c | 5 -----
> >  1 file changed, 5 deletions(-)
> 
> Patch 1-10 all:
> 
> Reviewed-by: David Herrmann <dh.herrmann@gmail.com>

All applied, thanks a lot for your review.
-Daniel

> 
> Thanks
> David
> 
> > diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c
> > index 8eab8944c736..5e5224460042 100644
> > --- a/drivers/gpu/drm/drm_atomic_helper.c
> > +++ b/drivers/gpu/drm/drm_atomic_helper.c
> > @@ -3286,11 +3286,6 @@ EXPORT_SYMBOL(drm_atomic_helper_duplicate_state);
> >  void
> >  __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
> >  {
> > -       /*
> > -        * This is currently a placeholder so that drivers that subclass the
> > -        * state will automatically do the right thing if code is ever added
> > -        * to this function.
> > -        */
> >         if (state->crtc)
> >                 drm_connector_unreference(state->connector);
> >  }
> > --
> > 2.7.4
> >
> > _______________________________________________
> > dri-devel mailing list
> > dri-devel@lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Thursday 29 Dec 2016 21:48:31 Daniel Vetter wrote:
> 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>

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.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,

-- 
Regards,

Laurent Pinchart

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

Re: [PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Thursday 29 Dec 2016 21:48:34 Daniel Vetter wrote:
> 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

Doesn't this belong to a different patch ?

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

How about s/DRM driver's // here and below ? It's kind of redundant now that 
you reference drm_driver directly, and some of the functions already don't 
mention "DRM driver's" in their documentation.

Apart from that,

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

>   */
>  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)
>  {

-- 
Regards,

Laurent Pinchart

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

Re: [PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

On Fri, Dec 30, 2016 at 04:11:44PM +0200, Laurent Pinchart wrote:
> Hi Daniel,
> 
> Thank you for the patch.
> 
> On Thursday 29 Dec 2016 21:48:34 Daniel Vetter wrote:
> > 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
> 
> Doesn't this belong to a different patch ?


Yup, that shoudl have been in the previous cma patch. I moved it while
applying.

> 
> >   * 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.
> 
> How about s/DRM driver's // here and below ? It's kind of redundant now that 
> you reference drm_driver directly, and some of the functions already don't 
> mention "DRM driver's" in their documentation.

Yeah, good idea. I did that while applying, and in doing so noticed 3 more
cases where we can replace a prose reference with a proper one.

> Apart from that,
> 
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Thanks for the review, both cma patches applied.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs

[Archit Taneja]

On 12/30/2016 2:18 AM, Daniel Vetter wrote:
> 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: Archit Taneja <architt@codeaurora.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/gpu/drm/drm_bridge.c | 27 +++++++++++--------------
>  include/drm/drm_bridge.h     | 48 +++++++++++++++++++++++++-------------------
>  2 files changed, 39 insertions(+), 36 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index ae5e57ad718c..86a7637ba344 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -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 &drm_bridge.next pointer.
>   *
>   * Both legacy CRTC helpers and the new atomic modeset helpers support bridges.
>   */
> @@ -179,7 +179,7 @@ void drm_bridge_detach(struct drm_bridge *bridge)
>   * @mode: desired mode to be set for the bridge
>   * @adjusted_mode: updated mode that works for this bridge
>   *
> - * Calls ->mode_fixup() &drm_bridge_funcs op for all the bridges in the
> + * Calls &drm_bridge_funcs.mode_fixup for all the bridges in the
>   * encoder chain, starting from the first bridge to the last.
>   *
>   * Note: the bridge passed should be the one closest to the encoder
> @@ -206,11 +206,10 @@ bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
>  EXPORT_SYMBOL(drm_bridge_mode_fixup);
>
>  /**
> - * drm_bridge_disable - calls ->disable() &drm_bridge_funcs op for all
> - *			bridges in the encoder chain.
> + * drm_bridge_disable - disables all bridges in the encoder chain
>   * @bridge: bridge control structure
>   *
> - * Calls ->disable() &drm_bridge_funcs op for all the bridges in the encoder
> + * Calls &drm_bridge_funcs.disable op for all the bridges in the encoder
>   * chain, starting from the last bridge to the first. These are called before
>   * calling the encoder's prepare op.
>   *
> @@ -229,11 +228,10 @@ void drm_bridge_disable(struct drm_bridge *bridge)
>  EXPORT_SYMBOL(drm_bridge_disable);
>
>  /**
> - * drm_bridge_post_disable - calls ->post_disable() &drm_bridge_funcs op for
> - *			     all bridges in the encoder chain.
> + * drm_bridge_post_disable - cleans up after disabling all bridges in the encoder chain
>   * @bridge: bridge control structure
>   *
> - * Calls ->post_disable() &drm_bridge_funcs op for all the bridges in the
> + * Calls &drm_bridge_funcs.post_disable op for all the bridges in the
>   * encoder chain, starting from the first bridge to the last. These are called
>   * after completing the encoder's prepare op.
>   *
> @@ -258,7 +256,7 @@ EXPORT_SYMBOL(drm_bridge_post_disable);
>   * @mode: desired mode to be set for the bridge
>   * @adjusted_mode: updated mode that works for this bridge
>   *
> - * Calls ->mode_set() &drm_bridge_funcs op for all the bridges in the
> + * Calls &drm_bridge_funcs.mode_set op for all the bridges in the
>   * encoder chain, starting from the first bridge to the last.
>   *
>   * Note: the bridge passed should be the one closest to the encoder
> @@ -278,11 +276,11 @@ void drm_bridge_mode_set(struct drm_bridge *bridge,
>  EXPORT_SYMBOL(drm_bridge_mode_set);
>
>  /**
> - * drm_bridge_pre_enable - calls ->pre_enable() &drm_bridge_funcs op for all
> - *			   bridges in the encoder chain.
> + * drm_bridge_pre_enable - prepares for enabling all
> + *			   bridges in the encoder chain
>   * @bridge: bridge control structure
>   *
> - * Calls ->pre_enable() &drm_bridge_funcs op for all the bridges in the encoder
> + * Calls &drm_bridge_funcs.pre_enable op for all the bridges in the encoder
>   * chain, starting from the last bridge to the first. These are called
>   * before calling the encoder's commit op.
>   *
> @@ -301,11 +299,10 @@ void drm_bridge_pre_enable(struct drm_bridge *bridge)
>  EXPORT_SYMBOL(drm_bridge_pre_enable);
>
>  /**
> - * drm_bridge_enable - calls ->enable() &drm_bridge_funcs op for all bridges
> - *		       in the encoder chain.
> + * drm_bridge_enable - enables all bridges in the encoder chain
>   * @bridge: bridge control structure
>   *
> - * Calls ->enable() &drm_bridge_funcs op for all the bridges in the encoder
> + * Calls &drm_bridge_funcs.enable op for all the bridges in the encoder
>   * chain, starting from the first bridge to the last. These are called
>   * after completing the encoder's commit op.
>   *
> diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
> index d3ca16f4da8f..1595a57dfbf2 100644
> --- a/include/drm/drm_bridge.h
> +++ b/include/drm/drm_bridge.h
> @@ -87,18 +87,19 @@ struct drm_bridge_funcs {
>  	 * True if an acceptable configuration is possible, false if the modeset
>  	 * operation should be rejected.
>  	 */
> -	bool (*mode_fixup)(struct drm_bridge *bridge,
> -			   const struct drm_display_mode *mode,
> -			   struct drm_display_mode *adjusted_mode);
> +	bool (*mode_fixup)(struct drm_bridge *bridge, const struct
> +			   drm_display_mode *mode, struct drm_display_mode
> +			   *adjusted_mode);

The change above doesn't seem to help with anything. Otherwise:

Reviewed-by: Archit Taneja <architt@codeaurora.org>

>  	/**
>  	 * @disable:
>  	 *
>  	 * This callback should disable the bridge. It is called right before
>  	 * the preceding element in the display pipe is disabled. If the
>  	 * 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.
> +	 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
> +	 * it's called right before the &drm_encoder_helper_funcs.disable,
> +	 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
> +	 * hook.
>  	 *
>  	 * The bridge can assume that the display pipe (i.e. clocks and timing
>  	 * signals) feeding it is still running when this callback is called.
> @@ -110,12 +111,13 @@ struct drm_bridge_funcs {
>  	/**
>  	 * @post_disable:
>  	 *
> -	 * This callback should disable the bridge. It is called right after
> -	 * the preceding element in the display pipe is disabled. If the
> -	 * 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.
> +	 * This callback should disable the bridge. It is called right after the
> +	 * preceding element in the display pipe is disabled. If the 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
> +	 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
> +	 * or &drm_encoder_helper_funcs.dpms hook.
>  	 *
>  	 * The bridge must assume that the display pipe (i.e. clocks and timing
>  	 * singals) feeding it is no longer running when this callback is
> @@ -129,9 +131,11 @@ struct drm_bridge_funcs {
>  	 * @mode_set:
>  	 *
>  	 * This callback should set the given mode on the bridge. It is called
> -	 * after the ->mode_set() callback for the preceding element in the
> -	 * display pipeline has been called already. The display pipe (i.e.
> -	 * clocks and timing signals) is off when this function is called.
> +	 * after the @mode_set callback for the preceding element in the display
> +	 * pipeline has been called already. If the bridge is the first element
> +	 * then this would be &drm_encoder_helper_funcs.mode_set. The display
> +	 * pipe (i.e.  clocks and timing signals) is off when this function is
> +	 * called.
>  	 */
>  	void (*mode_set)(struct drm_bridge *bridge,
>  			 struct drm_display_mode *mode,
> @@ -142,9 +146,10 @@ struct drm_bridge_funcs {
>  	 * This callback should enable the bridge. It is called right before
>  	 * the preceding element in the display pipe is enabled. If the
>  	 * 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.
> +	 * bridge's @pre_enable function. If the preceding element is a
> +	 * &drm_encoder it's called right before the encoder's
> +	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
> +	 * &drm_encoder_helper_funcs.dpms hook.
>  	 *
>  	 * 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
> @@ -161,9 +166,10 @@ struct drm_bridge_funcs {
>  	 * This callback should enable the bridge. It is called right after
>  	 * the preceding element in the display pipe is enabled. If the
>  	 * 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.
> +	 * bridge's @enable function. If the preceding element is a
> +	 * &drm_encoder it's called right after the encoder's
> +	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
> +	 * &drm_encoder_helper_funcs.dpms hook.
>  	 *
>  	 * The bridge can assume that the display pipe (i.e. clocks and timing
>  	 * signals) feeding it is running when this callback is called. This
>

-- 
Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
a Linux Foundation Collaborative Project
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst

[Tomeu Vizoso]

On 30 December 2016 at 12:12, David Herrmann <dh.herrmann@gmail.com> wrote:
> 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>

Reviewed-by: Tomeu Vizoso <tomeu.vizoso@collabora.com>

Regards,

Tomeu

>
> 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
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs

[Daniel Vetter]

On Mon, Jan 02, 2017 at 11:53:03AM +0530, Archit Taneja wrote:
> 
> 
> On 12/30/2016 2:18 AM, Daniel Vetter wrote:
> > 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: Archit Taneja <architt@codeaurora.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/gpu/drm/drm_bridge.c | 27 +++++++++++--------------
> >  include/drm/drm_bridge.h     | 48 +++++++++++++++++++++++++-------------------
> >  2 files changed, 39 insertions(+), 36 deletions(-)
> > 
> > diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> > index ae5e57ad718c..86a7637ba344 100644
> > --- a/drivers/gpu/drm/drm_bridge.c
> > +++ b/drivers/gpu/drm/drm_bridge.c
> > @@ -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 &drm_bridge.next pointer.
> >   *
> >   * Both legacy CRTC helpers and the new atomic modeset helpers support bridges.
> >   */
> > @@ -179,7 +179,7 @@ void drm_bridge_detach(struct drm_bridge *bridge)
> >   * @mode: desired mode to be set for the bridge
> >   * @adjusted_mode: updated mode that works for this bridge
> >   *
> > - * Calls ->mode_fixup() &drm_bridge_funcs op for all the bridges in the
> > + * Calls &drm_bridge_funcs.mode_fixup for all the bridges in the
> >   * encoder chain, starting from the first bridge to the last.
> >   *
> >   * Note: the bridge passed should be the one closest to the encoder
> > @@ -206,11 +206,10 @@ bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
> >  EXPORT_SYMBOL(drm_bridge_mode_fixup);
> > 
> >  /**
> > - * drm_bridge_disable - calls ->disable() &drm_bridge_funcs op for all
> > - *			bridges in the encoder chain.
> > + * drm_bridge_disable - disables all bridges in the encoder chain
> >   * @bridge: bridge control structure
> >   *
> > - * Calls ->disable() &drm_bridge_funcs op for all the bridges in the encoder
> > + * Calls &drm_bridge_funcs.disable op for all the bridges in the encoder
> >   * chain, starting from the last bridge to the first. These are called before
> >   * calling the encoder's prepare op.
> >   *
> > @@ -229,11 +228,10 @@ void drm_bridge_disable(struct drm_bridge *bridge)
> >  EXPORT_SYMBOL(drm_bridge_disable);
> > 
> >  /**
> > - * drm_bridge_post_disable - calls ->post_disable() &drm_bridge_funcs op for
> > - *			     all bridges in the encoder chain.
> > + * drm_bridge_post_disable - cleans up after disabling all bridges in the encoder chain
> >   * @bridge: bridge control structure
> >   *
> > - * Calls ->post_disable() &drm_bridge_funcs op for all the bridges in the
> > + * Calls &drm_bridge_funcs.post_disable op for all the bridges in the
> >   * encoder chain, starting from the first bridge to the last. These are called
> >   * after completing the encoder's prepare op.
> >   *
> > @@ -258,7 +256,7 @@ EXPORT_SYMBOL(drm_bridge_post_disable);
> >   * @mode: desired mode to be set for the bridge
> >   * @adjusted_mode: updated mode that works for this bridge
> >   *
> > - * Calls ->mode_set() &drm_bridge_funcs op for all the bridges in the
> > + * Calls &drm_bridge_funcs.mode_set op for all the bridges in the
> >   * encoder chain, starting from the first bridge to the last.
> >   *
> >   * Note: the bridge passed should be the one closest to the encoder
> > @@ -278,11 +276,11 @@ void drm_bridge_mode_set(struct drm_bridge *bridge,
> >  EXPORT_SYMBOL(drm_bridge_mode_set);
> > 
> >  /**
> > - * drm_bridge_pre_enable - calls ->pre_enable() &drm_bridge_funcs op for all
> > - *			   bridges in the encoder chain.
> > + * drm_bridge_pre_enable - prepares for enabling all
> > + *			   bridges in the encoder chain
> >   * @bridge: bridge control structure
> >   *
> > - * Calls ->pre_enable() &drm_bridge_funcs op for all the bridges in the encoder
> > + * Calls &drm_bridge_funcs.pre_enable op for all the bridges in the encoder
> >   * chain, starting from the last bridge to the first. These are called
> >   * before calling the encoder's commit op.
> >   *
> > @@ -301,11 +299,10 @@ void drm_bridge_pre_enable(struct drm_bridge *bridge)
> >  EXPORT_SYMBOL(drm_bridge_pre_enable);
> > 
> >  /**
> > - * drm_bridge_enable - calls ->enable() &drm_bridge_funcs op for all bridges
> > - *		       in the encoder chain.
> > + * drm_bridge_enable - enables all bridges in the encoder chain
> >   * @bridge: bridge control structure
> >   *
> > - * Calls ->enable() &drm_bridge_funcs op for all the bridges in the encoder
> > + * Calls &drm_bridge_funcs.enable op for all the bridges in the encoder
> >   * chain, starting from the first bridge to the last. These are called
> >   * after completing the encoder's commit op.
> >   *
> > diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
> > index d3ca16f4da8f..1595a57dfbf2 100644
> > --- a/include/drm/drm_bridge.h
> > +++ b/include/drm/drm_bridge.h
> > @@ -87,18 +87,19 @@ struct drm_bridge_funcs {
> >  	 * True if an acceptable configuration is possible, false if the modeset
> >  	 * operation should be rejected.
> >  	 */
> > -	bool (*mode_fixup)(struct drm_bridge *bridge,
> > -			   const struct drm_display_mode *mode,
> > -			   struct drm_display_mode *adjusted_mode);
> > +	bool (*mode_fixup)(struct drm_bridge *bridge, const struct
> > +			   drm_display_mode *mode, struct drm_display_mode
> > +			   *adjusted_mode);
> 
> The change above doesn't seem to help with anything. Otherwise:

Indeed, that shouldn't have been there, I removed it while applying.

> Reviewed-by: Archit Taneja <architt@codeaurora.org>

Thanks a lot for your review.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel