* [PATCH 02/17] drm/doc: link style-guide to doc-guide
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 03/17] drm/mm: Some doc polish Daniel Vetter
` (16 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 03/17] drm/mm: Some doc polish
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
2016-12-29 20:48 ` [PATCH 02/17] drm/doc: link style-guide to doc-guide Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-30 11:15 ` David Herrmann
2016-12-29 20:48 ` [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc Daniel Vetter
` (15 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 03/17] drm/mm: Some doc polish
2016-12-29 20:48 ` [PATCH 03/17] drm/mm: Some doc polish Daniel Vetter
@ 2016-12-30 11:15 ` David Herrmann
0 siblings, 0 replies; 31+ messages in thread
From: David Herrmann @ 2016-12-30 11:15 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
2016-12-29 20:48 ` [PATCH 02/17] drm/doc: link style-guide to doc-guide Daniel Vetter
2016-12-29 20:48 ` [PATCH 03/17] drm/mm: Some doc polish Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-30 11:16 ` David Herrmann
2016-12-29 20:48 ` [PATCH 05/17] dma-buf: Use recommended structure member reference Daniel Vetter
` (14 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development, 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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc
2016-12-29 20:48 ` [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc Daniel Vetter
@ 2016-12-30 11:16 ` David Herrmann
2016-12-30 11:55 ` Daniel Vetter
0 siblings, 1 reply; 31+ messages in thread
From: David Herrmann @ 2016-12-30 11:16 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc
2016-12-30 11:16 ` David Herrmann
@ 2016-12-30 11:55 ` Daniel Vetter
0 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-30 11:55 UTC (permalink / raw)
To: David Herrmann
Cc: Daniel Vetter, Intel Graphics Development, DRI Development,
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 05/17] dma-buf: Use recommended structure member reference
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (2 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 04/17] dma-buf: use preferred struct reference in kernel-doc Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 06/17] drm/doc: use preferred struct reference in kernel-doc Daniel Vetter
` (13 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development, 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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 06/17] drm/doc: use preferred struct reference in kernel-doc
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (3 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 05/17] dma-buf: Use recommended structure member reference Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 07/17] drm: Nuke connector_list locking assert Daniel Vetter
` (12 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 07/17] drm: Nuke connector_list locking assert
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (4 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 06/17] drm/doc: use preferred struct reference in kernel-doc Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 22:35 ` Sean Paul
2016-12-29 20:48 ` [PATCH 08/17] drm/doc: Update styleguide Daniel Vetter
` (11 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development, 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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 07/17] drm: Nuke connector_list locking assert
2016-12-29 20:48 ` [PATCH 07/17] drm: Nuke connector_list locking assert Daniel Vetter
@ 2016-12-29 22:35 ` Sean Paul
0 siblings, 0 replies; 31+ messages in thread
From: Sean Paul @ 2016-12-29 22:35 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 08/17] drm/doc: Update styleguide
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (5 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 07/17] drm: Nuke connector_list locking assert Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 09/17] drm/rect: Fix formatting of example code Daniel Vetter
` (10 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 09/17] drm/rect: Fix formatting of example code
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (6 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 08/17] drm/doc: Update styleguide Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 10/17] drm/atomic-helpers: Remove outdated comment Daniel Vetter
` (9 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 10/17] drm/atomic-helpers: Remove outdated comment
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (7 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 09/17] drm/rect: Fix formatting of example code Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-30 11:18 ` David Herrmann
2016-12-29 20:48 ` [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks Daniel Vetter
` (8 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 10/17] drm/atomic-helpers: Remove outdated comment
2016-12-29 20:48 ` [PATCH 10/17] drm/atomic-helpers: Remove outdated comment Daniel Vetter
@ 2016-12-30 11:18 ` David Herrmann
2016-12-30 12:48 ` Daniel Vetter
0 siblings, 1 reply; 31+ messages in thread
From: David Herrmann @ 2016-12-30 11:18 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 10/17] drm/atomic-helpers: Remove outdated comment
2016-12-30 11:18 ` David Herrmann
@ 2016-12-30 12:48 ` Daniel Vetter
0 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-30 12:48 UTC (permalink / raw)
To: David Herrmann; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (8 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 10/17] drm/atomic-helpers: Remove outdated comment Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-30 13:44 ` Laurent Pinchart
2016-12-29 20:48 ` [PATCH 12/17] drm/kms-helpers: Use recommened kerneldoc for struct member refs Daniel Vetter
` (7 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development
Cc: Daniel Vetter, Intel Graphics Development, Noralf Trønnes,
Laurent Pinchart, 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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks
2016-12-29 20:48 ` [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks Daniel Vetter
@ 2016-12-30 13:44 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2016-12-30 13:44 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 12/17] drm/kms-helpers: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (9 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 11/17] drm/cma-helper: simplify setup for drivers with ->dirty callbacks Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 13/17] drm/bridge: " Daniel Vetter
` (6 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (10 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 12/17] drm/kms-helpers: Use recommened kerneldoc for struct member refs Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2017-01-02 6:23 ` Archit Taneja
2016-12-29 20:48 ` [PATCH 14/17] drm/cma-helpers: " Daniel Vetter
` (5 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development
Cc: Archit Taneja, Daniel Vetter, Intel Graphics Development, 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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 ` [PATCH 13/17] drm/bridge: " Daniel Vetter
@ 2017-01-02 6:23 ` Archit Taneja
2017-01-02 8:18 ` Daniel Vetter
0 siblings, 1 reply; 31+ messages in thread
From: Archit Taneja @ 2017-01-02 6:23 UTC (permalink / raw)
To: Daniel Vetter, DRI Development; +Cc: Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs
2017-01-02 6:23 ` Archit Taneja
@ 2017-01-02 8:18 ` Daniel Vetter
0 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2017-01-02 8:18 UTC (permalink / raw)
To: Archit Taneja
Cc: Daniel Vetter, Intel Graphics Development, DRI Development,
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (11 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 13/17] drm/bridge: " Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-30 14:11 ` Laurent Pinchart
2016-12-29 20:48 ` [PATCH 15/17] drm/kms-core: " Daniel Vetter
` (4 subsequent siblings)
17 siblings, 1 reply; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development
Cc: Daniel Vetter, Intel Graphics Development, Laurent Pinchart,
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 ` [PATCH 14/17] drm/cma-helpers: " Daniel Vetter
@ 2016-12-30 14:11 ` Laurent Pinchart
2016-12-30 17:00 ` Daniel Vetter
0 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2016-12-30 14:11 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 14/17] drm/cma-helpers: Use recommened kerneldoc for struct member refs
2016-12-30 14:11 ` Laurent Pinchart
@ 2016-12-30 17:00 ` Daniel Vetter
0 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-30 17:00 UTC (permalink / raw)
To: Laurent Pinchart
Cc: Daniel Vetter, Intel Graphics Development, DRI Development,
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
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 15/17] drm/kms-core: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (12 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 14/17] drm/cma-helpers: " Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 16/17] drm/gem|prime|mm: " Daniel Vetter
` (3 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 16/17] drm/gem|prime|mm: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (13 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 15/17] drm/kms-core: " Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 20:48 ` [PATCH 17/17] drm/core: " Daniel Vetter
` (2 subsequent siblings)
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH 17/17] drm/core: Use recommened kerneldoc for struct member refs
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (14 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 16/17] drm/gem|prime|mm: " Daniel Vetter
@ 2016-12-29 20:48 ` Daniel Vetter
2016-12-29 21:23 ` ✗ Fi.CI.BAT: failure for series starting with [01/17] drm/docs: Small cleanup in drm-uapi.rst Patchwork
2016-12-30 11:12 ` [PATCH 01/17] " David Herrmann
17 siblings, 0 replies; 31+ messages in thread
From: Daniel Vetter @ 2016-12-29 20:48 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply related [flat|nested] 31+ messages in thread* ✗ Fi.CI.BAT: failure for series starting with [01/17] drm/docs: Small cleanup in drm-uapi.rst
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (15 preceding siblings ...)
2016-12-29 20:48 ` [PATCH 17/17] drm/core: " Daniel Vetter
@ 2016-12-29 21:23 ` Patchwork
2016-12-30 11:12 ` [PATCH 01/17] " David Herrmann
17 siblings, 0 replies; 31+ messages in thread
From: Patchwork @ 2016-12-29 21:23 UTC (permalink / raw)
To: Daniel Vetter; +Cc: intel-gfx
== 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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst
2016-12-29 20:48 [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
` (16 preceding siblings ...)
2016-12-29 21:23 ` ✗ Fi.CI.BAT: failure for series starting with [01/17] drm/docs: Small cleanup in drm-uapi.rst Patchwork
@ 2016-12-30 11:12 ` David Herrmann
2017-01-02 7:28 ` Tomeu Vizoso
17 siblings, 1 reply; 31+ messages in thread
From: David Herrmann @ 2016-12-30 11:12 UTC (permalink / raw)
To: Daniel Vetter
Cc: Jani Nikula, Daniel Vetter, Intel Graphics Development,
Tomeu Vizoso, DRI Development
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
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH 01/17] drm/docs: Small cleanup in drm-uapi.rst
2016-12-30 11:12 ` [PATCH 01/17] " David Herrmann
@ 2017-01-02 7:28 ` Tomeu Vizoso
0 siblings, 0 replies; 31+ messages in thread
From: Tomeu Vizoso @ 2017-01-02 7:28 UTC (permalink / raw)
To: David Herrmann
Cc: Jani Nikula, Daniel Vetter, Intel Graphics Development,
DRI Development, Daniel Vetter
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
^ permalink raw reply [flat|nested] 31+ messages in thread