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