1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Support for Intel Camera Imaging ISP subsystem.
4 * Copyright (c) 2015, Intel Corporation.
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.
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
16 #ifndef __IA_CSS_STREAM_PUBLIC_H
17 #define __IA_CSS_STREAM_PUBLIC_H
20 * This file contains support for configuring and controlling streams
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_tpg.h"
28 #include "ia_css_prbs.h"
29 #include "ia_css_input_port.h"
31 /* Input modes, these enumerate all supported input modes.
32 * Note that not all ISP modes support all input modes.
34 enum ia_css_input_mode {
35 IA_CSS_INPUT_MODE_SENSOR, /** data from sensor */
36 IA_CSS_INPUT_MODE_FIFO, /** data from input-fifo */
37 IA_CSS_INPUT_MODE_TPG, /** data from test-pattern generator */
38 IA_CSS_INPUT_MODE_PRBS, /** data from pseudo-random bit stream */
39 IA_CSS_INPUT_MODE_MEMORY, /** data from a frame in memory */
40 IA_CSS_INPUT_MODE_BUFFERED_SENSOR /** data is sent through mipi buffer */
43 /* Structure of the MIPI buffer configuration
45 struct ia_css_mipi_buffer_config {
46 unsigned int size_mem_words; /** The frame size in the system memory
48 bool contiguous; /** Allocated memory physically
49 contiguously or not. \deprecated{Will be false always.}*/
50 unsigned int nof_mipi_buffers; /** The number of MIPI buffers required for this
55 IA_CSS_STREAM_ISYS_STREAM_0 = 0,
56 IA_CSS_STREAM_DEFAULT_ISYS_STREAM_IDX = IA_CSS_STREAM_ISYS_STREAM_0,
57 IA_CSS_STREAM_ISYS_STREAM_1,
58 IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH
61 /* This is input data configuration for one MIPI data type. We can have
62 * multiple of this in one virtual channel.
64 struct ia_css_stream_isys_stream_config {
65 struct ia_css_resolution input_res; /** Resolution of input data */
66 enum atomisp_input_format format; /** Format of input stream. This data
67 format will be mapped to MIPI data
69 int linked_isys_stream_id; /** default value is -1, other value means
70 current isys_stream shares the same buffer with
71 indicated isys_stream*/
72 bool valid; /** indicate whether other fields have valid value */
75 struct ia_css_stream_input_config {
76 struct ia_css_resolution input_res; /** Resolution of input data */
77 struct ia_css_resolution effective_res; /** Resolution of input data.
78 Used for CSS 2400/1 System and deprecated for other
79 systems (replaced by input_effective_res in
80 ia_css_pipe_config) */
81 enum atomisp_input_format format; /** Format of input stream. This data
82 format will be mapped to MIPI data
84 enum ia_css_bayer_order bayer_order; /** Bayer order for RAW streams */
87 /* Input stream description. This describes how input will flow into the
88 * CSS. This is used to program the CSS hardware.
90 struct ia_css_stream_config {
91 enum ia_css_input_mode mode; /** Input mode */
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
102 isys_config[IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH];
103 struct ia_css_stream_input_config input_config;
106 * Currently, Linux and Windows platforms interpret the binning_factor
107 * parameter differently. In Linux, the binning factor is expressed
108 * in the form 2^N * 2^N
111 unsigned int sensor_binning_factor; /** Binning factor used by sensor
112 to produce image data. This is
113 used for shading correction. */
114 unsigned int pixels_per_clock; /** Number of pixels per clock, which can be
116 bool online; /** offline will activate RAW copy on SP, use this for
117 continuous capture. */
118 /* ISYS2401 usage: ISP receives data directly from sensor, no copy. */
119 unsigned int init_num_cont_raw_buf; /** initial number of raw buffers to
121 unsigned int target_num_cont_raw_buf; /** total number of raw buffers to
123 bool pack_raw_pixels; /** Pack pixels in the raw buffers */
124 bool continuous; /** Use SP copy feature to continuously capture frames
125 to system memory and run pipes in offline mode */
126 bool disable_cont_viewfinder; /** disable continuous viewfinder for ZSL use case */
127 s32 flash_gpio_pin; /** pin on which the flash is connected, -1 for no flash */
128 int left_padding; /** The number of input-formatter left-paddings, -1 for default from binary.*/
129 struct ia_css_mipi_buffer_config
130 mipi_buffer_config; /** mipi buffer configuration */
131 struct ia_css_metadata_config
132 metadata_config; /** Metadata configuration. */
133 bool ia_css_enable_raw_buffer_locking; /** Enable Raw Buffer Locking for HALv3 Support */
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. */
141 struct ia_css_stream;
143 /* Stream info, this struct describes properties of a stream after it has been
146 struct ia_css_stream_info {
147 struct ia_css_metadata_info metadata_info;
148 /** Info about the metadata layout, this contains the stride. */
151 /* @brief Load default stream configuration
152 * @param[in,out] stream_config The stream configuration.
155 * This function will reset the stream configuration to the default state:
157 memset(stream_config, 0, sizeof(*stream_config));
158 stream_config->online = true;
159 stream_config->left_padding = -1;
162 void ia_css_stream_config_defaults(struct ia_css_stream_config *stream_config);
165 * create the internal structures and fill in the configuration data and pipes
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 0 or the error code.
175 * This function will create a stream with a given configuration and given pipes.
178 ia_css_stream_create(const struct ia_css_stream_config *stream_config,
180 struct ia_css_pipe *pipes[],
181 struct ia_css_stream **stream);
183 /* @brief Destroys a stream
184 * @param[in] stream The stream.
185 * @return 0 or the error code.
187 * This function will destroy a given stream.
190 ia_css_stream_destroy(struct ia_css_stream *stream);
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 0 or the error code.
197 * This function will destroy a given stream.
200 ia_css_stream_get_info(const struct ia_css_stream *stream,
201 struct ia_css_stream_info *stream_info);
204 /* @brief Starts the stream.
205 * @param[in] stream The stream.
206 * @return 0 or the error code.
208 * The dynamic data in
209 * the buffers are not used and need to be queued with a separate call
210 * to ia_css_pipe_enqueue_buffer.
211 * NOTE: this function will only send start event to corresponding
212 * thread and will not start SP any more.
215 ia_css_stream_start(struct ia_css_stream *stream);
217 /* @brief Stop the stream.
218 * @param[in] stream The stream.
219 * @return 0 or the error code.
221 * NOTE: this function will send stop event to pipes belong to this
222 * stream but will not terminate threads.
225 ia_css_stream_stop(struct ia_css_stream *stream);
227 /* @brief Check if a stream has stopped
228 * @param[in] stream The stream.
229 * @return boolean flag
231 * This function will check if the stream has stopped and return the correspondent boolean flag.
234 ia_css_stream_has_stopped(struct ia_css_stream *stream);
236 /* @brief destroy a stream according to the stream seed previosly saved in the seed array.
237 * @param[in] stream The stream.
238 * @return 0 (no other errors are generated now)
240 * Destroy the stream and all the pipes related to it.
243 ia_css_stream_unload(struct ia_css_stream *stream);
245 /* @brief Returns stream format
246 * @param[in] stream The stream.
247 * @return format of the string
249 * This function will return the stream format.
251 enum atomisp_input_format
252 ia_css_stream_get_format(const struct ia_css_stream *stream);
254 /* @brief Check if the stream is configured for 2 pixels per clock
255 * @param[in] stream The stream.
256 * @return boolean flag
258 * This function will check if the stream is configured for 2 pixels per clock and
259 * return the correspondent boolean flag.
262 ia_css_stream_get_two_pixels_per_clock(const struct ia_css_stream *stream);
264 /* @brief Sets the output frame stride (at the last pipe)
265 * @param[in] stream The stream
266 * @param[in] output_padded_width - the output buffer stride.
269 * This function will Set the output frame stride (at the last pipe)
272 ia_css_stream_set_output_padded_width(struct ia_css_stream *stream,
273 unsigned int output_padded_width);
275 /* @brief Return max number of continuous RAW frames.
276 * @param[in] stream The stream.
277 * @param[out] buffer_depth The maximum number of continuous RAW frames.
278 * @return 0 or -EINVAL
280 * This function will return the maximum number of continuous RAW frames
281 * the system can support.
284 ia_css_stream_get_max_buffer_depth(struct ia_css_stream *stream,
287 /* @brief Set nr of continuous RAW frames to use.
289 * @param[in] stream The stream.
290 * @param[in] buffer_depth Number of frames to set.
291 * @return 0 or error code upon error.
293 * Set the number of continuous frames to use during continuous modes.
296 ia_css_stream_set_buffer_depth(struct ia_css_stream *stream, int buffer_depth);
298 /* @brief Get number of continuous RAW frames to use.
299 * @param[in] stream The stream.
300 * @param[out] buffer_depth The number of frames to use
301 * @return 0 or -EINVAL
303 * Get the currently set number of continuous frames
304 * to use during continuous modes.
307 ia_css_stream_get_buffer_depth(struct ia_css_stream *stream, int *buffer_depth);
309 /* ===== CAPTURE ===== */
311 /* @brief Configure the continuous capture
313 * @param[in] stream The stream.
314 * @param[in] num_captures The number of RAW frames to be processed to
315 * YUV. Setting this to -1 will make continuous
316 * capture run until it is stopped.
317 * This number will also be used to allocate RAW
318 * buffers. To allow the viewfinder to also
319 * keep operating, 2 extra buffers will always be
321 * If the offset is negative and the skip setting
322 * is greater than 0, additional buffers may be
324 * @param[in] skip Skip N frames in between captures. This can be
325 * used to select a slower capture frame rate than
326 * the sensor output frame rate.
327 * @param[in] offset Start the RAW-to-YUV processing at RAW buffer
328 * with this offset. This allows the user to
329 * process RAW frames that were captured in the
331 * @return 0 or error code upon error.
333 * For example, to capture the current frame plus the 2 previous
334 * frames and 2 subsequent frames, you would call
335 * ia_css_stream_capture(5, 0, -2).
338 ia_css_stream_capture(struct ia_css_stream *stream,
343 /* @brief Specify which raw frame to tag based on exp_id found in frame info
345 * @param[in] stream The stream.
346 * @param[in] exp_id The exposure id of the raw frame to tag.
348 * @return 0 or error code upon error.
350 * This function allows the user to tag a raw frame based on the exposure id
351 * found in the viewfinder frames' frame info.
354 ia_css_stream_capture_frame(struct ia_css_stream *stream,
355 unsigned int exp_id);
357 /* ===== VIDEO ===== */
359 /* @brief Send streaming data into the css input FIFO
361 * @param[in] stream The stream.
362 * @param[in] data Pointer to the pixels to be send.
363 * @param[in] width Width of the input frame.
364 * @param[in] height Height of the input frame.
367 * Send streaming data into the css input FIFO. This is for testing purposes
368 * only. This uses the channel ID and input format as set by the user with
369 * the regular functions for this.
370 * This function blocks until the entire frame has been written into the
374 * For higher flexibility the ia_css_stream_send_input_frame is replaced by
375 * three separate functions:
376 * 1) ia_css_stream_start_input_frame
377 * 2) ia_css_stream_send_input_line
378 * 3) ia_css_stream_end_input_frame
379 * In this way it is possible to stream multiple frames on different
380 * channel ID's on a line basis. It will be possible to simulate
381 * line-interleaved Stereo 3D muxed on 1 mipi port.
382 * These 3 functions are for testing purpose only and can be used in
383 * conjunction with ia_css_stream_send_input_frame
386 ia_css_stream_send_input_frame(const struct ia_css_stream *stream,
387 const unsigned short *data,
389 unsigned int height);
391 /* @brief Start an input frame on the CSS input FIFO.
393 * @param[in] stream The stream.
396 * Starts the streaming to mipi frame by sending SoF for channel channel_id.
397 * It will use the input_format and two_pixels_per_clock as provided by
399 * For the "correct" use-case, input_format and two_pixels_per_clock must match
400 * with the values as set by the user with the regular functions.
401 * To simulate an error, the user can provide "incorrect" values for
402 * input_format and/or two_pixels_per_clock.
405 ia_css_stream_start_input_frame(const struct ia_css_stream *stream);
407 /* @brief Send a line of input data into the CSS input FIFO.
409 * @param[in] stream The stream.
410 * @param[in] data Array of the first line of image data.
411 * @param width The width (in pixels) of the first line.
412 * @param[in] data2 Array of the second line of image data.
413 * @param width2 The width (in pixels) of the second line.
416 * Sends 1 frame line. Start with SoL followed by width bytes of data, followed
417 * by width2 bytes of data2 and followed by and EoL
418 * It will use the input_format and two_pixels_per_clock settings as provided
419 * with the ia_css_stream_start_input_frame function call.
421 * This function blocks until the entire line has been written into the
425 ia_css_stream_send_input_line(const struct ia_css_stream *stream,
426 const unsigned short *data,
428 const unsigned short *data2,
429 unsigned int width2);
431 /* @brief Send a line of input embedded data into the CSS input FIFO.
433 * @param[in] stream Pointer of the stream.
434 * @param[in] format Format of the embedded data.
435 * @param[in] data Pointer of the embedded data line.
436 * @param[in] width The width (in pixels) of the line.
439 * Sends one embedded data line to input fifo. Start with SoL followed by
440 * width bytes of data, and followed by and EoL.
441 * It will use the two_pixels_per_clock settings as provided with the
442 * ia_css_stream_start_input_frame function call.
444 * This function blocks until the entire line has been written into the
448 ia_css_stream_send_input_embedded_line(const struct ia_css_stream *stream,
449 enum atomisp_input_format format,
450 const unsigned short *data,
453 /* @brief End an input frame on the CSS input FIFO.
455 * @param[in] stream The stream.
458 * Send the end-of-frame signal into the CSS input FIFO.
461 ia_css_stream_end_input_frame(const struct ia_css_stream *stream);
463 /* @brief send a request flash command to SP
465 * @param[in] stream The stream.
468 * Driver needs to call this function to send a flash request command
469 * to SP, SP will be responsible for switching on/off the flash at proper
470 * time. Due to the SP multi-threading environment, this request may have
471 * one-frame delay, the driver needs to check the flashed flag in frame info
472 * to determine which frame is being flashed.
475 ia_css_stream_request_flash(struct ia_css_stream *stream);
477 /* @brief Configure a stream with filter coefficients.
478 * @deprecated {Replaced by
479 * ia_css_pipe_set_isp_config_on_pipe()}
481 * @param[in] stream The stream.
482 * @param[in] config The set of filter coefficients.
483 * @param[in] pipe Pipe to be updated when set isp config, NULL means to
484 * update all pipes in the stream.
485 * @return 0 or error code upon error.
487 * This function configures the filter coefficients for an image
488 * stream. For image pipes that do not execute any ISP filters, this
489 * function will have no effect.
490 * It is safe to call this function while the image stream is running,
491 * in fact this is the expected behavior most of the time. Proper
492 * resource locking and double buffering is in place to allow for this.
495 ia_css_stream_set_isp_config_on_pipe(struct ia_css_stream *stream,
496 const struct ia_css_isp_config *config,
497 struct ia_css_pipe *pipe);
499 /* @brief Configure a stream with filter coefficients.
500 * @deprecated {Replaced by
501 * ia_css_pipe_set_isp_config()}
502 * @param[in] stream The stream.
503 * @param[in] config The set of filter coefficients.
504 * @return 0 or error code upon error.
506 * This function configures the filter coefficients for an image
507 * stream. For image pipes that do not execute any ISP filters, this
508 * function will have no effect. All pipes of a stream will be updated.
509 * See ::ia_css_stream_set_isp_config_on_pipe() for the per-pipe alternative.
510 * It is safe to call this function while the image stream is running,
511 * in fact this is the expected behaviour most of the time. Proper
512 * resource locking and double buffering is in place to allow for this.
515 ia_css_stream_set_isp_config(
516 struct ia_css_stream *stream,
517 const struct ia_css_isp_config *config);
519 /* @brief Get selected configuration settings
520 * @param[in] stream The stream.
521 * @param[out] config Configuration settings.
525 ia_css_stream_get_isp_config(const struct ia_css_stream *stream,
526 struct ia_css_isp_config *config);
528 /* @brief allocate continuous raw frames for continuous capture
529 * @param[in] stream The stream.
530 * @return 0 or error code.
532 * because this allocation takes a long time (around 120ms per frame),
533 * we separate the allocation part and update part to let driver call
534 * this function without locking. This function is the allocation part
535 * and next one is update part
538 ia_css_alloc_continuous_frame_remain(struct ia_css_stream *stream);
540 /* @brief allocate continuous raw frames for continuous capture
541 * @param[in] stream The stream.
542 * @return 0 or error code.
544 * because this allocation takes a long time (around 120ms per frame),
545 * we separate the allocation part and update part to let driver call
546 * this function without locking. This function is the update part
549 ia_css_update_continuous_frames(struct ia_css_stream *stream);
551 /* @brief ia_css_unlock_raw_frame . unlock a raw frame (HALv3 Support)
552 * @param[in] stream The stream.
553 * @param[in] exp_id exposure id that uniquely identifies the locked Raw Frame Buffer
554 * @return ia_css_err 0 or error code
556 * As part of HALv3 Feature requirement, SP locks raw buffer until the Application
557 * releases its reference to a raw buffer (which are managed by SP), this function allows
558 * application to explicitly unlock that buffer in SP.
561 ia_css_unlock_raw_frame(struct ia_css_stream *stream, uint32_t exp_id);
563 /* @brief ia_css_en_dz_capt_pipe . Enable/Disable digital zoom for capture pipe
564 * @param[in] stream The stream.
565 * @param[in] enable - true, disable - false
568 * Enables or disables digital zoom for capture pipe in provided stream, if capture pipe
569 * exists. This function sets enable_zoom flag in CAPTURE_PP stage of the capture pipe.
570 * In process_zoom_and_motion(), decision to enable or disable zoom for every stage depends
574 ia_css_en_dz_capt_pipe(struct ia_css_stream *stream, bool enable);
575 #endif /* __IA_CSS_STREAM_PUBLIC_H */