1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Support for Intel Camera Imaging ISP subsystem.
4  * Copyright (c) 2015, Intel Corporation.
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms and conditions of the GNU General Public License,
8  * version 2, as published by the Free Software Foundation.
9  *
10  * This program is distributed in the hope it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
13  * more details.
14  */
15 
16 #ifndef __IA_CSS_PIPE_PUBLIC_H
17 #define __IA_CSS_PIPE_PUBLIC_H
18 
19 /* @file
20  * This file contains the public interface for CSS pipes.
21  */
22 
23 #include <type_support.h>
24 #include <ia_css_err.h>
25 #include <ia_css_types.h>
26 #include <ia_css_frame_public.h>
27 #include <ia_css_buffer.h>
28 /* ISP2401 */
29 #include <ia_css_acc_types.h>
30 
31 enum {
32 	IA_CSS_PIPE_OUTPUT_STAGE_0 = 0,
33 	IA_CSS_PIPE_OUTPUT_STAGE_1,
34 	IA_CSS_PIPE_MAX_OUTPUT_STAGE,
35 };
36 
37 /* Enumeration of pipe modes. This mode can be used to create
38  *  an image pipe for this mode. These pipes can be combined
39  *  to configure and run streams on the ISP.
40  *
41  *  For example, one can create a preview and capture pipe to
42  *  create a continuous capture stream.
43  */
44 enum ia_css_pipe_mode {
45 	IA_CSS_PIPE_MODE_PREVIEW,	/** Preview pipe */
46 	IA_CSS_PIPE_MODE_VIDEO,		/** Video pipe */
47 	IA_CSS_PIPE_MODE_CAPTURE,	/** Still capture pipe */
48 	IA_CSS_PIPE_MODE_ACC,		/** Accelerated pipe */
49 	IA_CSS_PIPE_MODE_COPY,		/** Copy pipe, only used for embedded/image data copying */
50 	IA_CSS_PIPE_MODE_YUVPP,		/** YUV post processing pipe, used for all use cases with YUV input,
51 									for SoC sensor and external ISP */
52 };
53 
54 /* Temporary define  */
55 #define IA_CSS_PIPE_MODE_NUM (IA_CSS_PIPE_MODE_YUVPP + 1)
56 
57 /**
58  * Enumeration of pipe versions.
59  * the order should match with definition in sh_css_defs.h
60  */
61 enum ia_css_pipe_version {
62 	IA_CSS_PIPE_VERSION_1 = 1,		/** ISP1.0 pipe */
63 	IA_CSS_PIPE_VERSION_2_2 = 2,		/** ISP2.2 pipe */
64 	IA_CSS_PIPE_VERSION_2_6_1 = 3,		/** ISP2.6.1 pipe */
65 	IA_CSS_PIPE_VERSION_2_7 = 4		/** ISP2.7 pipe */
66 };
67 
68 /**
69  * Pipe configuration structure.
70  * Resolution properties are filled by Driver, kernel configurations are
71  * set by AIC
72  */
73 struct ia_css_pipe_config {
74 	enum ia_css_pipe_mode mode;
75 	/** mode, indicates which mode the pipe should use. */
76 	enum ia_css_pipe_version isp_pipe_version;
77 	/** pipe version, indicates which imaging pipeline the pipe should use. */
78 	struct ia_css_resolution input_effective_res;
79 	/** input effective resolution */
80 	struct ia_css_resolution bayer_ds_out_res;
81 	/** bayer down scaling */
82 	struct ia_css_resolution capt_pp_in_res;
83 	/** capture post processing input resolution */
84 	struct ia_css_resolution vf_pp_in_res;
85 
86 	/** ISP2401: view finder post processing input resolution */
87 	struct ia_css_resolution output_system_in_res;
88 	/** For IPU3 only: use output_system_in_res to specify what input resolution
89 	     will OSYS receive, this resolution is equal to the output resolution of GDC
90 	     if not determined CSS will set output_system_in_res with main osys output pin resolution
91 	     All other IPUs may ignore this property */
92 	struct ia_css_resolution dvs_crop_out_res;
93 	/** dvs crop, video only, not in use yet. Use dvs_envelope below. */
94 	struct ia_css_frame_info output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE];
95 	/** output of YUV scaling */
96 	struct ia_css_frame_info vf_output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE];
97 	/** output of VF YUV scaling */
98 	struct ia_css_fw_info *acc_extension;
99 	/** Pipeline extension accelerator */
100 	struct ia_css_fw_info **acc_stages;
101 	/** Standalone accelerator stages */
102 	u32 num_acc_stages;
103 	/** Number of standalone accelerator stages */
104 	struct ia_css_capture_config default_capture_config;
105 	/** Default capture config for initial capture pipe configuration. */
106 	struct ia_css_resolution dvs_envelope; /** temporary */
107 	enum ia_css_frame_delay dvs_frame_delay;
108 	/** indicates the DVS loop delay in frame periods */
109 	int acc_num_execs;
110 	/** For acceleration pipes only: determine how many times the pipe
111 	     should be run. Setting this to -1 means it will run until
112 	     stopped. */
113 	bool enable_dz;
114 	/** Disabling digital zoom for a pipeline, if this is set to false,
115 	     then setting a zoom factor will have no effect.
116 	     In some use cases this provides better performance. */
117 	bool enable_dpc;
118 	/** Disabling "Defect Pixel Correction" for a pipeline, if this is set
119 	     to false. In some use cases this provides better performance. */
120 	bool enable_vfpp_bci;
121 	/** Enabling BCI mode will cause yuv_scale binary to be picked up
122 	     instead of vf_pp. This only applies to viewfinder post
123 	     processing stages. */
124 
125 /* ISP2401 */
126 	bool enable_tnr;
127 	/** Enabling of TNR (temporal noise reduction). This is only applicable to video
128 	     pipes. Non video-pipes should always set this parameter to false. */
129 
130 	struct ia_css_isp_config *p_isp_config;
131 	/** Pointer to ISP configuration */
132 	struct ia_css_resolution gdc_in_buffer_res;
133 	/** GDC in buffer resolution. */
134 	struct ia_css_point gdc_in_buffer_offset;
135 	/** GDC in buffer offset - indicates the pixel coordinates of the first valid pixel inside the buffer */
136 
137 /* ISP2401 */
138 	struct ia_css_coordinate internal_frame_origin_bqs_on_sctbl;
139 	/** Origin of internal frame positioned on shading table at shading correction in ISP.
140 	     NOTE: Shading table is larger than or equal to internal frame.
141 		   Shading table has shading gains and internal frame has bayer data.
142 		   The origin of internal frame is used in shading correction in ISP
143 		   to retrieve shading gains which correspond to bayer data. */
144 };
145 
146 /**
147  * Default settings for newly created pipe configurations.
148  */
149 #define DEFAULT_PIPE_CONFIG { \
150 	.mode			= IA_CSS_PIPE_MODE_PREVIEW, \
151 	.isp_pipe_version	= 1, \
152 	.output_info		= {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \
153 	.vf_output_info		= {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \
154 	.default_capture_config	= DEFAULT_CAPTURE_CONFIG, \
155 	.dvs_frame_delay	= IA_CSS_FRAME_DELAY_1, \
156 	.acc_num_execs		= -1, \
157 }
158 
159 /* Pipe info, this struct describes properties of a pipe after it's stream has
160  * been created.
161  * ~~~** DO NOT ADD NEW FIELD **~~~ This structure will be deprecated.
162  *           - On the Behalf of CSS-API Committee.
163  */
164 struct ia_css_pipe_info {
165 	struct ia_css_frame_info output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE];
166 	/** Info about output resolution. This contains the stride which
167 	     should be used for memory allocation. */
168 	struct ia_css_frame_info vf_output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE];
169 	/** Info about viewfinder output resolution (optional). This contains
170 	     the stride that should be used for memory allocation. */
171 	struct ia_css_frame_info raw_output_info;
172 	/** Raw output resolution. This indicates the resolution of the
173 	     RAW bayer output for pipes that support this. Currently, only the
174 	     still capture pipes support this feature. When this resolution is
175 	     smaller than the input resolution, cropping will be performed by
176 	     the ISP. The first cropping that will be performed is on the upper
177 	     left corner where we crop 8 lines and 8 columns to remove the
178 	     pixels normally used to initialize the ISP filters.
179 	     This is why the raw output resolution should normally be set to
180 	     the input resolution - 8x8. */
181 	/* ISP2401 */
182 	struct ia_css_resolution output_system_in_res_info;
183 	/** For IPU3 only. Info about output system in resolution which is considered
184 	     as gdc out resolution. */
185 	struct ia_css_shading_info shading_info;
186 	/** After an image pipe is created, this field will contain the info
187 	     for the shading correction. */
188 	struct ia_css_grid_info  grid_info;
189 	/** After an image pipe is created, this field will contain the grid
190 	     info for 3A and DVS. */
191 	int num_invalid_frames;
192 	/** The very first frames in a started stream do not contain valid data.
193 	     In this field, the CSS-firmware communicates to the host-driver how
194 	     many initial frames will contain invalid data; this allows the
195 	     host-driver to discard those initial invalid frames and start it's
196 	     output at the first valid frame. */
197 };
198 
199 /**
200  * Defaults for ia_css_pipe_info structs.
201  */
202 #define DEFAULT_PIPE_INFO {\
203 	.output_info		= {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \
204 	.vf_output_info		= {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \
205 	.raw_output_info	= IA_CSS_BINARY_DEFAULT_FRAME_INFO, \
206 	.shading_info		= DEFAULT_SHADING_INFO, \
207 	.grid_info		= DEFAULT_GRID_INFO, \
208 }
209 
210 /* @brief Load default pipe configuration
211  * @param[out]	pipe_config The pipe configuration.
212  * @return	None
213  *
214  * This function will load the default pipe configuration:
215 @code
216 	struct ia_css_pipe_config def_config = {
217 		IA_CSS_PIPE_MODE_PREVIEW,  // mode
218 		1,      // isp_pipe_version
219 		{0, 0}, // bayer_ds_out_res
220 		{0, 0}, // capt_pp_in_res
221 		{0, 0}, // vf_pp_in_res
222 		{0, 0}, // dvs_crop_out_res
223 		{{0, 0}, 0, 0, 0, 0}, // output_info
224 		{{0, 0}, 0, 0, 0, 0}, // second_output_info
225 		{{0, 0}, 0, 0, 0, 0}, // vf_output_info
226 		{{0, 0}, 0, 0, 0, 0}, // second_vf_output_info
227 		NULL,   // acc_extension
228 		NULL,   // acc_stages
229 		0,      // num_acc_stages
230 		{
231 			IA_CSS_CAPTURE_MODE_RAW, // mode
232 			false, // enable_xnr
233 			false  // enable_raw_output
234 		},      // default_capture_config
235 		{0, 0}, // dvs_envelope
236 		1,      // dvs_frame_delay
237 		-1,     // acc_num_execs
238 		true,   // enable_dz
239 		NULL,   // p_isp_config
240 	};
241 @endcode
242  */
243 void ia_css_pipe_config_defaults(struct ia_css_pipe_config *pipe_config);
244 
245 /* @brief Create a pipe
246  * @param[in]	config The pipe configuration.
247  * @param[out]	pipe The pipe.
248  * @return	0 or the error code.
249  *
250  * This function will create a pipe with the given
251  * configuration.
252  */
253 int
254 ia_css_pipe_create(const struct ia_css_pipe_config *config,
255 		   struct ia_css_pipe **pipe);
256 
257 /* @brief Destroy a pipe
258  * @param[in]	pipe The pipe.
259  * @return	0 or the error code.
260  *
261  * This function will destroy a given pipe.
262  */
263 int
264 ia_css_pipe_destroy(struct ia_css_pipe *pipe);
265 
266 /* @brief Provides information about a pipe
267  * @param[in]	pipe The pipe.
268  * @param[out]	pipe_info The pipe information.
269  * @return	0 or -EINVAL.
270  *
271  * This function will provide information about a given pipe.
272  */
273 int
274 ia_css_pipe_get_info(const struct ia_css_pipe *pipe,
275 		     struct ia_css_pipe_info *pipe_info);
276 
277 /* @brief Configure a pipe with filter coefficients.
278  * @param[in]	pipe	The pipe.
279  * @param[in]	config	The pointer to ISP configuration.
280  * @return		0 or error code upon error.
281  *
282  * This function configures the filter coefficients for an image
283  * pipe.
284  */
285 int
286 ia_css_pipe_set_isp_config(struct ia_css_pipe *pipe,
287 			   struct ia_css_isp_config *config);
288 
289 /* @brief Controls when the Event generator raises an IRQ to the Host.
290  *
291  * @param[in]	pipe	The pipe.
292  * @param[in]	or_mask	Binary or of enum ia_css_event_irq_mask_type. Each pipe
293 			related event that is part of this mask will directly
294 			raise an IRQ to	the Host when the event occurs in the
295 			CSS.
296  * @param[in]	and_mask Binary or of enum ia_css_event_irq_mask_type. An event
297 			IRQ for the Host is only raised after all pipe related
298 			events have occurred at least once for all the active
299 			pipes. Events are remembered and don't need to occurred
300 			at the same moment in time. There is no control over
301 			the order of these events. Once an IRQ has been raised
302 			all remembered events are reset.
303  * @return		0.
304  *
305  Controls when the Event generator in the CSS raises an IRQ to the Host.
306  The main purpose of this function is to reduce the amount of interrupts
307  between the CSS and the Host. This will help saving power as it wakes up the
308  Host less often. In case both or_mask and and_mask are
309  IA_CSS_EVENT_TYPE_NONE for all pipes, no event IRQ's will be raised. An
310  exception holds for IA_CSS_EVENT_TYPE_PORT_EOF, for this event an IRQ is always
311  raised.
312  Note that events are still queued and the Host can poll for them. The
313  or_mask and and_mask may be active at the same time\n
314  \n
315  Default values, for all pipe id's, after ia_css_init:\n
316  or_mask = IA_CSS_EVENT_TYPE_ALL\n
317  and_mask = IA_CSS_EVENT_TYPE_NONE\n
318  \n
319  Examples\n
320  \code
321  ia_css_pipe_set_irq_mask(h_pipe,
322  IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE |
323  IA_CSS_EVENT_TYPE_DIS_STATISTICS_DONE ,
324  IA_CSS_EVENT_TYPE_NONE);
325  \endcode
326  The event generator will only raise an interrupt to the Host when there are
327  3A or DIS statistics available from the preview pipe. It will not generate
328  an interrupt for any other event of the preview pipe e.g when there is an
329  output frame available.
330 
331  \code
332  ia_css_pipe_set_irq_mask(h_pipe_preview,
333 	IA_CSS_EVENT_TYPE_NONE,
334 	IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE |
335 	IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE );
336 
337  ia_css_pipe_set_irq_mask(h_pipe_capture,
338 	IA_CSS_EVENT_TYPE_NONE,
339 	IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE );
340  \endcode
341  The event generator will only raise an interrupt to the Host when there is
342  both a frame done and 3A event available from the preview pipe AND when there
343  is a frame done available from the capture pipe. Note that these events
344  may occur at different moments in time. Also the order of the events is not
345  relevant.
346 
347  \code
348  ia_css_pipe_set_irq_mask(h_pipe_preview,
349 	IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE,
350 	IA_CSS_EVENT_TYPE_ALL );
351 
352  ia_css_pipe_set_irq_mask(h_pipe_capture,
353 	IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE,
354 	IA_CSS_EVENT_TYPE_ALL );
355  \endcode
356  The event generator will only raise an interrupt to the Host when there is an
357  output frame from the preview pipe OR an output frame from the capture pipe.
358  All other events (3A, VF output, pipeline done) will not raise an interrupt
359  to the Host. These events are not lost but always stored in the event queue.
360  */
361 int
362 ia_css_pipe_set_irq_mask(struct ia_css_pipe *pipe,
363 			 unsigned int or_mask,
364 			 unsigned int and_mask);
365 
366 /* @brief Reads the current event IRQ mask from the CSS.
367  *
368  * @param[in]	pipe The pipe.
369  * @param[out]	or_mask	Current or_mask. The bits in this mask are a binary or
370 		of enum ia_css_event_irq_mask_type. Pointer may be NULL.
371  * @param[out]	and_mask Current and_mask.The bits in this mask are a binary or
372 		of enum ia_css_event_irq_mask_type. Pointer may be NULL.
373  * @return	0.
374  *
375  Reads the current event IRQ mask from the CSS. Reading returns the actual
376  values as used by the SP and not any mirrored values stored at the Host.\n
377 \n
378 Precondition:\n
379 SP must be running.\n
380 
381 */
382 int
383 ia_css_event_get_irq_mask(const struct ia_css_pipe *pipe,
384 			  unsigned int *or_mask,
385 			  unsigned int *and_mask);
386 
387 /* @brief Queue a buffer for an image pipe.
388  *
389  * @param[in] pipe	The pipe that will own the buffer.
390  * @param[in] buffer	Pointer to the buffer.
391  *			Note that the caller remains owner of the buffer
392  *			structure. Only the data pointer within it will
393  *			be passed into the internal queues.
394  * @return		IA_CSS_INTERNAL_ERROR in case of unexpected errors,
395  *			0 otherwise.
396  *
397  * This function adds a buffer (which has a certain buffer type) to the queue
398  * for this type. This queue is owned by the image pipe. After this function
399  * completes successfully, the buffer is now owned by the image pipe and should
400  * no longer be accessed by any other code until it gets dequeued. The image
401  * pipe will dequeue buffers from this queue, use them and return them to the
402  * host code via an interrupt. Buffers will be consumed in the same order they
403  * get queued, but may be returned to the host out of order.
404  */
405 int
406 ia_css_pipe_enqueue_buffer(struct ia_css_pipe *pipe,
407 			   const struct ia_css_buffer *buffer);
408 
409 /* @brief Dequeue a buffer from an image pipe.
410  *
411  * @param[in]    pipe	 The pipeline that the buffer queue belongs to.
412  * @param[in,out] buffer The buffer is used to lookup the type which determines
413  *			 which internal queue to use.
414  *			 The resulting buffer pointer is written into the dta
415  *			 field.
416  * @return		 IA_CSS_ERR_NO_BUFFER if the queue is empty or
417  *			 0 otherwise.
418  *
419  * This function dequeues a buffer from a buffer queue. The queue is indicated
420  * by the buffer type argument. This function can be called after an interrupt
421  * has been generated that signalled that a new buffer was available and can
422  * be used in a polling-like situation where the NO_BUFFER return value is used
423  * to determine whether a buffer was available or not.
424  */
425 int
426 ia_css_pipe_dequeue_buffer(struct ia_css_pipe *pipe,
427 			   struct ia_css_buffer *buffer);
428 
429 /* @brief  Set the state (Enable or Disable) of the Extension stage in the
430  *          given pipe.
431  * @param[in] pipe         Pipe handle.
432  * @param[in] fw_handle    Extension firmware Handle (ia_css_fw_info.handle)
433  * @param[in] enable       Enable Flag (1 to enable ; 0 to disable)
434  *
435  * @return
436  * 0			: Success
437  * -EINVAL		: Invalid Parameters
438  * -EBUSY	: Inactive QOS Pipe
439  *					(No active stream with this pipe)
440  *
441  * This function will request state change (enable or disable) for the Extension
442  * stage (firmware handle) in the given pipe.
443  *
444  * Note:
445  *	1. Extension can be enabled/disabled only on QOS Extensions
446  *	2. Extension can be enabled/disabled only with an active QOS Pipe
447  *	3. Initial(Default) state of QOS Extensions is Disabled
448  *	4. State change cannot be guaranteed immediately OR on frame boundary
449  *
450  */
451 int
452 ia_css_pipe_set_qos_ext_state(struct ia_css_pipe *pipe,
453 			      u32 fw_handle,
454 			      bool  enable);
455 
456 /* @brief  Get the state (Enable or Disable) of the Extension stage in the
457  *          given pipe.
458  * @param[in]  pipe        Pipe handle.
459  * @param[in]  fw_handle   Extension firmware Handle (ia_css_fw_info.handle)
460  * @param[out] *enable     Enable Flag
461  *
462  * @return
463  * 0			: Success
464  * -EINVAL		: Invalid Parameters
465  * -EBUSY	: Inactive QOS Pipe
466  *					(No active stream with this pipe)
467  *
468  * This function will query the state of the Extension stage (firmware handle)
469  * in the given Pipe.
470  *
471  * Note:
472  *	1. Extension state can be queried only on QOS Extensions
473  *	2. Extension can be enabled/disabled only with an active QOS Pipe
474  *	3. Initial(Default) state of QOS Extensions is Disabled.
475  *
476  */
477 int
478 ia_css_pipe_get_qos_ext_state(struct ia_css_pipe *pipe,
479 			      u32 fw_handle,
480 			      bool *enable);
481 
482 /* @brief Get selected configuration settings
483  * @param[in]	pipe	The pipe.
484  * @param[out]	config	Configuration settings.
485  * @return		None
486  */
487 void
488 ia_css_pipe_get_isp_config(struct ia_css_pipe *pipe,
489 			   struct ia_css_isp_config *config);
490 
491 /* @brief Set the scaler lut on this pipe. A copy of lut is made in the inuit
492  *         address space. So the LUT can be freed by caller.
493  * @param[in]  pipe        Pipe handle.
494  * @param[in]  lut         Look up tabel
495  *
496  * @return
497  * 0			: Success
498  * -EINVAL		: Invalid Parameters
499  *
500  * Note:
501  * 1) Note that both GDC's are programmed with the same table.
502  * 2) Current implementation ignores the pipe and overrides the
503  *    global lut. This will be fixed in the future
504  * 3) This function must be called before stream start
505  *
506  */
507 int
508 ia_css_pipe_set_bci_scaler_lut(struct ia_css_pipe *pipe,
509 			       const void *lut);
510 /* @brief Checking of DVS statistics ability
511  * @param[in]	pipe_info	The pipe info.
512  * @return		true - has DVS statistics ability
513  *			false - otherwise
514  */
515 bool ia_css_pipe_has_dvs_stats(struct ia_css_pipe_info *pipe_info);
516 
517 /* ISP2401 */
518 /* @brief Override the frameformat set on the output pins.
519  * @param[in]  pipe        Pipe handle.
520  * @param[in]  output_pin  Pin index to set the format on
521  *                         0 - main output pin
522  *                         1 - display output pin
523  * @param[in]  format      Format to set
524  *
525  * @return
526  * 0		: Success
527  * -EINVAL	: Invalid Parameters
528  * -EINVAL	: Pipe misses binary info
529  *
530  * Note:
531  * 1) This is an optional function to override the formats set in the pipe.
532  * 2) Only overriding with IA_CSS_FRAME_FORMAT_NV12_TILEY is currently allowed.
533  * 3) This function is only to be used on pipes that use the output system.
534  * 4) If this function is used, it MUST be called after ia_css_pipe_create.
535  * 5) If this function is used, this function MUST be called before ia_css_stream_start.
536  */
537 int
538 ia_css_pipe_override_frame_format(struct ia_css_pipe *pipe,
539 				  int output_pin,
540 				  enum ia_css_frame_format format);
541 
542 #endif /* __IA_CSS_PIPE_PUBLIC_H */
543