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

Commit 9de5d4a6 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: Document adjusted/request modes a bit better 



Laurent started a massive discussion on IRC about this. Let's try to
document common usage a bit better.

v2: Cross-links+typos.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Jose Abreu <Jose.Abreu@synopsys.com>
Reviewed-by: default avatarJose Abreu <joabreu@synopsys.com>
Reviewed-by: default avatarAndrzej Hajda <a.hajda@samsung.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170515091136.26307-1-daniel.vetter@ffwll.ch
parent 3eb220a5

include/drm/drm_bridge.h

+1 −1
Original line number Diff line number Diff line
@@ -100,7 +100,7 @@ struct drm_bridge_funcs { 
	 * the display chain, either the final &drm_connector or the next

	 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge

	 * requires. It can be modified by this callback and does not need to

	 * match mode.

	 * match mode. See also &drm_crtc_state.adjusted_mode for more details.

	 *

	 * This is the only hook that allows a bridge to reject a modeset. If

	 * this function passes all other callbacks must succeed for this

include/drm/drm_crtc.h

+25 −3
Original line number Diff line number Diff line
@@ -90,8 +90,6 @@ struct drm_plane_helper_funcs; 
 * @plane_mask: bitmask of (1 << drm_plane_index(plane)) of attached planes

 * @connector_mask: bitmask of (1 << drm_connector_index(connector)) of attached connectors

 * @encoder_mask: bitmask of (1 << drm_encoder_index(encoder)) of attached encoders

 * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings

 * @mode: current mode timings

 * @mode_blob: &drm_property_blob for @mode

 * @state: backpointer to global drm_atomic_state

 *
@@ -131,9 +129,33 @@ struct drm_crtc_state { 
	u32 connector_mask;

	u32 encoder_mask;



	/* adjusted_mode: for use by helpers and drivers */

	/**

	 * @adjusted_mode:

	 *

	 * Internal display timings which can be used by the driver to handle

	 * differences between the mode requested by userspace in @mode and what

	 * is actually programmed into the hardware. It is purely driver

	 * implementation defined what exactly this adjusted mode means. Usually

	 * it is used to store the hardware display timings used between the

	 * CRTC and encoder blocks.

	 */

	struct drm_display_mode adjusted_mode;



	/**

	 * @mode:

	 *

	 * Display timings requested by userspace. The driver should try to

	 * match the refresh rate as close as possible (but note that it's

	 * undefined what exactly is close enough, e.g. some of the HDMI modes

	 * only differ in less than 1% of the refresh rate). The active width

	 * and height as observed by userspace for positioning planes must match

	 * exactly.

	 *

	 * For external connectors where the sink isn't fixed (like with a

	 * built-in panel), this mode here should match the physical mode on the

	 * wire to the last details (i.e. including sync polarities and

	 * everything).

	 */

	struct drm_display_mode mode;



	/* blob property to expose current mode to atomic userspace */

include/drm/drm_modeset_helper_vtables.h

+4 −2
Original line number Diff line number Diff line
@@ -147,7 +147,8 @@ struct drm_crtc_helper_funcs { 
	 * encoders need to be fed with. Note that this is the inverse semantics

	 * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup

	 * vfunc. If the CRTC cannot support the requested conversion from mode

	 * to adjusted_mode it should reject the modeset.

	 * to adjusted_mode it should reject the modeset. See also

	 * &drm_crtc_state.adjusted_mode for more details.

	 *

	 * This function is used by both legacy CRTC helpers and atomic helpers.

	 * With atomic helpers it is optional.
@@ -528,7 +529,8 @@ struct drm_encoder_helper_funcs { 
	 * mode is the display mode that should be fed to the next element in

	 * the display chain, either the final &drm_connector or a &drm_bridge.

	 * The parameter adjusted_mode is the input mode the encoder requires. It

	 * can be modified by this callback and does not need to match mode.

	 * can be modified by this callback and does not need to match mode. See

	 * also &drm_crtc_state.adjusted_mode for more details.

	 *

	 * This function is used by both legacy CRTC helpers and atomic helpers.

	 * This hook is optional.