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_PIPE_PUBLIC_H 8 #define __IA_CSS_PIPE_PUBLIC_H 9 10 /* @file 11 * This file contains the public interface for CSS pipes. 12 */ 13 14 #include <type_support.h> 15 #include <ia_css_err.h> 16 #include <ia_css_types.h> 17 #include <ia_css_frame_public.h> 18 #include <ia_css_buffer.h> 19 /* ISP2401 */ 20 #include <ia_css_acc_types.h> 21 22 enum { 23 IA_CSS_PIPE_OUTPUT_STAGE_0 = 0, 24 IA_CSS_PIPE_OUTPUT_STAGE_1, 25 IA_CSS_PIPE_MAX_OUTPUT_STAGE, 26 }; 27 28 /* Enumeration of pipe modes. This mode can be used to create 29 * an image pipe for this mode. These pipes can be combined 30 * to configure and run streams on the ISP. 31 * 32 * For example, one can create a preview and capture pipe to 33 * create a continuous capture stream. 34 */ 35 enum ia_css_pipe_mode { 36 IA_CSS_PIPE_MODE_PREVIEW, /** Preview pipe */ 37 IA_CSS_PIPE_MODE_VIDEO, /** Video pipe */ 38 IA_CSS_PIPE_MODE_CAPTURE, /** Still capture pipe */ 39 IA_CSS_PIPE_MODE_COPY, /** Copy pipe, only used for embedded/image data copying */ 40 IA_CSS_PIPE_MODE_YUVPP, /** YUV post processing pipe, used for all use cases with YUV input, 41 for SoC sensor and external ISP */ 42 }; 43 44 /* Temporary define */ 45 #define IA_CSS_PIPE_MODE_NUM (IA_CSS_PIPE_MODE_YUVPP + 1) 46 47 /** 48 * Enumeration of pipe versions. 49 * the order should match with definition in sh_css_defs.h 50 */ 51 enum ia_css_pipe_version { 52 IA_CSS_PIPE_VERSION_1 = 1, /** ISP1.0 pipe */ 53 IA_CSS_PIPE_VERSION_2_2 = 2, /** ISP2.2 pipe */ 54 IA_CSS_PIPE_VERSION_2_6_1 = 3, /** ISP2.6.1 pipe */ 55 IA_CSS_PIPE_VERSION_2_7 = 4 /** ISP2.7 pipe */ 56 }; 57 58 /** 59 * Pipe configuration structure. 60 * Resolution properties are filled by Driver, kernel configurations are 61 * set by AIC 62 */ 63 struct ia_css_pipe_config { 64 enum ia_css_pipe_mode mode; 65 /** mode, indicates which mode the pipe should use. */ 66 enum ia_css_pipe_version isp_pipe_version; 67 /** pipe version, indicates which imaging pipeline the pipe should use. */ 68 struct ia_css_resolution input_effective_res; 69 /** input effective resolution */ 70 struct ia_css_resolution bayer_ds_out_res; 71 /** bayer down scaling */ 72 struct ia_css_resolution capt_pp_in_res; 73 /** capture post processing input resolution */ 74 struct ia_css_resolution vf_pp_in_res; 75 76 /** ISP2401: view finder post processing input resolution */ 77 struct ia_css_resolution output_system_in_res; 78 /** For IPU3 only: use output_system_in_res to specify what input resolution 79 will OSYS receive, this resolution is equal to the output resolution of GDC 80 if not determined CSS will set output_system_in_res with main osys output pin resolution 81 All other IPUs may ignore this property */ 82 struct ia_css_resolution dvs_crop_out_res; 83 /** dvs crop, video only, not in use yet. Use dvs_envelope below. */ 84 struct ia_css_frame_info output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE]; 85 /** output of YUV scaling */ 86 struct ia_css_frame_info vf_output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE]; 87 /** output of VF YUV scaling */ 88 struct ia_css_capture_config default_capture_config; 89 /** Default capture config for initial capture pipe configuration. */ 90 struct ia_css_resolution dvs_envelope; /** temporary */ 91 enum ia_css_frame_delay dvs_frame_delay; 92 /** indicates the DVS loop delay in frame periods */ 93 bool enable_dz; 94 /** Disabling digital zoom for a pipeline, if this is set to false, 95 then setting a zoom factor will have no effect. 96 In some use cases this provides better performance. */ 97 bool enable_dpc; 98 /** Disabling "Defect Pixel Correction" for a pipeline, if this is set 99 to false. In some use cases this provides better performance. */ 100 bool enable_vfpp_bci; 101 /** Enabling BCI mode will cause yuv_scale binary to be picked up 102 instead of vf_pp. This only applies to viewfinder post 103 processing stages. */ 104 105 /* ISP2401 */ 106 bool enable_tnr; 107 /** Enabling of TNR (temporal noise reduction). This is only applicable to video 108 pipes. Non video-pipes should always set this parameter to false. */ 109 110 struct ia_css_isp_config *p_isp_config; 111 /** Pointer to ISP configuration */ 112 struct ia_css_resolution gdc_in_buffer_res; 113 /** GDC in buffer resolution. */ 114 struct ia_css_point gdc_in_buffer_offset; 115 /** GDC in buffer offset - indicates the pixel coordinates of the first valid pixel inside the buffer */ 116 117 /* ISP2401 */ 118 struct ia_css_coordinate internal_frame_origin_bqs_on_sctbl; 119 /** Origin of internal frame positioned on shading table at shading correction in ISP. 120 NOTE: Shading table is larger than or equal to internal frame. 121 Shading table has shading gains and internal frame has bayer data. 122 The origin of internal frame is used in shading correction in ISP 123 to retrieve shading gains which correspond to bayer data. */ 124 }; 125 126 /** 127 * Default settings for newly created pipe configurations. 128 */ 129 #define DEFAULT_PIPE_CONFIG { \ 130 .mode = IA_CSS_PIPE_MODE_PREVIEW, \ 131 .isp_pipe_version = 1, \ 132 .output_info = {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \ 133 .vf_output_info = {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \ 134 .default_capture_config = DEFAULT_CAPTURE_CONFIG, \ 135 .dvs_frame_delay = IA_CSS_FRAME_DELAY_1, \ 136 } 137 138 /* Pipe info, this struct describes properties of a pipe after it's stream has 139 * been created. 140 * ~~~** DO NOT ADD NEW FIELD **~~~ This structure will be deprecated. 141 * - On the Behalf of CSS-API Committee. 142 */ 143 struct ia_css_pipe_info { 144 struct ia_css_frame_info output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE]; 145 /** Info about output resolution. This contains the stride which 146 should be used for memory allocation. */ 147 struct ia_css_frame_info vf_output_info[IA_CSS_PIPE_MAX_OUTPUT_STAGE]; 148 /** Info about viewfinder output resolution (optional). This contains 149 the stride that should be used for memory allocation. */ 150 struct ia_css_frame_info raw_output_info; 151 /** Raw output resolution. This indicates the resolution of the 152 RAW bayer output for pipes that support this. Currently, only the 153 still capture pipes support this feature. When this resolution is 154 smaller than the input resolution, cropping will be performed by 155 the ISP. The first cropping that will be performed is on the upper 156 left corner where we crop 8 lines and 8 columns to remove the 157 pixels normally used to initialize the ISP filters. 158 This is why the raw output resolution should normally be set to 159 the input resolution - 8x8. */ 160 /* ISP2401 */ 161 struct ia_css_resolution output_system_in_res_info; 162 /** For IPU3 only. Info about output system in resolution which is considered 163 as gdc out resolution. */ 164 struct ia_css_shading_info shading_info; 165 /** After an image pipe is created, this field will contain the info 166 for the shading correction. */ 167 struct ia_css_grid_info grid_info; 168 /** After an image pipe is created, this field will contain the grid 169 info for 3A and DVS. */ 170 int num_invalid_frames; 171 /** The very first frames in a started stream do not contain valid data. 172 In this field, the CSS-firmware communicates to the host-driver how 173 many initial frames will contain invalid data; this allows the 174 host-driver to discard those initial invalid frames and start it's 175 output at the first valid frame. */ 176 }; 177 178 /** 179 * Defaults for ia_css_pipe_info structs. 180 */ 181 #define DEFAULT_PIPE_INFO {\ 182 .output_info = {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \ 183 .vf_output_info = {IA_CSS_BINARY_DEFAULT_FRAME_INFO}, \ 184 .raw_output_info = IA_CSS_BINARY_DEFAULT_FRAME_INFO, \ 185 .shading_info = DEFAULT_SHADING_INFO, \ 186 .grid_info = DEFAULT_GRID_INFO, \ 187 } 188 189 /* @brief Load default pipe configuration 190 * @param[out] pipe_config The pipe configuration. 191 * @return None 192 * 193 * This function will load the default pipe configuration: 194 @code 195 struct ia_css_pipe_config def_config = { 196 IA_CSS_PIPE_MODE_PREVIEW, // mode 197 1, // isp_pipe_version 198 {0, 0}, // bayer_ds_out_res 199 {0, 0}, // capt_pp_in_res 200 {0, 0}, // vf_pp_in_res 201 {0, 0}, // dvs_crop_out_res 202 {{0, 0}, 0, 0, 0, 0}, // output_info 203 {{0, 0}, 0, 0, 0, 0}, // second_output_info 204 {{0, 0}, 0, 0, 0, 0}, // vf_output_info 205 {{0, 0}, 0, 0, 0, 0}, // second_vf_output_info 206 { 207 IA_CSS_CAPTURE_MODE_RAW, // mode 208 false, // enable_xnr 209 false // enable_raw_output 210 }, // default_capture_config 211 {0, 0}, // dvs_envelope 212 1, // dvs_frame_delay 213 true, // enable_dz 214 NULL, // p_isp_config 215 }; 216 @endcode 217 */ 218 void ia_css_pipe_config_defaults(struct ia_css_pipe_config *pipe_config); 219 220 /* @brief Create a pipe 221 * @param[in] config The pipe configuration. 222 * @param[out] pipe The pipe. 223 * @return 0 or the error code. 224 * 225 * This function will create a pipe with the given 226 * configuration. 227 */ 228 int 229 ia_css_pipe_create(const struct ia_css_pipe_config *config, 230 struct ia_css_pipe **pipe); 231 232 /* @brief Destroy a pipe 233 * @param[in] pipe The pipe. 234 * @return 0 or the error code. 235 * 236 * This function will destroy a given pipe. 237 */ 238 int 239 ia_css_pipe_destroy(struct ia_css_pipe *pipe); 240 241 /* @brief Provides information about a pipe 242 * @param[in] pipe The pipe. 243 * @param[out] pipe_info The pipe information. 244 * @return 0 or -EINVAL. 245 * 246 * This function will provide information about a given pipe. 247 */ 248 int 249 ia_css_pipe_get_info(const struct ia_css_pipe *pipe, 250 struct ia_css_pipe_info *pipe_info); 251 252 /* @brief Configure a pipe with filter coefficients. 253 * @param[in] pipe The pipe. 254 * @param[in] config The pointer to ISP configuration. 255 * @return 0 or error code upon error. 256 * 257 * This function configures the filter coefficients for an image 258 * pipe. 259 */ 260 int 261 ia_css_pipe_set_isp_config(struct ia_css_pipe *pipe, 262 struct ia_css_isp_config *config); 263 264 /* @brief Controls when the Event generator raises an IRQ to the Host. 265 * 266 * @param[in] pipe The pipe. 267 * @param[in] or_mask Binary or of enum ia_css_event_irq_mask_type. Each pipe 268 related event that is part of this mask will directly 269 raise an IRQ to the Host when the event occurs in the 270 CSS. 271 * @param[in] and_mask Binary or of enum ia_css_event_irq_mask_type. An event 272 IRQ for the Host is only raised after all pipe related 273 events have occurred at least once for all the active 274 pipes. Events are remembered and don't need to occurred 275 at the same moment in time. There is no control over 276 the order of these events. Once an IRQ has been raised 277 all remembered events are reset. 278 * @return 0. 279 * 280 Controls when the Event generator in the CSS raises an IRQ to the Host. 281 The main purpose of this function is to reduce the amount of interrupts 282 between the CSS and the Host. This will help saving power as it wakes up the 283 Host less often. In case both or_mask and and_mask are 284 IA_CSS_EVENT_TYPE_NONE for all pipes, no event IRQ's will be raised. An 285 exception holds for IA_CSS_EVENT_TYPE_PORT_EOF, for this event an IRQ is always 286 raised. 287 Note that events are still queued and the Host can poll for them. The 288 or_mask and and_mask may be active at the same time\n 289 \n 290 Default values, for all pipe id's, after ia_css_init:\n 291 or_mask = IA_CSS_EVENT_TYPE_ALL\n 292 and_mask = IA_CSS_EVENT_TYPE_NONE\n 293 \n 294 Examples\n 295 \code 296 ia_css_pipe_set_irq_mask(h_pipe, 297 IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE | 298 IA_CSS_EVENT_TYPE_DIS_STATISTICS_DONE , 299 IA_CSS_EVENT_TYPE_NONE); 300 \endcode 301 The event generator will only raise an interrupt to the Host when there are 302 3A or DIS statistics available from the preview pipe. It will not generate 303 an interrupt for any other event of the preview pipe e.g when there is an 304 output frame available. 305 306 \code 307 ia_css_pipe_set_irq_mask(h_pipe_preview, 308 IA_CSS_EVENT_TYPE_NONE, 309 IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE | 310 IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE ); 311 312 ia_css_pipe_set_irq_mask(h_pipe_capture, 313 IA_CSS_EVENT_TYPE_NONE, 314 IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE ); 315 \endcode 316 The event generator will only raise an interrupt to the Host when there is 317 both a frame done and 3A event available from the preview pipe AND when there 318 is a frame done available from the capture pipe. Note that these events 319 may occur at different moments in time. Also the order of the events is not 320 relevant. 321 322 \code 323 ia_css_pipe_set_irq_mask(h_pipe_preview, 324 IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE, 325 IA_CSS_EVENT_TYPE_ALL ); 326 327 ia_css_pipe_set_irq_mask(h_pipe_capture, 328 IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE, 329 IA_CSS_EVENT_TYPE_ALL ); 330 \endcode 331 The event generator will only raise an interrupt to the Host when there is an 332 output frame from the preview pipe OR an output frame from the capture pipe. 333 All other events (3A, VF output, pipeline done) will not raise an interrupt 334 to the Host. These events are not lost but always stored in the event queue. 335 */ 336 int 337 ia_css_pipe_set_irq_mask(struct ia_css_pipe *pipe, 338 unsigned int or_mask, 339 unsigned int and_mask); 340 341 /* @brief Reads the current event IRQ mask from the CSS. 342 * 343 * @param[in] pipe The pipe. 344 * @param[out] or_mask Current or_mask. The bits in this mask are a binary or 345 of enum ia_css_event_irq_mask_type. Pointer may be NULL. 346 * @param[out] and_mask Current and_mask.The bits in this mask are a binary or 347 of enum ia_css_event_irq_mask_type. Pointer may be NULL. 348 * @return 0. 349 * 350 Reads the current event IRQ mask from the CSS. Reading returns the actual 351 values as used by the SP and not any mirrored values stored at the Host.\n 352 \n 353 Precondition:\n 354 SP must be running.\n 355 356 */ 357 int 358 ia_css_event_get_irq_mask(const struct ia_css_pipe *pipe, 359 unsigned int *or_mask, 360 unsigned int *and_mask); 361 362 /* @brief Queue a buffer for an image pipe. 363 * 364 * @param[in] pipe The pipe that will own the buffer. 365 * @param[in] buffer Pointer to the buffer. 366 * Note that the caller remains owner of the buffer 367 * structure. Only the data pointer within it will 368 * be passed into the internal queues. 369 * @return IA_CSS_INTERNAL_ERROR in case of unexpected errors, 370 * 0 otherwise. 371 * 372 * This function adds a buffer (which has a certain buffer type) to the queue 373 * for this type. This queue is owned by the image pipe. After this function 374 * completes successfully, the buffer is now owned by the image pipe and should 375 * no longer be accessed by any other code until it gets dequeued. The image 376 * pipe will dequeue buffers from this queue, use them and return them to the 377 * host code via an interrupt. Buffers will be consumed in the same order they 378 * get queued, but may be returned to the host out of order. 379 */ 380 int 381 ia_css_pipe_enqueue_buffer(struct ia_css_pipe *pipe, 382 const struct ia_css_buffer *buffer); 383 384 /* @brief Dequeue a buffer from an image pipe. 385 * 386 * @param[in] pipe The pipeline that the buffer queue belongs to. 387 * @param[in,out] buffer The buffer is used to lookup the type which determines 388 * which internal queue to use. 389 * The resulting buffer pointer is written into the dta 390 * field. 391 * @return IA_CSS_ERR_NO_BUFFER if the queue is empty or 392 * 0 otherwise. 393 * 394 * This function dequeues a buffer from a buffer queue. The queue is indicated 395 * by the buffer type argument. This function can be called after an interrupt 396 * has been generated that signalled that a new buffer was available and can 397 * be used in a polling-like situation where the NO_BUFFER return value is used 398 * to determine whether a buffer was available or not. 399 */ 400 int 401 ia_css_pipe_dequeue_buffer(struct ia_css_pipe *pipe, 402 struct ia_css_buffer *buffer); 403 404 /* @brief Get selected configuration settings 405 * @param[in] pipe The pipe. 406 * @param[out] config Configuration settings. 407 * @return None 408 */ 409 void 410 ia_css_pipe_get_isp_config(struct ia_css_pipe *pipe, 411 struct ia_css_isp_config *config); 412 413 /* @brief Set the scaler lut on this pipe. A copy of lut is made in the inuit 414 * address space. So the LUT can be freed by caller. 415 * @param[in] pipe Pipe handle. 416 * @param[in] lut Look up tabel 417 * 418 * @return 419 * 0 : Success 420 * -EINVAL : Invalid Parameters 421 * 422 * Note: 423 * 1) Note that both GDC's are programmed with the same table. 424 * 2) Current implementation ignores the pipe and overrides the 425 * global lut. This will be fixed in the future 426 * 3) This function must be called before stream start 427 * 428 */ 429 int 430 ia_css_pipe_set_bci_scaler_lut(struct ia_css_pipe *pipe, 431 const void *lut); 432 /* @brief Checking of DVS statistics ability 433 * @param[in] pipe_info The pipe info. 434 * @return true - has DVS statistics ability 435 * false - otherwise 436 */ 437 bool ia_css_pipe_has_dvs_stats(struct ia_css_pipe_info *pipe_info); 438 439 /* ISP2401 */ 440 /* @brief Override the frameformat set on the output pins. 441 * @param[in] pipe Pipe handle. 442 * @param[in] output_pin Pin index to set the format on 443 * 0 - main output pin 444 * 1 - display output pin 445 * @param[in] format Format to set 446 * 447 * @return 448 * 0 : Success 449 * -EINVAL : Invalid Parameters 450 * -EINVAL : Pipe misses binary info 451 * 452 * Note: 453 * 1) This is an optional function to override the formats set in the pipe. 454 * 2) Only overriding with IA_CSS_FRAME_FORMAT_NV12_TILEY is currently allowed. 455 * 3) This function is only to be used on pipes that use the output system. 456 * 4) If this function is used, it MUST be called after ia_css_pipe_create. 457 * 5) If this function is used, this function MUST be called before ia_css_stream_start. 458 */ 459 int 460 ia_css_pipe_override_frame_format(struct ia_css_pipe *pipe, 461 int output_pin, 462 enum ia_css_frame_format format); 463 464 #endif /* __IA_CSS_PIPE_PUBLIC_H */ 465