1/* SPDX-License-Identifier: GPL-2.0-or-later */
  2/*
  3 * Copyright (C) 2017 Icenowy Zheng <icenowy@aosc.io>
  4 */
  5
  6#ifndef _SUNXI_ENGINE_H_
  7#define _SUNXI_ENGINE_H_
  8
  9struct drm_plane;
 10struct drm_crtc;
 11struct drm_device;
 12struct drm_crtc_state;
 13struct drm_display_mode;
 14
 15struct sunxi_engine;
 16
 17/**
 18 * struct sunxi_engine_ops - helper operations for sunXi engines
 19 *
 20 * These hooks are used by the common part of the DRM driver to
 21 * implement the proper behaviour.
 22 */
 23struct sunxi_engine_ops {
 24	/**
 25	 * @atomic_begin:
 26	 *
 27	 * This callback allows to prepare our engine for an atomic
 28	 * update. This is mirroring the
 29	 * &drm_crtc_helper_funcs.atomic_begin callback, so any
 30	 * documentation there applies.
 31	 *
 32	 * This function is optional.
 33	 */
 34	void (*atomic_begin)(struct sunxi_engine *engine,
 35			     struct drm_crtc_state *old_state);
 36
 37	/**
 38	 * @atomic_check:
 39	 *
 40	 * This callback allows to validate plane-update related CRTC
 41	 * constraints specific to engines. This is mirroring the
 42	 * &drm_crtc_helper_funcs.atomic_check callback, so any
 43	 * documentation there applies.
 44	 *
 45	 * This function is optional.
 46	 *
 47	 * RETURNS:
 48	 *
 49	 * 0 on success or a negative error code.
 50	 */
 51	int (*atomic_check)(struct sunxi_engine *engine,
 52			    struct drm_crtc_state *state);
 53
 54	/**
 55	 * @commit:
 56	 *
 57	 * This callback will trigger the hardware switch to commit
 58	 * the new configuration that has been setup during the next
 59	 * vblank period.
 60	 *
 61	 * This function is optional.
 62	 */
 63	void (*commit)(struct sunxi_engine *engine,
 64		       struct drm_crtc *crtc,
 65		       struct drm_atomic_state *state);
 66
 67	/**
 68	 * @layers_init:
 69	 *
 70	 * This callback is used to allocate, initialize and register
 71	 * the layers supported by that engine.
 72	 *
 73	 * This function is mandatory.
 74	 *
 75	 * RETURNS:
 76	 *
 77	 * The array of struct drm_plane backing the layers, or an
 78	 * error pointer on failure.
 79	 */
 80	struct drm_plane **(*layers_init)(struct drm_device *drm,
 81					  struct sunxi_engine *engine);
 82
 83	/**
 84	 * @apply_color_correction:
 85	 *
 86	 * This callback will enable the color correction in the
 87	 * engine. This is useful only for the composite output.
 88	 *
 89	 * This function is optional.
 90	 */
 91	void (*apply_color_correction)(struct sunxi_engine *engine);
 92
 93	/**
 94	 * @disable_color_correction:
 95	 *
 96	 * This callback will stop the color correction in the
 97	 * engine. This is useful only for the composite output.
 98	 *
 99	 * This function is optional.
100	 */
101	void (*disable_color_correction)(struct sunxi_engine *engine);
102
103	/**
104	 * @vblank_quirk:
105	 *
106	 * This callback is used to implement engine-specific
107	 * behaviour part of the VBLANK event. It is run with all the
108	 * constraints of an interrupt (can't sleep, all local
109	 * interrupts disabled) and therefore should be as fast as
110	 * possible.
111	 *
112	 * This function is optional.
113	 */
114	void (*vblank_quirk)(struct sunxi_engine *engine);
115
116	/**
117	 * @mode_set
118	 *
119	 * This callback is used to set mode related parameters
120	 * like interlacing, screen size, etc. once per mode set.
121	 *
122	 * This function is optional.
123	 */
124	void (*mode_set)(struct sunxi_engine *engine,
125			 const struct drm_display_mode *mode);
126};
127
128/**
129 * struct sunxi_engine - the common parts of an engine for sun4i-drm driver
130 * @ops:	the operations of the engine
131 * @node:	the of device node of the engine
132 * @regs:	the regmap of the engine
133 * @id:		the id of the engine (-1 if not used)
134 */
135struct sunxi_engine {
136	const struct sunxi_engine_ops	*ops;
137
138	struct device_node		*node;
139	struct regmap			*regs;
140
141	int id;
142
143	/* Engine list management */
144	struct list_head		list;
145};
146
147/**
148 * sunxi_engine_commit() - commit all changes of the engine
149 * @engine:	pointer to the engine
150 * @crtc:	pointer to crtc the engine is associated with
151 * @state:	atomic state
152 */
153static inline void
154sunxi_engine_commit(struct sunxi_engine *engine,
155		    struct drm_crtc *crtc,
156		    struct drm_atomic_state *state)
157{
158	if (engine->ops && engine->ops->commit)
159		engine->ops->commit(engine, crtc, state);
160}
161
162/**
163 * sunxi_engine_layers_init() - Create planes (layers) for the engine
164 * @drm:	pointer to the drm_device for which planes will be created
165 * @engine:	pointer to the engine
166 */
167static inline struct drm_plane **
168sunxi_engine_layers_init(struct drm_device *drm, struct sunxi_engine *engine)
169{
170	if (engine->ops && engine->ops->layers_init)
171		return engine->ops->layers_init(drm, engine);
172	return ERR_PTR(-ENOSYS);
173}
174
175/**
176 * sunxi_engine_apply_color_correction - Apply the RGB2YUV color correction
177 * @engine:	pointer to the engine
178 *
179 * This functionality is optional for an engine, however, if the engine is
180 * intended to be used with TV Encoder, the output will be incorrect
181 * without the color correction, due to TV Encoder expects the engine to
182 * output directly YUV signal.
183 */
184static inline void
185sunxi_engine_apply_color_correction(struct sunxi_engine *engine)
186{
187	if (engine->ops && engine->ops->apply_color_correction)
188		engine->ops->apply_color_correction(engine);
189}
190
191/**
192 * sunxi_engine_disable_color_correction - Disable the color space correction
193 * @engine:	pointer to the engine
194 *
195 * This function is paired with apply_color_correction().
196 */
197static inline void
198sunxi_engine_disable_color_correction(struct sunxi_engine *engine)
199{
200	if (engine->ops && engine->ops->disable_color_correction)
201		engine->ops->disable_color_correction(engine);
202}
203
204/**
205 * sunxi_engine_mode_set - Inform engine of a new mode
206 * @engine:	pointer to the engine
207 * @mode:	new mode
208 *
209 * Engine can use this functionality to set specifics once per mode change.
210 */
211static inline void
212sunxi_engine_mode_set(struct sunxi_engine *engine,
213		      const struct drm_display_mode *mode)
214{
215	if (engine->ops && engine->ops->mode_set)
216		engine->ops->mode_set(engine, mode);
217}
218#endif /* _SUNXI_ENGINE_H_ */