1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * V4L2 JPEG helpers header
4  *
5  * Copyright (C) 2019 Pengutronix, Philipp Zabel <kernel@pengutronix.de>
6  *
7  * For reference, see JPEG ITU-T.81 (ISO/IEC 10918-1)
8  */
9 
10 #ifndef _V4L2_JPEG_H
11 #define _V4L2_JPEG_H
12 
13 #include <linux/v4l2-controls.h>
14 
15 #define V4L2_JPEG_MAX_COMPONENTS	4
16 #define V4L2_JPEG_MAX_TABLES		4
17 
18 /**
19  * struct v4l2_jpeg_reference - reference into the JPEG buffer
20  * @start: pointer to the start of the referenced segment or table
21  * @length: size of the referenced segment or table
22  *
23  * Wnen referencing marker segments, start points right after the marker code,
24  * and length is the size of the segment parameters, excluding the marker code.
25  */
26 struct v4l2_jpeg_reference {
27 	u8 *start;
28 	size_t length;
29 };
30 
31 /* B.2.2 Frame header syntax */
32 
33 /**
34  * struct v4l2_jpeg_frame_component_spec - frame component-specification
35  * @component_identifier: C[i]
36  * @horizontal_sampling_factor: H[i]
37  * @vertical_sampling_factor: V[i]
38  * @quantization_table_selector: quantization table destination selector Tq[i]
39  */
40 struct v4l2_jpeg_frame_component_spec {
41 	u8 component_identifier;
42 	u8 horizontal_sampling_factor;
43 	u8 vertical_sampling_factor;
44 	u8 quantization_table_selector;
45 };
46 
47 /**
48  * struct v4l2_jpeg_frame_header - JPEG frame header
49  * @height: Y
50  * @width: X
51  * @precision: P
52  * @num_components: Nf
53  * @component: component-specification, see v4l2_jpeg_frame_component_spec
54  * @subsampling: decoded subsampling from component-specification
55  */
56 struct v4l2_jpeg_frame_header {
57 	u16 height;
58 	u16 width;
59 	u8 precision;
60 	u8 num_components;
61 	struct v4l2_jpeg_frame_component_spec component[V4L2_JPEG_MAX_COMPONENTS];
62 	enum v4l2_jpeg_chroma_subsampling subsampling;
63 };
64 
65 /* B.2.3 Scan header syntax */
66 
67 /**
68  * struct v4l2_jpeg_scan_component_spec - scan component-specification
69  * @component_selector: Cs[j]
70  * @dc_entropy_coding_table_selector: Td[j]
71  * @ac_entropy_coding_table_selector: Ta[j]
72  */
73 struct v4l2_jpeg_scan_component_spec {
74 	u8 component_selector;
75 	u8 dc_entropy_coding_table_selector;
76 	u8 ac_entropy_coding_table_selector;
77 };
78 
79 /**
80  * struct v4l2_jpeg_scan_header - JPEG scan header
81  * @num_components: Ns
82  * @component: component-specification, see v4l2_jpeg_scan_component_spec
83  */
84 struct v4l2_jpeg_scan_header {
85 	u8 num_components;				/* Ns */
86 	struct v4l2_jpeg_scan_component_spec component[V4L2_JPEG_MAX_COMPONENTS];
87 	/* Ss, Se, Ah, and Al are not used by any driver */
88 };
89 
90 /**
91  * enum v4l2_jpeg_app14_tf - APP14 transform flag
92  * According to Rec. ITU-T T.872 (06/2012) 6.5.3
93  * APP14 segment is for color encoding, it contains a transform flag,
94  * which may have values of 0, 1 and 2 and are interpreted as follows:
95  * @V4L2_JPEG_APP14_TF_CMYK_RGB: CMYK for images encoded with four components
96  *                               RGB for images encoded with three components
97  * @V4L2_JPEG_APP14_TF_YCBCR: an image encoded with three components using YCbCr
98  * @V4L2_JPEG_APP14_TF_YCCK: an image encoded with four components using YCCK
99  * @V4L2_JPEG_APP14_TF_UNKNOWN: indicate app14 is not present
100  */
101 enum v4l2_jpeg_app14_tf {
102 	V4L2_JPEG_APP14_TF_CMYK_RGB	= 0,
103 	V4L2_JPEG_APP14_TF_YCBCR	= 1,
104 	V4L2_JPEG_APP14_TF_YCCK		= 2,
105 	V4L2_JPEG_APP14_TF_UNKNOWN	= -1,
106 };
107 
108 /**
109  * struct v4l2_jpeg_header - parsed JPEG header
110  * @sof: pointer to frame header and size
111  * @sos: pointer to scan header and size
112  * @num_dht: number of entries in @dht
113  * @dht: pointers to huffman tables and sizes
114  * @num_dqt: number of entries in @dqt
115  * @dqt: pointers to quantization tables and sizes
116  * @frame: parsed frame header
117  * @scan: pointer to parsed scan header, optional
118  * @quantization_tables: references to four quantization tables, optional
119  * @huffman_tables: references to four Huffman tables in DC0, DC1, AC0, AC1
120  *                  order, optional
121  * @restart_interval: number of MCU per restart interval, Ri
122  * @ecs_offset: buffer offset in bytes to the entropy coded segment
123  * @app14_tf: transform flag from app14 data
124  *
125  * When this structure is passed to v4l2_jpeg_parse_header, the optional scan,
126  * quantization_tables, and huffman_tables pointers must be initialized to NULL
127  * or point at valid memory.
128  */
129 struct v4l2_jpeg_header {
130 	struct v4l2_jpeg_reference sof;
131 	struct v4l2_jpeg_reference sos;
132 	unsigned int num_dht;
133 	struct v4l2_jpeg_reference dht[V4L2_JPEG_MAX_TABLES];
134 	unsigned int num_dqt;
135 	struct v4l2_jpeg_reference dqt[V4L2_JPEG_MAX_TABLES];
136 
137 	struct v4l2_jpeg_frame_header frame;
138 	struct v4l2_jpeg_scan_header *scan;
139 	struct v4l2_jpeg_reference *quantization_tables;
140 	struct v4l2_jpeg_reference *huffman_tables;
141 	u16 restart_interval;
142 	size_t ecs_offset;
143 	enum v4l2_jpeg_app14_tf app14_tf;
144 };
145 
146 int v4l2_jpeg_parse_header(void *buf, size_t len, struct v4l2_jpeg_header *out);
147 
148 int v4l2_jpeg_parse_frame_header(void *buf, size_t len,
149 				 struct v4l2_jpeg_frame_header *frame_header);
150 int v4l2_jpeg_parse_scan_header(void *buf, size_t len,
151 				struct v4l2_jpeg_scan_header *scan_header);
152 int v4l2_jpeg_parse_quantization_tables(void *buf, size_t len, u8 precision,
153 					struct v4l2_jpeg_reference *q_tables);
154 int v4l2_jpeg_parse_huffman_tables(void *buf, size_t len,
155 				   struct v4l2_jpeg_reference *huffman_tables);
156 
157 #endif
158