From 6c4789edc55d5a0acefc85380d7a3f7c4f21c7cd Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 14 Nov 2016 12:58:20 +0100 Subject: [PATCH] drm: Clean up kerneldoc for struct drm_driver Just cleans up what's there, still plenty missing. Reviewed-by: Chris Wilson Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/20161114115825.22050-6-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-internals.rst | 3 + include/drm/drm_drv.h | 168 +++++++++++++++++++++++------------- 2 files changed, 109 insertions(+), 62 deletions(-) diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 25ee92c5df65..a54ac97510b3 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 :export: +.. kernel-doc:: include/drm/drm_drv.h + :internal: + Driver Load ----------- diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h index 0faf5ec72d19..048086e38ef6 100644 --- a/include/drm/drm_drv.h +++ b/include/drm/drm_drv.h @@ -77,92 +77,110 @@ struct drm_driver { int (*set_busid)(struct drm_device *dev, struct drm_master *master); /** - * get_vblank_counter - get raw hardware vblank counter - * @dev: DRM device - * @pipe: counter to fetch + * @get_vblank_counter: * - * Driver callback for fetching a raw hardware vblank counter for @crtc. - * If a device doesn't have a hardware counter, the driver can simply - * use drm_vblank_no_hw_counter() function. The DRM core will account for + * Driver callback for fetching a raw hardware vblank counter for the + * CRTC specified with the pipe argument. If a device doesn't have a + * hardware counter, the driver can simply use + * drm_vblank_no_hw_counter() function. The DRM core will account for * missed vblank events while interrupts where disabled based on system * timestamps. * * Wraparound handling and loss of events due to modesetting is dealt - * with in the DRM core code. + * with in the DRM core code, as long as drivers call + * drm_crtc_vblank_off() and drm_crtc_vblank_on() when disabling or + * enabling a CRTC. + * + * Returns: * - * RETURNS * Raw vblank counter value. */ u32 (*get_vblank_counter) (struct drm_device *dev, unsigned int pipe); /** - * enable_vblank - enable vblank interrupt events - * @dev: DRM device - * @pipe: which irq to enable + * @enable_vblank: + * + * Enable vblank interrupts for the CRTC specified with the pipe + * argument. * - * Enable vblank interrupts for @crtc. If the device doesn't have - * a hardware vblank counter, the driver should use the - * drm_vblank_no_hw_counter() function that keeps a virtual counter. + * Returns: * - * RETURNS * Zero on success, appropriate errno if the given @crtc's vblank * interrupt cannot be enabled. */ int (*enable_vblank) (struct drm_device *dev, unsigned int pipe); /** - * disable_vblank - disable vblank interrupt events - * @dev: DRM device - * @pipe: which irq to enable + * @disable_vblank: * - * Disable vblank interrupts for @crtc. If the device doesn't have - * a hardware vblank counter, the driver should use the - * drm_vblank_no_hw_counter() function that keeps a virtual counter. + * Disable vblank interrupts for the CRTC specified with the pipe + * argument. */ void (*disable_vblank) (struct drm_device *dev, unsigned int pipe); /** - * Called by \c drm_device_is_agp. Typically used to determine if a - * card is really attached to AGP or not. + * @device_is_agp: + * + * Called by drm_device_is_agp(). Typically used to determine if a card + * is really attached to AGP or not. * - * \param dev DRM device handle + * Returns: * - * \returns * One of three values is returned depending on whether or not the - * card is absolutely \b not AGP (return of 0), absolutely \b is AGP + * card is absolutely not AGP (return of 0), absolutely is AGP * (return of 1), or may or may not be AGP (return of 2). */ int (*device_is_agp) (struct drm_device *dev); /** + * @get_scanout_position: + * * Called by vblank timestamping code. * - * Return the current display scanout position from a crtc, and an - * optional accurate ktime_get timestamp of when position was measured. + * Returns the current display scanout position from a crtc, and an + * optional accurate ktime_get() timestamp of when position was + * measured. Note that this is a helper callback which is only used if a + * driver uses drm_calc_vbltimestamp_from_scanoutpos() for the + * @get_vblank_timestamp callback. + * + * Parameters: * - * \param dev DRM device. - * \param pipe Id of the crtc to query. - * \param flags Flags from the caller (DRM_CALLED_FROM_VBLIRQ or 0). - * \param *vpos Target location for current vertical scanout position. - * \param *hpos Target location for current horizontal scanout position. - * \param *stime Target location for timestamp taken immediately before - * scanout position query. Can be NULL to skip timestamp. - * \param *etime Target location for timestamp taken immediately after - * scanout position query. Can be NULL to skip timestamp. - * \param mode Current display timings. + * dev: + * DRM device. + * pipe: + * Id of the crtc to query. + * flags: + * Flags from the caller (DRM_CALLED_FROM_VBLIRQ or 0). + * vpos: + * Target location for current vertical scanout position. + * hpos: + * Target location for current horizontal scanout position. + * stime: + * Target location for timestamp taken immediately before + * scanout position query. Can be NULL to skip timestamp. + * etime: + * Target location for timestamp taken immediately after + * scanout position query. Can be NULL to skip timestamp. + * mode: + * Current display timings. * * Returns vpos as a positive number while in active scanout area. * Returns vpos as a negative number inside vblank, counting the number * of scanlines to go until end of vblank, e.g., -1 means "one scanline * until start of active scanout / end of vblank." * - * \return Flags, or'ed together as follows: + * Returns: + * + * Flags, or'ed together as follows: * - * DRM_SCANOUTPOS_VALID = Query successful. - * DRM_SCANOUTPOS_INVBL = Inside vblank. - * DRM_SCANOUTPOS_ACCURATE = Returned position is accurate. A lack of - * this flag means that returned position may be offset by a constant - * but unknown small number of scanlines wrt. real scanout position. + * DRM_SCANOUTPOS_VALID: + * Query successful. + * DRM_SCANOUTPOS_INVBL: + * Inside vblank. + * DRM_SCANOUTPOS_ACCURATE: Returned position is accurate. A lack of + * this flag means that returned position may be offset by a + * constant but unknown small number of scanlines wrt. real scanout + * position. * */ int (*get_scanout_position) (struct drm_device *dev, unsigned int pipe, @@ -171,7 +189,9 @@ struct drm_driver { const struct drm_display_mode *mode); /** - * Called by \c drm_get_last_vbltimestamp. Should return a precise + * @get_vblank_timestamp: + * + * Called by drm_get_last_vbltimestamp(). Should return a precise * timestamp when the most recent VBLANK interval ended or will end. * * Specifically, the timestamp in @vblank_time should correspond as @@ -183,19 +203,27 @@ struct drm_driver { * past start time of the current scanout. This is meant to adhere * to the OpenML OML_sync_control extension specification. * - * \param dev dev DRM device handle. - * \param pipe crtc for which timestamp should be returned. - * \param *max_error Maximum allowable timestamp error in nanoseconds. - * Implementation should strive to provide timestamp - * with an error of at most *max_error nanoseconds. - * Returns true upper bound on error for timestamp. - * \param *vblank_time Target location for returned vblank timestamp. - * \param flags 0 = Defaults, no special treatment needed. - * \param DRM_CALLED_FROM_VBLIRQ = Function is called from vblank - * irq handler. Some drivers need to apply some workarounds - * for gpu-specific vblank irq quirks if flag is set. - * - * \returns + * Paramters: + * + * dev: + * dev DRM device handle. + * pipe: + * crtc for which timestamp should be returned. + * max_error: + * Maximum allowable timestamp error in nanoseconds. + * Implementation should strive to provide timestamp + * with an error of at most max_error nanoseconds. + * Returns true upper bound on error for timestamp. + * vblank_time: + * Target location for returned vblank timestamp. + * flags: + * 0 = Defaults, no special treatment needed. + * DRM_CALLED_FROM_VBLIRQ = Function is called from vblank + * irq handler. Some drivers need to apply some workarounds + * for gpu-specific vblank irq quirks if flag is set. + * + * Returns: + * * Zero if timestamping isn't supported in current display mode or a * negative number on failure. A positive status code on success, * which describes how the vblank_time timestamp was computed. @@ -212,16 +240,32 @@ struct drm_driver { int (*irq_postinstall) (struct drm_device *dev); void (*irq_uninstall) (struct drm_device *dev); - /* Master routines */ + /** + * @master_create: + * + * Called whenever a new master is created. Only used by vmwgfx. + */ int (*master_create)(struct drm_device *dev, struct drm_master *master); - void (*master_destroy)(struct drm_device *dev, struct drm_master *master); + /** - * master_set is called whenever the minor master is set. - * master_drop is called whenever the minor master is dropped. + * @master_destroy: + * + * Called whenever a master is destroyed. Only used by vmwgfx. */ + void (*master_destroy)(struct drm_device *dev, struct drm_master *master); + /** + * @master_set: + * + * Called whenever the minor master is set. Only used by vmwgfx. + */ int (*master_set)(struct drm_device *dev, struct drm_file *file_priv, bool from_open); + /** + * @master_drop: + * + * Called whenever the minor master is dropped. Only used by vmwgfx. + */ void (*master_drop)(struct drm_device *dev, struct drm_file *file_priv); int (*debugfs_init)(struct drm_minor *minor); -- 2.11.0