[PATCH v2 0/3] drm, drm/vmwgfx: fixes and updates related to drm_master

[PATCH v2 0/3] drm, drm/vmwgfx: fixes and updates related to drm_master

[Desmond Cheong Zhi Xi]

Hi,

Just a note that only patch 2 changed from v1 to v2 of this series.

This series contains some improvements that Daniel Vetter proposed following a discussion on a recent series:
https://lore.kernel.org/lkml/20210712043508.11584-1-desmondcheongzx@gmail.com/

While preparing these patches, I also noticed some unprotected uses of drm_master in the vmwgfx driver that can be addressed by new functions from the previous series.

This series is thus broken up into three patches:

1. Switch from the outer drm_device.master_mutex to the inner drm_file.master_lookup_lock in drm_is_current_master.

2. Update the kerneldoc for drm leases to clarify usage and lifetime/locking rules.

3. Prevent potential use-after-free bugs by replacing calls to drm_master_get with drm_file_get_master in vmwgfx_surface.c.

v1 -> v2:
Changes to patch 2:
- Clarified description of lease fields in drm_master with suggestions from Daniel Vetter.
- Added an overview DOC: section for drm leases in drm-uapi.rst.
- Cleaned up function documentation in drm_lease.c to use kernel-doc formatting.

Best wishes,
Desmond

Desmond Cheong Zhi Xi (3):
  drm: use the lookup lock in drm_is_current_master
  drm: clarify usage of drm leases
  drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

 Documentation/gpu/drm-uapi.rst          |  15 ++
 drivers/gpu/drm/drm_auth.c              |   9 +-
 drivers/gpu/drm/drm_lease.c             | 182 ++++++++++++++----------
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c |   4 +-
 include/drm/drm_auth.h                  |  67 +++++++--
 5 files changed, 187 insertions(+), 90 deletions(-)

-- 
2.25.1

[PATCH v2 0/3] drm, drm/vmwgfx: fixes and updates related to drm_master

[Desmond Cheong Zhi Xi]

Hi,

Just a note that only patch 2 changed from v1 to v2 of this series.

This series contains some improvements that Daniel Vetter proposed following a discussion on a recent series:
https://lore.kernel.org/lkml/20210712043508.11584-1-desmondcheongzx@gmail.com/

While preparing these patches, I also noticed some unprotected uses of drm_master in the vmwgfx driver that can be addressed by new functions from the previous series.

This series is thus broken up into three patches:

1. Switch from the outer drm_device.master_mutex to the inner drm_file.master_lookup_lock in drm_is_current_master.

2. Update the kerneldoc for drm leases to clarify usage and lifetime/locking rules.

3. Prevent potential use-after-free bugs by replacing calls to drm_master_get with drm_file_get_master in vmwgfx_surface.c.

v1 -> v2:
Changes to patch 2:
- Clarified description of lease fields in drm_master with suggestions from Daniel Vetter.
- Added an overview DOC: section for drm leases in drm-uapi.rst.
- Cleaned up function documentation in drm_lease.c to use kernel-doc formatting.

Best wishes,
Desmond

Desmond Cheong Zhi Xi (3):
  drm: use the lookup lock in drm_is_current_master
  drm: clarify usage of drm leases
  drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

 Documentation/gpu/drm-uapi.rst          |  15 ++
 drivers/gpu/drm/drm_auth.c              |   9 +-
 drivers/gpu/drm/drm_lease.c             | 182 ++++++++++++++----------
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c |   4 +-
 include/drm/drm_auth.h                  |  67 +++++++--
 5 files changed, 187 insertions(+), 90 deletions(-)

-- 
2.25.1

[PATCH v2 0/3] drm, drm/vmwgfx: fixes and updates related to drm_master

[Desmond Cheong Zhi Xi]

Hi,

Just a note that only patch 2 changed from v1 to v2 of this series.

This series contains some improvements that Daniel Vetter proposed following a discussion on a recent series:
https://lore.kernel.org/lkml/20210712043508.11584-1-desmondcheongzx@gmail.com/

While preparing these patches, I also noticed some unprotected uses of drm_master in the vmwgfx driver that can be addressed by new functions from the previous series.

This series is thus broken up into three patches:

1. Switch from the outer drm_device.master_mutex to the inner drm_file.master_lookup_lock in drm_is_current_master.

2. Update the kerneldoc for drm leases to clarify usage and lifetime/locking rules.

3. Prevent potential use-after-free bugs by replacing calls to drm_master_get with drm_file_get_master in vmwgfx_surface.c.

v1 -> v2:
Changes to patch 2:
- Clarified description of lease fields in drm_master with suggestions from Daniel Vetter.
- Added an overview DOC: section for drm leases in drm-uapi.rst.
- Cleaned up function documentation in drm_lease.c to use kernel-doc formatting.

Best wishes,
Desmond

Desmond Cheong Zhi Xi (3):
  drm: use the lookup lock in drm_is_current_master
  drm: clarify usage of drm leases
  drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

 Documentation/gpu/drm-uapi.rst          |  15 ++
 drivers/gpu/drm/drm_auth.c              |   9 +-
 drivers/gpu/drm/drm_lease.c             | 182 ++++++++++++++----------
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c |   4 +-
 include/drm/drm_auth.h                  |  67 +++++++--
 5 files changed, 187 insertions(+), 90 deletions(-)

-- 
2.25.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Desmond Cheong Zhi Xi]

Inside drm_is_current_master, using the outer drm_device.master_mutex
to protect reads of drm_file.master makes the function prone to creating
lock hierarchy inversions. Instead, we can use the
drm_file.master_lookup_lock that sits at the bottom of the lock
hierarchy.

Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/drm_auth.c | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
index f00354bec3fb..9c24b8cc8e36 100644
--- a/drivers/gpu/drm/drm_auth.c
+++ b/drivers/gpu/drm/drm_auth.c
@@ -63,8 +63,9 @@
 
 static bool drm_is_current_master_locked(struct drm_file *fpriv)
 {
-	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
-
+	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
+	 * should be held here.
+	 */
 	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
 }
 
@@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
 {
 	bool ret;
 
-	mutex_lock(&fpriv->minor->dev->master_mutex);
+	spin_lock(&fpriv->master_lookup_lock);
 	ret = drm_is_current_master_locked(fpriv);
-	mutex_unlock(&fpriv->minor->dev->master_mutex);
+	spin_unlock(&fpriv->master_lookup_lock);
 
 	return ret;
 }
-- 
2.25.1

[Intel-gfx] [PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Desmond Cheong Zhi Xi]

Inside drm_is_current_master, using the outer drm_device.master_mutex
to protect reads of drm_file.master makes the function prone to creating
lock hierarchy inversions. Instead, we can use the
drm_file.master_lookup_lock that sits at the bottom of the lock
hierarchy.

Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/drm_auth.c | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
index f00354bec3fb..9c24b8cc8e36 100644
--- a/drivers/gpu/drm/drm_auth.c
+++ b/drivers/gpu/drm/drm_auth.c
@@ -63,8 +63,9 @@
 
 static bool drm_is_current_master_locked(struct drm_file *fpriv)
 {
-	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
-
+	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
+	 * should be held here.
+	 */
 	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
 }
 
@@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
 {
 	bool ret;
 
-	mutex_lock(&fpriv->minor->dev->master_mutex);
+	spin_lock(&fpriv->master_lookup_lock);
 	ret = drm_is_current_master_locked(fpriv);
-	mutex_unlock(&fpriv->minor->dev->master_mutex);
+	spin_unlock(&fpriv->master_lookup_lock);
 
 	return ret;
 }
-- 
2.25.1

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

[PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Desmond Cheong Zhi Xi]

Inside drm_is_current_master, using the outer drm_device.master_mutex
to protect reads of drm_file.master makes the function prone to creating
lock hierarchy inversions. Instead, we can use the
drm_file.master_lookup_lock that sits at the bottom of the lock
hierarchy.

Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/drm_auth.c | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
index f00354bec3fb..9c24b8cc8e36 100644
--- a/drivers/gpu/drm/drm_auth.c
+++ b/drivers/gpu/drm/drm_auth.c
@@ -63,8 +63,9 @@
 
 static bool drm_is_current_master_locked(struct drm_file *fpriv)
 {
-	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
-
+	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
+	 * should be held here.
+	 */
 	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
 }
 
@@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
 {
 	bool ret;
 
-	mutex_lock(&fpriv->minor->dev->master_mutex);
+	spin_lock(&fpriv->master_lookup_lock);
 	ret = drm_is_current_master_locked(fpriv);
-	mutex_unlock(&fpriv->minor->dev->master_mutex);
+	spin_unlock(&fpriv->master_lookup_lock);
 
 	return ret;
 }
-- 
2.25.1

[PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Desmond Cheong Zhi Xi]

Inside drm_is_current_master, using the outer drm_device.master_mutex
to protect reads of drm_file.master makes the function prone to creating
lock hierarchy inversions. Instead, we can use the
drm_file.master_lookup_lock that sits at the bottom of the lock
hierarchy.

Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 drivers/gpu/drm/drm_auth.c | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
index f00354bec3fb..9c24b8cc8e36 100644
--- a/drivers/gpu/drm/drm_auth.c
+++ b/drivers/gpu/drm/drm_auth.c
@@ -63,8 +63,9 @@
 
 static bool drm_is_current_master_locked(struct drm_file *fpriv)
 {
-	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
-
+	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
+	 * should be held here.
+	 */
 	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
 }
 
@@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
 {
 	bool ret;
 
-	mutex_lock(&fpriv->minor->dev->master_mutex);
+	spin_lock(&fpriv->master_lookup_lock);
 	ret = drm_is_current_master_locked(fpriv);
-	mutex_unlock(&fpriv->minor->dev->master_mutex);
+	spin_unlock(&fpriv->master_lookup_lock);
 
 	return ret;
 }
-- 
2.25.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:22PM +0800, Desmond Cheong Zhi Xi wrote:
> Inside drm_is_current_master, using the outer drm_device.master_mutex
> to protect reads of drm_file.master makes the function prone to creating
> lock hierarchy inversions. Instead, we can use the
> drm_file.master_lookup_lock that sits at the bottom of the lock
> hierarchy.
> 
> Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Applied to drm-misc-next, thanks for your patch.
-Daniel

> ---
>  drivers/gpu/drm/drm_auth.c | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
> index f00354bec3fb..9c24b8cc8e36 100644
> --- a/drivers/gpu/drm/drm_auth.c
> +++ b/drivers/gpu/drm/drm_auth.c
> @@ -63,8 +63,9 @@
>  
>  static bool drm_is_current_master_locked(struct drm_file *fpriv)
>  {
> -	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
> -
> +	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
> +	 * should be held here.
> +	 */
>  	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
>  }
>  
> @@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
>  {
>  	bool ret;
>  
> -	mutex_lock(&fpriv->minor->dev->master_mutex);
> +	spin_lock(&fpriv->master_lookup_lock);
>  	ret = drm_is_current_master_locked(fpriv);
> -	mutex_unlock(&fpriv->minor->dev->master_mutex);
> +	spin_unlock(&fpriv->master_lookup_lock);
>  
>  	return ret;
>  }
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [Intel-gfx] [PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:22PM +0800, Desmond Cheong Zhi Xi wrote:
> Inside drm_is_current_master, using the outer drm_device.master_mutex
> to protect reads of drm_file.master makes the function prone to creating
> lock hierarchy inversions. Instead, we can use the
> drm_file.master_lookup_lock that sits at the bottom of the lock
> hierarchy.
> 
> Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Applied to drm-misc-next, thanks for your patch.
-Daniel

> ---
>  drivers/gpu/drm/drm_auth.c | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
> index f00354bec3fb..9c24b8cc8e36 100644
> --- a/drivers/gpu/drm/drm_auth.c
> +++ b/drivers/gpu/drm/drm_auth.c
> @@ -63,8 +63,9 @@
>  
>  static bool drm_is_current_master_locked(struct drm_file *fpriv)
>  {
> -	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
> -
> +	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
> +	 * should be held here.
> +	 */
>  	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
>  }
>  
> @@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
>  {
>  	bool ret;
>  
> -	mutex_lock(&fpriv->minor->dev->master_mutex);
> +	spin_lock(&fpriv->master_lookup_lock);
>  	ret = drm_is_current_master_locked(fpriv);
> -	mutex_unlock(&fpriv->minor->dev->master_mutex);
> +	spin_unlock(&fpriv->master_lookup_lock);
>  
>  	return ret;
>  }
> -- 
> 2.25.1
> 

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

Re: [PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:22PM +0800, Desmond Cheong Zhi Xi wrote:
> Inside drm_is_current_master, using the outer drm_device.master_mutex
> to protect reads of drm_file.master makes the function prone to creating
> lock hierarchy inversions. Instead, we can use the
> drm_file.master_lookup_lock that sits at the bottom of the lock
> hierarchy.
> 
> Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Applied to drm-misc-next, thanks for your patch.
-Daniel

> ---
>  drivers/gpu/drm/drm_auth.c | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
> index f00354bec3fb..9c24b8cc8e36 100644
> --- a/drivers/gpu/drm/drm_auth.c
> +++ b/drivers/gpu/drm/drm_auth.c
> @@ -63,8 +63,9 @@
>  
>  static bool drm_is_current_master_locked(struct drm_file *fpriv)
>  {
> -	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
> -
> +	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
> +	 * should be held here.
> +	 */
>  	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
>  }
>  
> @@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
>  {
>  	bool ret;
>  
> -	mutex_lock(&fpriv->minor->dev->master_mutex);
> +	spin_lock(&fpriv->master_lookup_lock);
>  	ret = drm_is_current_master_locked(fpriv);
> -	mutex_unlock(&fpriv->minor->dev->master_mutex);
> +	spin_unlock(&fpriv->master_lookup_lock);
>  
>  	return ret;
>  }
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH v2 1/3] drm: use the lookup lock in drm_is_current_master

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:22PM +0800, Desmond Cheong Zhi Xi wrote:
> Inside drm_is_current_master, using the outer drm_device.master_mutex
> to protect reads of drm_file.master makes the function prone to creating
> lock hierarchy inversions. Instead, we can use the
> drm_file.master_lookup_lock that sits at the bottom of the lock
> hierarchy.
> 
> Reported-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Applied to drm-misc-next, thanks for your patch.
-Daniel

> ---
>  drivers/gpu/drm/drm_auth.c | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
> index f00354bec3fb..9c24b8cc8e36 100644
> --- a/drivers/gpu/drm/drm_auth.c
> +++ b/drivers/gpu/drm/drm_auth.c
> @@ -63,8 +63,9 @@
>  
>  static bool drm_is_current_master_locked(struct drm_file *fpriv)
>  {
> -	lockdep_assert_held_once(&fpriv->minor->dev->master_mutex);
> -
> +	/* Either drm_device.master_mutex or drm_file.master_lookup_lock
> +	 * should be held here.
> +	 */
>  	return fpriv->is_master && drm_lease_owner(fpriv->master) == fpriv->minor->dev->master;
>  }
>  
> @@ -82,9 +83,9 @@ bool drm_is_current_master(struct drm_file *fpriv)
>  {
>  	bool ret;
>  
> -	mutex_lock(&fpriv->minor->dev->master_mutex);
> +	spin_lock(&fpriv->master_lookup_lock);
>  	ret = drm_is_current_master_locked(fpriv);
> -	mutex_unlock(&fpriv->minor->dev->master_mutex);
> +	spin_unlock(&fpriv->master_lookup_lock);
>  
>  	return ret;
>  }
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking rules of lease fields in drm_master:

1. Make it clear that &drm_device.mode_config.idr_mutex protects the
lease idr and list structures for drm_master. The lessor field itself
doesn't need to be protected as it doesn't change after it's set in
drm_lease_create.

2. Add descriptions for the lifetime of lessors and leases.

3. Add an overview DOC: section in drm-uapi.rst that defines the
terminology for drm leasing, and explains how leases work and why
they're used.

4. Clean up function documentation in drm_lease.c to use kernel-doc
formatting.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
---

Hi,

After I updated the formatting for comments in drm_lease.c, I noticed
that none of these were driver interfaces (i.e. no structs/inline
functions declared in headers, and no exported symbols in .c files).

I left the kernel-doc links inside drm-uapi.rst so that if any such
interfaces are defined in the future, they'll go to the appropriate
place. But if these should be removed, or if the formatting changes for
function comments should be removed, please let me know.

Best wishes,
Desmond

 Documentation/gpu/drm-uapi.rst |  15 +++
 drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
 include/drm/drm_auth.h         |  67 ++++++++++--
 3 files changed, 180 insertions(+), 84 deletions(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 7e51dd40bf6e..6d7233a9fb14 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
 .. kernel-doc:: include/drm/drm_auth.h
    :internal:
 
+
+.. _drm_leasing:
+
+DRM Display Resource Leasing
+============================
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :doc: drm leasing
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_lease.h
+   :internal:
+
 Open-Source Userspace Requirements
 ==================================
 
diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
index 92eac73d9001..9b68617840ed 100644
--- a/drivers/gpu/drm/drm_lease.c
+++ b/drivers/gpu/drm/drm_lease.c
@@ -15,18 +15,67 @@
 #include "drm_crtc_internal.h"
 #include "drm_internal.h"
 
+/**
+ * DOC: drm leasing
+ *
+ * DRM leases provide information about whether a DRM master may control a DRM
+ * mode setting object. This enables the creation of multiple DRM masters that
+ * manage subsets of display resources.
+ *
+ * The original DRM master of a device 'owns' the available drm resources. It
+ * may create additional DRM masters and 'lease' resources which it controls
+ * to the new DRM master. This gives the new DRM master control over the
+ * leased resources until the owner revokes the lease, or the new DRM master
+ * is closed. Some helpful terminology:
+ *
+ * - An 'owner' is a &struct drm_master that is not leasing objects from
+ *   another &struct drm_master, and hence 'owns' the objects. The owner can be
+ *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
+ *
+ * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
+ *   other &struct drm_master. Currently, lessees are not allowed to
+ *   create sub-leases, hence the lessor is the same as the owner.
+ *
+ * - A 'lessee' is a &struct drm_master which is leasing objects from some
+ *   other &struct drm_master. Each lessee only leases resources from a single
+ *   lessor recorded in &drm_master.lessor, and holds the set of objects that
+ *   it is leasing in &drm_master.leases.
+ *
+ * - A 'lease' is a contract between the lessor and lessee that identifies
+ *   which resources may be controlled by the lessee. All of the resources
+ *   that are leased must be owned by or leased to the lessor, and lessors are
+ *   not permitted to lease the same object to multiple lessees.
+ *
+ * The set of objects any &struct drm_master 'controls' is limited to the set
+ * of objects it leases (for lessees) or all objects (for owners).
+ *
+ * Objects not controlled by a &struct drm_master cannot be modified through
+ * the various state manipulating ioctls, and any state reported back to user
+ * space will be edited to make them appear idle and/or unusable. For
+ * instance, connectors always report 'disconnected', while encoders
+ * report no possible crtcs or clones.
+ *
+ * Since each lessee may lease objects from a single lessor, display resource
+ * leases form a tree of &struct drm_master. As lessees are currently not
+ * allowed to create sub-leases, the tree depth is limited to 1. All of
+ * these get activated simultaneously, so &drm_device.master points to the
+ * owner at the top of the lease tree (i.e. the &struct drm_master for which
+ * &drm_master.lessor is NULL). The full list of lessees that are leasing
+ * objects from the owner can be searched via the owner's
+ * &drm_master.lessee_idr.
+ */
+
 #define drm_for_each_lessee(lessee, lessor) \
 	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
 
 static uint64_t drm_lease_idr_object;
 
 /**
- * drm_lease_owner - return ancestor owner drm_master
- * @master: drm_master somewhere within tree of lessees and lessors
- *
- * RETURN:
+ * drm_lease_owner - return the device owner in @master's lease tree
+ * @master: &struct drm_master somewhere within tree of lessees and lessors
  *
- * drm_master at the top of the tree (i.e, with lessor NULL
+ * Returns the &struct drm_master that owns the device, i.e. the &struct
+ * drm_master at the top of the tree for which &drm_master.lessor is NULL.
  */
 struct drm_master *drm_lease_owner(struct drm_master *master)
 {
@@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
 
 /**
  * _drm_find_lessee - find lessee by id (idr_mutex held)
- * @master: drm_master of lessor
- * @lessee_id: id
+ * @master: &struct drm_master of lessor
+ * @lessee_id: &drm_master.lessee_id of lessee
  *
- * RETURN:
- *
- * drm_master of the lessee if valid, NULL otherwise
+ * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
  */
 
 static struct drm_master*
@@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
 }
 
 /**
- * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * _drm_lease_held_master - check to see if an object is leased (or owned) by
+ * @master (idr_mutex held)
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @master holds a lease on (or owns) the object, false if not.
  */
 static int _drm_lease_held_master(struct drm_master *master, int id)
 {
@@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
 
 /**
  * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- * Checks if any lessee of 'master' holds a lease on 'id'. Return
- * value:
- *
- *	true		Some lessee holds a lease on the object.
- *	false		No lessee has a lease on the object.
+ * Returns true if any lessee of @master holds a lease on the given object,
+ * false if no lessee has a lease on the object.
  */
 static bool _drm_has_leased(struct drm_master *master, int id)
 {
@@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
 
 /**
  * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
- * @file_priv: the master drm_file
- * @id: the object id
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool _drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
 
 /**
  * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
- * @file_priv: the master drm_file
- * @id: the object id
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- * Checks if the specified master holds a lease on the object. Return
- * value:
- *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
 }
 
 /**
- * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
+ * drm_lease_filter_crtcs - restricted crtc set to leased values
+ * (idr_mutex not held)
  * @file_priv: requestor file
  * @crtcs_in: bitmask of crtcs to check
  *
@@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
 }
 
 /*
- * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
+ * drm_lease_create - create a new &struct drm_master with leased objects
+ * (idr_mutex not held)
  * @lessor: lease holder (or owner) of objects
  * @leases: objects to lease to the new drm_master
  *
- * Uses drm_master_create to allocate a new drm_master, then checks to
- * make sure all of the desired objects can be leased, atomically
- * leasing them to the new drmmaster.
+ * Uses drm_master_create() to allocate a new &struct drm_master, then checks
+ * to make sure all of the desired objects can be leased, atomically
+ * leasing them to the new &struct drm_master.
  *
  * 	ERR_PTR(-EACCES)	some other master holds the title to any object
  * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
@@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
 }
 
 /**
- * drm_lease_destroy - a master is going away (idr_mutex not held)
- * @master: the drm_master being destroyed
+ * drm_lease_destroy - destroy a master  (idr_mutex not held)
+ * @master: the &struct drm_master being destroyed
  *
- * All lessees will have been destroyed as they
- * hold a reference on their lessor. Notify any
- * lessor for this master so that it can check
- * the list of lessees.
+ * Destroys @master, then notifies any lessor for this master so that it can
+ * check the list of lessees. Note that all lessees of @master will have been
+ * destroyed for this function to be called as they hold a reference on their
+ * lessor.
  */
 void drm_lease_destroy(struct drm_master *master)
 {
@@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
 
 /**
  * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 static void _drm_lease_revoke(struct drm_master *top)
 {
@@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
 
 /**
  * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 void drm_lease_revoke(struct drm_master *top)
 {
@@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
 
 /**
  * drm_mode_create_lease_ioctl - create a new lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_create_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_create_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * The master associated with the specified file will have a lease
+ * The &struct drm_master associated with @lessor_priv will have a lease
  * created containing the objects specified in the ioctl structure.
  * A file descriptor will be allocated for that and returned to the
  * application.
+ *
+ * Note that creating recursive sub-leases for existing lessees is not allowed.
  */
 int drm_mode_create_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
@@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
 }
 
 /**
- * drm_mode_list_lessees_ioctl - list lessee ids
- * @dev: the drm device
- * @data: pointer to struct drm_mode_list_lessees
- * @lessor_priv: the file being manipulated
+ * drm_mode_list_lessees_ioctl - list lessee IDs
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_list_lessees
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * Starting from the master associated with the specified file,
- * the master with the provided lessee_id is found, and then
- * an array of lessee ids associated with leases from that master
- * are returned.
+ * Returns an array of &drm_master.lessee_id associated with lessees of
+ * @lessor_priv's &drm_file.master that have unrevoked leases.
  */
 
 int drm_mode_list_lessees_ioctl(struct drm_device *dev,
@@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_get_lease_ioctl - list leased objects
- * @dev: the drm device
- * @data: pointer to struct drm_mode_get_lease
- * @lessee_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_get_lease
+ * @lessee_priv: the &struct drm_file being manipulated
  *
  * Return the list of leased objects for the specified lessee
  */
@@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_revoke_lease_ioctl - revoke lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_revoke_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_revoke_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * This removes all of the objects from the lease without
- * actually getting rid of the lease itself; that way all
- * references to it still work correctly
+ * Removes all of the objects from the lessee without actually getting rid
+ * of the lessee itself; that way all references to it still work correctly.
  */
 int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
index f99d3417f304..ba248ca8866f 100644
--- a/include/drm/drm_auth.h
+++ b/include/drm/drm_auth.h
@@ -58,12 +58,6 @@ struct drm_lock_data {
  * @refcount: Refcount for this master object.
  * @dev: Link back to the DRM device
  * @driver_priv: Pointer to driver-private information.
- * @lessor: Lease holder
- * @lessee_id: id for lessees. Owners always have id 0
- * @lessee_list: other lessees of the same master
- * @lessees: drm_masters leasing from this one
- * @leases: Objects leased to this drm_master.
- * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
  *
  * Note that master structures are only relevant for the legacy/primary device
  * nodes, hence there can only be one per device, not one per drm_minor.
@@ -88,17 +82,68 @@ struct drm_master {
 	struct idr magic_map;
 	void *driver_priv;
 
-	/* Tree of display resource leases, each of which is a drm_master struct
-	 * All of these get activated simultaneously, so drm_device master points
-	 * at the top of the tree (for which lessor is NULL). Protected by
-	 * &drm_device.mode_config.idr_mutex.
+	/**
+	 * @lessor:
+	 *
+	 * Lease grantor, only set if this &struct drm_master represents a
+	 * lessee holding a lease of objects from @lessor. Full owners of the
+	 * device have this set to NULL.
+	 *
+	 * The lessor does not change once it's set in drm_lease_create(), and
+	 * each lessee holds a reference to its lessor that it releases upon
+	 * being destroyed in drm_lease_destroy().
+	 *
+	 * See also the :ref:`section on display resource leasing
+	 * <drm_leasing>`.
 	 */
-
 	struct drm_master *lessor;
+
+	/**
+	 * @lessee_id:
+	 *
+	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	int	lessee_id;
+
+	/**
+	 * @lessee_list:
+	 *
+	 * List entry of lessees of @lessor, where they are linked to @lessees.
+	 * Not used for owners. Protected by &drm_device.mode_config's
+	 * &drm_mode_config.idr_mutex.
+	 */
 	struct list_head lessee_list;
+
+	/**
+	 * @lessees:
+	 *
+	 * List of drm_masters leasing from this one. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * This list is empty if no leases have been granted, or if all lessees
+	 * have been destroyed. Since lessors are referenced by all their
+	 * lessees, this master cannot be destroyed unless the list is empty.
+	 */
 	struct list_head lessees;
+
+	/**
+	 * @leases:
+	 *
+	 * Objects leased to this drm_master. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * Objects are leased all together in drm_lease_create(), and are
+	 * removed all together when the lease is revoked.
+	 */
 	struct idr leases;
+
+	/**
+	 * @lessee_idr:
+	 *
+	 * All lessees under this owner (only used where @lessor is NULL).
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	struct idr lessee_idr;
 	/* private: */
 #if IS_ENABLED(CONFIG_DRM_LEGACY)
-- 
2.25.1

[Intel-gfx] [PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking rules of lease fields in drm_master:

1. Make it clear that &drm_device.mode_config.idr_mutex protects the
lease idr and list structures for drm_master. The lessor field itself
doesn't need to be protected as it doesn't change after it's set in
drm_lease_create.

2. Add descriptions for the lifetime of lessors and leases.

3. Add an overview DOC: section in drm-uapi.rst that defines the
terminology for drm leasing, and explains how leases work and why
they're used.

4. Clean up function documentation in drm_lease.c to use kernel-doc
formatting.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
---

Hi,

After I updated the formatting for comments in drm_lease.c, I noticed
that none of these were driver interfaces (i.e. no structs/inline
functions declared in headers, and no exported symbols in .c files).

I left the kernel-doc links inside drm-uapi.rst so that if any such
interfaces are defined in the future, they'll go to the appropriate
place. But if these should be removed, or if the formatting changes for
function comments should be removed, please let me know.

Best wishes,
Desmond

 Documentation/gpu/drm-uapi.rst |  15 +++
 drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
 include/drm/drm_auth.h         |  67 ++++++++++--
 3 files changed, 180 insertions(+), 84 deletions(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 7e51dd40bf6e..6d7233a9fb14 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
 .. kernel-doc:: include/drm/drm_auth.h
    :internal:
 
+
+.. _drm_leasing:
+
+DRM Display Resource Leasing
+============================
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :doc: drm leasing
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_lease.h
+   :internal:
+
 Open-Source Userspace Requirements
 ==================================
 
diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
index 92eac73d9001..9b68617840ed 100644
--- a/drivers/gpu/drm/drm_lease.c
+++ b/drivers/gpu/drm/drm_lease.c
@@ -15,18 +15,67 @@
 #include "drm_crtc_internal.h"
 #include "drm_internal.h"
 
+/**
+ * DOC: drm leasing
+ *
+ * DRM leases provide information about whether a DRM master may control a DRM
+ * mode setting object. This enables the creation of multiple DRM masters that
+ * manage subsets of display resources.
+ *
+ * The original DRM master of a device 'owns' the available drm resources. It
+ * may create additional DRM masters and 'lease' resources which it controls
+ * to the new DRM master. This gives the new DRM master control over the
+ * leased resources until the owner revokes the lease, or the new DRM master
+ * is closed. Some helpful terminology:
+ *
+ * - An 'owner' is a &struct drm_master that is not leasing objects from
+ *   another &struct drm_master, and hence 'owns' the objects. The owner can be
+ *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
+ *
+ * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
+ *   other &struct drm_master. Currently, lessees are not allowed to
+ *   create sub-leases, hence the lessor is the same as the owner.
+ *
+ * - A 'lessee' is a &struct drm_master which is leasing objects from some
+ *   other &struct drm_master. Each lessee only leases resources from a single
+ *   lessor recorded in &drm_master.lessor, and holds the set of objects that
+ *   it is leasing in &drm_master.leases.
+ *
+ * - A 'lease' is a contract between the lessor and lessee that identifies
+ *   which resources may be controlled by the lessee. All of the resources
+ *   that are leased must be owned by or leased to the lessor, and lessors are
+ *   not permitted to lease the same object to multiple lessees.
+ *
+ * The set of objects any &struct drm_master 'controls' is limited to the set
+ * of objects it leases (for lessees) or all objects (for owners).
+ *
+ * Objects not controlled by a &struct drm_master cannot be modified through
+ * the various state manipulating ioctls, and any state reported back to user
+ * space will be edited to make them appear idle and/or unusable. For
+ * instance, connectors always report 'disconnected', while encoders
+ * report no possible crtcs or clones.
+ *
+ * Since each lessee may lease objects from a single lessor, display resource
+ * leases form a tree of &struct drm_master. As lessees are currently not
+ * allowed to create sub-leases, the tree depth is limited to 1. All of
+ * these get activated simultaneously, so &drm_device.master points to the
+ * owner at the top of the lease tree (i.e. the &struct drm_master for which
+ * &drm_master.lessor is NULL). The full list of lessees that are leasing
+ * objects from the owner can be searched via the owner's
+ * &drm_master.lessee_idr.
+ */
+
 #define drm_for_each_lessee(lessee, lessor) \
 	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
 
 static uint64_t drm_lease_idr_object;
 
 /**
- * drm_lease_owner - return ancestor owner drm_master
- * @master: drm_master somewhere within tree of lessees and lessors
- *
- * RETURN:
+ * drm_lease_owner - return the device owner in @master's lease tree
+ * @master: &struct drm_master somewhere within tree of lessees and lessors
  *
- * drm_master at the top of the tree (i.e, with lessor NULL
+ * Returns the &struct drm_master that owns the device, i.e. the &struct
+ * drm_master at the top of the tree for which &drm_master.lessor is NULL.
  */
 struct drm_master *drm_lease_owner(struct drm_master *master)
 {
@@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
 
 /**
  * _drm_find_lessee - find lessee by id (idr_mutex held)
- * @master: drm_master of lessor
- * @lessee_id: id
+ * @master: &struct drm_master of lessor
+ * @lessee_id: &drm_master.lessee_id of lessee
  *
- * RETURN:
- *
- * drm_master of the lessee if valid, NULL otherwise
+ * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
  */
 
 static struct drm_master*
@@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
 }
 
 /**
- * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * _drm_lease_held_master - check to see if an object is leased (or owned) by
+ * @master (idr_mutex held)
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @master holds a lease on (or owns) the object, false if not.
  */
 static int _drm_lease_held_master(struct drm_master *master, int id)
 {
@@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
 
 /**
  * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- * Checks if any lessee of 'master' holds a lease on 'id'. Return
- * value:
- *
- *	true		Some lessee holds a lease on the object.
- *	false		No lessee has a lease on the object.
+ * Returns true if any lessee of @master holds a lease on the given object,
+ * false if no lessee has a lease on the object.
  */
 static bool _drm_has_leased(struct drm_master *master, int id)
 {
@@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
 
 /**
  * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
- * @file_priv: the master drm_file
- * @id: the object id
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool _drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
 
 /**
  * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
- * @file_priv: the master drm_file
- * @id: the object id
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- * Checks if the specified master holds a lease on the object. Return
- * value:
- *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
 }
 
 /**
- * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
+ * drm_lease_filter_crtcs - restricted crtc set to leased values
+ * (idr_mutex not held)
  * @file_priv: requestor file
  * @crtcs_in: bitmask of crtcs to check
  *
@@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
 }
 
 /*
- * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
+ * drm_lease_create - create a new &struct drm_master with leased objects
+ * (idr_mutex not held)
  * @lessor: lease holder (or owner) of objects
  * @leases: objects to lease to the new drm_master
  *
- * Uses drm_master_create to allocate a new drm_master, then checks to
- * make sure all of the desired objects can be leased, atomically
- * leasing them to the new drmmaster.
+ * Uses drm_master_create() to allocate a new &struct drm_master, then checks
+ * to make sure all of the desired objects can be leased, atomically
+ * leasing them to the new &struct drm_master.
  *
  * 	ERR_PTR(-EACCES)	some other master holds the title to any object
  * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
@@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
 }
 
 /**
- * drm_lease_destroy - a master is going away (idr_mutex not held)
- * @master: the drm_master being destroyed
+ * drm_lease_destroy - destroy a master  (idr_mutex not held)
+ * @master: the &struct drm_master being destroyed
  *
- * All lessees will have been destroyed as they
- * hold a reference on their lessor. Notify any
- * lessor for this master so that it can check
- * the list of lessees.
+ * Destroys @master, then notifies any lessor for this master so that it can
+ * check the list of lessees. Note that all lessees of @master will have been
+ * destroyed for this function to be called as they hold a reference on their
+ * lessor.
  */
 void drm_lease_destroy(struct drm_master *master)
 {
@@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
 
 /**
  * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 static void _drm_lease_revoke(struct drm_master *top)
 {
@@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
 
 /**
  * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 void drm_lease_revoke(struct drm_master *top)
 {
@@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
 
 /**
  * drm_mode_create_lease_ioctl - create a new lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_create_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_create_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * The master associated with the specified file will have a lease
+ * The &struct drm_master associated with @lessor_priv will have a lease
  * created containing the objects specified in the ioctl structure.
  * A file descriptor will be allocated for that and returned to the
  * application.
+ *
+ * Note that creating recursive sub-leases for existing lessees is not allowed.
  */
 int drm_mode_create_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
@@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
 }
 
 /**
- * drm_mode_list_lessees_ioctl - list lessee ids
- * @dev: the drm device
- * @data: pointer to struct drm_mode_list_lessees
- * @lessor_priv: the file being manipulated
+ * drm_mode_list_lessees_ioctl - list lessee IDs
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_list_lessees
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * Starting from the master associated with the specified file,
- * the master with the provided lessee_id is found, and then
- * an array of lessee ids associated with leases from that master
- * are returned.
+ * Returns an array of &drm_master.lessee_id associated with lessees of
+ * @lessor_priv's &drm_file.master that have unrevoked leases.
  */
 
 int drm_mode_list_lessees_ioctl(struct drm_device *dev,
@@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_get_lease_ioctl - list leased objects
- * @dev: the drm device
- * @data: pointer to struct drm_mode_get_lease
- * @lessee_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_get_lease
+ * @lessee_priv: the &struct drm_file being manipulated
  *
  * Return the list of leased objects for the specified lessee
  */
@@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_revoke_lease_ioctl - revoke lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_revoke_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_revoke_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * This removes all of the objects from the lease without
- * actually getting rid of the lease itself; that way all
- * references to it still work correctly
+ * Removes all of the objects from the lessee without actually getting rid
+ * of the lessee itself; that way all references to it still work correctly.
  */
 int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
index f99d3417f304..ba248ca8866f 100644
--- a/include/drm/drm_auth.h
+++ b/include/drm/drm_auth.h
@@ -58,12 +58,6 @@ struct drm_lock_data {
  * @refcount: Refcount for this master object.
  * @dev: Link back to the DRM device
  * @driver_priv: Pointer to driver-private information.
- * @lessor: Lease holder
- * @lessee_id: id for lessees. Owners always have id 0
- * @lessee_list: other lessees of the same master
- * @lessees: drm_masters leasing from this one
- * @leases: Objects leased to this drm_master.
- * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
  *
  * Note that master structures are only relevant for the legacy/primary device
  * nodes, hence there can only be one per device, not one per drm_minor.
@@ -88,17 +82,68 @@ struct drm_master {
 	struct idr magic_map;
 	void *driver_priv;
 
-	/* Tree of display resource leases, each of which is a drm_master struct
-	 * All of these get activated simultaneously, so drm_device master points
-	 * at the top of the tree (for which lessor is NULL). Protected by
-	 * &drm_device.mode_config.idr_mutex.
+	/**
+	 * @lessor:
+	 *
+	 * Lease grantor, only set if this &struct drm_master represents a
+	 * lessee holding a lease of objects from @lessor. Full owners of the
+	 * device have this set to NULL.
+	 *
+	 * The lessor does not change once it's set in drm_lease_create(), and
+	 * each lessee holds a reference to its lessor that it releases upon
+	 * being destroyed in drm_lease_destroy().
+	 *
+	 * See also the :ref:`section on display resource leasing
+	 * <drm_leasing>`.
 	 */
-
 	struct drm_master *lessor;
+
+	/**
+	 * @lessee_id:
+	 *
+	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	int	lessee_id;
+
+	/**
+	 * @lessee_list:
+	 *
+	 * List entry of lessees of @lessor, where they are linked to @lessees.
+	 * Not used for owners. Protected by &drm_device.mode_config's
+	 * &drm_mode_config.idr_mutex.
+	 */
 	struct list_head lessee_list;
+
+	/**
+	 * @lessees:
+	 *
+	 * List of drm_masters leasing from this one. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * This list is empty if no leases have been granted, or if all lessees
+	 * have been destroyed. Since lessors are referenced by all their
+	 * lessees, this master cannot be destroyed unless the list is empty.
+	 */
 	struct list_head lessees;
+
+	/**
+	 * @leases:
+	 *
+	 * Objects leased to this drm_master. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * Objects are leased all together in drm_lease_create(), and are
+	 * removed all together when the lease is revoked.
+	 */
 	struct idr leases;
+
+	/**
+	 * @lessee_idr:
+	 *
+	 * All lessees under this owner (only used where @lessor is NULL).
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	struct idr lessee_idr;
 	/* private: */
 #if IS_ENABLED(CONFIG_DRM_LEGACY)
-- 
2.25.1

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

[PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking rules of lease fields in drm_master:

1. Make it clear that &drm_device.mode_config.idr_mutex protects the
lease idr and list structures for drm_master. The lessor field itself
doesn't need to be protected as it doesn't change after it's set in
drm_lease_create.

2. Add descriptions for the lifetime of lessors and leases.

3. Add an overview DOC: section in drm-uapi.rst that defines the
terminology for drm leasing, and explains how leases work and why
they're used.

4. Clean up function documentation in drm_lease.c to use kernel-doc
formatting.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
---

Hi,

After I updated the formatting for comments in drm_lease.c, I noticed
that none of these were driver interfaces (i.e. no structs/inline
functions declared in headers, and no exported symbols in .c files).

I left the kernel-doc links inside drm-uapi.rst so that if any such
interfaces are defined in the future, they'll go to the appropriate
place. But if these should be removed, or if the formatting changes for
function comments should be removed, please let me know.

Best wishes,
Desmond

 Documentation/gpu/drm-uapi.rst |  15 +++
 drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
 include/drm/drm_auth.h         |  67 ++++++++++--
 3 files changed, 180 insertions(+), 84 deletions(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 7e51dd40bf6e..6d7233a9fb14 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
 .. kernel-doc:: include/drm/drm_auth.h
    :internal:
 
+
+.. _drm_leasing:
+
+DRM Display Resource Leasing
+============================
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :doc: drm leasing
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_lease.h
+   :internal:
+
 Open-Source Userspace Requirements
 ==================================
 
diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
index 92eac73d9001..9b68617840ed 100644
--- a/drivers/gpu/drm/drm_lease.c
+++ b/drivers/gpu/drm/drm_lease.c
@@ -15,18 +15,67 @@
 #include "drm_crtc_internal.h"
 #include "drm_internal.h"
 
+/**
+ * DOC: drm leasing
+ *
+ * DRM leases provide information about whether a DRM master may control a DRM
+ * mode setting object. This enables the creation of multiple DRM masters that
+ * manage subsets of display resources.
+ *
+ * The original DRM master of a device 'owns' the available drm resources. It
+ * may create additional DRM masters and 'lease' resources which it controls
+ * to the new DRM master. This gives the new DRM master control over the
+ * leased resources until the owner revokes the lease, or the new DRM master
+ * is closed. Some helpful terminology:
+ *
+ * - An 'owner' is a &struct drm_master that is not leasing objects from
+ *   another &struct drm_master, and hence 'owns' the objects. The owner can be
+ *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
+ *
+ * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
+ *   other &struct drm_master. Currently, lessees are not allowed to
+ *   create sub-leases, hence the lessor is the same as the owner.
+ *
+ * - A 'lessee' is a &struct drm_master which is leasing objects from some
+ *   other &struct drm_master. Each lessee only leases resources from a single
+ *   lessor recorded in &drm_master.lessor, and holds the set of objects that
+ *   it is leasing in &drm_master.leases.
+ *
+ * - A 'lease' is a contract between the lessor and lessee that identifies
+ *   which resources may be controlled by the lessee. All of the resources
+ *   that are leased must be owned by or leased to the lessor, and lessors are
+ *   not permitted to lease the same object to multiple lessees.
+ *
+ * The set of objects any &struct drm_master 'controls' is limited to the set
+ * of objects it leases (for lessees) or all objects (for owners).
+ *
+ * Objects not controlled by a &struct drm_master cannot be modified through
+ * the various state manipulating ioctls, and any state reported back to user
+ * space will be edited to make them appear idle and/or unusable. For
+ * instance, connectors always report 'disconnected', while encoders
+ * report no possible crtcs or clones.
+ *
+ * Since each lessee may lease objects from a single lessor, display resource
+ * leases form a tree of &struct drm_master. As lessees are currently not
+ * allowed to create sub-leases, the tree depth is limited to 1. All of
+ * these get activated simultaneously, so &drm_device.master points to the
+ * owner at the top of the lease tree (i.e. the &struct drm_master for which
+ * &drm_master.lessor is NULL). The full list of lessees that are leasing
+ * objects from the owner can be searched via the owner's
+ * &drm_master.lessee_idr.
+ */
+
 #define drm_for_each_lessee(lessee, lessor) \
 	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
 
 static uint64_t drm_lease_idr_object;
 
 /**
- * drm_lease_owner - return ancestor owner drm_master
- * @master: drm_master somewhere within tree of lessees and lessors
- *
- * RETURN:
+ * drm_lease_owner - return the device owner in @master's lease tree
+ * @master: &struct drm_master somewhere within tree of lessees and lessors
  *
- * drm_master at the top of the tree (i.e, with lessor NULL
+ * Returns the &struct drm_master that owns the device, i.e. the &struct
+ * drm_master at the top of the tree for which &drm_master.lessor is NULL.
  */
 struct drm_master *drm_lease_owner(struct drm_master *master)
 {
@@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
 
 /**
  * _drm_find_lessee - find lessee by id (idr_mutex held)
- * @master: drm_master of lessor
- * @lessee_id: id
+ * @master: &struct drm_master of lessor
+ * @lessee_id: &drm_master.lessee_id of lessee
  *
- * RETURN:
- *
- * drm_master of the lessee if valid, NULL otherwise
+ * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
  */
 
 static struct drm_master*
@@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
 }
 
 /**
- * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * _drm_lease_held_master - check to see if an object is leased (or owned) by
+ * @master (idr_mutex held)
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @master holds a lease on (or owns) the object, false if not.
  */
 static int _drm_lease_held_master(struct drm_master *master, int id)
 {
@@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
 
 /**
  * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- * Checks if any lessee of 'master' holds a lease on 'id'. Return
- * value:
- *
- *	true		Some lessee holds a lease on the object.
- *	false		No lessee has a lease on the object.
+ * Returns true if any lessee of @master holds a lease on the given object,
+ * false if no lessee has a lease on the object.
  */
 static bool _drm_has_leased(struct drm_master *master, int id)
 {
@@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
 
 /**
  * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
- * @file_priv: the master drm_file
- * @id: the object id
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool _drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
 
 /**
  * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
- * @file_priv: the master drm_file
- * @id: the object id
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- * Checks if the specified master holds a lease on the object. Return
- * value:
- *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
 }
 
 /**
- * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
+ * drm_lease_filter_crtcs - restricted crtc set to leased values
+ * (idr_mutex not held)
  * @file_priv: requestor file
  * @crtcs_in: bitmask of crtcs to check
  *
@@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
 }
 
 /*
- * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
+ * drm_lease_create - create a new &struct drm_master with leased objects
+ * (idr_mutex not held)
  * @lessor: lease holder (or owner) of objects
  * @leases: objects to lease to the new drm_master
  *
- * Uses drm_master_create to allocate a new drm_master, then checks to
- * make sure all of the desired objects can be leased, atomically
- * leasing them to the new drmmaster.
+ * Uses drm_master_create() to allocate a new &struct drm_master, then checks
+ * to make sure all of the desired objects can be leased, atomically
+ * leasing them to the new &struct drm_master.
  *
  * 	ERR_PTR(-EACCES)	some other master holds the title to any object
  * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
@@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
 }
 
 /**
- * drm_lease_destroy - a master is going away (idr_mutex not held)
- * @master: the drm_master being destroyed
+ * drm_lease_destroy - destroy a master  (idr_mutex not held)
+ * @master: the &struct drm_master being destroyed
  *
- * All lessees will have been destroyed as they
- * hold a reference on their lessor. Notify any
- * lessor for this master so that it can check
- * the list of lessees.
+ * Destroys @master, then notifies any lessor for this master so that it can
+ * check the list of lessees. Note that all lessees of @master will have been
+ * destroyed for this function to be called as they hold a reference on their
+ * lessor.
  */
 void drm_lease_destroy(struct drm_master *master)
 {
@@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
 
 /**
  * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 static void _drm_lease_revoke(struct drm_master *top)
 {
@@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
 
 /**
  * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 void drm_lease_revoke(struct drm_master *top)
 {
@@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
 
 /**
  * drm_mode_create_lease_ioctl - create a new lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_create_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_create_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * The master associated with the specified file will have a lease
+ * The &struct drm_master associated with @lessor_priv will have a lease
  * created containing the objects specified in the ioctl structure.
  * A file descriptor will be allocated for that and returned to the
  * application.
+ *
+ * Note that creating recursive sub-leases for existing lessees is not allowed.
  */
 int drm_mode_create_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
@@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
 }
 
 /**
- * drm_mode_list_lessees_ioctl - list lessee ids
- * @dev: the drm device
- * @data: pointer to struct drm_mode_list_lessees
- * @lessor_priv: the file being manipulated
+ * drm_mode_list_lessees_ioctl - list lessee IDs
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_list_lessees
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * Starting from the master associated with the specified file,
- * the master with the provided lessee_id is found, and then
- * an array of lessee ids associated with leases from that master
- * are returned.
+ * Returns an array of &drm_master.lessee_id associated with lessees of
+ * @lessor_priv's &drm_file.master that have unrevoked leases.
  */
 
 int drm_mode_list_lessees_ioctl(struct drm_device *dev,
@@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_get_lease_ioctl - list leased objects
- * @dev: the drm device
- * @data: pointer to struct drm_mode_get_lease
- * @lessee_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_get_lease
+ * @lessee_priv: the &struct drm_file being manipulated
  *
  * Return the list of leased objects for the specified lessee
  */
@@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_revoke_lease_ioctl - revoke lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_revoke_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_revoke_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * This removes all of the objects from the lease without
- * actually getting rid of the lease itself; that way all
- * references to it still work correctly
+ * Removes all of the objects from the lessee without actually getting rid
+ * of the lessee itself; that way all references to it still work correctly.
  */
 int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
index f99d3417f304..ba248ca8866f 100644
--- a/include/drm/drm_auth.h
+++ b/include/drm/drm_auth.h
@@ -58,12 +58,6 @@ struct drm_lock_data {
  * @refcount: Refcount for this master object.
  * @dev: Link back to the DRM device
  * @driver_priv: Pointer to driver-private information.
- * @lessor: Lease holder
- * @lessee_id: id for lessees. Owners always have id 0
- * @lessee_list: other lessees of the same master
- * @lessees: drm_masters leasing from this one
- * @leases: Objects leased to this drm_master.
- * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
  *
  * Note that master structures are only relevant for the legacy/primary device
  * nodes, hence there can only be one per device, not one per drm_minor.
@@ -88,17 +82,68 @@ struct drm_master {
 	struct idr magic_map;
 	void *driver_priv;
 
-	/* Tree of display resource leases, each of which is a drm_master struct
-	 * All of these get activated simultaneously, so drm_device master points
-	 * at the top of the tree (for which lessor is NULL). Protected by
-	 * &drm_device.mode_config.idr_mutex.
+	/**
+	 * @lessor:
+	 *
+	 * Lease grantor, only set if this &struct drm_master represents a
+	 * lessee holding a lease of objects from @lessor. Full owners of the
+	 * device have this set to NULL.
+	 *
+	 * The lessor does not change once it's set in drm_lease_create(), and
+	 * each lessee holds a reference to its lessor that it releases upon
+	 * being destroyed in drm_lease_destroy().
+	 *
+	 * See also the :ref:`section on display resource leasing
+	 * <drm_leasing>`.
 	 */
-
 	struct drm_master *lessor;
+
+	/**
+	 * @lessee_id:
+	 *
+	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	int	lessee_id;
+
+	/**
+	 * @lessee_list:
+	 *
+	 * List entry of lessees of @lessor, where they are linked to @lessees.
+	 * Not used for owners. Protected by &drm_device.mode_config's
+	 * &drm_mode_config.idr_mutex.
+	 */
 	struct list_head lessee_list;
+
+	/**
+	 * @lessees:
+	 *
+	 * List of drm_masters leasing from this one. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * This list is empty if no leases have been granted, or if all lessees
+	 * have been destroyed. Since lessors are referenced by all their
+	 * lessees, this master cannot be destroyed unless the list is empty.
+	 */
 	struct list_head lessees;
+
+	/**
+	 * @leases:
+	 *
+	 * Objects leased to this drm_master. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * Objects are leased all together in drm_lease_create(), and are
+	 * removed all together when the lease is revoked.
+	 */
 	struct idr leases;
+
+	/**
+	 * @lessee_idr:
+	 *
+	 * All lessees under this owner (only used where @lessor is NULL).
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	struct idr lessee_idr;
 	/* private: */
 #if IS_ENABLED(CONFIG_DRM_LEGACY)
-- 
2.25.1

[PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking rules of lease fields in drm_master:

1. Make it clear that &drm_device.mode_config.idr_mutex protects the
lease idr and list structures for drm_master. The lessor field itself
doesn't need to be protected as it doesn't change after it's set in
drm_lease_create.

2. Add descriptions for the lifetime of lessors and leases.

3. Add an overview DOC: section in drm-uapi.rst that defines the
terminology for drm leasing, and explains how leases work and why
they're used.

4. Clean up function documentation in drm_lease.c to use kernel-doc
formatting.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
---

Hi,

After I updated the formatting for comments in drm_lease.c, I noticed
that none of these were driver interfaces (i.e. no structs/inline
functions declared in headers, and no exported symbols in .c files).

I left the kernel-doc links inside drm-uapi.rst so that if any such
interfaces are defined in the future, they'll go to the appropriate
place. But if these should be removed, or if the formatting changes for
function comments should be removed, please let me know.

Best wishes,
Desmond

 Documentation/gpu/drm-uapi.rst |  15 +++
 drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
 include/drm/drm_auth.h         |  67 ++++++++++--
 3 files changed, 180 insertions(+), 84 deletions(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 7e51dd40bf6e..6d7233a9fb14 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
 .. kernel-doc:: include/drm/drm_auth.h
    :internal:
 
+
+.. _drm_leasing:
+
+DRM Display Resource Leasing
+============================
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :doc: drm leasing
+
+.. kernel-doc:: drivers/gpu/drm/drm_lease.c
+   :export:
+
+.. kernel-doc:: include/drm/drm_lease.h
+   :internal:
+
 Open-Source Userspace Requirements
 ==================================
 
diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
index 92eac73d9001..9b68617840ed 100644
--- a/drivers/gpu/drm/drm_lease.c
+++ b/drivers/gpu/drm/drm_lease.c
@@ -15,18 +15,67 @@
 #include "drm_crtc_internal.h"
 #include "drm_internal.h"
 
+/**
+ * DOC: drm leasing
+ *
+ * DRM leases provide information about whether a DRM master may control a DRM
+ * mode setting object. This enables the creation of multiple DRM masters that
+ * manage subsets of display resources.
+ *
+ * The original DRM master of a device 'owns' the available drm resources. It
+ * may create additional DRM masters and 'lease' resources which it controls
+ * to the new DRM master. This gives the new DRM master control over the
+ * leased resources until the owner revokes the lease, or the new DRM master
+ * is closed. Some helpful terminology:
+ *
+ * - An 'owner' is a &struct drm_master that is not leasing objects from
+ *   another &struct drm_master, and hence 'owns' the objects. The owner can be
+ *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
+ *
+ * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
+ *   other &struct drm_master. Currently, lessees are not allowed to
+ *   create sub-leases, hence the lessor is the same as the owner.
+ *
+ * - A 'lessee' is a &struct drm_master which is leasing objects from some
+ *   other &struct drm_master. Each lessee only leases resources from a single
+ *   lessor recorded in &drm_master.lessor, and holds the set of objects that
+ *   it is leasing in &drm_master.leases.
+ *
+ * - A 'lease' is a contract between the lessor and lessee that identifies
+ *   which resources may be controlled by the lessee. All of the resources
+ *   that are leased must be owned by or leased to the lessor, and lessors are
+ *   not permitted to lease the same object to multiple lessees.
+ *
+ * The set of objects any &struct drm_master 'controls' is limited to the set
+ * of objects it leases (for lessees) or all objects (for owners).
+ *
+ * Objects not controlled by a &struct drm_master cannot be modified through
+ * the various state manipulating ioctls, and any state reported back to user
+ * space will be edited to make them appear idle and/or unusable. For
+ * instance, connectors always report 'disconnected', while encoders
+ * report no possible crtcs or clones.
+ *
+ * Since each lessee may lease objects from a single lessor, display resource
+ * leases form a tree of &struct drm_master. As lessees are currently not
+ * allowed to create sub-leases, the tree depth is limited to 1. All of
+ * these get activated simultaneously, so &drm_device.master points to the
+ * owner at the top of the lease tree (i.e. the &struct drm_master for which
+ * &drm_master.lessor is NULL). The full list of lessees that are leasing
+ * objects from the owner can be searched via the owner's
+ * &drm_master.lessee_idr.
+ */
+
 #define drm_for_each_lessee(lessee, lessor) \
 	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
 
 static uint64_t drm_lease_idr_object;
 
 /**
- * drm_lease_owner - return ancestor owner drm_master
- * @master: drm_master somewhere within tree of lessees and lessors
- *
- * RETURN:
+ * drm_lease_owner - return the device owner in @master's lease tree
+ * @master: &struct drm_master somewhere within tree of lessees and lessors
  *
- * drm_master at the top of the tree (i.e, with lessor NULL
+ * Returns the &struct drm_master that owns the device, i.e. the &struct
+ * drm_master at the top of the tree for which &drm_master.lessor is NULL.
  */
 struct drm_master *drm_lease_owner(struct drm_master *master)
 {
@@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
 
 /**
  * _drm_find_lessee - find lessee by id (idr_mutex held)
- * @master: drm_master of lessor
- * @lessee_id: id
+ * @master: &struct drm_master of lessor
+ * @lessee_id: &drm_master.lessee_id of lessee
  *
- * RETURN:
- *
- * drm_master of the lessee if valid, NULL otherwise
+ * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
  */
 
 static struct drm_master*
@@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
 }
 
 /**
- * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * _drm_lease_held_master - check to see if an object is leased (or owned) by
+ * @master (idr_mutex held)
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @master holds a lease on (or owns) the object, false if not.
  */
 static int _drm_lease_held_master(struct drm_master *master, int id)
 {
@@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
 
 /**
  * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
- * @master: the master to check the lease status of
- * @id: the id to check
+ * @master: the &struct drm_master to check the lease status of
+ * @id: the object ID to check
  *
- * Checks if any lessee of 'master' holds a lease on 'id'. Return
- * value:
- *
- *	true		Some lessee holds a lease on the object.
- *	false		No lessee has a lease on the object.
+ * Returns true if any lessee of @master holds a lease on the given object,
+ * false if no lessee has a lease on the object.
  */
 static bool _drm_has_leased(struct drm_master *master, int id)
 {
@@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
 
 /**
  * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
- * @file_priv: the master drm_file
- * @id: the object id
- *
- * Checks if the specified master holds a lease on the object. Return
- * value:
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool _drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
 
 /**
  * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
- * @file_priv: the master drm_file
- * @id: the object id
+ * @file_priv: the master &struct drm_file
+ * @id: the object ID
  *
- * Checks if the specified master holds a lease on the object. Return
- * value:
- *
- *	true		'master' holds a lease on (or owns) the object
- *	false		'master' does not hold a lease.
+ * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
+ * object, false if it does not.
  */
 bool drm_lease_held(struct drm_file *file_priv, int id)
 {
@@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
 }
 
 /**
- * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
+ * drm_lease_filter_crtcs - restricted crtc set to leased values
+ * (idr_mutex not held)
  * @file_priv: requestor file
  * @crtcs_in: bitmask of crtcs to check
  *
@@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
 }
 
 /*
- * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
+ * drm_lease_create - create a new &struct drm_master with leased objects
+ * (idr_mutex not held)
  * @lessor: lease holder (or owner) of objects
  * @leases: objects to lease to the new drm_master
  *
- * Uses drm_master_create to allocate a new drm_master, then checks to
- * make sure all of the desired objects can be leased, atomically
- * leasing them to the new drmmaster.
+ * Uses drm_master_create() to allocate a new &struct drm_master, then checks
+ * to make sure all of the desired objects can be leased, atomically
+ * leasing them to the new &struct drm_master.
  *
  * 	ERR_PTR(-EACCES)	some other master holds the title to any object
  * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
@@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
 }
 
 /**
- * drm_lease_destroy - a master is going away (idr_mutex not held)
- * @master: the drm_master being destroyed
+ * drm_lease_destroy - destroy a master  (idr_mutex not held)
+ * @master: the &struct drm_master being destroyed
  *
- * All lessees will have been destroyed as they
- * hold a reference on their lessor. Notify any
- * lessor for this master so that it can check
- * the list of lessees.
+ * Destroys @master, then notifies any lessor for this master so that it can
+ * check the list of lessees. Note that all lessees of @master will have been
+ * destroyed for this function to be called as they hold a reference on their
+ * lessor.
  */
 void drm_lease_destroy(struct drm_master *master)
 {
@@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
 
 /**
  * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 static void _drm_lease_revoke(struct drm_master *top)
 {
@@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
 
 /**
  * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
- * @top: the master losing its lease
+ * @top: the &struct drm_master losing its lease
  */
 void drm_lease_revoke(struct drm_master *top)
 {
@@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
 
 /**
  * drm_mode_create_lease_ioctl - create a new lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_create_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_create_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * The master associated with the specified file will have a lease
+ * The &struct drm_master associated with @lessor_priv will have a lease
  * created containing the objects specified in the ioctl structure.
  * A file descriptor will be allocated for that and returned to the
  * application.
+ *
+ * Note that creating recursive sub-leases for existing lessees is not allowed.
  */
 int drm_mode_create_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
@@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
 }
 
 /**
- * drm_mode_list_lessees_ioctl - list lessee ids
- * @dev: the drm device
- * @data: pointer to struct drm_mode_list_lessees
- * @lessor_priv: the file being manipulated
+ * drm_mode_list_lessees_ioctl - list lessee IDs
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_list_lessees
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * Starting from the master associated with the specified file,
- * the master with the provided lessee_id is found, and then
- * an array of lessee ids associated with leases from that master
- * are returned.
+ * Returns an array of &drm_master.lessee_id associated with lessees of
+ * @lessor_priv's &drm_file.master that have unrevoked leases.
  */
 
 int drm_mode_list_lessees_ioctl(struct drm_device *dev,
@@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_get_lease_ioctl - list leased objects
- * @dev: the drm device
- * @data: pointer to struct drm_mode_get_lease
- * @lessee_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_get_lease
+ * @lessee_priv: the &struct drm_file being manipulated
  *
  * Return the list of leased objects for the specified lessee
  */
@@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
 
 /**
  * drm_mode_revoke_lease_ioctl - revoke lease
- * @dev: the drm device
- * @data: pointer to struct drm_mode_revoke_lease
- * @lessor_priv: the file being manipulated
+ * @dev: the &struct drm_device
+ * @data: pointer to &struct drm_mode_revoke_lease
+ * @lessor_priv: the &struct drm_file being manipulated
  *
- * This removes all of the objects from the lease without
- * actually getting rid of the lease itself; that way all
- * references to it still work correctly
+ * Removes all of the objects from the lessee without actually getting rid
+ * of the lessee itself; that way all references to it still work correctly.
  */
 int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
 				void *data, struct drm_file *lessor_priv)
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
index f99d3417f304..ba248ca8866f 100644
--- a/include/drm/drm_auth.h
+++ b/include/drm/drm_auth.h
@@ -58,12 +58,6 @@ struct drm_lock_data {
  * @refcount: Refcount for this master object.
  * @dev: Link back to the DRM device
  * @driver_priv: Pointer to driver-private information.
- * @lessor: Lease holder
- * @lessee_id: id for lessees. Owners always have id 0
- * @lessee_list: other lessees of the same master
- * @lessees: drm_masters leasing from this one
- * @leases: Objects leased to this drm_master.
- * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
  *
  * Note that master structures are only relevant for the legacy/primary device
  * nodes, hence there can only be one per device, not one per drm_minor.
@@ -88,17 +82,68 @@ struct drm_master {
 	struct idr magic_map;
 	void *driver_priv;
 
-	/* Tree of display resource leases, each of which is a drm_master struct
-	 * All of these get activated simultaneously, so drm_device master points
-	 * at the top of the tree (for which lessor is NULL). Protected by
-	 * &drm_device.mode_config.idr_mutex.
+	/**
+	 * @lessor:
+	 *
+	 * Lease grantor, only set if this &struct drm_master represents a
+	 * lessee holding a lease of objects from @lessor. Full owners of the
+	 * device have this set to NULL.
+	 *
+	 * The lessor does not change once it's set in drm_lease_create(), and
+	 * each lessee holds a reference to its lessor that it releases upon
+	 * being destroyed in drm_lease_destroy().
+	 *
+	 * See also the :ref:`section on display resource leasing
+	 * <drm_leasing>`.
 	 */
-
 	struct drm_master *lessor;
+
+	/**
+	 * @lessee_id:
+	 *
+	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	int	lessee_id;
+
+	/**
+	 * @lessee_list:
+	 *
+	 * List entry of lessees of @lessor, where they are linked to @lessees.
+	 * Not used for owners. Protected by &drm_device.mode_config's
+	 * &drm_mode_config.idr_mutex.
+	 */
 	struct list_head lessee_list;
+
+	/**
+	 * @lessees:
+	 *
+	 * List of drm_masters leasing from this one. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * This list is empty if no leases have been granted, or if all lessees
+	 * have been destroyed. Since lessors are referenced by all their
+	 * lessees, this master cannot be destroyed unless the list is empty.
+	 */
 	struct list_head lessees;
+
+	/**
+	 * @leases:
+	 *
+	 * Objects leased to this drm_master. Protected by
+	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 *
+	 * Objects are leased all together in drm_lease_create(), and are
+	 * removed all together when the lease is revoked.
+	 */
 	struct idr leases;
+
+	/**
+	 * @lessee_idr:
+	 *
+	 * All lessees under this owner (only used where @lessor is NULL).
+	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
+	 */
 	struct idr lessee_idr;
 	/* private: */
 #if IS_ENABLED(CONFIG_DRM_LEGACY)
-- 
2.25.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
> We make the following changes to the documentation of drm leases to
> make it easier to reason about their usage. In particular, we clarify
> the lifetime and locking rules of lease fields in drm_master:
> 
> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
> lease idr and list structures for drm_master. The lessor field itself
> doesn't need to be protected as it doesn't change after it's set in
> drm_lease_create.
> 
> 2. Add descriptions for the lifetime of lessors and leases.
> 
> 3. Add an overview DOC: section in drm-uapi.rst that defines the
> terminology for drm leasing, and explains how leases work and why
> they're used.
> 
> 4. Clean up function documentation in drm_lease.c to use kernel-doc
> formatting.
> 
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> ---
> 
> Hi,
> 
> After I updated the formatting for comments in drm_lease.c, I noticed
> that none of these were driver interfaces (i.e. no structs/inline
> functions declared in headers, and no exported symbols in .c files).
> 
> I left the kernel-doc links inside drm-uapi.rst so that if any such
> interfaces are defined in the future, they'll go to the appropriate
> place. But if these should be removed, or if the formatting changes for
> function comments should be removed, please let me know.


Hm indeed, so there's not really any need to either include the
drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
useful.

For the internal pieces usually what we do is remove the comment outright
if it doesn't provide anything useful (like just repeats what the function
name says already). If there's something interesting in the comment then
we leave it that sentence in there as a normal comment, but without any of
the structured comment stuff (so no /**, nor @arguments, or the function
summary).



> 
> Best wishes,
> Desmond
> 
>  Documentation/gpu/drm-uapi.rst |  15 +++
>  drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>  include/drm/drm_auth.h         |  67 ++++++++++--
>  3 files changed, 180 insertions(+), 84 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 7e51dd40bf6e..6d7233a9fb14 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>  .. kernel-doc:: include/drm/drm_auth.h
>     :internal:
>  
> +
> +.. _drm_leasing:
> +
> +DRM Display Resource Leasing
> +============================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :doc: drm leasing
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :export:
> +
> +.. kernel-doc:: include/drm/drm_lease.h
> +   :internal:
> +
>  Open-Source Userspace Requirements
>  ==================================
>  
> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
> index 92eac73d9001..9b68617840ed 100644
> --- a/drivers/gpu/drm/drm_lease.c
> +++ b/drivers/gpu/drm/drm_lease.c
> @@ -15,18 +15,67 @@
>  #include "drm_crtc_internal.h"
>  #include "drm_internal.h"
>  
> +/**
> + * DOC: drm leasing
> + *
> + * DRM leases provide information about whether a DRM master may control a DRM
> + * mode setting object. This enables the creation of multiple DRM masters that
> + * manage subsets of display resources.
> + *
> + * The original DRM master of a device 'owns' the available drm resources. It
> + * may create additional DRM masters and 'lease' resources which it controls
> + * to the new DRM master. This gives the new DRM master control over the
> + * leased resources until the owner revokes the lease, or the new DRM master
> + * is closed. Some helpful terminology:
> + *
> + * - An 'owner' is a &struct drm_master that is not leasing objects from
> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
> + *
> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
> + *   other &struct drm_master. Currently, lessees are not allowed to
> + *   create sub-leases, hence the lessor is the same as the owner.
> + *
> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
> + *   other &struct drm_master. Each lessee only leases resources from a single
> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
> + *   it is leasing in &drm_master.leases.
> + *
> + * - A 'lease' is a contract between the lessor and lessee that identifies
> + *   which resources may be controlled by the lessee. All of the resources
> + *   that are leased must be owned by or leased to the lessor, and lessors are
> + *   not permitted to lease the same object to multiple lessees.
> + *
> + * The set of objects any &struct drm_master 'controls' is limited to the set
> + * of objects it leases (for lessees) or all objects (for owners).
> + *
> + * Objects not controlled by a &struct drm_master cannot be modified through
> + * the various state manipulating ioctls, and any state reported back to user
> + * space will be edited to make them appear idle and/or unusable. For
> + * instance, connectors always report 'disconnected', while encoders
> + * report no possible crtcs or clones.
> + *
> + * Since each lessee may lease objects from a single lessor, display resource
> + * leases form a tree of &struct drm_master. As lessees are currently not
> + * allowed to create sub-leases, the tree depth is limited to 1. All of
> + * these get activated simultaneously, so &drm_device.master points to the

I think it would be good to clarify that this happens when the top level
owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
looks good, thanks for typing it up.

> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
> + * objects from the owner can be searched via the owner's
> + * &drm_master.lessee_idr.
> + */
> +
>  #define drm_for_each_lessee(lessee, lessor) \
>  	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>  
>  static uint64_t drm_lease_idr_object;
>  
>  /**
> - * drm_lease_owner - return ancestor owner drm_master
> - * @master: drm_master somewhere within tree of lessees and lessors
> - *
> - * RETURN:
> + * drm_lease_owner - return the device owner in @master's lease tree
> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>   *
> - * drm_master at the top of the tree (i.e, with lessor NULL
> + * Returns the &struct drm_master that owns the device, i.e. the &struct
> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>   */
>  struct drm_master *drm_lease_owner(struct drm_master *master)
>  {
> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>  
>  /**
>   * _drm_find_lessee - find lessee by id (idr_mutex held)
> - * @master: drm_master of lessor
> - * @lessee_id: id
> + * @master: &struct drm_master of lessor
> + * @lessee_id: &drm_master.lessee_id of lessee
>   *
> - * RETURN:
> - *
> - * drm_master of the lessee if valid, NULL otherwise
> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>   */
>  
>  static struct drm_master*
> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>  }
>  
>  /**
> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
> + * @master (idr_mutex held)
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>   */
>  static int _drm_lease_held_master(struct drm_master *master, int id)
>  {
> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>  
>  /**
>   * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
> - * value:
> - *
> - *	true		Some lessee holds a lease on the object.
> - *	false		No lessee has a lease on the object.
> + * Returns true if any lessee of @master holds a lease on the given object,
> + * false if no lessee has a lease on the object.
>   */
>  static bool _drm_has_leased(struct drm_master *master, int id)
>  {
> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>  
>  /**
>   * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool _drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>  
>  /**
>   * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> - *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>  }
>  
>  /**
> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
> + * drm_lease_filter_crtcs - restricted crtc set to leased values
> + * (idr_mutex not held)
>   * @file_priv: requestor file
>   * @crtcs_in: bitmask of crtcs to check
>   *
> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>  }
>  
>  /*
> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
> + * drm_lease_create - create a new &struct drm_master with leased objects
> + * (idr_mutex not held)
>   * @lessor: lease holder (or owner) of objects
>   * @leases: objects to lease to the new drm_master
>   *
> - * Uses drm_master_create to allocate a new drm_master, then checks to
> - * make sure all of the desired objects can be leased, atomically
> - * leasing them to the new drmmaster.
> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
> + * to make sure all of the desired objects can be leased, atomically
> + * leasing them to the new &struct drm_master.
>   *
>   * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>   * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>  }
>  
>  /**
> - * drm_lease_destroy - a master is going away (idr_mutex not held)
> - * @master: the drm_master being destroyed
> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
> + * @master: the &struct drm_master being destroyed
>   *
> - * All lessees will have been destroyed as they
> - * hold a reference on their lessor. Notify any
> - * lessor for this master so that it can check
> - * the list of lessees.
> + * Destroys @master, then notifies any lessor for this master so that it can
> + * check the list of lessees. Note that all lessees of @master will have been
> + * destroyed for this function to be called as they hold a reference on their
> + * lessor.
>   */
>  void drm_lease_destroy(struct drm_master *master)
>  {
> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>  
>  /**
>   * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  static void _drm_lease_revoke(struct drm_master *top)
>  {
> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>  
>  /**
>   * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  void drm_lease_revoke(struct drm_master *top)
>  {
> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>  
>  /**
>   * drm_mode_create_lease_ioctl - create a new lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_create_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_create_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * The master associated with the specified file will have a lease
> + * The &struct drm_master associated with @lessor_priv will have a lease
>   * created containing the objects specified in the ioctl structure.
>   * A file descriptor will be allocated for that and returned to the
>   * application.
> + *
> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>   */
>  int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  }
>  
>  /**
> - * drm_mode_list_lessees_ioctl - list lessee ids
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_list_lessees
> - * @lessor_priv: the file being manipulated
> + * drm_mode_list_lessees_ioctl - list lessee IDs
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_list_lessees
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * Starting from the master associated with the specified file,
> - * the master with the provided lessee_id is found, and then
> - * an array of lessee ids associated with leases from that master
> - * are returned.
> + * Returns an array of &drm_master.lessee_id associated with lessees of
> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>   */
>  
>  int drm_mode_list_lessees_ioctl(struct drm_device *dev,
> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_get_lease_ioctl - list leased objects
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_get_lease
> - * @lessee_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_get_lease
> + * @lessee_priv: the &struct drm_file being manipulated
>   *
>   * Return the list of leased objects for the specified lessee
>   */
> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_revoke_lease_ioctl - revoke lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_revoke_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_revoke_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * This removes all of the objects from the lease without
> - * actually getting rid of the lease itself; that way all
> - * references to it still work correctly
> + * Removes all of the objects from the lessee without actually getting rid
> + * of the lessee itself; that way all references to it still work correctly.
>   */
>  int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
> index f99d3417f304..ba248ca8866f 100644
> --- a/include/drm/drm_auth.h
> +++ b/include/drm/drm_auth.h
> @@ -58,12 +58,6 @@ struct drm_lock_data {
>   * @refcount: Refcount for this master object.
>   * @dev: Link back to the DRM device
>   * @driver_priv: Pointer to driver-private information.
> - * @lessor: Lease holder
> - * @lessee_id: id for lessees. Owners always have id 0
> - * @lessee_list: other lessees of the same master
> - * @lessees: drm_masters leasing from this one
> - * @leases: Objects leased to this drm_master.
> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>   *
>   * Note that master structures are only relevant for the legacy/primary device
>   * nodes, hence there can only be one per device, not one per drm_minor.
> @@ -88,17 +82,68 @@ struct drm_master {
>  	struct idr magic_map;
>  	void *driver_priv;
>  
> -	/* Tree of display resource leases, each of which is a drm_master struct
> -	 * All of these get activated simultaneously, so drm_device master points
> -	 * at the top of the tree (for which lessor is NULL). Protected by
> -	 * &drm_device.mode_config.idr_mutex.
> +	/**
> +	 * @lessor:
> +	 *
> +	 * Lease grantor, only set if this &struct drm_master represents a
> +	 * lessee holding a lease of objects from @lessor. Full owners of the
> +	 * device have this set to NULL.
> +	 *
> +	 * The lessor does not change once it's set in drm_lease_create(), and
> +	 * each lessee holds a reference to its lessor that it releases upon
> +	 * being destroyed in drm_lease_destroy().
> +	 *
> +	 * See also the :ref:`section on display resource leasing
> +	 * <drm_leasing>`.
>  	 */
> -
>  	struct drm_master *lessor;
> +
> +	/**
> +	 * @lessee_id:
> +	 *
> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */
>  	int	lessee_id;
> +
> +	/**
> +	 * @lessee_list:
> +	 *
> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
> +	 * Not used for owners. Protected by &drm_device.mode_config's
> +	 * &drm_mode_config.idr_mutex.
> +	 */
>  	struct list_head lessee_list;
> +
> +	/**
> +	 * @lessees:
> +	 *
> +	 * List of drm_masters leasing from this one. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * This list is empty if no leases have been granted, or if all lessees
> +	 * have been destroyed. Since lessors are referenced by all their
> +	 * lessees, this master cannot be destroyed unless the list is empty.
> +	 */
>  	struct list_head lessees;
> +
> +	/**
> +	 * @leases:
> +	 *
> +	 * Objects leased to this drm_master. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * Objects are leased all together in drm_lease_create(), and are
> +	 * removed all together when the lease is revoked.
> +	 */
>  	struct idr leases;
> +
> +	/**
> +	 * @lessee_idr:
> +	 *
> +	 * All lessees under this owner (only used where @lessor is NULL).
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */

This also looks great now. With the one improvement addressed and I guess
the includes for drm_lease.[hc] and those parts of the patch removed
again:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

If you want perhaps do a follow-up patch to clean up the comments in
drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
maintained when it's not included, so short comments where they provide
real insight is imo best.
-Daniel

>  	struct idr lessee_idr;
>  	/* private: */
>  #if IS_ENABLED(CONFIG_DRM_LEGACY)
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [Intel-gfx] [PATCH v2 2/3] drm: clarify usage of drm leases

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
> We make the following changes to the documentation of drm leases to
> make it easier to reason about their usage. In particular, we clarify
> the lifetime and locking rules of lease fields in drm_master:
> 
> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
> lease idr and list structures for drm_master. The lessor field itself
> doesn't need to be protected as it doesn't change after it's set in
> drm_lease_create.
> 
> 2. Add descriptions for the lifetime of lessors and leases.
> 
> 3. Add an overview DOC: section in drm-uapi.rst that defines the
> terminology for drm leasing, and explains how leases work and why
> they're used.
> 
> 4. Clean up function documentation in drm_lease.c to use kernel-doc
> formatting.
> 
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> ---
> 
> Hi,
> 
> After I updated the formatting for comments in drm_lease.c, I noticed
> that none of these were driver interfaces (i.e. no structs/inline
> functions declared in headers, and no exported symbols in .c files).
> 
> I left the kernel-doc links inside drm-uapi.rst so that if any such
> interfaces are defined in the future, they'll go to the appropriate
> place. But if these should be removed, or if the formatting changes for
> function comments should be removed, please let me know.


Hm indeed, so there's not really any need to either include the
drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
useful.

For the internal pieces usually what we do is remove the comment outright
if it doesn't provide anything useful (like just repeats what the function
name says already). If there's something interesting in the comment then
we leave it that sentence in there as a normal comment, but without any of
the structured comment stuff (so no /**, nor @arguments, or the function
summary).



> 
> Best wishes,
> Desmond
> 
>  Documentation/gpu/drm-uapi.rst |  15 +++
>  drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>  include/drm/drm_auth.h         |  67 ++++++++++--
>  3 files changed, 180 insertions(+), 84 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 7e51dd40bf6e..6d7233a9fb14 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>  .. kernel-doc:: include/drm/drm_auth.h
>     :internal:
>  
> +
> +.. _drm_leasing:
> +
> +DRM Display Resource Leasing
> +============================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :doc: drm leasing
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :export:
> +
> +.. kernel-doc:: include/drm/drm_lease.h
> +   :internal:
> +
>  Open-Source Userspace Requirements
>  ==================================
>  
> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
> index 92eac73d9001..9b68617840ed 100644
> --- a/drivers/gpu/drm/drm_lease.c
> +++ b/drivers/gpu/drm/drm_lease.c
> @@ -15,18 +15,67 @@
>  #include "drm_crtc_internal.h"
>  #include "drm_internal.h"
>  
> +/**
> + * DOC: drm leasing
> + *
> + * DRM leases provide information about whether a DRM master may control a DRM
> + * mode setting object. This enables the creation of multiple DRM masters that
> + * manage subsets of display resources.
> + *
> + * The original DRM master of a device 'owns' the available drm resources. It
> + * may create additional DRM masters and 'lease' resources which it controls
> + * to the new DRM master. This gives the new DRM master control over the
> + * leased resources until the owner revokes the lease, or the new DRM master
> + * is closed. Some helpful terminology:
> + *
> + * - An 'owner' is a &struct drm_master that is not leasing objects from
> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
> + *
> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
> + *   other &struct drm_master. Currently, lessees are not allowed to
> + *   create sub-leases, hence the lessor is the same as the owner.
> + *
> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
> + *   other &struct drm_master. Each lessee only leases resources from a single
> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
> + *   it is leasing in &drm_master.leases.
> + *
> + * - A 'lease' is a contract between the lessor and lessee that identifies
> + *   which resources may be controlled by the lessee. All of the resources
> + *   that are leased must be owned by or leased to the lessor, and lessors are
> + *   not permitted to lease the same object to multiple lessees.
> + *
> + * The set of objects any &struct drm_master 'controls' is limited to the set
> + * of objects it leases (for lessees) or all objects (for owners).
> + *
> + * Objects not controlled by a &struct drm_master cannot be modified through
> + * the various state manipulating ioctls, and any state reported back to user
> + * space will be edited to make them appear idle and/or unusable. For
> + * instance, connectors always report 'disconnected', while encoders
> + * report no possible crtcs or clones.
> + *
> + * Since each lessee may lease objects from a single lessor, display resource
> + * leases form a tree of &struct drm_master. As lessees are currently not
> + * allowed to create sub-leases, the tree depth is limited to 1. All of
> + * these get activated simultaneously, so &drm_device.master points to the

I think it would be good to clarify that this happens when the top level
owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
looks good, thanks for typing it up.

> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
> + * objects from the owner can be searched via the owner's
> + * &drm_master.lessee_idr.
> + */
> +
>  #define drm_for_each_lessee(lessee, lessor) \
>  	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>  
>  static uint64_t drm_lease_idr_object;
>  
>  /**
> - * drm_lease_owner - return ancestor owner drm_master
> - * @master: drm_master somewhere within tree of lessees and lessors
> - *
> - * RETURN:
> + * drm_lease_owner - return the device owner in @master's lease tree
> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>   *
> - * drm_master at the top of the tree (i.e, with lessor NULL
> + * Returns the &struct drm_master that owns the device, i.e. the &struct
> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>   */
>  struct drm_master *drm_lease_owner(struct drm_master *master)
>  {
> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>  
>  /**
>   * _drm_find_lessee - find lessee by id (idr_mutex held)
> - * @master: drm_master of lessor
> - * @lessee_id: id
> + * @master: &struct drm_master of lessor
> + * @lessee_id: &drm_master.lessee_id of lessee
>   *
> - * RETURN:
> - *
> - * drm_master of the lessee if valid, NULL otherwise
> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>   */
>  
>  static struct drm_master*
> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>  }
>  
>  /**
> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
> + * @master (idr_mutex held)
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>   */
>  static int _drm_lease_held_master(struct drm_master *master, int id)
>  {
> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>  
>  /**
>   * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
> - * value:
> - *
> - *	true		Some lessee holds a lease on the object.
> - *	false		No lessee has a lease on the object.
> + * Returns true if any lessee of @master holds a lease on the given object,
> + * false if no lessee has a lease on the object.
>   */
>  static bool _drm_has_leased(struct drm_master *master, int id)
>  {
> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>  
>  /**
>   * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool _drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>  
>  /**
>   * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> - *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>  }
>  
>  /**
> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
> + * drm_lease_filter_crtcs - restricted crtc set to leased values
> + * (idr_mutex not held)
>   * @file_priv: requestor file
>   * @crtcs_in: bitmask of crtcs to check
>   *
> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>  }
>  
>  /*
> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
> + * drm_lease_create - create a new &struct drm_master with leased objects
> + * (idr_mutex not held)
>   * @lessor: lease holder (or owner) of objects
>   * @leases: objects to lease to the new drm_master
>   *
> - * Uses drm_master_create to allocate a new drm_master, then checks to
> - * make sure all of the desired objects can be leased, atomically
> - * leasing them to the new drmmaster.
> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
> + * to make sure all of the desired objects can be leased, atomically
> + * leasing them to the new &struct drm_master.
>   *
>   * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>   * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>  }
>  
>  /**
> - * drm_lease_destroy - a master is going away (idr_mutex not held)
> - * @master: the drm_master being destroyed
> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
> + * @master: the &struct drm_master being destroyed
>   *
> - * All lessees will have been destroyed as they
> - * hold a reference on their lessor. Notify any
> - * lessor for this master so that it can check
> - * the list of lessees.
> + * Destroys @master, then notifies any lessor for this master so that it can
> + * check the list of lessees. Note that all lessees of @master will have been
> + * destroyed for this function to be called as they hold a reference on their
> + * lessor.
>   */
>  void drm_lease_destroy(struct drm_master *master)
>  {
> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>  
>  /**
>   * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  static void _drm_lease_revoke(struct drm_master *top)
>  {
> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>  
>  /**
>   * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  void drm_lease_revoke(struct drm_master *top)
>  {
> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>  
>  /**
>   * drm_mode_create_lease_ioctl - create a new lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_create_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_create_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * The master associated with the specified file will have a lease
> + * The &struct drm_master associated with @lessor_priv will have a lease
>   * created containing the objects specified in the ioctl structure.
>   * A file descriptor will be allocated for that and returned to the
>   * application.
> + *
> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>   */
>  int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  }
>  
>  /**
> - * drm_mode_list_lessees_ioctl - list lessee ids
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_list_lessees
> - * @lessor_priv: the file being manipulated
> + * drm_mode_list_lessees_ioctl - list lessee IDs
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_list_lessees
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * Starting from the master associated with the specified file,
> - * the master with the provided lessee_id is found, and then
> - * an array of lessee ids associated with leases from that master
> - * are returned.
> + * Returns an array of &drm_master.lessee_id associated with lessees of
> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>   */
>  
>  int drm_mode_list_lessees_ioctl(struct drm_device *dev,
> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_get_lease_ioctl - list leased objects
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_get_lease
> - * @lessee_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_get_lease
> + * @lessee_priv: the &struct drm_file being manipulated
>   *
>   * Return the list of leased objects for the specified lessee
>   */
> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_revoke_lease_ioctl - revoke lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_revoke_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_revoke_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * This removes all of the objects from the lease without
> - * actually getting rid of the lease itself; that way all
> - * references to it still work correctly
> + * Removes all of the objects from the lessee without actually getting rid
> + * of the lessee itself; that way all references to it still work correctly.
>   */
>  int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
> index f99d3417f304..ba248ca8866f 100644
> --- a/include/drm/drm_auth.h
> +++ b/include/drm/drm_auth.h
> @@ -58,12 +58,6 @@ struct drm_lock_data {
>   * @refcount: Refcount for this master object.
>   * @dev: Link back to the DRM device
>   * @driver_priv: Pointer to driver-private information.
> - * @lessor: Lease holder
> - * @lessee_id: id for lessees. Owners always have id 0
> - * @lessee_list: other lessees of the same master
> - * @lessees: drm_masters leasing from this one
> - * @leases: Objects leased to this drm_master.
> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>   *
>   * Note that master structures are only relevant for the legacy/primary device
>   * nodes, hence there can only be one per device, not one per drm_minor.
> @@ -88,17 +82,68 @@ struct drm_master {
>  	struct idr magic_map;
>  	void *driver_priv;
>  
> -	/* Tree of display resource leases, each of which is a drm_master struct
> -	 * All of these get activated simultaneously, so drm_device master points
> -	 * at the top of the tree (for which lessor is NULL). Protected by
> -	 * &drm_device.mode_config.idr_mutex.
> +	/**
> +	 * @lessor:
> +	 *
> +	 * Lease grantor, only set if this &struct drm_master represents a
> +	 * lessee holding a lease of objects from @lessor. Full owners of the
> +	 * device have this set to NULL.
> +	 *
> +	 * The lessor does not change once it's set in drm_lease_create(), and
> +	 * each lessee holds a reference to its lessor that it releases upon
> +	 * being destroyed in drm_lease_destroy().
> +	 *
> +	 * See also the :ref:`section on display resource leasing
> +	 * <drm_leasing>`.
>  	 */
> -
>  	struct drm_master *lessor;
> +
> +	/**
> +	 * @lessee_id:
> +	 *
> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */
>  	int	lessee_id;
> +
> +	/**
> +	 * @lessee_list:
> +	 *
> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
> +	 * Not used for owners. Protected by &drm_device.mode_config's
> +	 * &drm_mode_config.idr_mutex.
> +	 */
>  	struct list_head lessee_list;
> +
> +	/**
> +	 * @lessees:
> +	 *
> +	 * List of drm_masters leasing from this one. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * This list is empty if no leases have been granted, or if all lessees
> +	 * have been destroyed. Since lessors are referenced by all their
> +	 * lessees, this master cannot be destroyed unless the list is empty.
> +	 */
>  	struct list_head lessees;
> +
> +	/**
> +	 * @leases:
> +	 *
> +	 * Objects leased to this drm_master. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * Objects are leased all together in drm_lease_create(), and are
> +	 * removed all together when the lease is revoked.
> +	 */
>  	struct idr leases;
> +
> +	/**
> +	 * @lessee_idr:
> +	 *
> +	 * All lessees under this owner (only used where @lessor is NULL).
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */

This also looks great now. With the one improvement addressed and I guess
the includes for drm_lease.[hc] and those parts of the patch removed
again:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

If you want perhaps do a follow-up patch to clean up the comments in
drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
maintained when it's not included, so short comments where they provide
real insight is imo best.
-Daniel

>  	struct idr lessee_idr;
>  	/* private: */
>  #if IS_ENABLED(CONFIG_DRM_LEGACY)
> -- 
> 2.25.1
> 

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

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
> We make the following changes to the documentation of drm leases to
> make it easier to reason about their usage. In particular, we clarify
> the lifetime and locking rules of lease fields in drm_master:
> 
> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
> lease idr and list structures for drm_master. The lessor field itself
> doesn't need to be protected as it doesn't change after it's set in
> drm_lease_create.
> 
> 2. Add descriptions for the lifetime of lessors and leases.
> 
> 3. Add an overview DOC: section in drm-uapi.rst that defines the
> terminology for drm leasing, and explains how leases work and why
> they're used.
> 
> 4. Clean up function documentation in drm_lease.c to use kernel-doc
> formatting.
> 
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> ---
> 
> Hi,
> 
> After I updated the formatting for comments in drm_lease.c, I noticed
> that none of these were driver interfaces (i.e. no structs/inline
> functions declared in headers, and no exported symbols in .c files).
> 
> I left the kernel-doc links inside drm-uapi.rst so that if any such
> interfaces are defined in the future, they'll go to the appropriate
> place. But if these should be removed, or if the formatting changes for
> function comments should be removed, please let me know.


Hm indeed, so there's not really any need to either include the
drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
useful.

For the internal pieces usually what we do is remove the comment outright
if it doesn't provide anything useful (like just repeats what the function
name says already). If there's something interesting in the comment then
we leave it that sentence in there as a normal comment, but without any of
the structured comment stuff (so no /**, nor @arguments, or the function
summary).



> 
> Best wishes,
> Desmond
> 
>  Documentation/gpu/drm-uapi.rst |  15 +++
>  drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>  include/drm/drm_auth.h         |  67 ++++++++++--
>  3 files changed, 180 insertions(+), 84 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 7e51dd40bf6e..6d7233a9fb14 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>  .. kernel-doc:: include/drm/drm_auth.h
>     :internal:
>  
> +
> +.. _drm_leasing:
> +
> +DRM Display Resource Leasing
> +============================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :doc: drm leasing
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :export:
> +
> +.. kernel-doc:: include/drm/drm_lease.h
> +   :internal:
> +
>  Open-Source Userspace Requirements
>  ==================================
>  
> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
> index 92eac73d9001..9b68617840ed 100644
> --- a/drivers/gpu/drm/drm_lease.c
> +++ b/drivers/gpu/drm/drm_lease.c
> @@ -15,18 +15,67 @@
>  #include "drm_crtc_internal.h"
>  #include "drm_internal.h"
>  
> +/**
> + * DOC: drm leasing
> + *
> + * DRM leases provide information about whether a DRM master may control a DRM
> + * mode setting object. This enables the creation of multiple DRM masters that
> + * manage subsets of display resources.
> + *
> + * The original DRM master of a device 'owns' the available drm resources. It
> + * may create additional DRM masters and 'lease' resources which it controls
> + * to the new DRM master. This gives the new DRM master control over the
> + * leased resources until the owner revokes the lease, or the new DRM master
> + * is closed. Some helpful terminology:
> + *
> + * - An 'owner' is a &struct drm_master that is not leasing objects from
> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
> + *
> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
> + *   other &struct drm_master. Currently, lessees are not allowed to
> + *   create sub-leases, hence the lessor is the same as the owner.
> + *
> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
> + *   other &struct drm_master. Each lessee only leases resources from a single
> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
> + *   it is leasing in &drm_master.leases.
> + *
> + * - A 'lease' is a contract between the lessor and lessee that identifies
> + *   which resources may be controlled by the lessee. All of the resources
> + *   that are leased must be owned by or leased to the lessor, and lessors are
> + *   not permitted to lease the same object to multiple lessees.
> + *
> + * The set of objects any &struct drm_master 'controls' is limited to the set
> + * of objects it leases (for lessees) or all objects (for owners).
> + *
> + * Objects not controlled by a &struct drm_master cannot be modified through
> + * the various state manipulating ioctls, and any state reported back to user
> + * space will be edited to make them appear idle and/or unusable. For
> + * instance, connectors always report 'disconnected', while encoders
> + * report no possible crtcs or clones.
> + *
> + * Since each lessee may lease objects from a single lessor, display resource
> + * leases form a tree of &struct drm_master. As lessees are currently not
> + * allowed to create sub-leases, the tree depth is limited to 1. All of
> + * these get activated simultaneously, so &drm_device.master points to the

I think it would be good to clarify that this happens when the top level
owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
looks good, thanks for typing it up.

> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
> + * objects from the owner can be searched via the owner's
> + * &drm_master.lessee_idr.
> + */
> +
>  #define drm_for_each_lessee(lessee, lessor) \
>  	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>  
>  static uint64_t drm_lease_idr_object;
>  
>  /**
> - * drm_lease_owner - return ancestor owner drm_master
> - * @master: drm_master somewhere within tree of lessees and lessors
> - *
> - * RETURN:
> + * drm_lease_owner - return the device owner in @master's lease tree
> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>   *
> - * drm_master at the top of the tree (i.e, with lessor NULL
> + * Returns the &struct drm_master that owns the device, i.e. the &struct
> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>   */
>  struct drm_master *drm_lease_owner(struct drm_master *master)
>  {
> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>  
>  /**
>   * _drm_find_lessee - find lessee by id (idr_mutex held)
> - * @master: drm_master of lessor
> - * @lessee_id: id
> + * @master: &struct drm_master of lessor
> + * @lessee_id: &drm_master.lessee_id of lessee
>   *
> - * RETURN:
> - *
> - * drm_master of the lessee if valid, NULL otherwise
> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>   */
>  
>  static struct drm_master*
> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>  }
>  
>  /**
> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
> + * @master (idr_mutex held)
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>   */
>  static int _drm_lease_held_master(struct drm_master *master, int id)
>  {
> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>  
>  /**
>   * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
> - * value:
> - *
> - *	true		Some lessee holds a lease on the object.
> - *	false		No lessee has a lease on the object.
> + * Returns true if any lessee of @master holds a lease on the given object,
> + * false if no lessee has a lease on the object.
>   */
>  static bool _drm_has_leased(struct drm_master *master, int id)
>  {
> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>  
>  /**
>   * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool _drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>  
>  /**
>   * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> - *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>  }
>  
>  /**
> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
> + * drm_lease_filter_crtcs - restricted crtc set to leased values
> + * (idr_mutex not held)
>   * @file_priv: requestor file
>   * @crtcs_in: bitmask of crtcs to check
>   *
> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>  }
>  
>  /*
> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
> + * drm_lease_create - create a new &struct drm_master with leased objects
> + * (idr_mutex not held)
>   * @lessor: lease holder (or owner) of objects
>   * @leases: objects to lease to the new drm_master
>   *
> - * Uses drm_master_create to allocate a new drm_master, then checks to
> - * make sure all of the desired objects can be leased, atomically
> - * leasing them to the new drmmaster.
> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
> + * to make sure all of the desired objects can be leased, atomically
> + * leasing them to the new &struct drm_master.
>   *
>   * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>   * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>  }
>  
>  /**
> - * drm_lease_destroy - a master is going away (idr_mutex not held)
> - * @master: the drm_master being destroyed
> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
> + * @master: the &struct drm_master being destroyed
>   *
> - * All lessees will have been destroyed as they
> - * hold a reference on their lessor. Notify any
> - * lessor for this master so that it can check
> - * the list of lessees.
> + * Destroys @master, then notifies any lessor for this master so that it can
> + * check the list of lessees. Note that all lessees of @master will have been
> + * destroyed for this function to be called as they hold a reference on their
> + * lessor.
>   */
>  void drm_lease_destroy(struct drm_master *master)
>  {
> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>  
>  /**
>   * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  static void _drm_lease_revoke(struct drm_master *top)
>  {
> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>  
>  /**
>   * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  void drm_lease_revoke(struct drm_master *top)
>  {
> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>  
>  /**
>   * drm_mode_create_lease_ioctl - create a new lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_create_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_create_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * The master associated with the specified file will have a lease
> + * The &struct drm_master associated with @lessor_priv will have a lease
>   * created containing the objects specified in the ioctl structure.
>   * A file descriptor will be allocated for that and returned to the
>   * application.
> + *
> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>   */
>  int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  }
>  
>  /**
> - * drm_mode_list_lessees_ioctl - list lessee ids
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_list_lessees
> - * @lessor_priv: the file being manipulated
> + * drm_mode_list_lessees_ioctl - list lessee IDs
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_list_lessees
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * Starting from the master associated with the specified file,
> - * the master with the provided lessee_id is found, and then
> - * an array of lessee ids associated with leases from that master
> - * are returned.
> + * Returns an array of &drm_master.lessee_id associated with lessees of
> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>   */
>  
>  int drm_mode_list_lessees_ioctl(struct drm_device *dev,
> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_get_lease_ioctl - list leased objects
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_get_lease
> - * @lessee_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_get_lease
> + * @lessee_priv: the &struct drm_file being manipulated
>   *
>   * Return the list of leased objects for the specified lessee
>   */
> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_revoke_lease_ioctl - revoke lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_revoke_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_revoke_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * This removes all of the objects from the lease without
> - * actually getting rid of the lease itself; that way all
> - * references to it still work correctly
> + * Removes all of the objects from the lessee without actually getting rid
> + * of the lessee itself; that way all references to it still work correctly.
>   */
>  int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
> index f99d3417f304..ba248ca8866f 100644
> --- a/include/drm/drm_auth.h
> +++ b/include/drm/drm_auth.h
> @@ -58,12 +58,6 @@ struct drm_lock_data {
>   * @refcount: Refcount for this master object.
>   * @dev: Link back to the DRM device
>   * @driver_priv: Pointer to driver-private information.
> - * @lessor: Lease holder
> - * @lessee_id: id for lessees. Owners always have id 0
> - * @lessee_list: other lessees of the same master
> - * @lessees: drm_masters leasing from this one
> - * @leases: Objects leased to this drm_master.
> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>   *
>   * Note that master structures are only relevant for the legacy/primary device
>   * nodes, hence there can only be one per device, not one per drm_minor.
> @@ -88,17 +82,68 @@ struct drm_master {
>  	struct idr magic_map;
>  	void *driver_priv;
>  
> -	/* Tree of display resource leases, each of which is a drm_master struct
> -	 * All of these get activated simultaneously, so drm_device master points
> -	 * at the top of the tree (for which lessor is NULL). Protected by
> -	 * &drm_device.mode_config.idr_mutex.
> +	/**
> +	 * @lessor:
> +	 *
> +	 * Lease grantor, only set if this &struct drm_master represents a
> +	 * lessee holding a lease of objects from @lessor. Full owners of the
> +	 * device have this set to NULL.
> +	 *
> +	 * The lessor does not change once it's set in drm_lease_create(), and
> +	 * each lessee holds a reference to its lessor that it releases upon
> +	 * being destroyed in drm_lease_destroy().
> +	 *
> +	 * See also the :ref:`section on display resource leasing
> +	 * <drm_leasing>`.
>  	 */
> -
>  	struct drm_master *lessor;
> +
> +	/**
> +	 * @lessee_id:
> +	 *
> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */
>  	int	lessee_id;
> +
> +	/**
> +	 * @lessee_list:
> +	 *
> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
> +	 * Not used for owners. Protected by &drm_device.mode_config's
> +	 * &drm_mode_config.idr_mutex.
> +	 */
>  	struct list_head lessee_list;
> +
> +	/**
> +	 * @lessees:
> +	 *
> +	 * List of drm_masters leasing from this one. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * This list is empty if no leases have been granted, or if all lessees
> +	 * have been destroyed. Since lessors are referenced by all their
> +	 * lessees, this master cannot be destroyed unless the list is empty.
> +	 */
>  	struct list_head lessees;
> +
> +	/**
> +	 * @leases:
> +	 *
> +	 * Objects leased to this drm_master. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * Objects are leased all together in drm_lease_create(), and are
> +	 * removed all together when the lease is revoked.
> +	 */
>  	struct idr leases;
> +
> +	/**
> +	 * @lessee_idr:
> +	 *
> +	 * All lessees under this owner (only used where @lessor is NULL).
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */

This also looks great now. With the one improvement addressed and I guess
the includes for drm_lease.[hc] and those parts of the patch removed
again:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

If you want perhaps do a follow-up patch to clean up the comments in
drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
maintained when it's not included, so short comments where they provide
real insight is imo best.
-Daniel

>  	struct idr lessee_idr;
>  	/* private: */
>  #if IS_ENABLED(CONFIG_DRM_LEGACY)
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Daniel Vetter]

On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
> We make the following changes to the documentation of drm leases to
> make it easier to reason about their usage. In particular, we clarify
> the lifetime and locking rules of lease fields in drm_master:
> 
> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
> lease idr and list structures for drm_master. The lessor field itself
> doesn't need to be protected as it doesn't change after it's set in
> drm_lease_create.
> 
> 2. Add descriptions for the lifetime of lessors and leases.
> 
> 3. Add an overview DOC: section in drm-uapi.rst that defines the
> terminology for drm leasing, and explains how leases work and why
> they're used.
> 
> 4. Clean up function documentation in drm_lease.c to use kernel-doc
> formatting.
> 
> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
> ---
> 
> Hi,
> 
> After I updated the formatting for comments in drm_lease.c, I noticed
> that none of these were driver interfaces (i.e. no structs/inline
> functions declared in headers, and no exported symbols in .c files).
> 
> I left the kernel-doc links inside drm-uapi.rst so that if any such
> interfaces are defined in the future, they'll go to the appropriate
> place. But if these should be removed, or if the formatting changes for
> function comments should be removed, please let me know.


Hm indeed, so there's not really any need to either include the
drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
useful.

For the internal pieces usually what we do is remove the comment outright
if it doesn't provide anything useful (like just repeats what the function
name says already). If there's something interesting in the comment then
we leave it that sentence in there as a normal comment, but without any of
the structured comment stuff (so no /**, nor @arguments, or the function
summary).



> 
> Best wishes,
> Desmond
> 
>  Documentation/gpu/drm-uapi.rst |  15 +++
>  drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>  include/drm/drm_auth.h         |  67 ++++++++++--
>  3 files changed, 180 insertions(+), 84 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 7e51dd40bf6e..6d7233a9fb14 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>  .. kernel-doc:: include/drm/drm_auth.h
>     :internal:
>  
> +
> +.. _drm_leasing:
> +
> +DRM Display Resource Leasing
> +============================
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :doc: drm leasing
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
> +   :export:
> +
> +.. kernel-doc:: include/drm/drm_lease.h
> +   :internal:
> +
>  Open-Source Userspace Requirements
>  ==================================
>  
> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
> index 92eac73d9001..9b68617840ed 100644
> --- a/drivers/gpu/drm/drm_lease.c
> +++ b/drivers/gpu/drm/drm_lease.c
> @@ -15,18 +15,67 @@
>  #include "drm_crtc_internal.h"
>  #include "drm_internal.h"
>  
> +/**
> + * DOC: drm leasing
> + *
> + * DRM leases provide information about whether a DRM master may control a DRM
> + * mode setting object. This enables the creation of multiple DRM masters that
> + * manage subsets of display resources.
> + *
> + * The original DRM master of a device 'owns' the available drm resources. It
> + * may create additional DRM masters and 'lease' resources which it controls
> + * to the new DRM master. This gives the new DRM master control over the
> + * leased resources until the owner revokes the lease, or the new DRM master
> + * is closed. Some helpful terminology:
> + *
> + * - An 'owner' is a &struct drm_master that is not leasing objects from
> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
> + *
> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
> + *   other &struct drm_master. Currently, lessees are not allowed to
> + *   create sub-leases, hence the lessor is the same as the owner.
> + *
> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
> + *   other &struct drm_master. Each lessee only leases resources from a single
> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
> + *   it is leasing in &drm_master.leases.
> + *
> + * - A 'lease' is a contract between the lessor and lessee that identifies
> + *   which resources may be controlled by the lessee. All of the resources
> + *   that are leased must be owned by or leased to the lessor, and lessors are
> + *   not permitted to lease the same object to multiple lessees.
> + *
> + * The set of objects any &struct drm_master 'controls' is limited to the set
> + * of objects it leases (for lessees) or all objects (for owners).
> + *
> + * Objects not controlled by a &struct drm_master cannot be modified through
> + * the various state manipulating ioctls, and any state reported back to user
> + * space will be edited to make them appear idle and/or unusable. For
> + * instance, connectors always report 'disconnected', while encoders
> + * report no possible crtcs or clones.
> + *
> + * Since each lessee may lease objects from a single lessor, display resource
> + * leases form a tree of &struct drm_master. As lessees are currently not
> + * allowed to create sub-leases, the tree depth is limited to 1. All of
> + * these get activated simultaneously, so &drm_device.master points to the

I think it would be good to clarify that this happens when the top level
owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
looks good, thanks for typing it up.

> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
> + * objects from the owner can be searched via the owner's
> + * &drm_master.lessee_idr.
> + */
> +
>  #define drm_for_each_lessee(lessee, lessor) \
>  	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>  
>  static uint64_t drm_lease_idr_object;
>  
>  /**
> - * drm_lease_owner - return ancestor owner drm_master
> - * @master: drm_master somewhere within tree of lessees and lessors
> - *
> - * RETURN:
> + * drm_lease_owner - return the device owner in @master's lease tree
> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>   *
> - * drm_master at the top of the tree (i.e, with lessor NULL
> + * Returns the &struct drm_master that owns the device, i.e. the &struct
> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>   */
>  struct drm_master *drm_lease_owner(struct drm_master *master)
>  {
> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>  
>  /**
>   * _drm_find_lessee - find lessee by id (idr_mutex held)
> - * @master: drm_master of lessor
> - * @lessee_id: id
> + * @master: &struct drm_master of lessor
> + * @lessee_id: &drm_master.lessee_id of lessee
>   *
> - * RETURN:
> - *
> - * drm_master of the lessee if valid, NULL otherwise
> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>   */
>  
>  static struct drm_master*
> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>  }
>  
>  /**
> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
> + * @master (idr_mutex held)
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>   */
>  static int _drm_lease_held_master(struct drm_master *master, int id)
>  {
> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>  
>  /**
>   * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
> - * @master: the master to check the lease status of
> - * @id: the id to check
> + * @master: the &struct drm_master to check the lease status of
> + * @id: the object ID to check
>   *
> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
> - * value:
> - *
> - *	true		Some lessee holds a lease on the object.
> - *	false		No lessee has a lease on the object.
> + * Returns true if any lessee of @master holds a lease on the given object,
> + * false if no lessee has a lease on the object.
>   */
>  static bool _drm_has_leased(struct drm_master *master, int id)
>  {
> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>  
>  /**
>   * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> - *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool _drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>  
>  /**
>   * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
> - * @file_priv: the master drm_file
> - * @id: the object id
> + * @file_priv: the master &struct drm_file
> + * @id: the object ID
>   *
> - * Checks if the specified master holds a lease on the object. Return
> - * value:
> - *
> - *	true		'master' holds a lease on (or owns) the object
> - *	false		'master' does not hold a lease.
> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
> + * object, false if it does not.
>   */
>  bool drm_lease_held(struct drm_file *file_priv, int id)
>  {
> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>  }
>  
>  /**
> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
> + * drm_lease_filter_crtcs - restricted crtc set to leased values
> + * (idr_mutex not held)
>   * @file_priv: requestor file
>   * @crtcs_in: bitmask of crtcs to check
>   *
> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>  }
>  
>  /*
> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
> + * drm_lease_create - create a new &struct drm_master with leased objects
> + * (idr_mutex not held)
>   * @lessor: lease holder (or owner) of objects
>   * @leases: objects to lease to the new drm_master
>   *
> - * Uses drm_master_create to allocate a new drm_master, then checks to
> - * make sure all of the desired objects can be leased, atomically
> - * leasing them to the new drmmaster.
> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
> + * to make sure all of the desired objects can be leased, atomically
> + * leasing them to the new &struct drm_master.
>   *
>   * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>   * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>  }
>  
>  /**
> - * drm_lease_destroy - a master is going away (idr_mutex not held)
> - * @master: the drm_master being destroyed
> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
> + * @master: the &struct drm_master being destroyed
>   *
> - * All lessees will have been destroyed as they
> - * hold a reference on their lessor. Notify any
> - * lessor for this master so that it can check
> - * the list of lessees.
> + * Destroys @master, then notifies any lessor for this master so that it can
> + * check the list of lessees. Note that all lessees of @master will have been
> + * destroyed for this function to be called as they hold a reference on their
> + * lessor.
>   */
>  void drm_lease_destroy(struct drm_master *master)
>  {
> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>  
>  /**
>   * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  static void _drm_lease_revoke(struct drm_master *top)
>  {
> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>  
>  /**
>   * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
> - * @top: the master losing its lease
> + * @top: the &struct drm_master losing its lease
>   */
>  void drm_lease_revoke(struct drm_master *top)
>  {
> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>  
>  /**
>   * drm_mode_create_lease_ioctl - create a new lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_create_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_create_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * The master associated with the specified file will have a lease
> + * The &struct drm_master associated with @lessor_priv will have a lease
>   * created containing the objects specified in the ioctl structure.
>   * A file descriptor will be allocated for that and returned to the
>   * application.
> + *
> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>   */
>  int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>  }
>  
>  /**
> - * drm_mode_list_lessees_ioctl - list lessee ids
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_list_lessees
> - * @lessor_priv: the file being manipulated
> + * drm_mode_list_lessees_ioctl - list lessee IDs
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_list_lessees
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * Starting from the master associated with the specified file,
> - * the master with the provided lessee_id is found, and then
> - * an array of lessee ids associated with leases from that master
> - * are returned.
> + * Returns an array of &drm_master.lessee_id associated with lessees of
> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>   */
>  
>  int drm_mode_list_lessees_ioctl(struct drm_device *dev,
> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_get_lease_ioctl - list leased objects
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_get_lease
> - * @lessee_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_get_lease
> + * @lessee_priv: the &struct drm_file being manipulated
>   *
>   * Return the list of leased objects for the specified lessee
>   */
> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>  
>  /**
>   * drm_mode_revoke_lease_ioctl - revoke lease
> - * @dev: the drm device
> - * @data: pointer to struct drm_mode_revoke_lease
> - * @lessor_priv: the file being manipulated
> + * @dev: the &struct drm_device
> + * @data: pointer to &struct drm_mode_revoke_lease
> + * @lessor_priv: the &struct drm_file being manipulated
>   *
> - * This removes all of the objects from the lease without
> - * actually getting rid of the lease itself; that way all
> - * references to it still work correctly
> + * Removes all of the objects from the lessee without actually getting rid
> + * of the lessee itself; that way all references to it still work correctly.
>   */
>  int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>  				void *data, struct drm_file *lessor_priv)
> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
> index f99d3417f304..ba248ca8866f 100644
> --- a/include/drm/drm_auth.h
> +++ b/include/drm/drm_auth.h
> @@ -58,12 +58,6 @@ struct drm_lock_data {
>   * @refcount: Refcount for this master object.
>   * @dev: Link back to the DRM device
>   * @driver_priv: Pointer to driver-private information.
> - * @lessor: Lease holder
> - * @lessee_id: id for lessees. Owners always have id 0
> - * @lessee_list: other lessees of the same master
> - * @lessees: drm_masters leasing from this one
> - * @leases: Objects leased to this drm_master.
> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>   *
>   * Note that master structures are only relevant for the legacy/primary device
>   * nodes, hence there can only be one per device, not one per drm_minor.
> @@ -88,17 +82,68 @@ struct drm_master {
>  	struct idr magic_map;
>  	void *driver_priv;
>  
> -	/* Tree of display resource leases, each of which is a drm_master struct
> -	 * All of these get activated simultaneously, so drm_device master points
> -	 * at the top of the tree (for which lessor is NULL). Protected by
> -	 * &drm_device.mode_config.idr_mutex.
> +	/**
> +	 * @lessor:
> +	 *
> +	 * Lease grantor, only set if this &struct drm_master represents a
> +	 * lessee holding a lease of objects from @lessor. Full owners of the
> +	 * device have this set to NULL.
> +	 *
> +	 * The lessor does not change once it's set in drm_lease_create(), and
> +	 * each lessee holds a reference to its lessor that it releases upon
> +	 * being destroyed in drm_lease_destroy().
> +	 *
> +	 * See also the :ref:`section on display resource leasing
> +	 * <drm_leasing>`.
>  	 */
> -
>  	struct drm_master *lessor;
> +
> +	/**
> +	 * @lessee_id:
> +	 *
> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */
>  	int	lessee_id;
> +
> +	/**
> +	 * @lessee_list:
> +	 *
> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
> +	 * Not used for owners. Protected by &drm_device.mode_config's
> +	 * &drm_mode_config.idr_mutex.
> +	 */
>  	struct list_head lessee_list;
> +
> +	/**
> +	 * @lessees:
> +	 *
> +	 * List of drm_masters leasing from this one. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * This list is empty if no leases have been granted, or if all lessees
> +	 * have been destroyed. Since lessors are referenced by all their
> +	 * lessees, this master cannot be destroyed unless the list is empty.
> +	 */
>  	struct list_head lessees;
> +
> +	/**
> +	 * @leases:
> +	 *
> +	 * Objects leased to this drm_master. Protected by
> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 *
> +	 * Objects are leased all together in drm_lease_create(), and are
> +	 * removed all together when the lease is revoked.
> +	 */
>  	struct idr leases;
> +
> +	/**
> +	 * @lessee_idr:
> +	 *
> +	 * All lessees under this owner (only used where @lessor is NULL).
> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
> +	 */

This also looks great now. With the one improvement addressed and I guess
the includes for drm_lease.[hc] and those parts of the patch removed
again:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

If you want perhaps do a follow-up patch to clean up the comments in
drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
maintained when it's not included, so short comments where they provide
real insight is imo best.
-Daniel

>  	struct idr lessee_idr;
>  	/* private: */
>  #if IS_ENABLED(CONFIG_DRM_LEGACY)
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

On 27/7/21 9:04 pm, Daniel Vetter wrote:
> On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
>> We make the following changes to the documentation of drm leases to
>> make it easier to reason about their usage. In particular, we clarify
>> the lifetime and locking rules of lease fields in drm_master:
>>
>> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
>> lease idr and list structures for drm_master. The lessor field itself
>> doesn't need to be protected as it doesn't change after it's set in
>> drm_lease_create.
>>
>> 2. Add descriptions for the lifetime of lessors and leases.
>>
>> 3. Add an overview DOC: section in drm-uapi.rst that defines the
>> terminology for drm leasing, and explains how leases work and why
>> they're used.
>>
>> 4. Clean up function documentation in drm_lease.c to use kernel-doc
>> formatting.
>>
>> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
>> ---
>>
>> Hi,
>>
>> After I updated the formatting for comments in drm_lease.c, I noticed
>> that none of these were driver interfaces (i.e. no structs/inline
>> functions declared in headers, and no exported symbols in .c files).
>>
>> I left the kernel-doc links inside drm-uapi.rst so that if any such
>> interfaces are defined in the future, they'll go to the appropriate
>> place. But if these should be removed, or if the formatting changes for
>> function comments should be removed, please let me know.
> 
> 
> Hm indeed, so there's not really any need to either include the
> drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
> useful.
> 
> For the internal pieces usually what we do is remove the comment outright
> if it doesn't provide anything useful (like just repeats what the function
> name says already). If there's something interesting in the comment then
> we leave it that sentence in there as a normal comment, but without any of
> the structured comment stuff (so no /**, nor @arguments, or the function
> summary).
> 
> 
> 
>>
>> Best wishes,
>> Desmond
>>
>>   Documentation/gpu/drm-uapi.rst |  15 +++
>>   drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>>   include/drm/drm_auth.h         |  67 ++++++++++--
>>   3 files changed, 180 insertions(+), 84 deletions(-)
>>
>> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
>> index 7e51dd40bf6e..6d7233a9fb14 100644
>> --- a/Documentation/gpu/drm-uapi.rst
>> +++ b/Documentation/gpu/drm-uapi.rst
>> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>>   .. kernel-doc:: include/drm/drm_auth.h
>>      :internal:
>>   
>> +
>> +.. _drm_leasing:
>> +
>> +DRM Display Resource Leasing
>> +============================
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :doc: drm leasing
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :export:
>> +
>> +.. kernel-doc:: include/drm/drm_lease.h
>> +   :internal:
>> +
>>   Open-Source Userspace Requirements
>>   ==================================
>>   
>> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
>> index 92eac73d9001..9b68617840ed 100644
>> --- a/drivers/gpu/drm/drm_lease.c
>> +++ b/drivers/gpu/drm/drm_lease.c
>> @@ -15,18 +15,67 @@
>>   #include "drm_crtc_internal.h"
>>   #include "drm_internal.h"
>>   
>> +/**
>> + * DOC: drm leasing
>> + *
>> + * DRM leases provide information about whether a DRM master may control a DRM
>> + * mode setting object. This enables the creation of multiple DRM masters that
>> + * manage subsets of display resources.
>> + *
>> + * The original DRM master of a device 'owns' the available drm resources. It
>> + * may create additional DRM masters and 'lease' resources which it controls
>> + * to the new DRM master. This gives the new DRM master control over the
>> + * leased resources until the owner revokes the lease, or the new DRM master
>> + * is closed. Some helpful terminology:
>> + *
>> + * - An 'owner' is a &struct drm_master that is not leasing objects from
>> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
>> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
>> + *
>> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
>> + *   other &struct drm_master. Currently, lessees are not allowed to
>> + *   create sub-leases, hence the lessor is the same as the owner.
>> + *
>> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
>> + *   other &struct drm_master. Each lessee only leases resources from a single
>> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
>> + *   it is leasing in &drm_master.leases.
>> + *
>> + * - A 'lease' is a contract between the lessor and lessee that identifies
>> + *   which resources may be controlled by the lessee. All of the resources
>> + *   that are leased must be owned by or leased to the lessor, and lessors are
>> + *   not permitted to lease the same object to multiple lessees.
>> + *
>> + * The set of objects any &struct drm_master 'controls' is limited to the set
>> + * of objects it leases (for lessees) or all objects (for owners).
>> + *
>> + * Objects not controlled by a &struct drm_master cannot be modified through
>> + * the various state manipulating ioctls, and any state reported back to user
>> + * space will be edited to make them appear idle and/or unusable. For
>> + * instance, connectors always report 'disconnected', while encoders
>> + * report no possible crtcs or clones.
>> + *
>> + * Since each lessee may lease objects from a single lessor, display resource
>> + * leases form a tree of &struct drm_master. As lessees are currently not
>> + * allowed to create sub-leases, the tree depth is limited to 1. All of
>> + * these get activated simultaneously, so &drm_device.master points to the
> 
> I think it would be good to clarify that this happens when the top level
> owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
> looks good, thanks for typing it up.
> 
>> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
>> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
>> + * objects from the owner can be searched via the owner's
>> + * &drm_master.lessee_idr.
>> + */
>> +
>>   #define drm_for_each_lessee(lessee, lessor) \
>>   	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>>   
>>   static uint64_t drm_lease_idr_object;
>>   
>>   /**
>> - * drm_lease_owner - return ancestor owner drm_master
>> - * @master: drm_master somewhere within tree of lessees and lessors
>> - *
>> - * RETURN:
>> + * drm_lease_owner - return the device owner in @master's lease tree
>> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>>    *
>> - * drm_master at the top of the tree (i.e, with lessor NULL
>> + * Returns the &struct drm_master that owns the device, i.e. the &struct
>> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>>    */
>>   struct drm_master *drm_lease_owner(struct drm_master *master)
>>   {
>> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>>   
>>   /**
>>    * _drm_find_lessee - find lessee by id (idr_mutex held)
>> - * @master: drm_master of lessor
>> - * @lessee_id: id
>> + * @master: &struct drm_master of lessor
>> + * @lessee_id: &drm_master.lessee_id of lessee
>>    *
>> - * RETURN:
>> - *
>> - * drm_master of the lessee if valid, NULL otherwise
>> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>>    */
>>   
>>   static struct drm_master*
>> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>>   }
>>   
>>   /**
>> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
>> + * @master (idr_mutex held)
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>>    */
>>   static int _drm_lease_held_master(struct drm_master *master, int id)
>>   {
>> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
>> - * value:
>> - *
>> - *	true		Some lessee holds a lease on the object.
>> - *	false		No lessee has a lease on the object.
>> + * Returns true if any lessee of @master holds a lease on the given object,
>> + * false if no lessee has a lease on the object.
>>    */
>>   static bool _drm_has_leased(struct drm_master *master, int id)
>>   {
>> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   
>>   /**
>>    * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> - *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>>   }
>>   
>>   /**
>> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
>> + * drm_lease_filter_crtcs - restricted crtc set to leased values
>> + * (idr_mutex not held)
>>    * @file_priv: requestor file
>>    * @crtcs_in: bitmask of crtcs to check
>>    *
>> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>>   }
>>   
>>   /*
>> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
>> + * drm_lease_create - create a new &struct drm_master with leased objects
>> + * (idr_mutex not held)
>>    * @lessor: lease holder (or owner) of objects
>>    * @leases: objects to lease to the new drm_master
>>    *
>> - * Uses drm_master_create to allocate a new drm_master, then checks to
>> - * make sure all of the desired objects can be leased, atomically
>> - * leasing them to the new drmmaster.
>> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
>> + * to make sure all of the desired objects can be leased, atomically
>> + * leasing them to the new &struct drm_master.
>>    *
>>    * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>>    * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
>> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>>   }
>>   
>>   /**
>> - * drm_lease_destroy - a master is going away (idr_mutex not held)
>> - * @master: the drm_master being destroyed
>> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
>> + * @master: the &struct drm_master being destroyed
>>    *
>> - * All lessees will have been destroyed as they
>> - * hold a reference on their lessor. Notify any
>> - * lessor for this master so that it can check
>> - * the list of lessees.
>> + * Destroys @master, then notifies any lessor for this master so that it can
>> + * check the list of lessees. Note that all lessees of @master will have been
>> + * destroyed for this function to be called as they hold a reference on their
>> + * lessor.
>>    */
>>   void drm_lease_destroy(struct drm_master *master)
>>   {
>> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>>   
>>   /**
>>    * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   static void _drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>>   
>>   /**
>>    * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   void drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_create_lease_ioctl - create a new lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_create_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_create_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * The master associated with the specified file will have a lease
>> + * The &struct drm_master associated with @lessor_priv will have a lease
>>    * created containing the objects specified in the ioctl structure.
>>    * A file descriptor will be allocated for that and returned to the
>>    * application.
>> + *
>> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>>    */
>>   int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   }
>>   
>>   /**
>> - * drm_mode_list_lessees_ioctl - list lessee ids
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_list_lessees
>> - * @lessor_priv: the file being manipulated
>> + * drm_mode_list_lessees_ioctl - list lessee IDs
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_list_lessees
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * Starting from the master associated with the specified file,
>> - * the master with the provided lessee_id is found, and then
>> - * an array of lessee ids associated with leases from that master
>> - * are returned.
>> + * Returns an array of &drm_master.lessee_id associated with lessees of
>> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>>    */
>>   
>>   int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_get_lease_ioctl - list leased objects
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_get_lease
>> - * @lessee_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_get_lease
>> + * @lessee_priv: the &struct drm_file being manipulated
>>    *
>>    * Return the list of leased objects for the specified lessee
>>    */
>> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_revoke_lease_ioctl - revoke lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_revoke_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_revoke_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * This removes all of the objects from the lease without
>> - * actually getting rid of the lease itself; that way all
>> - * references to it still work correctly
>> + * Removes all of the objects from the lessee without actually getting rid
>> + * of the lessee itself; that way all references to it still work correctly.
>>    */
>>   int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
>> index f99d3417f304..ba248ca8866f 100644
>> --- a/include/drm/drm_auth.h
>> +++ b/include/drm/drm_auth.h
>> @@ -58,12 +58,6 @@ struct drm_lock_data {
>>    * @refcount: Refcount for this master object.
>>    * @dev: Link back to the DRM device
>>    * @driver_priv: Pointer to driver-private information.
>> - * @lessor: Lease holder
>> - * @lessee_id: id for lessees. Owners always have id 0
>> - * @lessee_list: other lessees of the same master
>> - * @lessees: drm_masters leasing from this one
>> - * @leases: Objects leased to this drm_master.
>> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>>    *
>>    * Note that master structures are only relevant for the legacy/primary device
>>    * nodes, hence there can only be one per device, not one per drm_minor.
>> @@ -88,17 +82,68 @@ struct drm_master {
>>   	struct idr magic_map;
>>   	void *driver_priv;
>>   
>> -	/* Tree of display resource leases, each of which is a drm_master struct
>> -	 * All of these get activated simultaneously, so drm_device master points
>> -	 * at the top of the tree (for which lessor is NULL). Protected by
>> -	 * &drm_device.mode_config.idr_mutex.
>> +	/**
>> +	 * @lessor:
>> +	 *
>> +	 * Lease grantor, only set if this &struct drm_master represents a
>> +	 * lessee holding a lease of objects from @lessor. Full owners of the
>> +	 * device have this set to NULL.
>> +	 *
>> +	 * The lessor does not change once it's set in drm_lease_create(), and
>> +	 * each lessee holds a reference to its lessor that it releases upon
>> +	 * being destroyed in drm_lease_destroy().
>> +	 *
>> +	 * See also the :ref:`section on display resource leasing
>> +	 * <drm_leasing>`.
>>   	 */
>> -
>>   	struct drm_master *lessor;
>> +
>> +	/**
>> +	 * @lessee_id:
>> +	 *
>> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
>>   	int	lessee_id;
>> +
>> +	/**
>> +	 * @lessee_list:
>> +	 *
>> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
>> +	 * Not used for owners. Protected by &drm_device.mode_config's
>> +	 * &drm_mode_config.idr_mutex.
>> +	 */
>>   	struct list_head lessee_list;
>> +
>> +	/**
>> +	 * @lessees:
>> +	 *
>> +	 * List of drm_masters leasing from this one. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * This list is empty if no leases have been granted, or if all lessees
>> +	 * have been destroyed. Since lessors are referenced by all their
>> +	 * lessees, this master cannot be destroyed unless the list is empty.
>> +	 */
>>   	struct list_head lessees;
>> +
>> +	/**
>> +	 * @leases:
>> +	 *
>> +	 * Objects leased to this drm_master. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * Objects are leased all together in drm_lease_create(), and are
>> +	 * removed all together when the lease is revoked.
>> +	 */
>>   	struct idr leases;
>> +
>> +	/**
>> +	 * @lessee_idr:
>> +	 *
>> +	 * All lessees under this owner (only used where @lessor is NULL).
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
> 
> This also looks great now. With the one improvement addressed and I guess
> the includes for drm_lease.[hc] and those parts of the patch removed
> again:
> 
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> If you want perhaps do a follow-up patch to clean up the comments in
> drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
> maintained when it's not included, so short comments where they provide
> real insight is imo best.
> -Daniel
> 

Thanks for the feedback, Daniel.

Sounds good, I'll send out the updated patch with the suggested changes, 
followed by a clean up of drm_lease.c.

Best wishes,
Desmond

>>   	struct idr lessee_idr;
>>   	/* private: */
>>   #if IS_ENABLED(CONFIG_DRM_LEGACY)
>> -- 
>> 2.25.1
>>
> 

Re: [Intel-gfx] [PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

On 27/7/21 9:04 pm, Daniel Vetter wrote:
> On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
>> We make the following changes to the documentation of drm leases to
>> make it easier to reason about their usage. In particular, we clarify
>> the lifetime and locking rules of lease fields in drm_master:
>>
>> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
>> lease idr and list structures for drm_master. The lessor field itself
>> doesn't need to be protected as it doesn't change after it's set in
>> drm_lease_create.
>>
>> 2. Add descriptions for the lifetime of lessors and leases.
>>
>> 3. Add an overview DOC: section in drm-uapi.rst that defines the
>> terminology for drm leasing, and explains how leases work and why
>> they're used.
>>
>> 4. Clean up function documentation in drm_lease.c to use kernel-doc
>> formatting.
>>
>> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
>> ---
>>
>> Hi,
>>
>> After I updated the formatting for comments in drm_lease.c, I noticed
>> that none of these were driver interfaces (i.e. no structs/inline
>> functions declared in headers, and no exported symbols in .c files).
>>
>> I left the kernel-doc links inside drm-uapi.rst so that if any such
>> interfaces are defined in the future, they'll go to the appropriate
>> place. But if these should be removed, or if the formatting changes for
>> function comments should be removed, please let me know.
> 
> 
> Hm indeed, so there's not really any need to either include the
> drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
> useful.
> 
> For the internal pieces usually what we do is remove the comment outright
> if it doesn't provide anything useful (like just repeats what the function
> name says already). If there's something interesting in the comment then
> we leave it that sentence in there as a normal comment, but without any of
> the structured comment stuff (so no /**, nor @arguments, or the function
> summary).
> 
> 
> 
>>
>> Best wishes,
>> Desmond
>>
>>   Documentation/gpu/drm-uapi.rst |  15 +++
>>   drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>>   include/drm/drm_auth.h         |  67 ++++++++++--
>>   3 files changed, 180 insertions(+), 84 deletions(-)
>>
>> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
>> index 7e51dd40bf6e..6d7233a9fb14 100644
>> --- a/Documentation/gpu/drm-uapi.rst
>> +++ b/Documentation/gpu/drm-uapi.rst
>> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>>   .. kernel-doc:: include/drm/drm_auth.h
>>      :internal:
>>   
>> +
>> +.. _drm_leasing:
>> +
>> +DRM Display Resource Leasing
>> +============================
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :doc: drm leasing
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :export:
>> +
>> +.. kernel-doc:: include/drm/drm_lease.h
>> +   :internal:
>> +
>>   Open-Source Userspace Requirements
>>   ==================================
>>   
>> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
>> index 92eac73d9001..9b68617840ed 100644
>> --- a/drivers/gpu/drm/drm_lease.c
>> +++ b/drivers/gpu/drm/drm_lease.c
>> @@ -15,18 +15,67 @@
>>   #include "drm_crtc_internal.h"
>>   #include "drm_internal.h"
>>   
>> +/**
>> + * DOC: drm leasing
>> + *
>> + * DRM leases provide information about whether a DRM master may control a DRM
>> + * mode setting object. This enables the creation of multiple DRM masters that
>> + * manage subsets of display resources.
>> + *
>> + * The original DRM master of a device 'owns' the available drm resources. It
>> + * may create additional DRM masters and 'lease' resources which it controls
>> + * to the new DRM master. This gives the new DRM master control over the
>> + * leased resources until the owner revokes the lease, or the new DRM master
>> + * is closed. Some helpful terminology:
>> + *
>> + * - An 'owner' is a &struct drm_master that is not leasing objects from
>> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
>> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
>> + *
>> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
>> + *   other &struct drm_master. Currently, lessees are not allowed to
>> + *   create sub-leases, hence the lessor is the same as the owner.
>> + *
>> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
>> + *   other &struct drm_master. Each lessee only leases resources from a single
>> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
>> + *   it is leasing in &drm_master.leases.
>> + *
>> + * - A 'lease' is a contract between the lessor and lessee that identifies
>> + *   which resources may be controlled by the lessee. All of the resources
>> + *   that are leased must be owned by or leased to the lessor, and lessors are
>> + *   not permitted to lease the same object to multiple lessees.
>> + *
>> + * The set of objects any &struct drm_master 'controls' is limited to the set
>> + * of objects it leases (for lessees) or all objects (for owners).
>> + *
>> + * Objects not controlled by a &struct drm_master cannot be modified through
>> + * the various state manipulating ioctls, and any state reported back to user
>> + * space will be edited to make them appear idle and/or unusable. For
>> + * instance, connectors always report 'disconnected', while encoders
>> + * report no possible crtcs or clones.
>> + *
>> + * Since each lessee may lease objects from a single lessor, display resource
>> + * leases form a tree of &struct drm_master. As lessees are currently not
>> + * allowed to create sub-leases, the tree depth is limited to 1. All of
>> + * these get activated simultaneously, so &drm_device.master points to the
> 
> I think it would be good to clarify that this happens when the top level
> owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
> looks good, thanks for typing it up.
> 
>> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
>> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
>> + * objects from the owner can be searched via the owner's
>> + * &drm_master.lessee_idr.
>> + */
>> +
>>   #define drm_for_each_lessee(lessee, lessor) \
>>   	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>>   
>>   static uint64_t drm_lease_idr_object;
>>   
>>   /**
>> - * drm_lease_owner - return ancestor owner drm_master
>> - * @master: drm_master somewhere within tree of lessees and lessors
>> - *
>> - * RETURN:
>> + * drm_lease_owner - return the device owner in @master's lease tree
>> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>>    *
>> - * drm_master at the top of the tree (i.e, with lessor NULL
>> + * Returns the &struct drm_master that owns the device, i.e. the &struct
>> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>>    */
>>   struct drm_master *drm_lease_owner(struct drm_master *master)
>>   {
>> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>>   
>>   /**
>>    * _drm_find_lessee - find lessee by id (idr_mutex held)
>> - * @master: drm_master of lessor
>> - * @lessee_id: id
>> + * @master: &struct drm_master of lessor
>> + * @lessee_id: &drm_master.lessee_id of lessee
>>    *
>> - * RETURN:
>> - *
>> - * drm_master of the lessee if valid, NULL otherwise
>> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>>    */
>>   
>>   static struct drm_master*
>> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>>   }
>>   
>>   /**
>> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
>> + * @master (idr_mutex held)
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>>    */
>>   static int _drm_lease_held_master(struct drm_master *master, int id)
>>   {
>> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
>> - * value:
>> - *
>> - *	true		Some lessee holds a lease on the object.
>> - *	false		No lessee has a lease on the object.
>> + * Returns true if any lessee of @master holds a lease on the given object,
>> + * false if no lessee has a lease on the object.
>>    */
>>   static bool _drm_has_leased(struct drm_master *master, int id)
>>   {
>> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   
>>   /**
>>    * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> - *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>>   }
>>   
>>   /**
>> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
>> + * drm_lease_filter_crtcs - restricted crtc set to leased values
>> + * (idr_mutex not held)
>>    * @file_priv: requestor file
>>    * @crtcs_in: bitmask of crtcs to check
>>    *
>> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>>   }
>>   
>>   /*
>> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
>> + * drm_lease_create - create a new &struct drm_master with leased objects
>> + * (idr_mutex not held)
>>    * @lessor: lease holder (or owner) of objects
>>    * @leases: objects to lease to the new drm_master
>>    *
>> - * Uses drm_master_create to allocate a new drm_master, then checks to
>> - * make sure all of the desired objects can be leased, atomically
>> - * leasing them to the new drmmaster.
>> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
>> + * to make sure all of the desired objects can be leased, atomically
>> + * leasing them to the new &struct drm_master.
>>    *
>>    * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>>    * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
>> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>>   }
>>   
>>   /**
>> - * drm_lease_destroy - a master is going away (idr_mutex not held)
>> - * @master: the drm_master being destroyed
>> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
>> + * @master: the &struct drm_master being destroyed
>>    *
>> - * All lessees will have been destroyed as they
>> - * hold a reference on their lessor. Notify any
>> - * lessor for this master so that it can check
>> - * the list of lessees.
>> + * Destroys @master, then notifies any lessor for this master so that it can
>> + * check the list of lessees. Note that all lessees of @master will have been
>> + * destroyed for this function to be called as they hold a reference on their
>> + * lessor.
>>    */
>>   void drm_lease_destroy(struct drm_master *master)
>>   {
>> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>>   
>>   /**
>>    * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   static void _drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>>   
>>   /**
>>    * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   void drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_create_lease_ioctl - create a new lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_create_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_create_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * The master associated with the specified file will have a lease
>> + * The &struct drm_master associated with @lessor_priv will have a lease
>>    * created containing the objects specified in the ioctl structure.
>>    * A file descriptor will be allocated for that and returned to the
>>    * application.
>> + *
>> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>>    */
>>   int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   }
>>   
>>   /**
>> - * drm_mode_list_lessees_ioctl - list lessee ids
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_list_lessees
>> - * @lessor_priv: the file being manipulated
>> + * drm_mode_list_lessees_ioctl - list lessee IDs
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_list_lessees
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * Starting from the master associated with the specified file,
>> - * the master with the provided lessee_id is found, and then
>> - * an array of lessee ids associated with leases from that master
>> - * are returned.
>> + * Returns an array of &drm_master.lessee_id associated with lessees of
>> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>>    */
>>   
>>   int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_get_lease_ioctl - list leased objects
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_get_lease
>> - * @lessee_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_get_lease
>> + * @lessee_priv: the &struct drm_file being manipulated
>>    *
>>    * Return the list of leased objects for the specified lessee
>>    */
>> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_revoke_lease_ioctl - revoke lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_revoke_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_revoke_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * This removes all of the objects from the lease without
>> - * actually getting rid of the lease itself; that way all
>> - * references to it still work correctly
>> + * Removes all of the objects from the lessee without actually getting rid
>> + * of the lessee itself; that way all references to it still work correctly.
>>    */
>>   int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
>> index f99d3417f304..ba248ca8866f 100644
>> --- a/include/drm/drm_auth.h
>> +++ b/include/drm/drm_auth.h
>> @@ -58,12 +58,6 @@ struct drm_lock_data {
>>    * @refcount: Refcount for this master object.
>>    * @dev: Link back to the DRM device
>>    * @driver_priv: Pointer to driver-private information.
>> - * @lessor: Lease holder
>> - * @lessee_id: id for lessees. Owners always have id 0
>> - * @lessee_list: other lessees of the same master
>> - * @lessees: drm_masters leasing from this one
>> - * @leases: Objects leased to this drm_master.
>> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>>    *
>>    * Note that master structures are only relevant for the legacy/primary device
>>    * nodes, hence there can only be one per device, not one per drm_minor.
>> @@ -88,17 +82,68 @@ struct drm_master {
>>   	struct idr magic_map;
>>   	void *driver_priv;
>>   
>> -	/* Tree of display resource leases, each of which is a drm_master struct
>> -	 * All of these get activated simultaneously, so drm_device master points
>> -	 * at the top of the tree (for which lessor is NULL). Protected by
>> -	 * &drm_device.mode_config.idr_mutex.
>> +	/**
>> +	 * @lessor:
>> +	 *
>> +	 * Lease grantor, only set if this &struct drm_master represents a
>> +	 * lessee holding a lease of objects from @lessor. Full owners of the
>> +	 * device have this set to NULL.
>> +	 *
>> +	 * The lessor does not change once it's set in drm_lease_create(), and
>> +	 * each lessee holds a reference to its lessor that it releases upon
>> +	 * being destroyed in drm_lease_destroy().
>> +	 *
>> +	 * See also the :ref:`section on display resource leasing
>> +	 * <drm_leasing>`.
>>   	 */
>> -
>>   	struct drm_master *lessor;
>> +
>> +	/**
>> +	 * @lessee_id:
>> +	 *
>> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
>>   	int	lessee_id;
>> +
>> +	/**
>> +	 * @lessee_list:
>> +	 *
>> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
>> +	 * Not used for owners. Protected by &drm_device.mode_config's
>> +	 * &drm_mode_config.idr_mutex.
>> +	 */
>>   	struct list_head lessee_list;
>> +
>> +	/**
>> +	 * @lessees:
>> +	 *
>> +	 * List of drm_masters leasing from this one. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * This list is empty if no leases have been granted, or if all lessees
>> +	 * have been destroyed. Since lessors are referenced by all their
>> +	 * lessees, this master cannot be destroyed unless the list is empty.
>> +	 */
>>   	struct list_head lessees;
>> +
>> +	/**
>> +	 * @leases:
>> +	 *
>> +	 * Objects leased to this drm_master. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * Objects are leased all together in drm_lease_create(), and are
>> +	 * removed all together when the lease is revoked.
>> +	 */
>>   	struct idr leases;
>> +
>> +	/**
>> +	 * @lessee_idr:
>> +	 *
>> +	 * All lessees under this owner (only used where @lessor is NULL).
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
> 
> This also looks great now. With the one improvement addressed and I guess
> the includes for drm_lease.[hc] and those parts of the patch removed
> again:
> 
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> If you want perhaps do a follow-up patch to clean up the comments in
> drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
> maintained when it's not included, so short comments where they provide
> real insight is imo best.
> -Daniel
> 

Thanks for the feedback, Daniel.

Sounds good, I'll send out the updated patch with the suggested changes, 
followed by a clean up of drm_lease.c.

Best wishes,
Desmond

>>   	struct idr lessee_idr;
>>   	/* private: */
>>   #if IS_ENABLED(CONFIG_DRM_LEGACY)
>> -- 
>> 2.25.1
>>
> 

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

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

On 27/7/21 9:04 pm, Daniel Vetter wrote:
> On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
>> We make the following changes to the documentation of drm leases to
>> make it easier to reason about their usage. In particular, we clarify
>> the lifetime and locking rules of lease fields in drm_master:
>>
>> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
>> lease idr and list structures for drm_master. The lessor field itself
>> doesn't need to be protected as it doesn't change after it's set in
>> drm_lease_create.
>>
>> 2. Add descriptions for the lifetime of lessors and leases.
>>
>> 3. Add an overview DOC: section in drm-uapi.rst that defines the
>> terminology for drm leasing, and explains how leases work and why
>> they're used.
>>
>> 4. Clean up function documentation in drm_lease.c to use kernel-doc
>> formatting.
>>
>> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
>> ---
>>
>> Hi,
>>
>> After I updated the formatting for comments in drm_lease.c, I noticed
>> that none of these were driver interfaces (i.e. no structs/inline
>> functions declared in headers, and no exported symbols in .c files).
>>
>> I left the kernel-doc links inside drm-uapi.rst so that if any such
>> interfaces are defined in the future, they'll go to the appropriate
>> place. But if these should be removed, or if the formatting changes for
>> function comments should be removed, please let me know.
> 
> 
> Hm indeed, so there's not really any need to either include the
> drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
> useful.
> 
> For the internal pieces usually what we do is remove the comment outright
> if it doesn't provide anything useful (like just repeats what the function
> name says already). If there's something interesting in the comment then
> we leave it that sentence in there as a normal comment, but without any of
> the structured comment stuff (so no /**, nor @arguments, or the function
> summary).
> 
> 
> 
>>
>> Best wishes,
>> Desmond
>>
>>   Documentation/gpu/drm-uapi.rst |  15 +++
>>   drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>>   include/drm/drm_auth.h         |  67 ++++++++++--
>>   3 files changed, 180 insertions(+), 84 deletions(-)
>>
>> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
>> index 7e51dd40bf6e..6d7233a9fb14 100644
>> --- a/Documentation/gpu/drm-uapi.rst
>> +++ b/Documentation/gpu/drm-uapi.rst
>> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>>   .. kernel-doc:: include/drm/drm_auth.h
>>      :internal:
>>   
>> +
>> +.. _drm_leasing:
>> +
>> +DRM Display Resource Leasing
>> +============================
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :doc: drm leasing
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :export:
>> +
>> +.. kernel-doc:: include/drm/drm_lease.h
>> +   :internal:
>> +
>>   Open-Source Userspace Requirements
>>   ==================================
>>   
>> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
>> index 92eac73d9001..9b68617840ed 100644
>> --- a/drivers/gpu/drm/drm_lease.c
>> +++ b/drivers/gpu/drm/drm_lease.c
>> @@ -15,18 +15,67 @@
>>   #include "drm_crtc_internal.h"
>>   #include "drm_internal.h"
>>   
>> +/**
>> + * DOC: drm leasing
>> + *
>> + * DRM leases provide information about whether a DRM master may control a DRM
>> + * mode setting object. This enables the creation of multiple DRM masters that
>> + * manage subsets of display resources.
>> + *
>> + * The original DRM master of a device 'owns' the available drm resources. It
>> + * may create additional DRM masters and 'lease' resources which it controls
>> + * to the new DRM master. This gives the new DRM master control over the
>> + * leased resources until the owner revokes the lease, or the new DRM master
>> + * is closed. Some helpful terminology:
>> + *
>> + * - An 'owner' is a &struct drm_master that is not leasing objects from
>> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
>> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
>> + *
>> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
>> + *   other &struct drm_master. Currently, lessees are not allowed to
>> + *   create sub-leases, hence the lessor is the same as the owner.
>> + *
>> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
>> + *   other &struct drm_master. Each lessee only leases resources from a single
>> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
>> + *   it is leasing in &drm_master.leases.
>> + *
>> + * - A 'lease' is a contract between the lessor and lessee that identifies
>> + *   which resources may be controlled by the lessee. All of the resources
>> + *   that are leased must be owned by or leased to the lessor, and lessors are
>> + *   not permitted to lease the same object to multiple lessees.
>> + *
>> + * The set of objects any &struct drm_master 'controls' is limited to the set
>> + * of objects it leases (for lessees) or all objects (for owners).
>> + *
>> + * Objects not controlled by a &struct drm_master cannot be modified through
>> + * the various state manipulating ioctls, and any state reported back to user
>> + * space will be edited to make them appear idle and/or unusable. For
>> + * instance, connectors always report 'disconnected', while encoders
>> + * report no possible crtcs or clones.
>> + *
>> + * Since each lessee may lease objects from a single lessor, display resource
>> + * leases form a tree of &struct drm_master. As lessees are currently not
>> + * allowed to create sub-leases, the tree depth is limited to 1. All of
>> + * these get activated simultaneously, so &drm_device.master points to the
> 
> I think it would be good to clarify that this happens when the top level
> owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
> looks good, thanks for typing it up.
> 
>> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
>> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
>> + * objects from the owner can be searched via the owner's
>> + * &drm_master.lessee_idr.
>> + */
>> +
>>   #define drm_for_each_lessee(lessee, lessor) \
>>   	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>>   
>>   static uint64_t drm_lease_idr_object;
>>   
>>   /**
>> - * drm_lease_owner - return ancestor owner drm_master
>> - * @master: drm_master somewhere within tree of lessees and lessors
>> - *
>> - * RETURN:
>> + * drm_lease_owner - return the device owner in @master's lease tree
>> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>>    *
>> - * drm_master at the top of the tree (i.e, with lessor NULL
>> + * Returns the &struct drm_master that owns the device, i.e. the &struct
>> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>>    */
>>   struct drm_master *drm_lease_owner(struct drm_master *master)
>>   {
>> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>>   
>>   /**
>>    * _drm_find_lessee - find lessee by id (idr_mutex held)
>> - * @master: drm_master of lessor
>> - * @lessee_id: id
>> + * @master: &struct drm_master of lessor
>> + * @lessee_id: &drm_master.lessee_id of lessee
>>    *
>> - * RETURN:
>> - *
>> - * drm_master of the lessee if valid, NULL otherwise
>> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>>    */
>>   
>>   static struct drm_master*
>> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>>   }
>>   
>>   /**
>> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
>> + * @master (idr_mutex held)
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>>    */
>>   static int _drm_lease_held_master(struct drm_master *master, int id)
>>   {
>> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
>> - * value:
>> - *
>> - *	true		Some lessee holds a lease on the object.
>> - *	false		No lessee has a lease on the object.
>> + * Returns true if any lessee of @master holds a lease on the given object,
>> + * false if no lessee has a lease on the object.
>>    */
>>   static bool _drm_has_leased(struct drm_master *master, int id)
>>   {
>> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   
>>   /**
>>    * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> - *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>>   }
>>   
>>   /**
>> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
>> + * drm_lease_filter_crtcs - restricted crtc set to leased values
>> + * (idr_mutex not held)
>>    * @file_priv: requestor file
>>    * @crtcs_in: bitmask of crtcs to check
>>    *
>> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>>   }
>>   
>>   /*
>> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
>> + * drm_lease_create - create a new &struct drm_master with leased objects
>> + * (idr_mutex not held)
>>    * @lessor: lease holder (or owner) of objects
>>    * @leases: objects to lease to the new drm_master
>>    *
>> - * Uses drm_master_create to allocate a new drm_master, then checks to
>> - * make sure all of the desired objects can be leased, atomically
>> - * leasing them to the new drmmaster.
>> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
>> + * to make sure all of the desired objects can be leased, atomically
>> + * leasing them to the new &struct drm_master.
>>    *
>>    * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>>    * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
>> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>>   }
>>   
>>   /**
>> - * drm_lease_destroy - a master is going away (idr_mutex not held)
>> - * @master: the drm_master being destroyed
>> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
>> + * @master: the &struct drm_master being destroyed
>>    *
>> - * All lessees will have been destroyed as they
>> - * hold a reference on their lessor. Notify any
>> - * lessor for this master so that it can check
>> - * the list of lessees.
>> + * Destroys @master, then notifies any lessor for this master so that it can
>> + * check the list of lessees. Note that all lessees of @master will have been
>> + * destroyed for this function to be called as they hold a reference on their
>> + * lessor.
>>    */
>>   void drm_lease_destroy(struct drm_master *master)
>>   {
>> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>>   
>>   /**
>>    * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   static void _drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>>   
>>   /**
>>    * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   void drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_create_lease_ioctl - create a new lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_create_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_create_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * The master associated with the specified file will have a lease
>> + * The &struct drm_master associated with @lessor_priv will have a lease
>>    * created containing the objects specified in the ioctl structure.
>>    * A file descriptor will be allocated for that and returned to the
>>    * application.
>> + *
>> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>>    */
>>   int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   }
>>   
>>   /**
>> - * drm_mode_list_lessees_ioctl - list lessee ids
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_list_lessees
>> - * @lessor_priv: the file being manipulated
>> + * drm_mode_list_lessees_ioctl - list lessee IDs
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_list_lessees
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * Starting from the master associated with the specified file,
>> - * the master with the provided lessee_id is found, and then
>> - * an array of lessee ids associated with leases from that master
>> - * are returned.
>> + * Returns an array of &drm_master.lessee_id associated with lessees of
>> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>>    */
>>   
>>   int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_get_lease_ioctl - list leased objects
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_get_lease
>> - * @lessee_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_get_lease
>> + * @lessee_priv: the &struct drm_file being manipulated
>>    *
>>    * Return the list of leased objects for the specified lessee
>>    */
>> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_revoke_lease_ioctl - revoke lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_revoke_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_revoke_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * This removes all of the objects from the lease without
>> - * actually getting rid of the lease itself; that way all
>> - * references to it still work correctly
>> + * Removes all of the objects from the lessee without actually getting rid
>> + * of the lessee itself; that way all references to it still work correctly.
>>    */
>>   int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
>> index f99d3417f304..ba248ca8866f 100644
>> --- a/include/drm/drm_auth.h
>> +++ b/include/drm/drm_auth.h
>> @@ -58,12 +58,6 @@ struct drm_lock_data {
>>    * @refcount: Refcount for this master object.
>>    * @dev: Link back to the DRM device
>>    * @driver_priv: Pointer to driver-private information.
>> - * @lessor: Lease holder
>> - * @lessee_id: id for lessees. Owners always have id 0
>> - * @lessee_list: other lessees of the same master
>> - * @lessees: drm_masters leasing from this one
>> - * @leases: Objects leased to this drm_master.
>> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>>    *
>>    * Note that master structures are only relevant for the legacy/primary device
>>    * nodes, hence there can only be one per device, not one per drm_minor.
>> @@ -88,17 +82,68 @@ struct drm_master {
>>   	struct idr magic_map;
>>   	void *driver_priv;
>>   
>> -	/* Tree of display resource leases, each of which is a drm_master struct
>> -	 * All of these get activated simultaneously, so drm_device master points
>> -	 * at the top of the tree (for which lessor is NULL). Protected by
>> -	 * &drm_device.mode_config.idr_mutex.
>> +	/**
>> +	 * @lessor:
>> +	 *
>> +	 * Lease grantor, only set if this &struct drm_master represents a
>> +	 * lessee holding a lease of objects from @lessor. Full owners of the
>> +	 * device have this set to NULL.
>> +	 *
>> +	 * The lessor does not change once it's set in drm_lease_create(), and
>> +	 * each lessee holds a reference to its lessor that it releases upon
>> +	 * being destroyed in drm_lease_destroy().
>> +	 *
>> +	 * See also the :ref:`section on display resource leasing
>> +	 * <drm_leasing>`.
>>   	 */
>> -
>>   	struct drm_master *lessor;
>> +
>> +	/**
>> +	 * @lessee_id:
>> +	 *
>> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
>>   	int	lessee_id;
>> +
>> +	/**
>> +	 * @lessee_list:
>> +	 *
>> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
>> +	 * Not used for owners. Protected by &drm_device.mode_config's
>> +	 * &drm_mode_config.idr_mutex.
>> +	 */
>>   	struct list_head lessee_list;
>> +
>> +	/**
>> +	 * @lessees:
>> +	 *
>> +	 * List of drm_masters leasing from this one. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * This list is empty if no leases have been granted, or if all lessees
>> +	 * have been destroyed. Since lessors are referenced by all their
>> +	 * lessees, this master cannot be destroyed unless the list is empty.
>> +	 */
>>   	struct list_head lessees;
>> +
>> +	/**
>> +	 * @leases:
>> +	 *
>> +	 * Objects leased to this drm_master. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * Objects are leased all together in drm_lease_create(), and are
>> +	 * removed all together when the lease is revoked.
>> +	 */
>>   	struct idr leases;
>> +
>> +	/**
>> +	 * @lessee_idr:
>> +	 *
>> +	 * All lessees under this owner (only used where @lessor is NULL).
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
> 
> This also looks great now. With the one improvement addressed and I guess
> the includes for drm_lease.[hc] and those parts of the patch removed
> again:
> 
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> If you want perhaps do a follow-up patch to clean up the comments in
> drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
> maintained when it's not included, so short comments where they provide
> real insight is imo best.
> -Daniel
> 

Thanks for the feedback, Daniel.

Sounds good, I'll send out the updated patch with the suggested changes, 
followed by a clean up of drm_lease.c.

Best wishes,
Desmond

>>   	struct idr lessee_idr;
>>   	/* private: */
>>   #if IS_ENABLED(CONFIG_DRM_LEGACY)
>> -- 
>> 2.25.1
>>
> 

Re: [PATCH v2 2/3] drm: clarify usage of drm leases

[Desmond Cheong Zhi Xi]

On 27/7/21 9:04 pm, Daniel Vetter wrote:
> On Sat, Jul 24, 2021 at 07:18:23PM +0800, Desmond Cheong Zhi Xi wrote:
>> We make the following changes to the documentation of drm leases to
>> make it easier to reason about their usage. In particular, we clarify
>> the lifetime and locking rules of lease fields in drm_master:
>>
>> 1. Make it clear that &drm_device.mode_config.idr_mutex protects the
>> lease idr and list structures for drm_master. The lessor field itself
>> doesn't need to be protected as it doesn't change after it's set in
>> drm_lease_create.
>>
>> 2. Add descriptions for the lifetime of lessors and leases.
>>
>> 3. Add an overview DOC: section in drm-uapi.rst that defines the
>> terminology for drm leasing, and explains how leases work and why
>> they're used.
>>
>> 4. Clean up function documentation in drm_lease.c to use kernel-doc
>> formatting.
>>
>> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
>> ---
>>
>> Hi,
>>
>> After I updated the formatting for comments in drm_lease.c, I noticed
>> that none of these were driver interfaces (i.e. no structs/inline
>> functions declared in headers, and no exported symbols in .c files).
>>
>> I left the kernel-doc links inside drm-uapi.rst so that if any such
>> interfaces are defined in the future, they'll go to the appropriate
>> place. But if these should be removed, or if the formatting changes for
>> function comments should be removed, please let me know.
> 
> 
> Hm indeed, so there's not really any need to either include the
> drm_lease.c or drm_lease.h kerneldoc. The DOC section itself is still
> useful.
> 
> For the internal pieces usually what we do is remove the comment outright
> if it doesn't provide anything useful (like just repeats what the function
> name says already). If there's something interesting in the comment then
> we leave it that sentence in there as a normal comment, but without any of
> the structured comment stuff (so no /**, nor @arguments, or the function
> summary).
> 
> 
> 
>>
>> Best wishes,
>> Desmond
>>
>>   Documentation/gpu/drm-uapi.rst |  15 +++
>>   drivers/gpu/drm/drm_lease.c    | 182 ++++++++++++++++++++-------------
>>   include/drm/drm_auth.h         |  67 ++++++++++--
>>   3 files changed, 180 insertions(+), 84 deletions(-)
>>
>> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
>> index 7e51dd40bf6e..6d7233a9fb14 100644
>> --- a/Documentation/gpu/drm-uapi.rst
>> +++ b/Documentation/gpu/drm-uapi.rst
>> @@ -37,6 +37,21 @@ Primary Nodes, DRM Master and Authentication
>>   .. kernel-doc:: include/drm/drm_auth.h
>>      :internal:
>>   
>> +
>> +.. _drm_leasing:
>> +
>> +DRM Display Resource Leasing
>> +============================
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :doc: drm leasing
>> +
>> +.. kernel-doc:: drivers/gpu/drm/drm_lease.c
>> +   :export:
>> +
>> +.. kernel-doc:: include/drm/drm_lease.h
>> +   :internal:
>> +
>>   Open-Source Userspace Requirements
>>   ==================================
>>   
>> diff --git a/drivers/gpu/drm/drm_lease.c b/drivers/gpu/drm/drm_lease.c
>> index 92eac73d9001..9b68617840ed 100644
>> --- a/drivers/gpu/drm/drm_lease.c
>> +++ b/drivers/gpu/drm/drm_lease.c
>> @@ -15,18 +15,67 @@
>>   #include "drm_crtc_internal.h"
>>   #include "drm_internal.h"
>>   
>> +/**
>> + * DOC: drm leasing
>> + *
>> + * DRM leases provide information about whether a DRM master may control a DRM
>> + * mode setting object. This enables the creation of multiple DRM masters that
>> + * manage subsets of display resources.
>> + *
>> + * The original DRM master of a device 'owns' the available drm resources. It
>> + * may create additional DRM masters and 'lease' resources which it controls
>> + * to the new DRM master. This gives the new DRM master control over the
>> + * leased resources until the owner revokes the lease, or the new DRM master
>> + * is closed. Some helpful terminology:
>> + *
>> + * - An 'owner' is a &struct drm_master that is not leasing objects from
>> + *   another &struct drm_master, and hence 'owns' the objects. The owner can be
>> + *   identified as the &struct drm_master for which &drm_master.lessor is NULL.
>> + *
>> + * - A 'lessor' is a &struct drm_master which is leasing objects to one or more
>> + *   other &struct drm_master. Currently, lessees are not allowed to
>> + *   create sub-leases, hence the lessor is the same as the owner.
>> + *
>> + * - A 'lessee' is a &struct drm_master which is leasing objects from some
>> + *   other &struct drm_master. Each lessee only leases resources from a single
>> + *   lessor recorded in &drm_master.lessor, and holds the set of objects that
>> + *   it is leasing in &drm_master.leases.
>> + *
>> + * - A 'lease' is a contract between the lessor and lessee that identifies
>> + *   which resources may be controlled by the lessee. All of the resources
>> + *   that are leased must be owned by or leased to the lessor, and lessors are
>> + *   not permitted to lease the same object to multiple lessees.
>> + *
>> + * The set of objects any &struct drm_master 'controls' is limited to the set
>> + * of objects it leases (for lessees) or all objects (for owners).
>> + *
>> + * Objects not controlled by a &struct drm_master cannot be modified through
>> + * the various state manipulating ioctls, and any state reported back to user
>> + * space will be edited to make them appear idle and/or unusable. For
>> + * instance, connectors always report 'disconnected', while encoders
>> + * report no possible crtcs or clones.
>> + *
>> + * Since each lessee may lease objects from a single lessor, display resource
>> + * leases form a tree of &struct drm_master. As lessees are currently not
>> + * allowed to create sub-leases, the tree depth is limited to 1. All of
>> + * these get activated simultaneously, so &drm_device.master points to the
> 
> I think it would be good to clarify that this happens when the top level
> owner changes through the SETMASTER/DROPMASTER IOCTL. Otherwise this all
> looks good, thanks for typing it up.
> 
>> + * owner at the top of the lease tree (i.e. the &struct drm_master for which
>> + * &drm_master.lessor is NULL). The full list of lessees that are leasing
>> + * objects from the owner can be searched via the owner's
>> + * &drm_master.lessee_idr.
>> + */
>> +
>>   #define drm_for_each_lessee(lessee, lessor) \
>>   	list_for_each_entry((lessee), &(lessor)->lessees, lessee_list)
>>   
>>   static uint64_t drm_lease_idr_object;
>>   
>>   /**
>> - * drm_lease_owner - return ancestor owner drm_master
>> - * @master: drm_master somewhere within tree of lessees and lessors
>> - *
>> - * RETURN:
>> + * drm_lease_owner - return the device owner in @master's lease tree
>> + * @master: &struct drm_master somewhere within tree of lessees and lessors
>>    *
>> - * drm_master at the top of the tree (i.e, with lessor NULL
>> + * Returns the &struct drm_master that owns the device, i.e. the &struct
>> + * drm_master at the top of the tree for which &drm_master.lessor is NULL.
>>    */
>>   struct drm_master *drm_lease_owner(struct drm_master *master)
>>   {
>> @@ -37,12 +86,10 @@ struct drm_master *drm_lease_owner(struct drm_master *master)
>>   
>>   /**
>>    * _drm_find_lessee - find lessee by id (idr_mutex held)
>> - * @master: drm_master of lessor
>> - * @lessee_id: id
>> + * @master: &struct drm_master of lessor
>> + * @lessee_id: &drm_master.lessee_id of lessee
>>    *
>> - * RETURN:
>> - *
>> - * drm_master of the lessee if valid, NULL otherwise
>> + * Returns &struct drm_master of the lessee if the ID is valid, NULL otherwise.
>>    */
>>   
>>   static struct drm_master*
>> @@ -53,15 +100,12 @@ _drm_find_lessee(struct drm_master *master, int lessee_id)
>>   }
>>   
>>   /**
>> - * _drm_lease_held_master - check to see if an object is leased (or owned) by master (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * _drm_lease_held_master - check to see if an object is leased (or owned) by
>> + * @master (idr_mutex held)
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @master holds a lease on (or owns) the object, false if not.
>>    */
>>   static int _drm_lease_held_master(struct drm_master *master, int id)
>>   {
>> @@ -73,14 +117,11 @@ static int _drm_lease_held_master(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_has_leased - check to see if an object has been leased (idr_mutex held)
>> - * @master: the master to check the lease status of
>> - * @id: the id to check
>> + * @master: the &struct drm_master to check the lease status of
>> + * @id: the object ID to check
>>    *
>> - * Checks if any lessee of 'master' holds a lease on 'id'. Return
>> - * value:
>> - *
>> - *	true		Some lessee holds a lease on the object.
>> - *	false		No lessee has a lease on the object.
>> + * Returns true if any lessee of @master holds a lease on the given object,
>> + * false if no lessee has a lease on the object.
>>    */
>>   static bool _drm_has_leased(struct drm_master *master, int id)
>>   {
>> @@ -95,14 +136,11 @@ static bool _drm_has_leased(struct drm_master *master, int id)
>>   
>>   /**
>>    * _drm_lease_held - check drm_mode_object lease status (idr_mutex held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> - *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -123,14 +161,11 @@ bool _drm_lease_held(struct drm_file *file_priv, int id)
>>   
>>   /**
>>    * drm_lease_held - check drm_mode_object lease status (idr_mutex not held)
>> - * @file_priv: the master drm_file
>> - * @id: the object id
>> + * @file_priv: the master &struct drm_file
>> + * @id: the object ID
>>    *
>> - * Checks if the specified master holds a lease on the object. Return
>> - * value:
>> - *
>> - *	true		'master' holds a lease on (or owns) the object
>> - *	false		'master' does not hold a lease.
>> + * Returns true if @file_priv's &drm_file.master holds a lease on (or owns) the
>> + * object, false if it does not.
>>    */
>>   bool drm_lease_held(struct drm_file *file_priv, int id)
>>   {
>> @@ -157,7 +192,8 @@ bool drm_lease_held(struct drm_file *file_priv, int id)
>>   }
>>   
>>   /**
>> - * drm_lease_filter_crtcs - restricted crtc set to leased values (idr_mutex not held)
>> + * drm_lease_filter_crtcs - restricted crtc set to leased values
>> + * (idr_mutex not held)
>>    * @file_priv: requestor file
>>    * @crtcs_in: bitmask of crtcs to check
>>    *
>> @@ -207,13 +243,14 @@ uint32_t drm_lease_filter_crtcs(struct drm_file *file_priv, uint32_t crtcs_in)
>>   }
>>   
>>   /*
>> - * drm_lease_create - create a new drm_master with leased objects (idr_mutex not held)
>> + * drm_lease_create - create a new &struct drm_master with leased objects
>> + * (idr_mutex not held)
>>    * @lessor: lease holder (or owner) of objects
>>    * @leases: objects to lease to the new drm_master
>>    *
>> - * Uses drm_master_create to allocate a new drm_master, then checks to
>> - * make sure all of the desired objects can be leased, atomically
>> - * leasing them to the new drmmaster.
>> + * Uses drm_master_create() to allocate a new &struct drm_master, then checks
>> + * to make sure all of the desired objects can be leased, atomically
>> + * leasing them to the new &struct drm_master.
>>    *
>>    * 	ERR_PTR(-EACCES)	some other master holds the title to any object
>>    * 	ERR_PTR(-ENOENT)	some object is not a valid DRM object for this device
>> @@ -280,13 +317,13 @@ static struct drm_master *drm_lease_create(struct drm_master *lessor, struct idr
>>   }
>>   
>>   /**
>> - * drm_lease_destroy - a master is going away (idr_mutex not held)
>> - * @master: the drm_master being destroyed
>> + * drm_lease_destroy - destroy a master  (idr_mutex not held)
>> + * @master: the &struct drm_master being destroyed
>>    *
>> - * All lessees will have been destroyed as they
>> - * hold a reference on their lessor. Notify any
>> - * lessor for this master so that it can check
>> - * the list of lessees.
>> + * Destroys @master, then notifies any lessor for this master so that it can
>> + * check the list of lessees. Note that all lessees of @master will have been
>> + * destroyed for this function to be called as they hold a reference on their
>> + * lessor.
>>    */
>>   void drm_lease_destroy(struct drm_master *master)
>>   {
>> @@ -323,7 +360,7 @@ void drm_lease_destroy(struct drm_master *master)
>>   
>>   /**
>>    * _drm_lease_revoke - revoke access to all leased objects (idr_mutex held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   static void _drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -365,7 +402,7 @@ static void _drm_lease_revoke(struct drm_master *top)
>>   
>>   /**
>>    * drm_lease_revoke - revoke access to all leased objects (idr_mutex not held)
>> - * @top: the master losing its lease
>> + * @top: the &struct drm_master losing its lease
>>    */
>>   void drm_lease_revoke(struct drm_master *top)
>>   {
>> @@ -500,14 +537,16 @@ static int fill_object_idr(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_create_lease_ioctl - create a new lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_create_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_create_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * The master associated with the specified file will have a lease
>> + * The &struct drm_master associated with @lessor_priv will have a lease
>>    * created containing the objects specified in the ioctl structure.
>>    * A file descriptor will be allocated for that and returned to the
>>    * application.
>> + *
>> + * Note that creating recursive sub-leases for existing lessees is not allowed.
>>    */
>>   int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> @@ -626,15 +665,13 @@ int drm_mode_create_lease_ioctl(struct drm_device *dev,
>>   }
>>   
>>   /**
>> - * drm_mode_list_lessees_ioctl - list lessee ids
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_list_lessees
>> - * @lessor_priv: the file being manipulated
>> + * drm_mode_list_lessees_ioctl - list lessee IDs
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_list_lessees
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * Starting from the master associated with the specified file,
>> - * the master with the provided lessee_id is found, and then
>> - * an array of lessee ids associated with leases from that master
>> - * are returned.
>> + * Returns an array of &drm_master.lessee_id associated with lessees of
>> + * @lessor_priv's &drm_file.master that have unrevoked leases.
>>    */
>>   
>>   int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>> @@ -685,9 +722,9 @@ int drm_mode_list_lessees_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_get_lease_ioctl - list leased objects
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_get_lease
>> - * @lessee_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_get_lease
>> + * @lessee_priv: the &struct drm_file being manipulated
>>    *
>>    * Return the list of leased objects for the specified lessee
>>    */
>> @@ -747,13 +784,12 @@ int drm_mode_get_lease_ioctl(struct drm_device *dev,
>>   
>>   /**
>>    * drm_mode_revoke_lease_ioctl - revoke lease
>> - * @dev: the drm device
>> - * @data: pointer to struct drm_mode_revoke_lease
>> - * @lessor_priv: the file being manipulated
>> + * @dev: the &struct drm_device
>> + * @data: pointer to &struct drm_mode_revoke_lease
>> + * @lessor_priv: the &struct drm_file being manipulated
>>    *
>> - * This removes all of the objects from the lease without
>> - * actually getting rid of the lease itself; that way all
>> - * references to it still work correctly
>> + * Removes all of the objects from the lessee without actually getting rid
>> + * of the lessee itself; that way all references to it still work correctly.
>>    */
>>   int drm_mode_revoke_lease_ioctl(struct drm_device *dev,
>>   				void *data, struct drm_file *lessor_priv)
>> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h
>> index f99d3417f304..ba248ca8866f 100644
>> --- a/include/drm/drm_auth.h
>> +++ b/include/drm/drm_auth.h
>> @@ -58,12 +58,6 @@ struct drm_lock_data {
>>    * @refcount: Refcount for this master object.
>>    * @dev: Link back to the DRM device
>>    * @driver_priv: Pointer to driver-private information.
>> - * @lessor: Lease holder
>> - * @lessee_id: id for lessees. Owners always have id 0
>> - * @lessee_list: other lessees of the same master
>> - * @lessees: drm_masters leasing from this one
>> - * @leases: Objects leased to this drm_master.
>> - * @lessee_idr: All lessees under this owner (only used where lessor == NULL)
>>    *
>>    * Note that master structures are only relevant for the legacy/primary device
>>    * nodes, hence there can only be one per device, not one per drm_minor.
>> @@ -88,17 +82,68 @@ struct drm_master {
>>   	struct idr magic_map;
>>   	void *driver_priv;
>>   
>> -	/* Tree of display resource leases, each of which is a drm_master struct
>> -	 * All of these get activated simultaneously, so drm_device master points
>> -	 * at the top of the tree (for which lessor is NULL). Protected by
>> -	 * &drm_device.mode_config.idr_mutex.
>> +	/**
>> +	 * @lessor:
>> +	 *
>> +	 * Lease grantor, only set if this &struct drm_master represents a
>> +	 * lessee holding a lease of objects from @lessor. Full owners of the
>> +	 * device have this set to NULL.
>> +	 *
>> +	 * The lessor does not change once it's set in drm_lease_create(), and
>> +	 * each lessee holds a reference to its lessor that it releases upon
>> +	 * being destroyed in drm_lease_destroy().
>> +	 *
>> +	 * See also the :ref:`section on display resource leasing
>> +	 * <drm_leasing>`.
>>   	 */
>> -
>>   	struct drm_master *lessor;
>> +
>> +	/**
>> +	 * @lessee_id:
>> +	 *
>> +	 * ID for lessees. Owners (i.e. @lessor is NULL) always have ID 0.
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
>>   	int	lessee_id;
>> +
>> +	/**
>> +	 * @lessee_list:
>> +	 *
>> +	 * List entry of lessees of @lessor, where they are linked to @lessees.
>> +	 * Not used for owners. Protected by &drm_device.mode_config's
>> +	 * &drm_mode_config.idr_mutex.
>> +	 */
>>   	struct list_head lessee_list;
>> +
>> +	/**
>> +	 * @lessees:
>> +	 *
>> +	 * List of drm_masters leasing from this one. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * This list is empty if no leases have been granted, or if all lessees
>> +	 * have been destroyed. Since lessors are referenced by all their
>> +	 * lessees, this master cannot be destroyed unless the list is empty.
>> +	 */
>>   	struct list_head lessees;
>> +
>> +	/**
>> +	 * @leases:
>> +	 *
>> +	 * Objects leased to this drm_master. Protected by
>> +	 * &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 *
>> +	 * Objects are leased all together in drm_lease_create(), and are
>> +	 * removed all together when the lease is revoked.
>> +	 */
>>   	struct idr leases;
>> +
>> +	/**
>> +	 * @lessee_idr:
>> +	 *
>> +	 * All lessees under this owner (only used where @lessor is NULL).
>> +	 * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex.
>> +	 */
> 
> This also looks great now. With the one improvement addressed and I guess
> the includes for drm_lease.[hc] and those parts of the patch removed
> again:
> 
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> If you want perhaps do a follow-up patch to clean up the comments in
> drm_lease.c and remove the outdated/unused kerneldoc? It tends to not be
> maintained when it's not included, so short comments where they provide
> real insight is imo best.
> -Daniel
> 

Thanks for the feedback, Daniel.

Sounds good, I'll send out the updated patch with the suggested changes, 
followed by a clean up of drm_lease.c.

Best wishes,
Desmond

>>   	struct idr lessee_idr;
>>   	/* private: */
>>   #if IS_ENABLED(CONFIG_DRM_LEGACY)
>> -- 
>> 2.25.1
>>
> 

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[PATCH v2 3/3] drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

[Desmond Cheong Zhi Xi]

drm_file.master should be protected by either drm_device.master_mutex
or drm_file.master_lookup_lock when being dereferenced. However,
drm_master_get is called on unprotected file_priv->master pointers in
vmw_surface_define_ioctl and vmw_gb_surface_define_internal.

This is fixed by replacing drm_master_get with drm_file_get_master.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Zack Rusin <zackr@vmware.com>
---
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
index 0eba47762bed..5d53a5f9d123 100644
--- a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
+++ b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
@@ -865,7 +865,7 @@ int vmw_surface_define_ioctl(struct drm_device *dev, void *data,
 	user_srf->prime.base.shareable = false;
 	user_srf->prime.base.tfile = NULL;
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	/**
 	 * From this point, the generic resource management functions
@@ -1534,7 +1534,7 @@ vmw_gb_surface_define_internal(struct drm_device *dev,
 
 	user_srf = container_of(srf, struct vmw_user_surface, srf);
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	res = &user_srf->srf.res;
 
-- 
2.25.1

[Intel-gfx] [PATCH v2 3/3] drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

[Desmond Cheong Zhi Xi]

drm_file.master should be protected by either drm_device.master_mutex
or drm_file.master_lookup_lock when being dereferenced. However,
drm_master_get is called on unprotected file_priv->master pointers in
vmw_surface_define_ioctl and vmw_gb_surface_define_internal.

This is fixed by replacing drm_master_get with drm_file_get_master.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Zack Rusin <zackr@vmware.com>
---
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
index 0eba47762bed..5d53a5f9d123 100644
--- a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
+++ b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
@@ -865,7 +865,7 @@ int vmw_surface_define_ioctl(struct drm_device *dev, void *data,
 	user_srf->prime.base.shareable = false;
 	user_srf->prime.base.tfile = NULL;
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	/**
 	 * From this point, the generic resource management functions
@@ -1534,7 +1534,7 @@ vmw_gb_surface_define_internal(struct drm_device *dev,
 
 	user_srf = container_of(srf, struct vmw_user_surface, srf);
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	res = &user_srf->srf.res;
 
-- 
2.25.1

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

[PATCH v2 3/3] drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

[Desmond Cheong Zhi Xi]

drm_file.master should be protected by either drm_device.master_mutex
or drm_file.master_lookup_lock when being dereferenced. However,
drm_master_get is called on unprotected file_priv->master pointers in
vmw_surface_define_ioctl and vmw_gb_surface_define_internal.

This is fixed by replacing drm_master_get with drm_file_get_master.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Zack Rusin <zackr@vmware.com>
---
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
index 0eba47762bed..5d53a5f9d123 100644
--- a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
+++ b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
@@ -865,7 +865,7 @@ int vmw_surface_define_ioctl(struct drm_device *dev, void *data,
 	user_srf->prime.base.shareable = false;
 	user_srf->prime.base.tfile = NULL;
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	/**
 	 * From this point, the generic resource management functions
@@ -1534,7 +1534,7 @@ vmw_gb_surface_define_internal(struct drm_device *dev,
 
 	user_srf = container_of(srf, struct vmw_user_surface, srf);
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	res = &user_srf->srf.res;
 
-- 
2.25.1

[PATCH v2 3/3] drm/vmwgfx: fix potential UAF in vmwgfx_surface.c

[Desmond Cheong Zhi Xi]

drm_file.master should be protected by either drm_device.master_mutex
or drm_file.master_lookup_lock when being dereferenced. However,
drm_master_get is called on unprotected file_priv->master pointers in
vmw_surface_define_ioctl and vmw_gb_surface_define_internal.

This is fixed by replacing drm_master_get with drm_file_get_master.

Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Zack Rusin <zackr@vmware.com>
---
 drivers/gpu/drm/vmwgfx/vmwgfx_surface.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
index 0eba47762bed..5d53a5f9d123 100644
--- a/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
+++ b/drivers/gpu/drm/vmwgfx/vmwgfx_surface.c
@@ -865,7 +865,7 @@ int vmw_surface_define_ioctl(struct drm_device *dev, void *data,
 	user_srf->prime.base.shareable = false;
 	user_srf->prime.base.tfile = NULL;
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	/**
 	 * From this point, the generic resource management functions
@@ -1534,7 +1534,7 @@ vmw_gb_surface_define_internal(struct drm_device *dev,
 
 	user_srf = container_of(srf, struct vmw_user_surface, srf);
 	if (drm_is_primary_client(file_priv))
-		user_srf->master = drm_master_get(file_priv->master);
+		user_srf->master = drm_file_get_master(file_priv);
 
 	res = &user_srf->srf.res;
 
-- 
2.25.1

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[Intel-gfx] ✗ Fi.CI.SPARSE: warning for series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master

[Patchwork]

== Series Details ==

Series: series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master
URL   : https://patchwork.freedesktop.org/series/93005/
State : warning

== Summary ==

$ dim sparse --fast origin/drm-tip
Sparse version: v0.6.2
Fast mode used, each commit won't be checked separately.
-
+drivers/gpu/drm/amd/amdgpu/amdgv_sriovmsg.h:312:49: error: static assertion failed: "amd_sriov_msg_vf2pf_info must be 1 KB"
+drivers/gpu/drm/amd/amdgpu/amdgv_sriovmsg.h:316:49: error: static assertion failed: "amd_sriov_msg_pf2vf_info must be 1 KB"
+drivers/gpu/drm/drm_drv.c:425:6: warning: context imbalance in 'drm_dev_enter' - different lock contexts for basic block
+drivers/gpu/drm/i915/display/intel_display.c:1900:21:    expected struct i915_vma *[assigned] vma
+drivers/gpu/drm/i915/display/intel_display.c:1900:21:    got void [noderef] __iomem *[assigned] iomem
+drivers/gpu/drm/i915/display/intel_display.c:1900:21: warning: incorrect type in assignment (different address spaces)
+drivers/gpu/drm/i915/gem/i915_gem_context.c:1413:34:    expected struct i915_address_space *vm
+drivers/gpu/drm/i915/gem/i915_gem_context.c:1413:34:    got struct i915_address_space [noderef] __rcu *vm
+drivers/gpu/drm/i915/gem/i915_gem_context.c:1413:34: warning: incorrect type in argument 1 (different address spaces)
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:43:25:    expected struct i915_address_space [noderef] __rcu *vm
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:43:25:    got struct i915_address_space *
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:43:25: warning: incorrect type in assignment (different address spaces)
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:60:34:    expected struct i915_address_space *vm
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:60:34:    got struct i915_address_space [noderef] __rcu *vm
+drivers/gpu/drm/i915/gem/selftests/mock_context.c:60:34: warning: incorrect type in argument 1 (different address spaces)
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:27:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:27:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:27:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:32:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:32:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:49:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:49:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:49:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:56:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_engine_stats.h:56:9: warning: trying to copy expression type 31
+drivers/gpu/drm/i915/gt/intel_reset.c:1402:5: warning: context imbalance in 'intel_gt_reset_trylock' - different lock contexts for basic block
+drivers/gpu/drm/i915/gt/intel_ring_submission.c:1210:24: warning: Using plain integer as NULL pointer
+drivers/gpu/drm/i915/i915_perf.c:1443:15: warning: memset with byte count of 16777216
+drivers/gpu/drm/i915/i915_perf.c:1497:15: warning: memset with byte count of 16777216
+./include/asm-generic/bitops/find.h:112:45: warning: shift count is negative (-262080)
+./include/asm-generic/bitops/find.h:32:31: warning: shift count is negative (-262080)
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_read16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_read32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_read64' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_read8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'fwtable_write8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_read16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_read32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_read64' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_read8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen11_fwtable_write8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_read16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_read32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_read64' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_read8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen12_fwtable_write8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_read16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_read32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_read64' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_read8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen6_write8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen8_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen8_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'gen8_write8' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'xehp_fwtable_write16' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'xehp_fwtable_write32' - different lock contexts for basic block
+./include/linux/spinlock.h:409:9: warning: context imbalance in 'xehp_fwtable_write8' - different lock contexts for basic block
+./include/linux/srcu.h:188:9: warning: context imbalance in 'drm_dev_exit' - unexpected unlock
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+./include/linux/stddef.h:17:9: this was the original definition
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined
+/usr/lib/gcc/x86_64-linux-gnu/8/include/stddef.h:417:9: warning: preprocessor token offsetof redefined


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

[Intel-gfx] ✓ Fi.CI.BAT: success for series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master

[Patchwork]

[-- Attachment #1.1: Type: text/plain, Size: 2092 bytes --]

== Series Details ==

Series: series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master
URL   : https://patchwork.freedesktop.org/series/93005/
State : success

== Summary ==

CI Bug Log - changes from CI_DRM_10393 -> Patchwork_20704
====================================================

Summary
-------

  **SUCCESS**

  No regressions found.

  External URL: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/index.html

Known issues
------------

  Here are the changes found in Patchwork_20704 that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@i915_module_load@reload:
    - fi-kbl-soraka:      [PASS][1] -> [DMESG-WARN][2] ([i915#1982])
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/fi-kbl-soraka/igt@i915_module_load@reload.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/fi-kbl-soraka/igt@i915_module_load@reload.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [i915#1982]: https://gitlab.freedesktop.org/drm/intel/issues/1982
  [i915#3303]: https://gitlab.freedesktop.org/drm/intel/issues/3303


Participating hosts (42 -> 35)
------------------------------

  Missing    (7): fi-ilk-m540 fi-hsw-4200u fi-bsw-cyan bat-adlp-4 bat-adls-4 bat-adls-3 fi-bdw-samus 


Build changes
-------------

  * Linux: CI_DRM_10393 -> Patchwork_20704

  CI-20190529: 20190529
  CI_DRM_10393: c251a707c5b679d62cff229e0e8ee9cf543d3d33 @ git://anongit.freedesktop.org/gfx-ci/linux
  IGT_6149: 34ff2cf2bc352dce691593db803389fe0eb2be03 @ https://gitlab.freedesktop.org/drm/igt-gpu-tools.git
  Patchwork_20704: 711a8c303ff6edbb76037ea69bc5af68217e5bce @ git://anongit.freedesktop.org/gfx-ci/linux


== Linux commits ==

711a8c303ff6 drm/vmwgfx: fix potential UAF in vmwgfx_surface.c
3986804d3cd7 drm: clarify usage of drm leases
6397fa00eb03 drm: use the lookup lock in drm_is_current_master

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/index.html

[-- Attachment #1.2: Type: text/html, Size: 2638 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

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

[Intel-gfx] ✗ Fi.CI.IGT: failure for series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master

[Patchwork]

[-- Attachment #1.1: Type: text/plain, Size: 30302 bytes --]

== Series Details ==

Series: series starting with [v2,1/3] drm: use the lookup lock in drm_is_current_master
URL   : https://patchwork.freedesktop.org/series/93005/
State : failure

== Summary ==

CI Bug Log - changes from CI_DRM_10393_full -> Patchwork_20704_full
====================================================

Summary
-------

  **FAILURE**

  Serious unknown changes coming with Patchwork_20704_full absolutely need to be
  verified manually.
  
  If you think the reported changes have nothing to do with the changes
  introduced in Patchwork_20704_full, please notify your bug team to allow them
  to document this new failure mode, which will reduce false positives in CI.

  

Possible new issues
-------------------

  Here are the unknown changes that may have been introduced in Patchwork_20704_full:

### IGT changes ###

#### Possible regressions ####

  * igt@i915_selftest@mock@requests:
    - shard-glk:          [PASS][1] -> [INCOMPLETE][2]
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk9/igt@i915_selftest@mock@requests.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk2/igt@i915_selftest@mock@requests.html

  * igt@perf_pmu@multi-client@bcs0:
    - shard-skl:          [PASS][3] -> [FAIL][4]
   [3]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl5/igt@perf_pmu@multi-client@bcs0.html
   [4]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl10/igt@perf_pmu@multi-client@bcs0.html

  
#### Suppressed ####

  The following results come from untrusted machines, tests, or statuses.
  They do not affect the overall result.

  * igt@kms_psr@suspend:
    - {shard-rkl}:        [SKIP][5] ([i915#1072]) -> [DMESG-WARN][6]
   [5]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@kms_psr@suspend.html
   [6]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_psr@suspend.html

  * igt@prime_vgem@sync@bcs0:
    - {shard-rkl}:        [PASS][7] -> [INCOMPLETE][8]
   [7]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-5/igt@prime_vgem@sync@bcs0.html
   [8]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-1/igt@prime_vgem@sync@bcs0.html

  * igt@runner@aborted:
    - {shard-rkl}:        ([FAIL][9], [FAIL][10], [FAIL][11], [FAIL][12]) ([i915#3002] / [i915#3728] / [i915#3811]) -> ([FAIL][13], [FAIL][14], [FAIL][15], [FAIL][16]) ([i915#3002] / [i915#3811])
   [9]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-6/igt@runner@aborted.html
   [10]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-5/igt@runner@aborted.html
   [11]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@runner@aborted.html
   [12]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@runner@aborted.html
   [13]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-1/igt@runner@aborted.html
   [14]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-1/igt@runner@aborted.html
   [15]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-5/igt@runner@aborted.html
   [16]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-5/igt@runner@aborted.html

  
Known issues
------------

  Here are the changes found in Patchwork_20704_full that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@feature_discovery@chamelium:
    - shard-iclb:         NOTRUN -> [SKIP][17] ([fdo#111827])
   [17]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@feature_discovery@chamelium.html

  * igt@gem_ctx_persistence@idempotent:
    - shard-snb:          NOTRUN -> [SKIP][18] ([fdo#109271] / [i915#1099]) +5 similar issues
   [18]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-snb6/igt@gem_ctx_persistence@idempotent.html

  * igt@gem_exec_fair@basic-deadline:
    - shard-glk:          [PASS][19] -> [FAIL][20] ([i915#2846])
   [19]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk6/igt@gem_exec_fair@basic-deadline.html
   [20]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk7/igt@gem_exec_fair@basic-deadline.html

  * igt@gem_exec_fair@basic-none-share@rcs0:
    - shard-iclb:         [PASS][21] -> [FAIL][22] ([i915#2842])
   [21]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb4/igt@gem_exec_fair@basic-none-share@rcs0.html
   [22]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb5/igt@gem_exec_fair@basic-none-share@rcs0.html

  * igt@gem_exec_fair@basic-pace-solo@rcs0:
    - shard-iclb:         NOTRUN -> [FAIL][23] ([i915#2842])
   [23]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@gem_exec_fair@basic-pace-solo@rcs0.html

  * igt@gem_exec_fair@basic-pace@vecs0:
    - shard-kbl:          [PASS][24] -> [SKIP][25] ([fdo#109271])
   [24]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-kbl3/igt@gem_exec_fair@basic-pace@vecs0.html
   [25]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-kbl6/igt@gem_exec_fair@basic-pace@vecs0.html

  * igt@gem_exec_fair@basic-throttle@rcs0:
    - shard-glk:          [PASS][26] -> [FAIL][27] ([i915#2842]) +1 similar issue
   [26]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk7/igt@gem_exec_fair@basic-throttle@rcs0.html
   [27]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk8/igt@gem_exec_fair@basic-throttle@rcs0.html

  * igt@gem_huc_copy@huc-copy:
    - shard-tglb:         [PASS][28] -> [SKIP][29] ([i915#2190])
   [28]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-tglb3/igt@gem_huc_copy@huc-copy.html
   [29]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb6/igt@gem_huc_copy@huc-copy.html
    - shard-iclb:         NOTRUN -> [SKIP][30] ([i915#2190])
   [30]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@gem_huc_copy@huc-copy.html

  * igt@gem_pwrite@basic-exhaustion:
    - shard-apl:          NOTRUN -> [WARN][31] ([i915#2658])
   [31]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl1/igt@gem_pwrite@basic-exhaustion.html

  * igt@gem_userptr_blits@huge-split:
    - shard-glk:          [PASS][32] -> [FAIL][33] ([i915#3376])
   [32]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk9/igt@gem_userptr_blits@huge-split.html
   [33]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk7/igt@gem_userptr_blits@huge-split.html

  * igt@gem_userptr_blits@input-checking:
    - shard-snb:          NOTRUN -> [DMESG-WARN][34] ([i915#3002])
   [34]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-snb2/igt@gem_userptr_blits@input-checking.html

  * igt@i915_pm_rpm@basic-rte:
    - shard-iclb:         NOTRUN -> [FAIL][35] ([i915#579])
   [35]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@i915_pm_rpm@basic-rte.html

  * igt@i915_pm_rpm@drm-resources-equal:
    - shard-tglb:         NOTRUN -> [SKIP][36] ([i915#579])
   [36]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb5/igt@i915_pm_rpm@drm-resources-equal.html

  * igt@i915_pm_rpm@gem-mmap-type:
    - shard-iclb:         NOTRUN -> [SKIP][37] ([i915#579])
   [37]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@i915_pm_rpm@gem-mmap-type.html

  * igt@i915_suspend@forcewake:
    - shard-apl:          NOTRUN -> [DMESG-WARN][38] ([i915#180])
   [38]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl2/igt@i915_suspend@forcewake.html

  * igt@kms_big_fb@x-tiled-64bpp-rotate-90:
    - shard-iclb:         NOTRUN -> [SKIP][39] ([fdo#110725] / [fdo#111614])
   [39]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_big_fb@x-tiled-64bpp-rotate-90.html

  * igt@kms_big_fb@y-tiled-max-hw-stride-32bpp-rotate-180-hflip:
    - shard-skl:          NOTRUN -> [SKIP][40] ([fdo#109271] / [i915#3777])
   [40]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@kms_big_fb@y-tiled-max-hw-stride-32bpp-rotate-180-hflip.html

  * igt@kms_big_fb@yf-tiled-64bpp-rotate-0:
    - shard-iclb:         NOTRUN -> [SKIP][41] ([fdo#110723])
   [41]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_big_fb@yf-tiled-64bpp-rotate-0.html

  * igt@kms_big_fb@yf-tiled-64bpp-rotate-180:
    - shard-tglb:         NOTRUN -> [SKIP][42] ([fdo#111615])
   [42]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb5/igt@kms_big_fb@yf-tiled-64bpp-rotate-180.html

  * igt@kms_big_fb@yf-tiled-max-hw-stride-32bpp-rotate-0-hflip:
    - shard-apl:          NOTRUN -> [SKIP][43] ([fdo#109271] / [i915#3777]) +2 similar issues
   [43]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_big_fb@yf-tiled-max-hw-stride-32bpp-rotate-0-hflip.html

  * igt@kms_ccs@pipe-b-bad-pixel-format-y_tiled_ccs:
    - shard-snb:          NOTRUN -> [SKIP][44] ([fdo#109271]) +425 similar issues
   [44]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-snb7/igt@kms_ccs@pipe-b-bad-pixel-format-y_tiled_ccs.html

  * igt@kms_ccs@pipe-c-bad-pixel-format-y_tiled_ccs:
    - shard-tglb:         NOTRUN -> [SKIP][45] ([i915#3689])
   [45]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb5/igt@kms_ccs@pipe-c-bad-pixel-format-y_tiled_ccs.html

  * igt@kms_ccs@pipe-d-bad-rotation-90-y_tiled_gen12_rc_ccs_cc:
    - shard-iclb:         NOTRUN -> [SKIP][46] ([fdo#109278]) +14 similar issues
   [46]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb4/igt@kms_ccs@pipe-d-bad-rotation-90-y_tiled_gen12_rc_ccs_cc.html

  * igt@kms_chamelium@hdmi-hpd-storm:
    - shard-skl:          NOTRUN -> [SKIP][47] ([fdo#109271] / [fdo#111827]) +2 similar issues
   [47]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl8/igt@kms_chamelium@hdmi-hpd-storm.html

  * igt@kms_chamelium@vga-hpd-without-ddc:
    - shard-snb:          NOTRUN -> [SKIP][48] ([fdo#109271] / [fdo#111827]) +19 similar issues
   [48]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-snb5/igt@kms_chamelium@vga-hpd-without-ddc.html

  * igt@kms_color_chamelium@pipe-c-ctm-0-25:
    - shard-apl:          NOTRUN -> [SKIP][49] ([fdo#109271] / [fdo#111827]) +19 similar issues
   [49]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_color_chamelium@pipe-c-ctm-0-25.html

  * igt@kms_color_chamelium@pipe-c-ctm-0-5:
    - shard-iclb:         NOTRUN -> [SKIP][50] ([fdo#109284] / [fdo#111827]) +5 similar issues
   [50]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb4/igt@kms_color_chamelium@pipe-c-ctm-0-5.html

  * igt@kms_content_protection@mei_interface:
    - shard-iclb:         NOTRUN -> [SKIP][51] ([fdo#109300] / [fdo#111066]) +1 similar issue
   [51]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb4/igt@kms_content_protection@mei_interface.html

  * igt@kms_content_protection@srm:
    - shard-apl:          NOTRUN -> [TIMEOUT][52] ([i915#1319])
   [52]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl8/igt@kms_content_protection@srm.html

  * igt@kms_content_protection@uevent:
    - shard-apl:          NOTRUN -> [FAIL][53] ([i915#2105])
   [53]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_content_protection@uevent.html

  * igt@kms_cursor_crc@pipe-a-cursor-512x170-random:
    - shard-iclb:         NOTRUN -> [SKIP][54] ([fdo#109278] / [fdo#109279])
   [54]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_cursor_crc@pipe-a-cursor-512x170-random.html

  * igt@kms_cursor_legacy@cursorb-vs-flipa-legacy:
    - shard-iclb:         NOTRUN -> [SKIP][55] ([fdo#109274] / [fdo#109278]) +1 similar issue
   [55]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_cursor_legacy@cursorb-vs-flipa-legacy.html

  * igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions-varying-size:
    - shard-skl:          [PASS][56] -> [FAIL][57] ([i915#2346] / [i915#533])
   [56]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl8/igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions-varying-size.html
   [57]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl1/igt@kms_cursor_legacy@flip-vs-cursor-atomic-transitions-varying-size.html

  * igt@kms_flip@flip-vs-suspend@a-dp1:
    - shard-kbl:          [PASS][58] -> [INCOMPLETE][59] ([i915#155])
   [58]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-kbl7/igt@kms_flip@flip-vs-suspend@a-dp1.html
   [59]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-kbl4/igt@kms_flip@flip-vs-suspend@a-dp1.html

  * igt@kms_flip@plain-flip-fb-recreate-interruptible@c-hdmi-a2:
    - shard-glk:          [PASS][60] -> [FAIL][61] ([i915#2122])
   [60]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk3/igt@kms_flip@plain-flip-fb-recreate-interruptible@c-hdmi-a2.html
   [61]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk1/igt@kms_flip@plain-flip-fb-recreate-interruptible@c-hdmi-a2.html

  * igt@kms_flip@plain-flip-ts-check-interruptible@c-edp1:
    - shard-skl:          [PASS][62] -> [FAIL][63] ([i915#2122])
   [62]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl3/igt@kms_flip@plain-flip-ts-check-interruptible@c-edp1.html
   [63]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl6/igt@kms_flip@plain-flip-ts-check-interruptible@c-edp1.html

  * igt@kms_flip_scaled_crc@flip-32bpp-ytile-to-32bpp-ytilegen12rcccs:
    - shard-apl:          NOTRUN -> [SKIP][64] ([fdo#109271] / [i915#2672]) +1 similar issue
   [64]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl1/igt@kms_flip_scaled_crc@flip-32bpp-ytile-to-32bpp-ytilegen12rcccs.html

  * igt@kms_frontbuffer_tracking@fbcpsr-2p-primscrn-pri-shrfb-draw-blt:
    - shard-iclb:         NOTRUN -> [SKIP][65] ([fdo#109280]) +6 similar issues
   [65]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_frontbuffer_tracking@fbcpsr-2p-primscrn-pri-shrfb-draw-blt.html

  * igt@kms_plane@pixel-format@pipe-b-planes:
    - shard-skl:          [PASS][66] -> [DMESG-WARN][67] ([i915#1982])
   [66]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl5/igt@kms_plane@pixel-format@pipe-b-planes.html
   [67]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl10/igt@kms_plane@pixel-format@pipe-b-planes.html

  * igt@kms_plane_alpha_blend@pipe-a-alpha-7efc:
    - shard-apl:          NOTRUN -> [FAIL][68] ([fdo#108145] / [i915#265]) +3 similar issues
   [68]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_plane_alpha_blend@pipe-a-alpha-7efc.html

  * igt@kms_plane_alpha_blend@pipe-c-constant-alpha-min:
    - shard-skl:          NOTRUN -> [FAIL][69] ([fdo#108145] / [i915#265])
   [69]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl8/igt@kms_plane_alpha_blend@pipe-c-constant-alpha-min.html

  * igt@kms_plane_alpha_blend@pipe-c-coverage-vs-premult-vs-constant:
    - shard-iclb:         [PASS][70] -> [SKIP][71] ([fdo#109278])
   [70]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb4/igt@kms_plane_alpha_blend@pipe-c-coverage-vs-premult-vs-constant.html
   [71]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb2/igt@kms_plane_alpha_blend@pipe-c-coverage-vs-premult-vs-constant.html

  * igt@kms_plane_lowres@pipe-b-tiling-none:
    - shard-iclb:         NOTRUN -> [SKIP][72] ([i915#3536]) +1 similar issue
   [72]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_plane_lowres@pipe-b-tiling-none.html

  * igt@kms_psr2_sf@overlay-plane-update-sf-dmg-area-4:
    - shard-apl:          NOTRUN -> [SKIP][73] ([fdo#109271] / [i915#658]) +5 similar issues
   [73]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_psr2_sf@overlay-plane-update-sf-dmg-area-4.html

  * igt@kms_psr2_sf@overlay-primary-update-sf-dmg-area-2:
    - shard-iclb:         NOTRUN -> [SKIP][74] ([i915#658])
   [74]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_psr2_sf@overlay-primary-update-sf-dmg-area-2.html

  * igt@kms_psr@psr2_cursor_mmap_cpu:
    - shard-iclb:         NOTRUN -> [SKIP][75] ([fdo#109441]) +1 similar issue
   [75]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_psr@psr2_cursor_mmap_cpu.html

  * igt@kms_psr@psr2_sprite_render:
    - shard-iclb:         [PASS][76] -> [SKIP][77] ([fdo#109441]) +2 similar issues
   [76]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb2/igt@kms_psr@psr2_sprite_render.html
   [77]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb7/igt@kms_psr@psr2_sprite_render.html

  * igt@kms_sysfs_edid_timing:
    - shard-skl:          NOTRUN -> [FAIL][78] ([IGT#2])
   [78]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@kms_sysfs_edid_timing.html

  * igt@kms_vblank@pipe-d-wait-idle:
    - shard-apl:          NOTRUN -> [SKIP][79] ([fdo#109271] / [i915#533]) +3 similar issues
   [79]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl2/igt@kms_vblank@pipe-d-wait-idle.html

  * igt@kms_vrr@flip-suspend:
    - shard-iclb:         NOTRUN -> [SKIP][80] ([fdo#109502])
   [80]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_vrr@flip-suspend.html

  * igt@kms_writeback@writeback-fb-id:
    - shard-apl:          NOTRUN -> [SKIP][81] ([fdo#109271] / [i915#2437])
   [81]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl6/igt@kms_writeback@writeback-fb-id.html

  * igt@perf@polling-parameterized:
    - shard-skl:          [PASS][82] -> [FAIL][83] ([i915#1542])
   [82]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl1/igt@perf@polling-parameterized.html
   [83]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@perf@polling-parameterized.html

  * igt@perf@unprivileged-single-ctx-counters:
    - shard-iclb:         NOTRUN -> [SKIP][84] ([fdo#109289]) +1 similar issue
   [84]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@perf@unprivileged-single-ctx-counters.html

  * igt@prime_nv_api@i915_nv_reimport_twice_check_flink_name:
    - shard-apl:          NOTRUN -> [SKIP][85] ([fdo#109271]) +257 similar issues
   [85]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl2/igt@prime_nv_api@i915_nv_reimport_twice_check_flink_name.html

  * igt@prime_nv_api@i915_self_import:
    - shard-skl:          NOTRUN -> [SKIP][86] ([fdo#109271]) +20 similar issues
   [86]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@prime_nv_api@i915_self_import.html

  * igt@prime_nv_pcopy@test3_3:
    - shard-iclb:         NOTRUN -> [SKIP][87] ([fdo#109291])
   [87]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@prime_nv_pcopy@test3_3.html

  * igt@sysfs_clients@fair-1:
    - shard-apl:          NOTRUN -> [SKIP][88] ([fdo#109271] / [i915#2994]) +3 similar issues
   [88]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@sysfs_clients@fair-1.html

  
#### Possible fixes ####

  * igt@gem_ctx_persistence@engines-hang@rcs0:
    - {shard-rkl}:        [FAIL][89] ([i915#2410]) -> [PASS][90]
   [89]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@gem_ctx_persistence@engines-hang@rcs0.html
   [90]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-2/igt@gem_ctx_persistence@engines-hang@rcs0.html

  * igt@gem_eio@unwedge-stress:
    - {shard-rkl}:        [TIMEOUT][91] ([i915#3063]) -> [PASS][92]
   [91]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-6/igt@gem_eio@unwedge-stress.html
   [92]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-1/igt@gem_eio@unwedge-stress.html

  * igt@gem_exec_fair@basic-deadline:
    - shard-kbl:          [FAIL][93] ([i915#2846]) -> [PASS][94]
   [93]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-kbl1/igt@gem_exec_fair@basic-deadline.html
   [94]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-kbl7/igt@gem_exec_fair@basic-deadline.html

  * igt@gem_exec_fair@basic-pace-share@rcs0:
    - shard-tglb:         [FAIL][95] ([i915#2842]) -> [PASS][96] +1 similar issue
   [95]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-tglb7/igt@gem_exec_fair@basic-pace-share@rcs0.html
   [96]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb5/igt@gem_exec_fair@basic-pace-share@rcs0.html

  * igt@gem_exec_fair@basic-pace-solo@rcs0:
    - shard-glk:          [FAIL][97] ([i915#2842]) -> [PASS][98] +2 similar issues
   [97]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk1/igt@gem_exec_fair@basic-pace-solo@rcs0.html
   [98]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk3/igt@gem_exec_fair@basic-pace-solo@rcs0.html
    - shard-kbl:          [FAIL][99] ([i915#2842]) -> [PASS][100] +1 similar issue
   [99]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-kbl1/igt@gem_exec_fair@basic-pace-solo@rcs0.html
   [100]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-kbl7/igt@gem_exec_fair@basic-pace-solo@rcs0.html

  * igt@gem_exec_fair@basic-pace@vcs0:
    - shard-iclb:         [FAIL][101] ([i915#2842]) -> [PASS][102]
   [101]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb7/igt@gem_exec_fair@basic-pace@vcs0.html
   [102]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb7/igt@gem_exec_fair@basic-pace@vcs0.html

  * igt@gem_exec_fair@basic-throttle@rcs0:
    - {shard-rkl}:        [FAIL][103] ([i915#2842]) -> [PASS][104]
   [103]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-6/igt@gem_exec_fair@basic-throttle@rcs0.html
   [104]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-5/igt@gem_exec_fair@basic-throttle@rcs0.html

  * igt@gem_mmap_gtt@cpuset-big-copy-xy:
    - shard-iclb:         [FAIL][105] ([i915#307]) -> [PASS][106] +1 similar issue
   [105]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb8/igt@gem_mmap_gtt@cpuset-big-copy-xy.html
   [106]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb5/igt@gem_mmap_gtt@cpuset-big-copy-xy.html

  * igt@gen9_exec_parse@allowed-single:
    - shard-skl:          [DMESG-WARN][107] ([i915#1436] / [i915#716]) -> [PASS][108]
   [107]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl1/igt@gen9_exec_parse@allowed-single.html
   [108]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@gen9_exec_parse@allowed-single.html

  * igt@i915_pm_backlight@bad-brightness:
    - {shard-rkl}:        [SKIP][109] ([i915#3012]) -> [PASS][110]
   [109]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@i915_pm_backlight@bad-brightness.html
   [110]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@i915_pm_backlight@bad-brightness.html

  * igt@i915_pm_rc6_residency@rc6-fence:
    - shard-tglb:         [WARN][111] ([i915#2681]) -> [PASS][112]
   [111]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-tglb6/igt@i915_pm_rc6_residency@rc6-fence.html
   [112]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-tglb2/igt@i915_pm_rc6_residency@rc6-fence.html

  * igt@kms_big_fb@linear-64bpp-rotate-180:
    - shard-iclb:         [DMESG-WARN][113] ([i915#3621]) -> [PASS][114] +1 similar issue
   [113]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-iclb1/igt@kms_big_fb@linear-64bpp-rotate-180.html
   [114]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-iclb3/igt@kms_big_fb@linear-64bpp-rotate-180.html

  * igt@kms_big_fb@x-tiled-8bpp-rotate-0:
    - {shard-rkl}:        [SKIP][115] ([i915#3638]) -> [PASS][116] +5 similar issues
   [115]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@kms_big_fb@x-tiled-8bpp-rotate-0.html
   [116]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_big_fb@x-tiled-8bpp-rotate-0.html

  * igt@kms_big_fb@y-tiled-16bpp-rotate-90:
    - {shard-rkl}:        [SKIP][117] ([fdo#111614]) -> [PASS][118]
   [117]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@kms_big_fb@y-tiled-16bpp-rotate-90.html
   [118]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_big_fb@y-tiled-16bpp-rotate-90.html

  * igt@kms_big_fb@y-tiled-max-hw-stride-64bpp-rotate-0-async-flip:
    - {shard-rkl}:        [SKIP][119] ([i915#3721]) -> [PASS][120] +4 similar issues
   [119]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@kms_big_fb@y-tiled-max-hw-stride-64bpp-rotate-0-async-flip.html
   [120]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_big_fb@y-tiled-max-hw-stride-64bpp-rotate-0-async-flip.html

  * igt@kms_ccs@pipe-b-ccs-on-another-bo-y_tiled_gen12_rc_ccs_cc:
    - {shard-rkl}:        [FAIL][121] ([i915#3678]) -> [PASS][122] +7 similar issues
   [121]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-5/igt@kms_ccs@pipe-b-ccs-on-another-bo-y_tiled_gen12_rc_ccs_cc.html
   [122]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_ccs@pipe-b-ccs-on-another-bo-y_tiled_gen12_rc_ccs_cc.html

  * igt@kms_color@pipe-b-ctm-0-75:
    - {shard-rkl}:        [SKIP][123] ([i915#1149] / [i915#1849]) -> [PASS][124] +4 similar issues
   [123]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@kms_color@pipe-b-ctm-0-75.html
   [124]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_color@pipe-b-ctm-0-75.html

  * igt@kms_cursor_crc@pipe-a-cursor-128x42-offscreen:
    - {shard-rkl}:        [SKIP][125] ([fdo#112022]) -> [PASS][126] +16 similar issues
   [125]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-5/igt@kms_cursor_crc@pipe-a-cursor-128x42-offscreen.html
   [126]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_cursor_crc@pipe-a-cursor-128x42-offscreen.html

  * igt@kms_cursor_legacy@basic-busy-flip-before-cursor-atomic:
    - {shard-rkl}:        [SKIP][127] ([fdo#111825]) -> [PASS][128] +2 similar issues
   [127]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@kms_cursor_legacy@basic-busy-flip-before-cursor-atomic.html
   [128]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_cursor_legacy@basic-busy-flip-before-cursor-atomic.html

  * igt@kms_cursor_legacy@flip-vs-cursor-varying-size:
    - shard-skl:          [FAIL][129] ([i915#2346]) -> [PASS][130]
   [129]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl5/igt@kms_cursor_legacy@flip-vs-cursor-varying-size.html
   [130]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl7/igt@kms_cursor_legacy@flip-vs-cursor-varying-size.html

  * igt@kms_draw_crc@draw-method-xrgb8888-mmap-cpu-untiled:
    - {shard-rkl}:        [SKIP][131] ([fdo#111314]) -> [PASS][132] +10 similar issues
   [131]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@kms_draw_crc@draw-method-xrgb8888-mmap-cpu-untiled.html
   [132]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_draw_crc@draw-method-xrgb8888-mmap-cpu-untiled.html

  * igt@kms_flip@2x-flip-vs-expired-vblank-interruptible@ab-hdmi-a1-hdmi-a2:
    - shard-glk:          [FAIL][133] ([i915#2122]) -> [PASS][134]
   [133]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-glk8/igt@kms_flip@2x-flip-vs-expired-vblank-interruptible@ab-hdmi-a1-hdmi-a2.html
   [134]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-glk2/igt@kms_flip@2x-flip-vs-expired-vblank-interruptible@ab-hdmi-a1-hdmi-a2.html

  * igt@kms_flip@flip-vs-expired-vblank-interruptible@b-edp1:
    - shard-skl:          [FAIL][135] ([i915#79]) -> [PASS][136]
   [135]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl1/igt@kms_flip@flip-vs-expired-vblank-interruptible@b-edp1.html
   [136]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl5/igt@kms_flip@flip-vs-expired-vblank-interruptible@b-edp1.html

  * igt@kms_flip@flip-vs-suspend-interruptible@a-edp1:
    - shard-skl:          [INCOMPLETE][137] ([i915#146] / [i915#198]) -> [PASS][138]
   [137]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-skl4/igt@kms_flip@flip-vs-suspend-interruptible@a-edp1.html
   [138]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-skl8/igt@kms_flip@flip-vs-suspend-interruptible@a-edp1.html

  * igt@kms_frontbuffer_tracking@fbc-rgb101010-draw-pwrite:
    - {shard-rkl}:        [SKIP][139] ([i915#1849] / [i915#3180]) -> [PASS][140]
   [139]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-2/igt@kms_frontbuffer_tracking@fbc-rgb101010-draw-pwrite.html
   [140]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_frontbuffer_tracking@fbc-rgb101010-draw-pwrite.html

  * igt@kms_frontbuffer_tracking@psr-1p-primscrn-spr-indfb-draw-mmap-wc:
    - {shard-rkl}:        [SKIP][141] ([i915#1849]) -> [PASS][142] +44 similar issues
   [141]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-rkl-1/igt@kms_frontbuffer_tracking@psr-1p-primscrn-spr-indfb-draw-mmap-wc.html
   [142]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-rkl-6/igt@kms_frontbuffer_tracking@psr-1p-primscrn-spr-indfb-draw-mmap-wc.html

  * igt@kms_plane@plane-panning-bottom-right-suspend@pipe-a-planes:
    - shard-apl:          [DMESG-WARN][143] ([i915#180]) -> [PASS][144] +1 similar issue
   [143]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_10393/shard-apl3/igt@kms_plane@plane-panning-bottom-right-suspend@pipe-a-planes.html
   [144]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/shard-apl3/igt@kms_plane@plane-panning-bottom-right-suspend@pipe-a-planes.html

  * igt@kms_plane_alpha_blend@pipe-a-constant-alpha-min:
    - shard-skl:          [FAIL][145] ([fdo#108145] / [i915#265]) -> [PASS][146]
   [145

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_20704/index.html

[-- Attachment #1.2: Type: text/html, Size: 33421 bytes --]

[-- Attachment #2: Type: text/plain, Size: 160 bytes --]

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