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_tpg.h" 28 #include "ia_css_prbs.h" 29 #include "ia_css_input_port.h" 30 31 /* Input modes, these enumerate all supported input modes. 32 * Note that not all ISP modes support all input modes. 33 */ 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 */ 41 }; 42 43 /* Structure of the MIPI buffer configuration 44 */ 45 struct ia_css_mipi_buffer_config { 46 unsigned int size_mem_words; /** The frame size in the system memory 47 words (32B) */ 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 51 stream */ 52 }; 53 54 enum { 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 59 }; 60 61 /* This is input data configuration for one MIPI data type. We can have 62 * multiple of this in one virtual channel. 63 */ 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 68 type internally. */ 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 */ 73 }; 74 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 83 type internally. */ 84 enum ia_css_bayer_order bayer_order; /** Bayer order for RAW streams */ 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 102 isys_config[IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH]; 103 struct ia_css_stream_input_config input_config; 104 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 /* ISP2401 */ 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 int init_num_cont_raw_buf; /** initial number of raw buffers to 122 allocate */ 123 unsigned int 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 continuous viewfinder for ZSL use case */ 129 s32 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 132 mipi_buffer_config; /** mipi buffer configuration */ 133 struct ia_css_metadata_config 134 metadata_config; /** Metadata configuration. */ 135 bool ia_css_enable_raw_buffer_locking; /** Enable Raw Buffer Locking for HALv3 Support */ 136 bool lock_all; 137 /** Lock all RAW buffers (true) or lock only buffers processed by 138 video or preview pipe (false). 139 This setting needs to be enabled to allow raw buffer locking 140 without continuous viewfinder. */ 141 }; 142 143 struct ia_css_stream; 144 145 /* Stream info, this struct describes properties of a stream after it has been 146 * created. 147 */ 148 struct ia_css_stream_info { 149 struct ia_css_metadata_info metadata_info; 150 /** Info about the metadata layout, this contains the stride. */ 151 }; 152 153 /* @brief Load default stream configuration 154 * @param[in,out] stream_config The stream configuration. 155 * @return None 156 * 157 * This function will reset the stream configuration to the default state: 158 @code 159 memset(stream_config, 0, sizeof(*stream_config)); 160 stream_config->online = true; 161 stream_config->left_padding = -1; 162 @endcode 163 */ 164 void ia_css_stream_config_defaults(struct ia_css_stream_config *stream_config); 165 166 /* 167 * create the internal structures and fill in the configuration data and pipes 168 */ 169 170 /* @brief Creates a stream 171 * @param[in] stream_config The stream configuration. 172 * @param[in] num_pipes The number of pipes to incorporate in the stream. 173 * @param[in] pipes The pipes. 174 * @param[out] stream The stream. 175 * @return 0 or the error code. 176 * 177 * This function will create a stream with a given configuration and given pipes. 178 */ 179 int 180 ia_css_stream_create(const struct ia_css_stream_config *stream_config, 181 int num_pipes, 182 struct ia_css_pipe *pipes[], 183 struct ia_css_stream **stream); 184 185 /* @brief Destroys a stream 186 * @param[in] stream 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_destroy(struct ia_css_stream *stream); 193 194 /* @brief Provides information about a stream 195 * @param[in] stream The stream. 196 * @param[out] stream_info The information about the stream. 197 * @return 0 or the error code. 198 * 199 * This function will destroy a given stream. 200 */ 201 int 202 ia_css_stream_get_info(const struct ia_css_stream *stream, 203 struct ia_css_stream_info *stream_info); 204 205 /* @brief load (rebuild) a stream that was unloaded. 206 * @param[in] stream The stream 207 * @return 0 or the error code 208 * 209 * Rebuild a stream, including allocating structs, setting configuration and 210 * building the required pipes. 211 */ 212 int 213 ia_css_stream_load(struct ia_css_stream *stream); 214 215 /* @brief Starts the stream. 216 * @param[in] stream The stream. 217 * @return 0 or the error code. 218 * 219 * The dynamic data in 220 * the buffers are not used and need to be queued with a separate call 221 * to ia_css_pipe_enqueue_buffer. 222 * NOTE: this function will only send start event to corresponding 223 * thread and will not start SP any more. 224 */ 225 int 226 ia_css_stream_start(struct ia_css_stream *stream); 227 228 /* @brief Stop the stream. 229 * @param[in] stream The stream. 230 * @return 0 or the error code. 231 * 232 * NOTE: this function will send stop event to pipes belong to this 233 * stream but will not terminate threads. 234 */ 235 int 236 ia_css_stream_stop(struct ia_css_stream *stream); 237 238 /* @brief Check if a stream has stopped 239 * @param[in] stream The stream. 240 * @return boolean flag 241 * 242 * This function will check if the stream has stopped and return the correspondent boolean flag. 243 */ 244 bool 245 ia_css_stream_has_stopped(struct ia_css_stream *stream); 246 247 /* @brief destroy a stream according to the stream seed previosly saved in the seed array. 248 * @param[in] stream The stream. 249 * @return 0 (no other errors are generated now) 250 * 251 * Destroy the stream and all the pipes related to it. 252 */ 253 int 254 ia_css_stream_unload(struct ia_css_stream *stream); 255 256 /* @brief Returns stream format 257 * @param[in] stream The stream. 258 * @return format of the string 259 * 260 * This function will return the stream format. 261 */ 262 enum atomisp_input_format 263 ia_css_stream_get_format(const struct ia_css_stream *stream); 264 265 /* @brief Check if the stream is configured for 2 pixels per clock 266 * @param[in] stream The stream. 267 * @return boolean flag 268 * 269 * This function will check if the stream is configured for 2 pixels per clock and 270 * return the correspondent boolean flag. 271 */ 272 bool 273 ia_css_stream_get_two_pixels_per_clock(const struct ia_css_stream *stream); 274 275 /* @brief Sets the output frame stride (at the last pipe) 276 * @param[in] stream The stream 277 * @param[in] output_padded_width - the output buffer stride. 278 * @return ia_css_err 279 * 280 * This function will Set the output frame stride (at the last pipe) 281 */ 282 int 283 ia_css_stream_set_output_padded_width(struct ia_css_stream *stream, 284 unsigned int output_padded_width); 285 286 /* @brief Return max number of continuous RAW frames. 287 * @param[in] stream The stream. 288 * @param[out] buffer_depth The maximum number of continuous RAW frames. 289 * @return 0 or -EINVAL 290 * 291 * This function will return the maximum number of continuous RAW frames 292 * the system can support. 293 */ 294 int 295 ia_css_stream_get_max_buffer_depth(struct ia_css_stream *stream, 296 int *buffer_depth); 297 298 /* @brief Set nr of continuous RAW frames to use. 299 * 300 * @param[in] stream The stream. 301 * @param[in] buffer_depth Number of frames to set. 302 * @return 0 or error code upon error. 303 * 304 * Set the number of continuous frames to use during continuous modes. 305 */ 306 int 307 ia_css_stream_set_buffer_depth(struct ia_css_stream *stream, int buffer_depth); 308 309 /* @brief Get number of continuous RAW frames to use. 310 * @param[in] stream The stream. 311 * @param[out] buffer_depth The number of frames to use 312 * @return 0 or -EINVAL 313 * 314 * Get the currently set number of continuous frames 315 * to use during continuous modes. 316 */ 317 int 318 ia_css_stream_get_buffer_depth(struct ia_css_stream *stream, int *buffer_depth); 319 320 /* ===== CAPTURE ===== */ 321 322 /* @brief Configure the continuous capture 323 * 324 * @param[in] stream The stream. 325 * @param[in] num_captures The number of RAW frames to be processed to 326 * YUV. Setting this to -1 will make continuous 327 * capture run until it is stopped. 328 * This number will also be used to allocate RAW 329 * buffers. To allow the viewfinder to also 330 * keep operating, 2 extra buffers will always be 331 * allocated. 332 * If the offset is negative and the skip setting 333 * is greater than 0, additional buffers may be 334 * needed. 335 * @param[in] skip Skip N frames in between captures. This can be 336 * used to select a slower capture frame rate than 337 * the sensor output frame rate. 338 * @param[in] offset Start the RAW-to-YUV processing at RAW buffer 339 * with this offset. This allows the user to 340 * process RAW frames that were captured in the 341 * past or future. 342 * @return 0 or error code upon error. 343 * 344 * For example, to capture the current frame plus the 2 previous 345 * frames and 2 subsequent frames, you would call 346 * ia_css_stream_capture(5, 0, -2). 347 */ 348 int 349 ia_css_stream_capture(struct ia_css_stream *stream, 350 int num_captures, 351 unsigned int skip, 352 int offset); 353 354 /* @brief Specify which raw frame to tag based on exp_id found in frame info 355 * 356 * @param[in] stream The stream. 357 * @param[in] exp_id The exposure id of the raw frame to tag. 358 * 359 * @return 0 or error code upon error. 360 * 361 * This function allows the user to tag a raw frame based on the exposure id 362 * found in the viewfinder frames' frame info. 363 */ 364 int 365 ia_css_stream_capture_frame(struct ia_css_stream *stream, 366 unsigned int exp_id); 367 368 /* ===== VIDEO ===== */ 369 370 /* @brief Send streaming data into the css input FIFO 371 * 372 * @param[in] stream The stream. 373 * @param[in] data Pointer to the pixels to be send. 374 * @param[in] width Width of the input frame. 375 * @param[in] height Height of the input frame. 376 * @return None 377 * 378 * Send streaming data into the css input FIFO. This is for testing purposes 379 * only. This uses the channel ID and input format as set by the user with 380 * the regular functions for this. 381 * This function blocks until the entire frame has been written into the 382 * input FIFO. 383 * 384 * Note: 385 * For higher flexibility the ia_css_stream_send_input_frame is replaced by 386 * three separate functions: 387 * 1) ia_css_stream_start_input_frame 388 * 2) ia_css_stream_send_input_line 389 * 3) ia_css_stream_end_input_frame 390 * In this way it is possible to stream multiple frames on different 391 * channel ID's on a line basis. It will be possible to simulate 392 * line-interleaved Stereo 3D muxed on 1 mipi port. 393 * These 3 functions are for testing purpose only and can be used in 394 * conjunction with ia_css_stream_send_input_frame 395 */ 396 void 397 ia_css_stream_send_input_frame(const struct ia_css_stream *stream, 398 const unsigned short *data, 399 unsigned int width, 400 unsigned int height); 401 402 /* @brief Start an input frame on the CSS input FIFO. 403 * 404 * @param[in] stream The stream. 405 * @return None 406 * 407 * Starts the streaming to mipi frame by sending SoF for channel channel_id. 408 * It will use the input_format and two_pixels_per_clock as provided by 409 * the user. 410 * For the "correct" use-case, input_format and two_pixels_per_clock must match 411 * with the values as set by the user with the regular functions. 412 * To simulate an error, the user can provide "incorrect" values for 413 * input_format and/or two_pixels_per_clock. 414 */ 415 void 416 ia_css_stream_start_input_frame(const struct ia_css_stream *stream); 417 418 /* @brief Send a line of input data into the CSS input FIFO. 419 * 420 * @param[in] stream The stream. 421 * @param[in] data Array of the first line of image data. 422 * @param width The width (in pixels) of the first line. 423 * @param[in] data2 Array of the second line of image data. 424 * @param width2 The width (in pixels) of the second line. 425 * @return None 426 * 427 * Sends 1 frame line. Start with SoL followed by width bytes of data, followed 428 * by width2 bytes of data2 and followed by and EoL 429 * It will use the input_format and two_pixels_per_clock settings as provided 430 * with the ia_css_stream_start_input_frame function call. 431 * 432 * This function blocks until the entire line has been written into the 433 * input FIFO. 434 */ 435 void 436 ia_css_stream_send_input_line(const struct ia_css_stream *stream, 437 const unsigned short *data, 438 unsigned int width, 439 const unsigned short *data2, 440 unsigned int width2); 441 442 /* @brief Send a line of input embedded data into the CSS input FIFO. 443 * 444 * @param[in] stream Pointer of the stream. 445 * @param[in] format Format of the embedded data. 446 * @param[in] data Pointer of the embedded data line. 447 * @param[in] width The width (in pixels) of the line. 448 * @return None 449 * 450 * Sends one embedded data line to input fifo. Start with SoL followed by 451 * width bytes of data, and followed by and EoL. 452 * It will use the two_pixels_per_clock settings as provided with the 453 * ia_css_stream_start_input_frame function call. 454 * 455 * This function blocks until the entire line has been written into the 456 * input FIFO. 457 */ 458 void 459 ia_css_stream_send_input_embedded_line(const struct ia_css_stream *stream, 460 enum atomisp_input_format format, 461 const unsigned short *data, 462 unsigned int width); 463 464 /* @brief End an input frame on the CSS input FIFO. 465 * 466 * @param[in] stream The stream. 467 * @return None 468 * 469 * Send the end-of-frame signal into the CSS input FIFO. 470 */ 471 void 472 ia_css_stream_end_input_frame(const struct ia_css_stream *stream); 473 474 /* @brief send a request flash command to SP 475 * 476 * @param[in] stream The stream. 477 * @return None 478 * 479 * Driver needs to call this function to send a flash request command 480 * to SP, SP will be responsible for switching on/off the flash at proper 481 * time. Due to the SP multi-threading environment, this request may have 482 * one-frame delay, the driver needs to check the flashed flag in frame info 483 * to determine which frame is being flashed. 484 */ 485 void 486 ia_css_stream_request_flash(struct ia_css_stream *stream); 487 488 /* @brief Configure a stream with filter coefficients. 489 * @deprecated {Replaced by 490 * ia_css_pipe_set_isp_config_on_pipe()} 491 * 492 * @param[in] stream The stream. 493 * @param[in] config The set of filter coefficients. 494 * @param[in] pipe Pipe to be updated when set isp config, NULL means to 495 * update all pipes in the stream. 496 * @return 0 or error code upon error. 497 * 498 * This function configures the filter coefficients for an image 499 * stream. For image pipes that do not execute any ISP filters, this 500 * function will have no effect. 501 * It is safe to call this function while the image stream is running, 502 * in fact this is the expected behavior most of the time. Proper 503 * resource locking and double buffering is in place to allow for this. 504 */ 505 int 506 ia_css_stream_set_isp_config_on_pipe(struct ia_css_stream *stream, 507 const struct ia_css_isp_config *config, 508 struct ia_css_pipe *pipe); 509 510 /* @brief Configure a stream with filter coefficients. 511 * @deprecated {Replaced by 512 * ia_css_pipe_set_isp_config()} 513 * @param[in] stream The stream. 514 * @param[in] config The set of filter coefficients. 515 * @return 0 or error code upon error. 516 * 517 * This function configures the filter coefficients for an image 518 * stream. For image pipes that do not execute any ISP filters, this 519 * function will have no effect. All pipes of a stream will be updated. 520 * See ::ia_css_stream_set_isp_config_on_pipe() for the per-pipe alternative. 521 * It is safe to call this function while the image stream is running, 522 * in fact this is the expected behaviour most of the time. Proper 523 * resource locking and double buffering is in place to allow for this. 524 */ 525 int 526 ia_css_stream_set_isp_config( 527 struct ia_css_stream *stream, 528 const struct ia_css_isp_config *config); 529 530 /* @brief Get selected configuration settings 531 * @param[in] stream The stream. 532 * @param[out] config Configuration settings. 533 * @return None 534 */ 535 void 536 ia_css_stream_get_isp_config(const struct ia_css_stream *stream, 537 struct ia_css_isp_config *config); 538 539 /* @brief allocate continuous raw frames for continuous capture 540 * @param[in] stream The stream. 541 * @return 0 or error code. 542 * 543 * because this allocation takes a long time (around 120ms per frame), 544 * we separate the allocation part and update part to let driver call 545 * this function without locking. This function is the allocation part 546 * and next one is update part 547 */ 548 int 549 ia_css_alloc_continuous_frame_remain(struct ia_css_stream *stream); 550 551 /* @brief allocate continuous raw frames for continuous capture 552 * @param[in] stream The stream. 553 * @return 0 or error code. 554 * 555 * because this allocation takes a long time (around 120ms per frame), 556 * we separate the allocation part and update part to let driver call 557 * this function without locking. This function is the update part 558 */ 559 int 560 ia_css_update_continuous_frames(struct ia_css_stream *stream); 561 562 /* @brief ia_css_unlock_raw_frame . unlock a raw frame (HALv3 Support) 563 * @param[in] stream The stream. 564 * @param[in] exp_id exposure id that uniquely identifies the locked Raw Frame Buffer 565 * @return ia_css_err 0 or error code 566 * 567 * As part of HALv3 Feature requirement, SP locks raw buffer until the Application 568 * releases its reference to a raw buffer (which are managed by SP), this function allows 569 * application to explicitly unlock that buffer in SP. 570 */ 571 int 572 ia_css_unlock_raw_frame(struct ia_css_stream *stream, uint32_t exp_id); 573 574 /* @brief ia_css_en_dz_capt_pipe . Enable/Disable digital zoom for capture pipe 575 * @param[in] stream The stream. 576 * @param[in] enable - true, disable - false 577 * @return None 578 * 579 * Enables or disables digital zoom for capture pipe in provided stream, if capture pipe 580 * exists. This function sets enable_zoom flag in CAPTURE_PP stage of the capture pipe. 581 * In process_zoom_and_motion(), decision to enable or disable zoom for every stage depends 582 * on this flag. 583 */ 584 void 585 ia_css_en_dz_capt_pipe(struct ia_css_stream *stream, bool enable); 586 #endif /* __IA_CSS_STREAM_PUBLIC_H */ 587