| Message ID | 20210722092929.244629-3-desmondcheongzx@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm, drm/vmwgfx: fixes and updates related to drm_master | expand |
On 22/7/21 6:35 pm, Daniel Vetter wrote: > On Thu, Jul 22, 2021 at 05:29:28PM +0800, Desmond Cheong Zhi Xi wrote: >> In particular, we 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. >> >> Additionally, we add descriptions for the lifetime of lessors and >> leases to make it easier to reason about them. >> >> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com> >> --- >> include/drm/drm_auth.h | 62 ++++++++++++++++++++++++++++++++++-------- >> 1 file changed, 51 insertions(+), 11 deletions(-) >> >> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h >> index f99d3417f304..c978c85464fa 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,63 @@ 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 holder. The lessor does not change once it's set in > > Lessor is the lease grantor, lessee is the one receiving the lease. Maybe > clarify this with > > "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." > >> + * drm_lease_create(). Each lessee holds a reference to its lessor that > > I also figured it'd be a good idea to link to the drm_lease docs here to > explain the concepts, but alas we don't have those :-( Hence at least > define what we mean with lessor, lessee, lease and owner. > Thanks for the suggestions, Daniel. I'll incorporate them in a v2. Regarding the missing drm_lease docs... any reason we can't just add it in? Seems like most of the comments in drm_lease.c are almost correctly formatted too. I could clean them up, define the terms in a preamble, then add it to the v2 patch. >> + * it releases upon being destroyed in drm_lease_destroy(). >> + * >> + * Display resource leases form a tree of &struct drm_master. All of > > For now we've limited the tree to a depth of 1, you can't create another > lease if yourself are a lease. I guess another reason to update the > drm_lease.c docs. > > So maybe add "Currently the lease tree depth is limited to 1." > >> + * these get activated simultaneously, so &drm_device.master >> + * points at the top of the tree (for which lessor is NULL). >> */ >> - >> struct drm_master *lessor; >> + >> + /** >> + * @lessee_id: >> + * >> + * ID for lessees. Owners always have ID 0. Protected by > > Maybe clarify to "Owners (i.e. @lessor is NULL) ..." > >> + * &drm_device.mode_config's &drm_mode_config.idr_mutex. >> + */ >> int lessee_id; >> + >> + /** >> + * @lessee_list: >> + * >> + * List of lessees of the same master. Protected by > > We try to distinguis between list entries and the list, even though it's > the same struct. So maybe > > "List entry of lessees of @lessor, where they are linked to @lessee. Not > use for owners." > >> + * &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 master cannot be destroyed unless this list is empty as lessors >> + * are referenced by all their lessees. > > Maybe add "this list is empty of no leases have been granted." > >> + */ >> 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). > > @lessor so it's highlighted correctly > >> + * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex. >> + */ >> struct idr lessee_idr; >> /* private: */ > > With the nits addressed: > > Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > > Thanks for updating the docs! > -Daniel > >> #if IS_ENABLED(CONFIG_DRM_LEGACY) >> -- >> 2.25.1 >> >
On Thu, Jul 22, 2021 at 3:03 PM Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com> wrote: > > On 22/7/21 6:35 pm, Daniel Vetter wrote: > > On Thu, Jul 22, 2021 at 05:29:28PM +0800, Desmond Cheong Zhi Xi wrote: > >> In particular, we 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. > >> > >> Additionally, we add descriptions for the lifetime of lessors and > >> leases to make it easier to reason about them. > >> > >> Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com> > >> --- > >> include/drm/drm_auth.h | 62 ++++++++++++++++++++++++++++++++++-------- > >> 1 file changed, 51 insertions(+), 11 deletions(-) > >> > >> diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h > >> index f99d3417f304..c978c85464fa 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,63 @@ 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 holder. The lessor does not change once it's set in > > > > Lessor is the lease grantor, lessee is the one receiving the lease. Maybe > > clarify this with > > > > "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." > > > >> + * drm_lease_create(). Each lessee holds a reference to its lessor that > > > > I also figured it'd be a good idea to link to the drm_lease docs here to > > explain the concepts, but alas we don't have those :-( Hence at least > > define what we mean with lessor, lessee, lease and owner. > > > > Thanks for the suggestions, Daniel. I'll incorporate them in a v2. > > Regarding the missing drm_lease docs... any reason we can't just add it > in? Seems like most of the comments in drm_lease.c are almost correctly > formatted too. I could clean them up, define the terms in a preamble, > then add it to the v2 patch. Sure if you want to do that, that would be great. Usual style tips: - We only document driver interfaces, so structs/inline functions in headers and exported symbols in .c files. - Anything else interesting just leave as normal C comments - An overview DOC: section that explains a bit how leases work and why (git blame on the commit that added it should help, otherwise I can type that up) would also be really great. I think the right place for this is in the drm-uapi.rst section after the section about primary nodes: https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#modeset-base-object-abstraction Cheers, Daniel > > >> + * it releases upon being destroyed in drm_lease_destroy(). > >> + * > >> + * Display resource leases form a tree of &struct drm_master. All of > > > > For now we've limited the tree to a depth of 1, you can't create another > > lease if yourself are a lease. I guess another reason to update the > > drm_lease.c docs. > > > > So maybe add "Currently the lease tree depth is limited to 1." > > > >> + * these get activated simultaneously, so &drm_device.master > >> + * points at the top of the tree (for which lessor is NULL). > >> */ > >> - > >> struct drm_master *lessor; > >> + > >> + /** > >> + * @lessee_id: > >> + * > >> + * ID for lessees. Owners always have ID 0. Protected by > > > > Maybe clarify to "Owners (i.e. @lessor is NULL) ..." > > > >> + * &drm_device.mode_config's &drm_mode_config.idr_mutex. > >> + */ > >> int lessee_id; > >> + > >> + /** > >> + * @lessee_list: > >> + * > >> + * List of lessees of the same master. Protected by > > > > We try to distinguis between list entries and the list, even though it's > > the same struct. So maybe > > > > "List entry of lessees of @lessor, where they are linked to @lessee. Not > > use for owners." > > > >> + * &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 master cannot be destroyed unless this list is empty as lessors > >> + * are referenced by all their lessees. > > > > Maybe add "this list is empty of no leases have been granted." > > > >> + */ > >> 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). > > > > @lessor so it's highlighted correctly > > > >> + * Protected by &drm_device.mode_config's &drm_mode_config.idr_mutex. > >> + */ > >> struct idr lessee_idr; > >> /* private: */ > > > > With the nits addressed: > > > > Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > > > > Thanks for updating the docs! > > -Daniel > > > >> #if IS_ENABLED(CONFIG_DRM_LEGACY) > >> -- > >> 2.25.1 > >> > > >
diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h index f99d3417f304..c978c85464fa 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,63 @@ 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 holder. The lessor does not change once it's set in + * drm_lease_create(). Each lessee holds a reference to its lessor that + * it releases upon being destroyed in drm_lease_destroy(). + * + * Display resource leases form a tree of &struct drm_master. All of + * these get activated simultaneously, so &drm_device.master + * points at the top of the tree (for which lessor is NULL). */ - struct drm_master *lessor; + + /** + * @lessee_id: + * + * ID for lessees. Owners always have ID 0. Protected by + * &drm_device.mode_config's &drm_mode_config.idr_mutex. + */ int lessee_id; + + /** + * @lessee_list: + * + * List of lessees of the same master. 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 master cannot be destroyed unless this list is empty as lessors + * are referenced by all their lessees. + */ 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)
In particular, we 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. Additionally, we add descriptions for the lifetime of lessors and leases to make it easier to reason about them. Signed-off-by: Desmond Cheong Zhi Xi <desmondcheongzx@gmail.com> --- include/drm/drm_auth.h | 62 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 11 deletions(-)