From 3214a16684468f5429469c3b59dc25b312b9d6cc Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 11 Jan 2019 17:40:48 +0100 Subject: [PATCH] drm/doc: Polish kerneldoc for drm_device.h - Move all the legacy gunk at the bottom, and exclude it from kerneldoc. - Documentation for the remaining bits. v2: Fix typo (Sam). Cc: Sam Ravnborg Acked-by: Sam Ravnborg Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20190111164048.29067-5-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-internals.rst | 3 + include/drm/drm_device.h | 150 ++++++++++++++++------------ 2 files changed, 88 insertions(+), 65 deletions(-) diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 5ee9674fb9e9..9090fabf3f7a 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -143,6 +143,9 @@ Device Instance and Driver Handling .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview +.. kernel-doc:: include/drm/drm_device.h + :internal: + .. kernel-doc:: include/drm/drm_drv.h :internal: diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h index d7cedbac66a3..a6f8e5abb66f 100644 --- a/include/drm/drm_device.h +++ b/include/drm/drm_device.h @@ -69,7 +69,13 @@ struct drm_device { /** @driver: DRM driver managing the device */ struct drm_driver *driver; - /** @dev_private: DRM driver private data */ + /** + * @dev_private: + * + * DRM driver private data. Instead of using this pointer it is + * recommended that drivers use drm_dev_init() and embed struct + * &drm_device in their larger per-device structure. + */ void *dev_private; /** @primary: Primary node */ @@ -78,6 +84,11 @@ struct drm_device { /** @render: Render node */ struct drm_minor *render; + /** + * @registered: + * + * Internally used by drm_dev_register() and drm_connector_register(). + */ bool registered; /** @@ -134,16 +145,13 @@ struct drm_device { */ int open_count; - /** @buf_lock: Lock for &buf_use and a few other things. */ - spinlock_t buf_lock; - - /** @buf_use: Usage counter for buffers in use -- cannot alloc */ - int buf_use; - - /** @buf_alloc: Buffer allocation in progress */ - atomic_t buf_alloc; - + /** @filelist_mutex: Protects @filelist. */ struct mutex filelist_mutex; + /** + * @filelist: + * + * List of userspace clients, linked through &drm_file.lhead. + */ struct list_head filelist; /** @@ -168,46 +176,6 @@ struct drm_device { */ struct list_head clientlist; - /** @maplist: Memory management - linked list of regions */ - struct list_head maplist; - - /** @map_hash: Memory management - user token hash table for maps */ - struct drm_open_hash map_hash; - - /** - * @ctxlist: - * Context handle management - linked list of context handles - */ - struct list_head ctxlist; - - /** - * @ctxlist_mutex: - * - * Context handle management - mutex for &ctxlist - */ - struct mutex ctxlist_mutex; - - /** - * @ctx_idr: - * Context handle management - */ - struct idr ctx_idr; - - /** - * @vmalist: - * Context handle management - list of vmas (for debugging) - */ - struct list_head vmalist; - - /** @dma: Optional pointer for DMA support */ - struct drm_device_dma *dma; - - /** @context_flag: Context swapping flag */ - __volatile__ long context_flag; - - /** @last_context: Last current context */ - int last_context; - /** * @irq_enabled: * @@ -216,6 +184,10 @@ struct drm_device { * to true manually. */ bool irq_enabled; + + /** + * @irq: Used by the drm_irq_install() and drm_irq_unistall() helpers. + */ int irq; /** @@ -249,6 +221,10 @@ struct drm_device { * Protects vblank count and time updates during vblank enable/disable */ spinlock_t vblank_time_lock; + /** + * @vbl_lock: Top-level vblank references lock, wraps the low-level + * @vblank_time_lock. + */ spinlock_t vbl_lock; /** @@ -264,14 +240,19 @@ struct drm_device { * races and imprecision over longer time periods, hence exposing a * hardware vblank counter is always recommended. * - * If non-zeor, &drm_crtc_funcs.get_vblank_counter must be set. + * If non-zero, &drm_crtc_funcs.get_vblank_counter must be set. */ - - /** @max_vblank_count: Size of vblank counter register */ u32 max_vblank_count; /** @vblank_event_list: List of vblank events */ struct list_head vblank_event_list; + + /** + * @event_lock: + * + * Protects @vblank_event_list and event delivery in + * general. See drm_send_event() and drm_send_event_locked(). + */ spinlock_t event_lock; /** @agp: AGP data */ @@ -281,23 +262,12 @@ struct drm_device { struct pci_dev *pdev; #ifdef __alpha__ + /** @hose: PCI hose, only used on ALPHA platforms. */ struct pci_controller *hose; #endif - - /** @sg: Scatter gather memory */ - struct drm_sg_mem *sg; - /** @num_crtcs: Number of CRTCs on this device */ unsigned int num_crtcs; - struct { - int context; - struct drm_hw_lock *lock; - } sigdata; - - struct drm_local_map *agp_buffer_map; - unsigned int agp_buffer_token; - /** @mode_config: Current mode config */ struct drm_mode_config mode_config; @@ -327,6 +297,56 @@ struct drm_device { * Set by drm_fb_helper_init() and cleared by drm_fb_helper_fini(). */ struct drm_fb_helper *fb_helper; + + /* Everything below here is for legacy driver, never use! */ + /* private: */ + + /* Context handle management - linked list of context handles */ + struct list_head ctxlist; + + /* Context handle management - mutex for &ctxlist */ + struct mutex ctxlist_mutex; + + /* Context handle management */ + struct idr ctx_idr; + + /* Memory management - linked list of regions */ + struct list_head maplist; + + /* Memory management - user token hash table for maps */ + struct drm_open_hash map_hash; + + /* Context handle management - list of vmas (for debugging) */ + struct list_head vmalist; + + /* Optional pointer for DMA support */ + struct drm_device_dma *dma; + + /* Context swapping flag */ + __volatile__ long context_flag; + + /* Last current context */ + int last_context; + + /* Lock for &buf_use and a few other things. */ + spinlock_t buf_lock; + + /* Usage counter for buffers in use -- cannot alloc */ + int buf_use; + + /* Buffer allocation in progress */ + atomic_t buf_alloc; + + struct { + int context; + struct drm_hw_lock *lock; + } sigdata; + + struct drm_local_map *agp_buffer_map; + unsigned int agp_buffer_token; + + /* Scatter gather memory */ + struct drm_sg_mem *sg; }; #endif