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