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_STREAM_PUBLIC_H
17  #define __IA_CSS_STREAM_PUBLIC_H
18  
19  /* @file
20   * This file contains support for configuring and controlling streams
21   */
22  
23  #include <type_support.h>
24  #include "ia_css_types.h"
25  #include "ia_css_pipe_public.h"
26  #include "ia_css_metadata.h"
27  #include "ia_css_prbs.h"
28  #include "ia_css_input_port.h"
29  
30  /*
31   * Input modes, these enumerate all supported input modes.
32   * This enum is part of the atomisp firmware ABI and must
33   * NOT be changed!
34   * Note that not all ISP modes support all input modes.
35   */
36  enum ia_css_input_mode {
37  	IA_CSS_INPUT_MODE_SENSOR, /** data from sensor */
38  	IA_CSS_INPUT_MODE_FIFO,   /** data from input-fifo */
39  	IA_CSS_INPUT_MODE_TPG,    /** data from test-pattern generator */
40  	IA_CSS_INPUT_MODE_PRBS,   /** data from pseudo-random bit stream */
41  	IA_CSS_INPUT_MODE_MEMORY, /** data from a frame in memory */
42  	IA_CSS_INPUT_MODE_BUFFERED_SENSOR /** data is sent through mipi buffer */
43  };
44  
45  /* Structure of the MIPI buffer configuration
46   */
47  struct ia_css_mipi_buffer_config {
48  	unsigned int size_mem_words; /** The frame size in the system memory
49  					  words (32B) */
50  	bool contiguous;	     /** Allocated memory physically
51  					  contiguously or not. \deprecated{Will be false always.}*/
52  	unsigned int nof_mipi_buffers; /** The number of MIPI buffers required for this
53  					stream */
54  };
55  
56  enum {
57  	IA_CSS_STREAM_ISYS_STREAM_0 = 0,
58  	IA_CSS_STREAM_DEFAULT_ISYS_STREAM_IDX = IA_CSS_STREAM_ISYS_STREAM_0,
59  	IA_CSS_STREAM_ISYS_STREAM_1,
60  	IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH
61  };
62  
63  /* This is input data configuration for one MIPI data type. We can have
64   *  multiple of this in one virtual channel.
65   */
66  struct ia_css_stream_isys_stream_config {
67  	struct ia_css_resolution  input_res; /** Resolution of input data */
68  	enum atomisp_input_format format; /** Format of input stream. This data
69  					       format will be mapped to MIPI data
70  					       type internally. */
71  	int linked_isys_stream_id; /** default value is -1, other value means
72  							current isys_stream shares the same buffer with
73  							indicated isys_stream*/
74  	bool valid; /** indicate whether other fields have valid value */
75  };
76  
77  struct ia_css_stream_input_config {
78  	struct ia_css_resolution  input_res; /** Resolution of input data */
79  	struct ia_css_resolution  effective_res; /** Resolution of input data.
80  							Used for CSS 2400/1 System and deprecated for other
81  							systems (replaced by input_effective_res in
82  							ia_css_pipe_config) */
83  	enum atomisp_input_format format; /** Format of input stream. This data
84  					       format will be mapped to MIPI data
85  					       type internally. */
86  	enum ia_css_bayer_order bayer_order; /** Bayer order for RAW streams */
87  };
88  
89  /* Input stream description. This describes how input will flow into the
90   *  CSS. This is used to program the CSS hardware.
91   */
92  struct ia_css_stream_config {
93  	enum ia_css_input_mode    mode; /** Input mode */
94  	union {
95  		struct ia_css_input_port  port; /** Port, for sensor only. */
96  		struct ia_css_prbs_config prbs; /** PRBS configuration */
97  	} source; /** Source of input data */
98  	unsigned int	      channel_id; /** Channel on which input data
99  						   will arrive. Use this field
100  						   to specify virtual channel id.
101  						   Valid values are: 0, 1, 2, 3 */
102  	struct ia_css_stream_isys_stream_config
103  		isys_config[IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH];
104  	struct ia_css_stream_input_config input_config;
105  
106  	/*
107  	 * Currently, Linux and Windows platforms interpret the binning_factor
108  	 * parameter differently. In Linux, the binning factor is expressed
109  	 * in the form 2^N * 2^N
110  	 */
111  	/* ISP2401 */
112  	unsigned int sensor_binning_factor; /** Binning factor used by sensor
113  						 to produce image data. This is
114  						 used for shading correction. */
115  	unsigned int pixels_per_clock; /** Number of pixels per clock, which can be
116  					    1, 2 or 4. */
117  	bool online; /** offline will activate RAW copy on SP, use this for
118  			  continuous capture. */
119  	/* ISYS2401 usage: ISP receives data directly from sensor, no copy. */
120  	unsigned int init_num_cont_raw_buf; /** initial number of raw buffers to
121  					     allocate */
122  	unsigned int target_num_cont_raw_buf; /** total number of raw buffers to
123  					     allocate */
124  	bool pack_raw_pixels; /** Pack pixels in the raw buffers */
125  	bool continuous; /** Use SP copy feature to continuously capture frames
126  			      to system memory and run pipes in offline mode */
127  	bool disable_cont_viewfinder; /** disable continuous viewfinder for ZSL use case */
128  	s32 flash_gpio_pin; /** pin on which the flash is connected, -1 for no flash */
129  	int left_padding; /** The number of input-formatter left-paddings, -1 for default from binary.*/
130  	struct ia_css_mipi_buffer_config
131  		mipi_buffer_config; /** mipi buffer configuration */
132  	struct ia_css_metadata_config
133  		metadata_config;     /** Metadata configuration. */
134  	bool ia_css_enable_raw_buffer_locking; /** Enable Raw Buffer Locking for HALv3 Support */
135  	bool lock_all;
136  	/** Lock all RAW buffers (true) or lock only buffers processed by
137  	     video or preview pipe (false).
138  	     This setting needs to be enabled to allow raw buffer locking
139  	     without continuous viewfinder. */
140  };
141  
142  struct ia_css_stream;
143  
144  /* Stream info, this struct describes properties of a stream after it has been
145   *  created.
146   */
147  struct ia_css_stream_info {
148  	struct ia_css_metadata_info metadata_info;
149  	/** Info about the metadata layout, this contains the stride. */
150  };
151  
152  /* @brief Load default stream configuration
153   * @param[in,out]	stream_config The stream configuration.
154   * @return	None
155   *
156   * This function will reset the stream configuration to the default state:
157  @code
158  	memset(stream_config, 0, sizeof(*stream_config));
159  	stream_config->online = true;
160  	stream_config->left_padding = -1;
161  @endcode
162   */
163  void ia_css_stream_config_defaults(struct ia_css_stream_config *stream_config);
164  
165  /*
166   * create the internal structures and fill in the configuration data and pipes
167   */
168  
169  /* @brief Creates a stream
170  * @param[in]	stream_config The stream configuration.
171  * @param[in]	num_pipes The number of pipes to incorporate in the stream.
172  * @param[in]	pipes The pipes.
173  * @param[out]	stream The stream.
174  * @return	0 or the error code.
175  *
176  * This function will create a stream with a given configuration and given pipes.
177  */
178  int
179  ia_css_stream_create(const struct ia_css_stream_config *stream_config,
180  		     int num_pipes,
181  		     struct ia_css_pipe *pipes[],
182  		     struct ia_css_stream **stream);
183  
184  /* @brief Destroys a stream
185   * @param[in]	stream The stream.
186   * @return	0 or the error code.
187   *
188   * This function will destroy a given stream.
189   */
190  int
191  ia_css_stream_destroy(struct ia_css_stream *stream);
192  
193  /* @brief Provides information about a stream
194   * @param[in]	stream The stream.
195   * @param[out]	stream_info The information about the stream.
196   * @return	0 or the error code.
197   *
198   * This function will destroy a given stream.
199   */
200  int
201  ia_css_stream_get_info(const struct ia_css_stream *stream,
202  		       struct ia_css_stream_info *stream_info);
203  
204  
205  /* @brief Starts the stream.
206   * @param[in]	stream The stream.
207   * @return 0 or the error code.
208   *
209   * The dynamic data in
210   * the buffers are not used and need to be queued with a separate call
211   * to ia_css_pipe_enqueue_buffer.
212   * NOTE: this function will only send start event to corresponding
213   * thread and will not start SP any more.
214   */
215  int
216  ia_css_stream_start(struct ia_css_stream *stream);
217  
218  /* @brief Stop the stream.
219   * @param[in]	stream The stream.
220   * @return	0 or the error code.
221   *
222   * NOTE: this function will send stop event to pipes belong to this
223   * stream but will not terminate threads.
224   */
225  int
226  ia_css_stream_stop(struct ia_css_stream *stream);
227  
228  /* @brief Check if a stream has stopped
229   * @param[in]	stream The stream.
230   * @return	boolean flag
231   *
232   * This function will check if the stream has stopped and return the correspondent boolean flag.
233   */
234  bool
235  ia_css_stream_has_stopped(struct ia_css_stream *stream);
236  
237  /* @brief	destroy a stream according to the stream seed previosly saved in the seed array.
238   * @param[in]	stream The stream.
239   * @return	0 (no other errors are generated now)
240   *
241   * Destroy the stream and all the pipes related to it.
242   */
243  int
244  ia_css_stream_unload(struct ia_css_stream *stream);
245  
246  /* @brief Returns stream format
247   * @param[in]	stream The stream.
248   * @return	format of the string
249   *
250   * This function will return the stream format.
251   */
252  enum atomisp_input_format
253  ia_css_stream_get_format(const struct ia_css_stream *stream);
254  
255  /* @brief Check if the stream is configured for 2 pixels per clock
256   * @param[in]	stream The stream.
257   * @return	boolean flag
258   *
259   * This function will check if the stream is configured for 2 pixels per clock and
260   * return the correspondent boolean flag.
261   */
262  bool
263  ia_css_stream_get_two_pixels_per_clock(const struct ia_css_stream *stream);
264  
265  /* @brief Sets the output frame stride (at the last pipe)
266   * @param[in]	stream The stream
267   * @param[in]	output_padded_width - the output buffer stride.
268   * @return	ia_css_err
269   *
270   * This function will Set the output frame stride (at the last pipe)
271   */
272  int
273  ia_css_stream_set_output_padded_width(struct ia_css_stream *stream,
274  				      unsigned int output_padded_width);
275  
276  /* @brief Return max number of continuous RAW frames.
277   * @param[in]	stream The stream.
278   * @param[out]	buffer_depth The maximum number of continuous RAW frames.
279   * @return	0 or -EINVAL
280   *
281   * This function will return the maximum number of continuous RAW frames
282   * the system can support.
283   */
284  int
285  ia_css_stream_get_max_buffer_depth(struct ia_css_stream *stream,
286  				   int *buffer_depth);
287  
288  /* @brief Set nr of continuous RAW frames to use.
289   *
290   * @param[in]	stream The stream.
291   * @param[in]	buffer_depth	Number of frames to set.
292   * @return	0 or error code upon error.
293   *
294   * Set the number of continuous frames to use during continuous modes.
295   */
296  int
297  ia_css_stream_set_buffer_depth(struct ia_css_stream *stream, int buffer_depth);
298  
299  /* @brief Get number of continuous RAW frames to use.
300   * @param[in]	stream The stream.
301   * @param[out]	buffer_depth The number of frames to use
302   * @return	0 or -EINVAL
303   *
304   * Get the currently set number of continuous frames
305   * to use during continuous modes.
306   */
307  int
308  ia_css_stream_get_buffer_depth(struct ia_css_stream *stream, int *buffer_depth);
309  
310  /* ===== CAPTURE ===== */
311  
312  /* @brief Configure the continuous capture
313   *
314   * @param[in]	stream		The stream.
315   * @param[in]	num_captures	The number of RAW frames to be processed to
316   *				YUV. Setting this to -1 will make continuous
317   *				capture run until it is stopped.
318   *				This number will also be used to allocate RAW
319   *				buffers. To allow the viewfinder to also
320   *				keep operating, 2 extra buffers will always be
321   *				allocated.
322   *				If the offset is negative and the skip setting
323   *				is greater than 0, additional buffers may be
324   *				needed.
325   * @param[in]	skip		Skip N frames in between captures. This can be
326   *				used to select a slower capture frame rate than
327   *				the sensor output frame rate.
328   * @param[in]	offset		Start the RAW-to-YUV processing at RAW buffer
329   *				with this offset. This allows the user to
330   *				process RAW frames that were captured in the
331   *				past or future.
332   * @return			0 or error code upon error.
333   *
334   *  For example, to capture the current frame plus the 2 previous
335   *  frames and 2 subsequent frames, you would call
336   *  ia_css_stream_capture(5, 0, -2).
337   */
338  int
339  ia_css_stream_capture(struct ia_css_stream *stream,
340  		      int num_captures,
341  		      unsigned int skip,
342  		      int offset);
343  
344  /* @brief Specify which raw frame to tag based on exp_id found in frame info
345   *
346   * @param[in]	stream The stream.
347   * @param[in]	exp_id	The exposure id of the raw frame to tag.
348   *
349   * @return			0 or error code upon error.
350   *
351   * This function allows the user to tag a raw frame based on the exposure id
352   * found in the viewfinder frames' frame info.
353   */
354  int
355  ia_css_stream_capture_frame(struct ia_css_stream *stream,
356  			    unsigned int exp_id);
357  
358  /* ===== VIDEO ===== */
359  
360  /* @brief Send streaming data into the css input FIFO
361   *
362   * @param[in]	stream	The stream.
363   * @param[in]	data	Pointer to the pixels to be send.
364   * @param[in]	width	Width of the input frame.
365   * @param[in]	height	Height of the input frame.
366   * @return	None
367   *
368   * Send streaming data into the css input FIFO. This is for testing purposes
369   * only. This uses the channel ID and input format as set by the user with
370   * the regular functions for this.
371   * This function blocks until the entire frame has been written into the
372   * input FIFO.
373   *
374   * Note:
375   * For higher flexibility the ia_css_stream_send_input_frame is replaced by
376   * three separate functions:
377   * 1) ia_css_stream_start_input_frame
378   * 2) ia_css_stream_send_input_line
379   * 3) ia_css_stream_end_input_frame
380   * In this way it is possible to stream multiple frames on different
381   * channel ID's on a line basis. It will be possible to simulate
382   * line-interleaved Stereo 3D muxed on 1 mipi port.
383   * These 3 functions are for testing purpose only and can be used in
384   * conjunction with ia_css_stream_send_input_frame
385   */
386  void
387  ia_css_stream_send_input_frame(const struct ia_css_stream *stream,
388  			       const unsigned short *data,
389  			       unsigned int width,
390  			       unsigned int height);
391  
392  /* @brief Start an input frame on the CSS input FIFO.
393   *
394   * @param[in]	stream The stream.
395   * @return	None
396   *
397   * Starts the streaming to mipi frame by sending SoF for channel channel_id.
398   * It will use the input_format and two_pixels_per_clock as provided by
399   * the user.
400   * For the "correct" use-case, input_format and two_pixels_per_clock must match
401   * with the values as set by the user with the regular functions.
402   * To simulate an error, the user can provide "incorrect" values for
403   * input_format and/or two_pixels_per_clock.
404   */
405  void
406  ia_css_stream_start_input_frame(const struct ia_css_stream *stream);
407  
408  /* @brief Send a line of input data into the CSS input FIFO.
409   *
410   * @param[in]	stream		The stream.
411   * @param[in]	data	Array of the first line of image data.
412   * @param	width	The width (in pixels) of the first line.
413   * @param[in]	data2	Array of the second line of image data.
414   * @param	width2	The width (in pixels) of the second line.
415   * @return	None
416   *
417   * Sends 1 frame line. Start with SoL followed by width bytes of data, followed
418   * by width2 bytes of data2 and followed by and EoL
419   * It will use the input_format and two_pixels_per_clock settings as provided
420   * with the ia_css_stream_start_input_frame function call.
421   *
422   * This function blocks until the entire line has been written into the
423   * input FIFO.
424   */
425  void
426  ia_css_stream_send_input_line(const struct ia_css_stream *stream,
427  			      const unsigned short *data,
428  			      unsigned int width,
429  			      const unsigned short *data2,
430  			      unsigned int width2);
431  
432  /* @brief Send a line of input embedded data into the CSS input FIFO.
433   *
434   * @param[in]	stream     Pointer of the stream.
435   * @param[in]	format     Format of the embedded data.
436   * @param[in]	data       Pointer of the embedded data line.
437   * @param[in]	width      The width (in pixels) of the line.
438   * @return		None
439   *
440   * Sends one embedded data line to input fifo. Start with SoL followed by
441   * width bytes of data, and followed by and EoL.
442   * It will use the two_pixels_per_clock settings as provided with the
443   * ia_css_stream_start_input_frame function call.
444   *
445   * This function blocks until the entire line has been written into the
446   * input FIFO.
447   */
448  void
449  ia_css_stream_send_input_embedded_line(const struct ia_css_stream *stream,
450  				       enum atomisp_input_format format,
451  				       const unsigned short *data,
452  				       unsigned int width);
453  
454  /* @brief End an input frame on the CSS input FIFO.
455   *
456   * @param[in]	stream	The stream.
457   * @return	None
458   *
459   * Send the end-of-frame signal into the CSS input FIFO.
460   */
461  void
462  ia_css_stream_end_input_frame(const struct ia_css_stream *stream);
463  
464  /* @brief Configure a stream with filter coefficients.
465   *	   @deprecated {Replaced by
466   *				   ia_css_pipe_set_isp_config_on_pipe()}
467   *
468   * @param[in]	stream The stream.
469   * @param[in]	config	The set of filter coefficients.
470   * @param[in]   pipe Pipe to be updated when set isp config, NULL means to
471   *		   update all pipes in the stream.
472   * @return		0 or error code upon error.
473   *
474   * This function configures the filter coefficients for an image
475   * stream. For image pipes that do not execute any ISP filters, this
476   * function will have no effect.
477   * It is safe to call this function while the image stream is running,
478   * in fact this is the expected behavior most of the time. Proper
479   * resource locking and double buffering is in place to allow for this.
480   */
481  int
482  ia_css_stream_set_isp_config_on_pipe(struct ia_css_stream *stream,
483  				     const struct ia_css_isp_config *config,
484  				     struct ia_css_pipe *pipe);
485  
486  /* @brief Configure a stream with filter coefficients.
487   *	   @deprecated {Replaced by
488   *				   ia_css_pipe_set_isp_config()}
489   * @param[in]	stream	The stream.
490   * @param[in]	config	The set of filter coefficients.
491   * @return		0 or error code upon error.
492   *
493   * This function configures the filter coefficients for an image
494   * stream. For image pipes that do not execute any ISP filters, this
495   * function will have no effect. All pipes of a stream will be updated.
496   * See ::ia_css_stream_set_isp_config_on_pipe() for the per-pipe alternative.
497   * It is safe to call this function while the image stream is running,
498   * in fact this is the expected behaviour most of the time. Proper
499   * resource locking and double buffering is in place to allow for this.
500   */
501  int
502  ia_css_stream_set_isp_config(
503      struct ia_css_stream *stream,
504      const struct ia_css_isp_config *config);
505  
506  /* @brief Get selected configuration settings
507   * @param[in]	stream	The stream.
508   * @param[out]	config	Configuration settings.
509   * @return		None
510   */
511  void
512  ia_css_stream_get_isp_config(const struct ia_css_stream *stream,
513  			     struct ia_css_isp_config *config);
514  
515  /* @brief allocate continuous raw frames for continuous capture
516   * @param[in]	stream The stream.
517   * @return 0 or error code.
518   *
519   *  because this allocation takes a long time (around 120ms per frame),
520   *  we separate the allocation part and update part to let driver call
521   *  this function without locking. This function is the allocation part
522   *  and next one is update part
523   */
524  int
525  ia_css_alloc_continuous_frame_remain(struct ia_css_stream *stream);
526  
527  /* @brief allocate continuous raw frames for continuous capture
528   * @param[in]	stream The stream.
529   * @return	0 or error code.
530   *
531   *  because this allocation takes a long time (around 120ms per frame),
532   *  we separate the allocation part and update part to let driver call
533   *  this function without locking. This function is the update part
534   */
535  int
536  ia_css_update_continuous_frames(struct ia_css_stream *stream);
537  
538  /* @brief ia_css_unlock_raw_frame . unlock a raw frame (HALv3 Support)
539   * @param[in]	stream The stream.
540   * @param[in]   exp_id exposure id that uniquely identifies the locked Raw Frame Buffer
541   * @return      ia_css_err 0 or error code
542   *
543   * As part of HALv3 Feature requirement, SP locks raw buffer until the Application
544   * releases its reference to a raw buffer (which are managed by SP), this function allows
545   * application to explicitly unlock that buffer in SP.
546   */
547  int
548  ia_css_unlock_raw_frame(struct ia_css_stream *stream, uint32_t exp_id);
549  
550  /* @brief ia_css_en_dz_capt_pipe . Enable/Disable digital zoom for capture pipe
551   * @param[in]   stream The stream.
552   * @param[in]   enable - true, disable - false
553   * @return      None
554   *
555   * Enables or disables digital zoom for capture pipe in provided stream, if capture pipe
556   * exists. This function sets enable_zoom flag in CAPTURE_PP stage of the capture pipe.
557   * In process_zoom_and_motion(), decision to enable or disable zoom for every stage depends
558   * on this flag.
559   */
560  void
561  ia_css_en_dz_capt_pipe(struct ia_css_stream *stream, bool enable);
562  #endif /* __IA_CSS_STREAM_PUBLIC_H */
563