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