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