Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3214a166 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

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 <sam@ravnborg.org>
Acked-by: default avatarSam Ravnborg <sam@ravnborg.org>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190111164048.29067-5-daniel.vetter@ffwll.ch
parent 9cd070a6

Documentation/gpu/drm-internals.rst

+3 −0
Original line number Diff line number Diff line
@@ -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:

include/drm/drm_device.h

+85 −65
Original line number Diff line number Diff line
@@ -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