imx-ipu-image-convert.h

  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
 12struct 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 */
 22struct 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 */
 40typedef void (*ipu_image_convert_cb_t)(struct ipu_image_convert_run *run,
 41				       void *ctx);
 42
 43/**
 44 * ipu_image_convert_adjust() - adjust input/output images to IPU restrictions.
 45 *
 46 * @in:		input image format, adjusted on return
 47 * @out:	output image format, adjusted on return
 48 * @rot_mode:	rotation mode
 49 *
 50 * In V4L2, drivers can call ipu_image_convert_adjust() in .try_fmt.
 51 */
 52void ipu_image_convert_adjust(struct ipu_image *in, struct ipu_image *out,
 53			      enum ipu_rotate_mode rot_mode);
 54
 55/**
 56 * ipu_image_convert_verify() - verify that input/output image formats
 57 *         and rotation mode meet IPU restrictions.
 58 *
 59 * @in:		input image format
 60 * @out:	output image format
 61 * @rot_mode:	rotation mode
 62 *
 63 * Returns 0 if the formats and rotation mode meet IPU restrictions,
 64 * -EINVAL otherwise.
 65 */
 66int ipu_image_convert_verify(struct ipu_image *in, struct ipu_image *out,
 67			     enum ipu_rotate_mode rot_mode);
 68
 69/**
 70 * ipu_image_convert_prepare() - prepare a conversion context.
 71 *
 72 * @ipu:	the IPU handle to use for the conversions
 73 * @ic_task:	the IC task to use for the conversions
 74 * @in:		input image format
 75 * @out:	output image format
 76 * @rot_mode:	rotation mode
 77 * @complete:	run completion callback
 78 * @complete_context:	a context pointer for the completion callback
 79 *
 80 * Returns an opaque conversion context pointer on success, error pointer
 81 * on failure. The input/output formats and rotation mode must already meet
 82 * IPU retrictions.
 83 *
 84 * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.
 85 */
 86struct ipu_image_convert_ctx *
 87ipu_image_convert_prepare(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
 88			  struct ipu_image *in, struct ipu_image *out,
 89			  enum ipu_rotate_mode rot_mode,
 90			  ipu_image_convert_cb_t complete,
 91			  void *complete_context);
 92
 93/**
 94 * ipu_image_convert_unprepare() - unprepare a conversion context.
 95 *
 96 * @ctx: the conversion context pointer to unprepare
 97 *
 98 * Aborts any active or pending conversions for this context and
 99 * frees the context. Any currently active or pending runs belonging
100 * to this context are returned via the completion callback with an
101 * error run status.
102 *
103 * In V4L2, drivers should call ipu_image_convert_unprepare() at
104 * streamoff.
105 */
106void ipu_image_convert_unprepare(struct ipu_image_convert_ctx *ctx);
107
108/**
109 * ipu_image_convert_queue() - queue a conversion run
110 *
111 * @run: the run request pointer
112 *
113 * ipu_image_convert_run must be dynamically allocated (_not_ as a local
114 * var) by callers and filled in with a previously prepared conversion
115 * context handle and the dma addr's of the input and output image buffers
116 * for this conversion run.
117 *
118 * When this conversion completes, the run pointer is returned via the
119 * completion callback. The caller is responsible for freeing the run
120 * object after it completes.
121 *
122 * In V4L2, drivers should call ipu_image_convert_queue() while
123 * streaming to queue the conversion of a received input buffer.
124 * For example mem2mem devices this would be called in .device_run.
125 */
126int ipu_image_convert_queue(struct ipu_image_convert_run *run);
127
128/**
129 * ipu_image_convert_abort() - abort conversions
130 *
131 * @ctx: the conversion context pointer
132 *
133 * This will abort any active or pending conversions for this context.
134 * Any currently active or pending runs belonging to this context are
135 * returned via the completion callback with an error run status.
136 */
137void ipu_image_convert_abort(struct ipu_image_convert_ctx *ctx);
138
139/**
140 * ipu_image_convert() - asynchronous image conversion request
141 *
142 * @ipu:	the IPU handle to use for the conversion
143 * @ic_task:	the IC task to use for the conversion
144 * @in:		input image format
145 * @out:	output image format
146 * @rot_mode:	rotation mode
147 * @complete:	run completion callback
148 * @complete_context:	a context pointer for the completion callback
149 *
150 * Request a single image conversion. Returns the run that has been queued.
151 * A conversion context is automatically created and is available in run->ctx.
152 * As with ipu_image_convert_prepare(), the input/output formats and rotation
153 * mode must already meet IPU retrictions.
154 *
155 * On successful return the caller can queue more run requests if needed, using
156 * the prepared context in run->ctx. The caller is responsible for unpreparing
157 * the context when no more conversion requests are needed.
158 */
159struct ipu_image_convert_run *
160ipu_image_convert(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
161		  struct ipu_image *in, struct ipu_image *out,
162		  enum ipu_rotate_mode rot_mode,
163		  ipu_image_convert_cb_t complete,
164		  void *complete_context);
165
166#endif /* __IMX_IPU_IMAGE_CONVERT_H__ */