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