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 
9 struct drm_plane;
10 struct drm_device;
11 struct drm_crtc_state;
12 
13 struct 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  */
21 struct 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  */
120 struct 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  */
136 static inline void
137 sunxi_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  */
148 static inline struct drm_plane **
149 sunxi_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  */
165 static inline void
166 sunxi_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  */
178 static inline void
179 sunxi_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_ */
185