From: Jeremy Cline jcline@redhat.com
Start on documentation for the Nouveau device structure and the NVIF client structure it uses. This documentation is not complete as the structures are non-trivial and I am not familiar with large portions of them.
Signed-off-by: Jeremy Cline jcline@redhat.com Signed-off-by: Lyude Paul lyude@redhat.com --- drivers/gpu/drm/nouveau/nouveau_drv.h | 67 +++++++++++++++++++++++++++ 1 file changed, 67 insertions(+)
diff --git a/drivers/gpu/drm/nouveau/nouveau_drv.h b/drivers/gpu/drm/nouveau/nouveau_drv.h index 8eb133fd6df0..43d751d2445f 100644 --- a/drivers/gpu/drm/nouveau/nouveau_drv.h +++ b/drivers/gpu/drm/nouveau/nouveau_drv.h @@ -88,8 +88,20 @@ enum nouveau_drm_handle { NVDRM_NVSW = 0x55550000, };
+/** + * struct nouveau_cli - A DRM-specific NVIF client. + * + * This encapsulates a NVIF client and is intended to be the sole interface + * between the DRM APIs and NVKM. An instance of this structure is allocated + * for each userspace client when they open the device file. Additionally, + * there are several allocated strictly for the kernel's use. + */ struct nouveau_cli { struct nvif_client base; + + /** + * @drm: A reference to the device that the client is associated with. + */ struct nouveau_drm *drm; struct mutex mutex;
@@ -99,6 +111,9 @@ struct nouveau_cli { struct nouveau_vmm svm; const struct nvif_mclass *mem;
+ /** + * @head: The list entry for this client in the @drm device's list of clients. + */ struct list_head head; void *abi16; struct list_head objects; @@ -106,13 +121,36 @@ struct nouveau_cli { char name[32];
struct work_struct work; + + /** + * @worker: List of pending &struct nouveau_cli_work associated with this client. + */ struct list_head worker; + + /** + * @lock: Protects the @worker list. Additionally, this lock on the + * @drm.master instance is used to serialize destruction of the @base + * member in this structure, as well as the destruction of the &struct + * nvif_mem embedded in &struct nouveau_mem instances. + */ struct mutex lock; };
+/** + * struct nouveau_cli_work - A pending work item for an NVIF client. + */ struct nouveau_cli_work { void (*func)(struct nouveau_cli_work *); + + /** + * @cli: Reference to the NVIF client this work belongs to. + */ struct nouveau_cli *cli; + + /** + * @head: The list entry for this work item in the &struct nouveau_cli + * worker list. + */ struct list_head head;
struct dma_fence *fence; @@ -131,9 +169,32 @@ nouveau_cli(struct drm_file *fpriv) #include <nvif/object.h> #include <nvif/parent.h>
+/** + * struct nouveau_drm - The nouveau-specific device structure. + * + * This structure is allocated for a device when it is probed and keeps track + * of all the nouveau-specific device details. The lifetime of this structure + * is the same as the lifetime of a &struct drm_device and is managed by the + * DRM layer. + */ struct nouveau_drm { + /** + * @parent: Implementation of the interface required to use the NVIF_DEBUG + * and NVIF_ERROR macros + */ struct nvif_parent parent; + + /** + * @master: This NVIF client is used to initialize the NVIF driver and used + * for TTM memory allocations. It is the root of the NVIF object tree. + */ struct nouveau_cli master; + + /** + * @client: This NVIF client is used by the DRM layer to interact with + * the NVKM layer for everything except TTM memory allocations. It, and + * all other clients, are children of the primary (@master) client. + */ struct nouveau_cli client;
/** @@ -141,6 +202,12 @@ struct nouveau_drm { */ struct drm_device drm_dev;
+ /** + * @clients: List of all &struct nouveau_cli allocated for userspace + * associated with this DRM device. Clients are allocated when the DRM + * file is opened and deallocated when the file is closed. This list is + * protected by the mutex in @client. + */ struct list_head clients;
u8 old_pm_cap;