1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3 * Copyright (C) 2012-2016 Mentor Graphics Inc.
4 *
5 * i.MX Queued image conversion support, with tiling and rotation.
6 */
7 #ifndef __IMX_IPU_IMAGE_CONVERT_H__
8 #define __IMX_IPU_IMAGE_CONVERT_H__
9
10 #include <video/imx-ipu-v3.h>
11
12 struct ipu_image_convert_ctx;
13
14 /**
15 * struct ipu_image_convert_run - image conversion run request struct
16 *
17 * @ctx: the conversion context
18 * @in_phys: dma addr of input image buffer for this run
19 * @out_phys: dma addr of output image buffer for this run
20 * @status: completion status of this run
21 */
22 struct ipu_image_convert_run {
23 struct ipu_image_convert_ctx *ctx;
24
25 dma_addr_t in_phys;
26 dma_addr_t out_phys;
27
28 int status;
29
30 /* internal to image converter, callers don't touch */
31 struct list_head list;
32 };
33
34 /**
35 * ipu_image_convert_cb_t - conversion callback function prototype
36 *
37 * @run: the completed conversion run pointer
38 * @ctx: a private context pointer for the callback
39 */
40 typedef void (*ipu_image_convert_cb_t)(struct ipu_image_convert_run *run,
41 void *ctx);
42
43 /**
44 * ipu_image_convert_enum_format() - enumerate the image converter's
45 * supported input and output pixel formats.
46 *
47 * @index: pixel format index
48 * @fourcc: v4l2 fourcc for this index
49 *
50 * Returns 0 with a valid index and fills in v4l2 fourcc, -EINVAL otherwise.
51 *
52 * In V4L2, drivers can call ipu_image_enum_format() in .enum_fmt.
53 */
54 int ipu_image_convert_enum_format(int index, u32 *fourcc);
55
56 /**
57 * ipu_image_convert_adjust() - adjust input/output images to IPU restrictions.
58 *
59 * @in: input image format, adjusted on return
60 * @out: output image format, adjusted on return
61 * @rot_mode: rotation mode
62 *
63 * In V4L2, drivers can call ipu_image_convert_adjust() in .try_fmt.
64 */
65 void ipu_image_convert_adjust(struct ipu_image *in, struct ipu_image *out,
66 enum ipu_rotate_mode rot_mode);
67
68 /**
69 * ipu_image_convert_verify() - verify that input/output image formats
70 * and rotation mode meet IPU restrictions.
71 *
72 * @in: input image format
73 * @out: output image format
74 * @rot_mode: rotation mode
75 *
76 * Returns 0 if the formats and rotation mode meet IPU restrictions,
77 * -EINVAL otherwise.
78 */
79 int ipu_image_convert_verify(struct ipu_image *in, struct ipu_image *out,
80 enum ipu_rotate_mode rot_mode);
81
82 /**
83 * ipu_image_convert_prepare() - prepare a conversion context.
84 *
85 * @ipu: the IPU handle to use for the conversions
86 * @ic_task: the IC task to use for the conversions
87 * @in: input image format
88 * @out: output image format
89 * @rot_mode: rotation mode
90 * @complete: run completion callback
91 * @complete_context: a context pointer for the completion callback
92 *
93 * Returns an opaque conversion context pointer on success, error pointer
94 * on failure. The input/output formats and rotation mode must already meet
95 * IPU retrictions.
96 *
97 * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.
98 */
99 struct ipu_image_convert_ctx *
100 ipu_image_convert_prepare(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
101 struct ipu_image *in, struct ipu_image *out,
102 enum ipu_rotate_mode rot_mode,
103 ipu_image_convert_cb_t complete,
104 void *complete_context);
105
106 /**
107 * ipu_image_convert_unprepare() - unprepare a conversion context.
108 *
109 * @ctx: the conversion context pointer to unprepare
110 *
111 * Aborts any active or pending conversions for this context and
112 * frees the context. Any currently active or pending runs belonging
113 * to this context are returned via the completion callback with an
114 * error run status.
115 *
116 * In V4L2, drivers should call ipu_image_convert_unprepare() at
117 * streamoff.
118 */
119 void ipu_image_convert_unprepare(struct ipu_image_convert_ctx *ctx);
120
121 /**
122 * ipu_image_convert_queue() - queue a conversion run
123 *
124 * @run: the run request pointer
125 *
126 * ipu_image_convert_run must be dynamically allocated (_not_ as a local
127 * var) by callers and filled in with a previously prepared conversion
128 * context handle and the dma addr's of the input and output image buffers
129 * for this conversion run.
130 *
131 * When this conversion completes, the run pointer is returned via the
132 * completion callback. The caller is responsible for freeing the run
133 * object after it completes.
134 *
135 * In V4L2, drivers should call ipu_image_convert_queue() while
136 * streaming to queue the conversion of a received input buffer.
137 * For example mem2mem devices this would be called in .device_run.
138 */
139 int ipu_image_convert_queue(struct ipu_image_convert_run *run);
140
141 /**
142 * ipu_image_convert_abort() - abort conversions
143 *
144 * @ctx: the conversion context pointer
145 *
146 * This will abort any active or pending conversions for this context.
147 * Any currently active or pending runs belonging to this context are
148 * returned via the completion callback with an error run status.
149 */
150 void ipu_image_convert_abort(struct ipu_image_convert_ctx *ctx);
151
152 /**
153 * ipu_image_convert() - asynchronous image conversion request
154 *
155 * @ipu: the IPU handle to use for the conversion
156 * @ic_task: the IC task to use for the conversion
157 * @in: input image format
158 * @out: output image format
159 * @rot_mode: rotation mode
160 * @complete: run completion callback
161 * @complete_context: a context pointer for the completion callback
162 *
163 * Request a single image conversion. Returns the run that has been queued.
164 * A conversion context is automatically created and is available in run->ctx.
165 * As with ipu_image_convert_prepare(), the input/output formats and rotation
166 * mode must already meet IPU retrictions.
167 *
168 * On successful return the caller can queue more run requests if needed, using
169 * the prepared context in run->ctx. The caller is responsible for unpreparing
170 * the context when no more conversion requests are needed.
171 */
172 struct ipu_image_convert_run *
173 ipu_image_convert(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
174 struct ipu_image *in, struct ipu_image *out,
175 enum ipu_rotate_mode rot_mode,
176 ipu_image_convert_cb_t complete,
177 void *complete_context);
178
179 /**
180 * ipu_image_convert_sync() - synchronous single image conversion request
181 *
182 * @ipu: the IPU handle to use for the conversion
183 * @ic_task: the IC task to use for the conversion
184 * @in: input image format
185 * @out: output image format
186 * @rot_mode: rotation mode
187 *
188 * Carry out a single image conversion. Returns when the conversion
189 * completes. The input/output formats and rotation mode must already
190 * meet IPU retrictions. The created context is automatically unprepared
191 * and the run freed on return.
192 */
193 int ipu_image_convert_sync(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
194 struct ipu_image *in, struct ipu_image *out,
195 enum ipu_rotate_mode rot_mode);
196
197
198 #endif /* __IMX_IPU_IMAGE_CONVERT_H__ */