[linux-2.6-block.git] / include / drm / drm_simple_kms_helper.h

/*
 * Copyright (C) 2016 Noralf Trønnes
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 */

#ifndef __LINUX_DRM_SIMPLE_KMS_HELPER_H
#define __LINUX_DRM_SIMPLE_KMS_HELPER_H

#include <drm/drm_crtc.h>
#include <drm/drm_encoder.h>
#include <drm/drm_plane.h>

struct drm_simple_display_pipe;

/**
 * struct drm_simple_display_pipe_funcs - helper operations for a simple
 *                                        display pipeline
 */
struct drm_simple_display_pipe_funcs {
	/**
	 * @mode_valid:
	 *
	 * This callback is used to check if a specific mode is valid in the
	 * crtc used in this simple display pipe. This should be implemented
	 * if the display pipe has some sort of restriction in the modes
	 * it can display. For example, a given display pipe may be responsible
	 * to set a clock value. If the clock can not produce all the values
	 * for the available modes then this callback can be used to restrict
	 * the number of modes to only the ones that can be displayed. Another
	 * reason can be bandwidth mitigation: the memory port on the display
	 * controller can have bandwidth limitations not allowing pixel data
	 * to be fetched at any rate.
	 *
	 * This hook is used by the probe helpers to filter the mode list in
	 * drm_helper_probe_single_connector_modes(), and it is used by the
	 * atomic helpers to validate modes supplied by userspace in
	 * drm_atomic_helper_check_modeset().
	 *
	 * This function is optional.
	 *
	 * NOTE:
	 *
	 * Since this function is both called from the check phase of an atomic
	 * commit, and the mode validation in the probe paths it is not allowed
	 * to look at anything else but the passed-in mode, and validate it
	 * against configuration-invariant hardware constraints.
	 *
	 * RETURNS:
	 *
	 * drm_mode_status Enum
	 */
	enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc,
					   const struct drm_display_mode *mode);

	/**
	 * @enable:
	 *
	 * This function should be used to enable the pipeline.
	 * It is called when the underlying crtc is enabled.
	 * This hook is optional.
	 */
	void (*enable)(struct drm_simple_display_pipe *pipe,
		       struct drm_crtc_state *crtc_state,
		       struct drm_plane_state *plane_state);
	/**
	 * @disable:
	 *
	 * This function should be used to disable the pipeline.
	 * It is called when the underlying crtc is disabled.
	 * This hook is optional.
	 */
	void (*disable)(struct drm_simple_display_pipe *pipe);

	/**
	 * @check:
	 *
	 * This function is called in the check phase of an atomic update,
	 * specifically when the underlying plane is checked.
	 * The simple display pipeline helpers already check that the plane is
	 * not scaled, fills the entire visible area and is always enabled
	 * when the crtc is also enabled.
	 * This hook is optional.
	 *
	 * RETURNS:
	 *
	 * 0 on success, -EINVAL if the state or the transition can't be
	 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
	 * attempt to obtain another state object ran into a &drm_modeset_lock
	 * deadlock.
	 */
	int (*check)(struct drm_simple_display_pipe *pipe,
		     struct drm_plane_state *plane_state,
		     struct drm_crtc_state *crtc_state);
	/**
	 * @update:
	 *
	 * This function is called when the underlying plane state is updated.
	 * This hook is optional.
	 *
	 * This is the function drivers should submit the
	 * &drm_pending_vblank_event from. Using either
	 * drm_crtc_arm_vblank_event(), when the driver supports vblank
	 * interrupt handling, or drm_crtc_send_vblank_event() directly in case
	 * the hardware lacks vblank support entirely.
	 */
	void (*update)(struct drm_simple_display_pipe *pipe,
		       struct drm_plane_state *old_plane_state);

	/**
	 * @prepare_fb:
	 *
	 * Optional, called by &drm_plane_helper_funcs.prepare_fb.  Please read
	 * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for
	 * more details.
	 *
	 * Drivers which always have their buffers pinned should use
	 * drm_gem_fb_simple_display_pipe_prepare_fb() for this hook.
	 */
	int (*prepare_fb)(struct drm_simple_display_pipe *pipe,
			  struct drm_plane_state *plane_state);

	/**
	 * @cleanup_fb:
	 *
	 * Optional, called by &drm_plane_helper_funcs.cleanup_fb.  Please read
	 * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for
	 * more details.
	 */
	void (*cleanup_fb)(struct drm_simple_display_pipe *pipe,
			   struct drm_plane_state *plane_state);

	/**
	 * @enable_vblank:
	 *
	 * Optional, called by &drm_crtc_funcs.enable_vblank. Please read
	 * the documentation for the &drm_crtc_funcs.enable_vblank hook for
	 * more details.
	 */
	int (*enable_vblank)(struct drm_simple_display_pipe *pipe);

	/**
	 * @disable_vblank:
	 *
	 * Optional, called by &drm_crtc_funcs.disable_vblank. Please read
	 * the documentation for the &drm_crtc_funcs.disable_vblank hook for
	 * more details.
	 */
	void (*disable_vblank)(struct drm_simple_display_pipe *pipe);
};

/**
 * struct drm_simple_display_pipe - simple display pipeline
 * @crtc: CRTC control structure
 * @plane: Plane control structure
 * @encoder: Encoder control structure
 * @connector: Connector control structure
 * @funcs: Pipeline control functions (optional)
 *
 * Simple display pipeline with plane, crtc and encoder collapsed into one
 * entity. It should be initialized by calling drm_simple_display_pipe_init().
 */
struct drm_simple_display_pipe {
	struct drm_crtc crtc;
	struct drm_plane plane;
	struct drm_encoder encoder;
	struct drm_connector *connector;

	const struct drm_simple_display_pipe_funcs *funcs;
};

int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe,
					  struct drm_bridge *bridge);

int drm_simple_display_pipe_init(struct drm_device *dev,
			struct drm_simple_display_pipe *pipe,
			const struct drm_simple_display_pipe_funcs *funcs,
			const uint32_t *formats, unsigned int format_count,
			const uint64_t *format_modifiers,
			struct drm_connector *connector);

#endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */
Commit	Line	Data
5b809074 NT	1	/*
	2	* Copyright (C) 2016 Noralf Trønnes
	3	*
	4	* This program is free software; you can redistribute it and/or modify
	5	* it under the terms of the GNU General Public License as published by
	6	* the Free Software Foundation; either version 2 of the License, or
	7	* (at your option) any later version.
	8	*/
	9
	10	#ifndef __LINUX_DRM_SIMPLE_KMS_HELPER_H
	11	#define __LINUX_DRM_SIMPLE_KMS_HELPER_H
	12
a6a9534c NT	13	#include <drm/drm_crtc.h>
	14	#include <drm/drm_encoder.h>
	15	#include <drm/drm_plane.h>
	16
5b809074 NT	17	struct drm_simple_display_pipe;
	18
	19	/**
	20	* struct drm_simple_display_pipe_funcs - helper operations for a simple
	21	* display pipeline
	22	*/
	23	struct drm_simple_display_pipe_funcs {
40275dc4 LW	24	/**
	25	* @mode_valid:
	26	*
afe09e43 LW	27	* This callback is used to check if a specific mode is valid in the
	28	* crtc used in this simple display pipe. This should be implemented
	29	* if the display pipe has some sort of restriction in the modes
	30	* it can display. For example, a given display pipe may be responsible
	31	* to set a clock value. If the clock can not produce all the values
	32	* for the available modes then this callback can be used to restrict
	33	* the number of modes to only the ones that can be displayed. Another
	34	* reason can be bandwidth mitigation: the memory port on the display
	35	* controller can have bandwidth limitations not allowing pixel data
	36	* to be fetched at any rate.
	37	*
	38	* This hook is used by the probe helpers to filter the mode list in
	39	* drm_helper_probe_single_connector_modes(), and it is used by the
	40	* atomic helpers to validate modes supplied by userspace in
	41	* drm_atomic_helper_check_modeset().
	42	*
	43	* This function is optional.
	44	*
	45	* NOTE:
	46	*
	47	* Since this function is both called from the check phase of an atomic
	48	* commit, and the mode validation in the probe paths it is not allowed
	49	* to look at anything else but the passed-in mode, and validate it
	50	* against configuration-invariant hardware constraints.
40275dc4 LW	51	*
	52	* RETURNS:
	53	*
	54	* drm_mode_status Enum
	55	*/
	56	enum drm_mode_status (mode_valid)(struct drm_crtc crtc,
	57	const struct drm_display_mode *mode);
	58
5b809074 NT	59	/**
	60	* @enable:
	61	*
	62	* This function should be used to enable the pipeline.
	63	* It is called when the underlying crtc is enabled.
	64	* This hook is optional.
	65	*/
	66	void (enable)(struct drm_simple_display_pipe pipe,
0c9c7fd0 VS	67	struct drm_crtc_state *crtc_state,
0c9c7fd0 VS	68	struct drm_plane_state *plane_state);
5b809074 NT	69	/**
	70	* @disable:
	71	*
	72	* This function should be used to disable the pipeline.
	73	* It is called when the underlying crtc is disabled.
	74	* This hook is optional.
	75	*/
	76	void (disable)(struct drm_simple_display_pipe pipe);
	77
	78	/**
	79	* @check:
	80	*
	81	* This function is called in the check phase of an atomic update,
	82	* specifically when the underlying plane is checked.
	83	* The simple display pipeline helpers already check that the plane is
	84	* not scaled, fills the entire visible area and is always enabled
	85	* when the crtc is also enabled.
	86	* This hook is optional.
	87	*
	88	* RETURNS:
	89	*
	90	* 0 on success, -EINVAL if the state or the transition can't be
	91	* supported, -ENOMEM on memory allocation failure and -EDEADLK if an
	92	* attempt to obtain another state object ran into a &drm_modeset_lock
	93	* deadlock.
	94	*/
	95	int (check)(struct drm_simple_display_pipe pipe,
	96	struct drm_plane_state *plane_state,
	97	struct drm_crtc_state *crtc_state);
	98	/**
	99	* @update:
	100	*
	101	* This function is called when the underlying plane state is updated.
	102	* This hook is optional.
6dcf0de7 DV	103	*
	104	* This is the function drivers should submit the
	105	* &drm_pending_vblank_event from. Using either
	106	* drm_crtc_arm_vblank_event(), when the driver supports vblank
	107	* interrupt handling, or drm_crtc_send_vblank_event() directly in case
	108	* the hardware lacks vblank support entirely.
5b809074 NT	109	*/
5b809074 NT	110	void (update)(struct drm_simple_display_pipe pipe,
bcd2ba02	111	struct drm_plane_state *old_plane_state);
7d83a155 MV	112
	113	/**
	114	* @prepare_fb:
	115	*
6806cdf9 DV	116	* Optional, called by &drm_plane_helper_funcs.prepare_fb. Please read
	117	* the documentation for the &drm_plane_helper_funcs.prepare_fb hook for
	118	* more details.
ccc3b2b3 DV	119	*
	120	* Drivers which always have their buffers pinned should use
	121	* drm_gem_fb_simple_display_pipe_prepare_fb() for this hook.
7d83a155 MV	122	*/
	123	int (prepare_fb)(struct drm_simple_display_pipe pipe,
	124	struct drm_plane_state *plane_state);
	125
	126	/**
	127	* @cleanup_fb:
	128	*
6806cdf9 DV	129	* Optional, called by &drm_plane_helper_funcs.cleanup_fb. Please read
	130	* the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for
	131	* more details.
7d83a155 MV	132	*/
	133	void (cleanup_fb)(struct drm_simple_display_pipe pipe,
	134	struct drm_plane_state *plane_state);
ac86cba9 OA	135
	136	/**
	137	* @enable_vblank:
	138	*
	139	* Optional, called by &drm_crtc_funcs.enable_vblank. Please read
	140	* the documentation for the &drm_crtc_funcs.enable_vblank hook for
	141	* more details.
	142	*/
	143	int (enable_vblank)(struct drm_simple_display_pipe pipe);
	144
	145	/**
	146	* @disable_vblank:
	147	*
	148	* Optional, called by &drm_crtc_funcs.disable_vblank. Please read
	149	* the documentation for the &drm_crtc_funcs.disable_vblank hook for
	150	* more details.
	151	*/
	152	void (disable_vblank)(struct drm_simple_display_pipe pipe);
5b809074 NT	153	};
	154
	155	/**
	156	* struct drm_simple_display_pipe - simple display pipeline
	157	* @crtc: CRTC control structure
	158	* @plane: Plane control structure
	159	* @encoder: Encoder control structure
	160	* @connector: Connector control structure
	161	* @funcs: Pipeline control functions (optional)
	162	*
	163	* Simple display pipeline with plane, crtc and encoder collapsed into one
	164	* entity. It should be initialized by calling drm_simple_display_pipe_init().
	165	*/
	166	struct drm_simple_display_pipe {
	167	struct drm_crtc crtc;
	168	struct drm_plane plane;
	169	struct drm_encoder encoder;
	170	struct drm_connector *connector;
	171
	172	const struct drm_simple_display_pipe_funcs *funcs;
	173	};
	174
315486c6 AM	175	int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe,
	176	struct drm_bridge *bridge);
	177
5b809074 NT	178	int drm_simple_display_pipe_init(struct drm_device *dev,
	179	struct drm_simple_display_pipe *pipe,
	180	const struct drm_simple_display_pipe_funcs *funcs,
	181	const uint32_t *formats, unsigned int format_count,
e6fc3b68	182	const uint64_t *format_modifiers,
5b809074 NT	183	struct drm_connector *connector);
	184
	185	#endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */