[mirror_ubuntu-jammy-kernel.git] / drivers / gpu / drm / sun4i / sunxi_engine.h

/* SPDX-License-Identifier: GPL-2.0-or-later */
/*
 * Copyright (C) 2017 Icenowy Zheng <icenowy@aosc.io>
 */

#ifndef _SUNXI_ENGINE_H_
#define _SUNXI_ENGINE_H_

struct drm_plane;
struct drm_device;
struct drm_crtc_state;

struct sunxi_engine;

/**
 * struct sunxi_engine_ops - helper operations for sunXi engines
 *
 * These hooks are used by the common part of the DRM driver to
 * implement the proper behaviour.
 */
struct sunxi_engine_ops {
	/**
	 * @atomic_begin:
	 *
	 * This callback allows to prepare our engine for an atomic
	 * update. This is mirroring the
	 * &drm_crtc_helper_funcs.atomic_begin callback, so any
	 * documentation there applies.
	 *
	 * This function is optional.
	 */
	void (*atomic_begin)(struct sunxi_engine *engine,
			     struct drm_crtc_state *old_state);

	/**
	 * @atomic_check:
	 *
	 * This callback allows to validate plane-update related CRTC
	 * constraints specific to engines. This is mirroring the
	 * &drm_crtc_helper_funcs.atomic_check callback, so any
	 * documentation there applies.
	 *
	 * This function is optional.
	 *
	 * RETURNS:
	 *
	 * 0 on success or a negative error code.
	 */
	int (*atomic_check)(struct sunxi_engine *engine,
			    struct drm_crtc_state *state);

	/**
	 * @commit:
	 *
	 * This callback will trigger the hardware switch to commit
	 * the new configuration that has been setup during the next
	 * vblank period.
	 *
	 * This function is optional.
	 */
	void (*commit)(struct sunxi_engine *engine);

	/**
	 * @layers_init:
	 *
	 * This callback is used to allocate, initialize and register
	 * the layers supported by that engine.
	 *
	 * This function is mandatory.
	 *
	 * RETURNS:
	 *
	 * The array of struct drm_plane backing the layers, or an
	 * error pointer on failure.
	 */
	struct drm_plane **(*layers_init)(struct drm_device *drm,
					  struct sunxi_engine *engine);

	/**
	 * @apply_color_correction:
	 *
	 * This callback will enable the color correction in the
	 * engine. This is useful only for the composite output.
	 *
	 * This function is optional.
	 */
	void (*apply_color_correction)(struct sunxi_engine *engine);

	/**
	 * @disable_color_correction:
	 *
	 * This callback will stop the color correction in the
	 * engine. This is useful only for the composite output.
	 *
	 * This function is optional.
	 */
	void (*disable_color_correction)(struct sunxi_engine *engine);

	/**
	 * @vblank_quirk:
	 *
	 * This callback is used to implement engine-specific
	 * behaviour part of the VBLANK event. It is run with all the
	 * constraints of an interrupt (can't sleep, all local
	 * interrupts disabled) and therefore should be as fast as
	 * possible.
	 *
	 * This function is optional.
	 */
	void (*vblank_quirk)(struct sunxi_engine *engine);
};

/**
 * struct sunxi_engine - the common parts of an engine for sun4i-drm driver
 * @ops:	the operations of the engine
 * @node:	the of device node of the engine
 * @regs:	the regmap of the engine
 * @id:		the id of the engine (-1 if not used)
 */
struct sunxi_engine {
	const struct sunxi_engine_ops	*ops;

	struct device_node		*node;
	struct regmap			*regs;

	int id;

	/* Engine list management */
	struct list_head		list;
};

/**
 * sunxi_engine_commit() - commit all changes of the engine
 * @engine:	pointer to the engine
 */
static inline void
sunxi_engine_commit(struct sunxi_engine *engine)
{
	if (engine->ops && engine->ops->commit)
		engine->ops->commit(engine);
}

/**
 * sunxi_engine_layers_init() - Create planes (layers) for the engine
 * @drm:	pointer to the drm_device for which planes will be created
 * @engine:	pointer to the engine
 */
static inline struct drm_plane **
sunxi_engine_layers_init(struct drm_device *drm, struct sunxi_engine *engine)
{
	if (engine->ops && engine->ops->layers_init)
		return engine->ops->layers_init(drm, engine);
	return ERR_PTR(-ENOSYS);
}

/**
 * sunxi_engine_apply_color_correction - Apply the RGB2YUV color correction
 * @engine:	pointer to the engine
 *
 * This functionality is optional for an engine, however, if the engine is
 * intended to be used with TV Encoder, the output will be incorrect
 * without the color correction, due to TV Encoder expects the engine to
 * output directly YUV signal.
 */
static inline void
sunxi_engine_apply_color_correction(struct sunxi_engine *engine)
{
	if (engine->ops && engine->ops->apply_color_correction)
		engine->ops->apply_color_correction(engine);
}

/**
 * sunxi_engine_disable_color_correction - Disable the color space correction
 * @engine:	pointer to the engine
 *
 * This function is paired with apply_color_correction().
 */
static inline void
sunxi_engine_disable_color_correction(struct sunxi_engine *engine)
{
	if (engine->ops && engine->ops->disable_color_correction)
		engine->ops->disable_color_correction(engine);
}
#endif /* _SUNXI_ENGINE_H_ */
Commit	Line	Data
2874c5fd	1	/* SPDX-License-Identifier: GPL-2.0-or-later */
87969338 IZ	2	/*
87969338 IZ	3	* Copyright (C) 2017 Icenowy Zheng <icenowy@aosc.io>
87969338 IZ	4	*/
	5
	6	#ifndef _SUNXI_ENGINE_H_
	7	#define _SUNXI_ENGINE_H_
	8
	9	struct drm_plane;
	10	struct drm_device;
a63b8e79	11	struct drm_crtc_state;
87969338 IZ	12
	13	struct sunxi_engine;
	14
c4c7c72e MR	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	*/
87969338	21	struct sunxi_engine_ops {
6b8562c8 MR	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
656e5f65 MR	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
c4c7c72e MR	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	*/
87969338	61	void (commit)(struct sunxi_engine engine);
c4c7c72e MR	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	*/
87969338 IZ	76	struct drm_plane *(layers_init)(struct drm_device *drm,
	77	struct sunxi_engine *engine);
	78
c4c7c72e MR	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	*/
87969338	87	void (apply_color_correction)(struct sunxi_engine engine);
c4c7c72e MR	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	*/
87969338	97	void (disable_color_correction)(struct sunxi_engine engine);
3004f75f MR	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);
87969338 IZ	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_ */