[Intel-gfx] [PATCH 19/28] drm: document drm_crtc_funcs

[Thierry Reding]

On Fri, Dec 04, 2015 at 09:46:00AM +0100, Daniel Vetter wrote:
[...]
> diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> index fbfe617bc492..72a7e096dd42 100644
> --- a/include/drm/drm_crtc.h
> +++ b/include/drm/drm_crtc.h
> @@ -320,12 +320,6 @@ struct drm_crtc_state {
>  
>  /**
>   * struct drm_crtc_funcs - control CRTCs for a given device
> - * @cursor_set: setup the cursor
> - * @cursor_set2: setup the cursor with hotspot, superseeds @cursor_set if set
> - * @cursor_move: move the cursor
> - * @gamma_set: specify color ramp for CRTC
> - * @set_config: apply a new CRTC configuration
> - * @page_flip: initiate a page flip
>   *
>   * The drm_crtc_funcs structure is the central CRTC management structure
>   * in the DRM.  Each CRTC controls one or more connectors (note that the name
> @@ -349,15 +343,86 @@ struct drm_crtc_funcs {
>  	 */
>  	void (*reset)(struct drm_crtc *crtc);
>  
> -	/* cursor controls */
> +	/**
> +	 * @cursor_set:
> +	 *
> +	 * Update the cursor image. The cursor position is relative to the CRTC
> +	 * and can be partially or fully outside of the visible area.
> +	 *
> +	 * Note that contrary to all other KMS function the legacy cursor entry

"functions"

> +	/**
> +	 * @cursor_move:
> +	 *
> +	 * Update the cursor position. The cursor does not need to be visible
> +	 * when this hook is called.
> +	 *
> +	 * This entry point is deprecated, drivers should instead implement
> +	 * universal plane support and register a proper cursor plane using
> +	 * drm_crtc_init_with_planes().
> +	 *
> +	 * This callback is optional

Nit: Append a full-stop here and in the above ->cursor_*() callback
descriptions.

> -	/*
> -	 * Flip to the given framebuffer.  This implements the page
> -	 * flip ioctl described in drm_mode.h, specifically, the
> -	 * implementation must return immediately and block all
> -	 * rendering to the current fb until the flip has completed.
> -	 * If userspace set the event flag in the ioctl, the event
> -	 * argument will point to an event to send back when the flip
> -	 * completes, otherwise it will be NULL.
> +	/**
> +	 * @page_flip:
> +	 *
> +	 * Legacy entry point to schedule a flip to the given framebuffer.
> +	 *
> +	 * Page flipping is a synchronization mechanism that replaces the frame
> +	 * buffer being scanned out by the CRTC with a new frame buffer during
> +	 * vertical blanking, avoiding tearing (except when requested otherwise
> +	 * through the DRM_MODE_PAGE_FLIP_ASYN flag). When an application

"DRM_MODE_PAGE_FLIP_ASYNC"

> +	 * requests a page flip the DRM core verifies that the new frame buffer is large

This line looks odd because it is wider than all the others.

> +	 * enough to be scanned out by the CRTC in the currently configured mode
> +	 * and then calls the CRTC page_flip operation with a pointer to the new

"->page_flip()"?

> +	 * frame buffer.
> +	 *
> +	 * The driver must wait for any pending rendering to the new framebuffer
> +	 * to complete before executing the flip. It should also wait for any
> +	 * pending rendering from other drivers if the underlying buffer is a
> +	 * shared dma-buf.
> +	 *
> +	 * An application can request to be notified when the page flip has
> +	 * completed. The drm core will supply a struct &drm_event in the event
> +	 * parameter in this case. This can be handled by the
> +	 * drm_crtc_send_vblank_event() function, which the driver should call on
> +	 * the provided event upon completion of the flip. Note that if
> +	 * the driver supports vblank signalling and timestamping the vblank
> +	 * counters and timestamps must agree with the ones returned from page
> +	 * flip events. With the current vblank helper infrastructure this can
> +	 * be achieved by holding a vblank reference while the page flip is
> +	 * pending, acquired through drm_crtc_vblank_get() and released with
> +	 * drm_crtc_vblank_put(). Drivers are free to implement their own vblank
> +	 * counter and timestamp tracking though, e.g. if they have accurate
> +	 * timestamp registers in hardware.
> +	 *
> +	 * FIXME:
> +	 *
> +	 * Up to that point drivers need to manage events themselves and can use
> +	 * even->base.list freely for that. Specifically they need to ensure
> +	 * that they don't send out page flip (or vblank) events for which the
> +	 * corresponding drm file has been closed already. The drm core
> +	 * unfortunately does not (yet) take care of that. Therefore drivers
> +	 * currently must clean up and release pending events in their
> +	 * ->preclose driver function.
> +	 *
> +	 * This callback is optional.
> +	 *
> +	 * NOTE:
> +	 *
> +	 * Very early versions of the KMS ABI mandated that the driver must
> +	 * block (but not reject) any rendering to the old framebuffer until the
> +	 * flip operation has completed and the old framebuffer is not longer

"no longer"

> +	 * visible. This requirement has been lifted, and userspace is instead
> +	 * expected to request delivery of a event and wait with recycling old

"an event"

Otherwise:

Reviewed-by: Thierry Reding <treding at nvidia.com>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/intel-gfx/attachments/20151207/c0b3d804/attachment-0001.sig>