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 
21 struct 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  */
31 struct 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  */
49 typedef 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  */
63 int 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  */
74 void 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  */
88 int 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  */
108 struct ipu_image_convert_ctx *
109 ipu_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  */
128 void 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  */
148 int 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  */
159 void 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  */
181 struct ipu_image_convert_run *
182 ipu_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  */
202 int 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