2 * Support for Intel Camera Imaging ISP subsystem.
3 * Copyright (c) 2015, Intel Corporation.
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.
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
15 #ifndef __IA_CSS_FRAME_PUBLIC_H
16 #define __IA_CSS_FRAME_PUBLIC_H
19 * This file contains structs to describe various frame-formats supported by the ISP.
22 #include <type_support.h>
23 #include "ia_css_err.h"
24 #include "ia_css_types.h"
25 #include "ia_css_frame_format.h"
26 #include "ia_css_buffer.h"
28 /** For RAW input, the bayer order needs to be specified separately. There
29 * are 4 possible orders. The name is constructed by taking the first two
30 * colors on the first line and the first two colors from the second line.
32 enum ia_css_bayer_order {
33 IA_CSS_BAYER_ORDER_GRBG, /**< GRGRGRGRGR .. BGBGBGBGBG */
34 IA_CSS_BAYER_ORDER_RGGB, /**< RGRGRGRGRG .. GBGBGBGBGB */
35 IA_CSS_BAYER_ORDER_BGGR, /**< BGBGBGBGBG .. GRGRGRGRGR */
36 IA_CSS_BAYER_ORDER_GBRG, /**< GBGBGBGBGB .. RGRGRGRGRG */
38 #define IA_CSS_BAYER_ORDER_NUM (IA_CSS_BAYER_ORDER_GBRG + 1)
40 /** Frame plane structure. This describes one plane in an image
43 struct ia_css_frame_plane {
44 unsigned int height; /**< height of a plane in lines */
45 unsigned int width; /**< width of a line, in DMA elements, note that
46 for RGB565 the three subpixels are stored in
47 one element. For all other formats this is
48 the number of subpixels per line. */
49 unsigned int stride; /**< stride of a line in bytes */
50 unsigned int offset; /**< offset in bytes to start of frame data.
51 offset is wrt data field in ia_css_frame */
54 /** Binary "plane". This is used to story binary streams such as jpeg
55 * images. This is not actually a real plane.
57 struct ia_css_frame_binary_plane {
58 unsigned int size; /**< number of bytes in the stream */
59 struct ia_css_frame_plane data; /**< plane */
62 /** Container for planar YUV frames. This contains 3 planes.
64 struct ia_css_frame_yuv_planes {
65 struct ia_css_frame_plane y; /**< Y plane */
66 struct ia_css_frame_plane u; /**< U plane */
67 struct ia_css_frame_plane v; /**< V plane */
70 /** Container for semi-planar YUV frames.
72 struct ia_css_frame_nv_planes {
73 struct ia_css_frame_plane y; /**< Y plane */
74 struct ia_css_frame_plane uv; /**< UV plane */
77 /** Container for planar RGB frames. Each color has its own plane.
79 struct ia_css_frame_rgb_planes {
80 struct ia_css_frame_plane r; /**< Red plane */
81 struct ia_css_frame_plane g; /**< Green plane */
82 struct ia_css_frame_plane b; /**< Blue plane */
85 /** Container for 6-plane frames. These frames are used internally
86 * in the advanced ISP only.
88 struct ia_css_frame_plane6_planes {
89 struct ia_css_frame_plane r; /**< Red plane */
90 struct ia_css_frame_plane r_at_b; /**< Red at blue plane */
91 struct ia_css_frame_plane gr; /**< Red-green plane */
92 struct ia_css_frame_plane gb; /**< Blue-green plane */
93 struct ia_css_frame_plane b; /**< Blue plane */
94 struct ia_css_frame_plane b_at_r; /**< Blue at red plane */
97 /* Crop info struct - stores the lines to be cropped in isp */
98 struct ia_css_crop_info {
99 /* the final start column and start line
100 * sum of lines to be cropped + bayer offset
102 unsigned int start_column;
103 unsigned int start_line;
106 /** Frame info struct. This describes the contents of an image frame buffer.
108 struct ia_css_frame_info {
109 struct ia_css_resolution res; /**< Frame resolution (valid data) */
110 unsigned int padded_width; /**< stride of line in memory (in pixels) */
111 enum ia_css_frame_format format; /**< format of the frame data */
112 unsigned int raw_bit_depth; /**< number of valid bits per pixel,
113 only valid for RAW bayer frames */
114 enum ia_css_bayer_order raw_bayer_order; /**< bayer order, only valid
115 for RAW bayer frames */
116 /* the params below are computed based on bayer_order
117 * we can remove the raw_bayer_order if it is redundant
118 * keeping it for now as bxt and fpn code seem to use it
120 struct ia_css_crop_info crop_info;
123 #define IA_CSS_BINARY_DEFAULT_FRAME_INFO \
127 0, /* padded_width */ \
128 IA_CSS_FRAME_FORMAT_NUM, /* format */ \
129 0, /* raw_bit_depth */ \
130 IA_CSS_BAYER_ORDER_NUM, /* raw_bayer_order */ \
132 0}, /*start line */ \
136 * Specifies the DVS loop delay in "frame periods"
138 enum ia_css_frame_delay {
139 IA_CSS_FRAME_DELAY_0, /**< Frame delay = 0 */
140 IA_CSS_FRAME_DELAY_1, /**< Frame delay = 1 */
141 IA_CSS_FRAME_DELAY_2 /**< Frame delay = 2 */
144 enum ia_css_frame_flash_state {
145 IA_CSS_FRAME_FLASH_STATE_NONE,
146 IA_CSS_FRAME_FLASH_STATE_PARTIAL,
147 IA_CSS_FRAME_FLASH_STATE_FULL
150 /** Frame structure. This structure describes an image buffer or frame.
151 * This is the main structure used for all input and output images.
153 struct ia_css_frame {
154 struct ia_css_frame_info info; /**< info struct describing the frame */
155 ia_css_ptr data; /**< pointer to start of image data */
156 unsigned int data_bytes; /**< size of image data in bytes */
157 /* LA: move this to ia_css_buffer */
159 * -1 if data address is static during life time of pipeline
160 * >=0 if data address can change per pipeline/frame iteration
161 * index to dynamic data: ia_css_frame_in, ia_css_frame_out
162 * ia_css_frame_out_vf
163 * index to host-sp queue id: queue_0, queue_1 etc.
165 int dynamic_queue_id;
167 * if it is dynamic frame, buf_type indicates which buffer type it
168 * should use for event generation. we have this because in vf_pp
169 * binary, we use output port, but we expect VF_OUTPUT_DONE event
171 enum ia_css_buffer_type buf_type;
172 enum ia_css_frame_flash_state flash_state;
174 /**< exposure id, see ia_css_event_public.h for more detail */
175 uint32_t isp_config_id; /**< Unique ID to track which config was actually applied to a particular frame */
176 bool valid; /**< First video output frame is not valid */
177 bool contiguous; /**< memory is allocated physically contiguously */
179 unsigned int _initialisation_dummy;
180 struct ia_css_frame_plane raw;
181 struct ia_css_frame_plane rgb;
182 struct ia_css_frame_rgb_planes planar_rgb;
183 struct ia_css_frame_plane yuyv;
184 struct ia_css_frame_yuv_planes yuv;
185 struct ia_css_frame_nv_planes nv;
186 struct ia_css_frame_plane6_planes plane6;
187 struct ia_css_frame_binary_plane binary;
188 } planes; /**< frame planes, select the right one based on
192 #define DEFAULT_FRAME \
194 IA_CSS_BINARY_DEFAULT_FRAME_INFO, /* info */ \
196 0, /* data_bytes */ \
197 SH_CSS_INVALID_QUEUE_ID, /* dynamic_data_index */ \
198 IA_CSS_BUFFER_TYPE_INVALID, /* buf_type */ \
199 IA_CSS_FRAME_FLASH_STATE_NONE, /* flash_state */ \
201 0, /* isp_config_id */ \
203 false, /* contiguous */ \
207 /** @brief Fill a frame with zeros
209 * @param frame The frame.
212 * Fill a frame with pixel values of zero
214 void ia_css_frame_zero(struct ia_css_frame *frame);
216 /** @brief Allocate a CSS frame structure
218 * @param frame The allocated frame.
219 * @param width The width (in pixels) of the frame.
220 * @param height The height (in lines) of the frame.
221 * @param format The frame format.
222 * @param stride The padded stride, in pixels.
223 * @param raw_bit_depth The raw bit depth, in bits.
224 * @return The error code.
226 * Allocate a CSS frame structure. The memory for the frame data will be
227 * allocated in the CSS address space.
230 ia_css_frame_allocate(struct ia_css_frame **frame,
233 enum ia_css_frame_format format,
235 unsigned int raw_bit_depth);
237 /** @brief Allocate a CSS frame structure using a frame info structure.
239 * @param frame The allocated frame.
240 * @param[in] info The frame info structure.
241 * @return The error code.
243 * Allocate a frame using the resolution and format from a frame info struct.
244 * This is a convenience function, implemented on top of
245 * ia_css_frame_allocate().
248 ia_css_frame_allocate_from_info(struct ia_css_frame **frame,
249 const struct ia_css_frame_info *info);
250 /** @brief Free a CSS frame structure.
252 * @param[in] frame Pointer to the frame.
255 * Free a CSS frame structure. This will free both the frame structure
256 * and the pixel data pointer contained within the frame structure.
259 ia_css_frame_free(struct ia_css_frame *frame);
261 /** @brief Allocate a contiguous CSS frame structure
263 * @param frame The allocated frame.
264 * @param width The width (in pixels) of the frame.
265 * @param height The height (in lines) of the frame.
266 * @param format The frame format.
267 * @param stride The padded stride, in pixels.
268 * @param raw_bit_depth The raw bit depth, in bits.
269 * @return The error code.
271 * Contiguous frame allocation, only for FPGA display driver which needs
272 * physically contiguous memory.
276 ia_css_frame_allocate_contiguous(struct ia_css_frame **frame,
279 enum ia_css_frame_format format,
281 unsigned int raw_bit_depth);
283 /** @brief Allocate a contiguous CSS frame from a frame info structure.
285 * @param frame The allocated frame.
286 * @param[in] info The frame info structure.
287 * @return The error code.
289 * Allocate a frame using the resolution and format from a frame info struct.
290 * This is a convenience function, implemented on top of
291 * ia_css_frame_allocate_contiguous().
292 * Only for FPGA display driver which needs physically contiguous memory.
296 ia_css_frame_allocate_contiguous_from_info(struct ia_css_frame **frame,
297 const struct ia_css_frame_info *info);
299 /** @brief Allocate a CSS frame structure using a frame info structure.
301 * @param frame The allocated frame.
302 * @param[in] info The frame info structure.
303 * @return The error code.
305 * Allocate an empty CSS frame with no data buffer using the parameters
309 ia_css_frame_create_from_info(struct ia_css_frame **frame,
310 const struct ia_css_frame_info *info);
312 /** @brief Set a mapped data buffer to a CSS frame
314 * @param[in] frame Valid CSS frame pointer
315 * @param[in] mapped_data Mapped data buffer to be assigned to the CSS frame
316 * @param[in] data_size_bytes Size of the mapped_data in bytes
317 * @return The error code.
319 * Sets a mapped data buffer to this frame. This function can be called multiple
320 * times with different buffers or NULL to reset the data pointer. This API
321 * would not try free the mapped_data and its the callers responsiblity to
322 * free the mapped_data buffer. However if ia_css_frame_free() is called and
323 * the frame had a valid data buffer, it would be freed along with the frame.
326 ia_css_frame_set_data(struct ia_css_frame *frame,
327 const ia_css_ptr mapped_data,
328 size_t data_size_bytes);
330 /** @brief Map an existing frame data pointer to a CSS frame.
332 * @param frame Pointer to the frame to be initialized
333 * @param[in] info The frame info.
334 * @param[in] data Pointer to the allocated frame data.
335 * @param[in] attribute Attributes to be passed to mmgr_mmap.
336 * @param[in] context Pointer to the a context to be passed to mmgr_mmap.
337 * @return The allocated frame structure.
339 * This function maps a pre-allocated pointer into a CSS frame. This can be
340 * used when an upper software layer is responsible for allocating the frame
341 * data and it wants to share that frame pointer with the CSS code.
342 * This function will fill the CSS frame structure just like
343 * ia_css_frame_allocate() does, but instead of allocating the memory, it will
344 * map the pre-allocated memory into the CSS address space.
347 ia_css_frame_map(struct ia_css_frame **frame,
348 const struct ia_css_frame_info *info,
353 /** @brief Unmap a CSS frame structure.
355 * @param[in] frame Pointer to the CSS frame.
358 * This function unmaps the frame data pointer within a CSS frame and
359 * then frees the CSS frame structure. Use this for frame pointers created
360 * using ia_css_frame_map().
363 ia_css_frame_unmap(struct ia_css_frame *frame);
365 #endif /* __IA_CSS_FRAME_PUBLIC_H */