include/media/v4l2-jpeg.h

   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  * Prefixes used to generate huffman table class and destination identifiers as
  19  * described below:
  20  *
  21  * V4L2_JPEG_LUM_HT | V4L2_JPEG_DC_HT : Prefix for Luma DC coefficients
  22  *                                      huffman table
  23  * V4L2_JPEG_LUM_HT | V4L2_JPEG_AC_HT : Prefix for Luma AC coefficients
  24  *                                      huffman table
  25  * V4L2_JPEG_CHR_HT | V4L2_JPEG_DC_HT : Prefix for Chroma DC coefficients
  26  *                                      huffman table
  27  * V4L2_JPEG_CHR_HT | V4L2_JPEG_AC_HT : Prefix for Chroma AC coefficients
  28  *                                      huffman table
  29  */
  30 #define V4L2_JPEG_LUM_HT                0x00
  31 #define V4L2_JPEG_CHR_HT                0x01
  32 #define V4L2_JPEG_DC_HT                 0x00
  33 #define V4L2_JPEG_AC_HT                 0x10
  34
  35 /* Length of reference huffman tables as provided in Table K.3 of ITU-T.81 */
  36 #define V4L2_JPEG_REF_HT_AC_LEN         178
  37 #define V4L2_JPEG_REF_HT_DC_LEN         28
  38
  39 /* Array size for 8x8 block of samples or DCT coefficient */
  40 #define V4L2_JPEG_PIXELS_IN_BLOCK       64
  41
  42 /**
  43  * struct v4l2_jpeg_reference - reference into the JPEG buffer
  44  * @start: pointer to the start of the referenced segment or table
  45  * @length: size of the referenced segment or table
  46  *
  47  * Wnen referencing marker segments, start points right after the marker code,
  48  * and length is the size of the segment parameters, excluding the marker code.
  49  */
  50 struct v4l2_jpeg_reference {
  51         u8 *start;
  52         size_t length;
  53 };
  54
  55 /* B.2.2 Frame header syntax */
  56
  57 /**
  58  * struct v4l2_jpeg_frame_component_spec - frame component-specification
  59  * @component_identifier: C[i]
  60  * @horizontal_sampling_factor: H[i]
  61  * @vertical_sampling_factor: V[i]
  62  * @quantization_table_selector: quantization table destination selector Tq[i]
  63  */
  64 struct v4l2_jpeg_frame_component_spec {
  65         u8 component_identifier;
  66         u8 horizontal_sampling_factor;
  67         u8 vertical_sampling_factor;
  68         u8 quantization_table_selector;
  69 };
  70
  71 /**
  72  * struct v4l2_jpeg_frame_header - JPEG frame header
  73  * @height: Y
  74  * @width: X
  75  * @precision: P
  76  * @num_components: Nf
  77  * @component: component-specification, see v4l2_jpeg_frame_component_spec
  78  * @subsampling: decoded subsampling from component-specification
  79  */
  80 struct v4l2_jpeg_frame_header {
  81         u16 height;
  82         u16 width;
  83         u8 precision;
  84         u8 num_components;
  85         struct v4l2_jpeg_frame_component_spec component[V4L2_JPEG_MAX_COMPONENTS];
  86         enum v4l2_jpeg_chroma_subsampling subsampling;
  87 };
  88
  89 /* B.2.3 Scan header syntax */
  90
  91 /**
  92  * struct v4l2_jpeg_scan_component_spec - scan component-specification
  93  * @component_selector: Cs[j]
  94  * @dc_entropy_coding_table_selector: Td[j]
  95  * @ac_entropy_coding_table_selector: Ta[j]
  96  */
  97 struct v4l2_jpeg_scan_component_spec {
  98         u8 component_selector;
  99         u8 dc_entropy_coding_table_selector;
 100         u8 ac_entropy_coding_table_selector;
 101 };
 102
 103 /**
 104  * struct v4l2_jpeg_scan_header - JPEG scan header
 105  * @num_components: Ns
 106  * @component: component-specification, see v4l2_jpeg_scan_component_spec
 107  */
 108 struct v4l2_jpeg_scan_header {
 109         u8 num_components;                              /* Ns */
 110         struct v4l2_jpeg_scan_component_spec component[V4L2_JPEG_MAX_COMPONENTS];
 111         /* Ss, Se, Ah, and Al are not used by any driver */
 112 };
 113
 114 /**
 115  * enum v4l2_jpeg_app14_tf - APP14 transform flag
 116  * According to Rec. ITU-T T.872 (06/2012) 6.5.3
 117  * APP14 segment is for color encoding, it contains a transform flag,
 118  * which may have values of 0, 1 and 2 and are interpreted as follows:
 119  * @V4L2_JPEG_APP14_TF_CMYK_RGB: CMYK for images encoded with four components
 120  *                               RGB for images encoded with three components
 121  * @V4L2_JPEG_APP14_TF_YCBCR: an image encoded with three components using YCbCr
 122  * @V4L2_JPEG_APP14_TF_YCCK: an image encoded with four components using YCCK
 123  * @V4L2_JPEG_APP14_TF_UNKNOWN: indicate app14 is not present
 124  */
 125 enum v4l2_jpeg_app14_tf {
 126         V4L2_JPEG_APP14_TF_CMYK_RGB     = 0,
 127         V4L2_JPEG_APP14_TF_YCBCR        = 1,
 128         V4L2_JPEG_APP14_TF_YCCK         = 2,
 129         V4L2_JPEG_APP14_TF_UNKNOWN      = -1,
 130 };
 131
 132 /**
 133  * struct v4l2_jpeg_header - parsed JPEG header
 134  * @sof: pointer to frame header and size
 135  * @sos: pointer to scan header and size
 136  * @num_dht: number of entries in @dht
 137  * @dht: pointers to huffman tables and sizes
 138  * @num_dqt: number of entries in @dqt
 139  * @dqt: pointers to quantization tables and sizes
 140  * @frame: parsed frame header
 141  * @scan: pointer to parsed scan header, optional
 142  * @quantization_tables: references to four quantization tables, optional
 143  * @huffman_tables: references to four Huffman tables in DC0, DC1, AC0, AC1
 144  *                  order, optional
 145  * @restart_interval: number of MCU per restart interval, Ri
 146  * @ecs_offset: buffer offset in bytes to the entropy coded segment
 147  * @app14_tf: transform flag from app14 data
 148  *
 149  * When this structure is passed to v4l2_jpeg_parse_header, the optional scan,
 150  * quantization_tables, and huffman_tables pointers must be initialized to NULL
 151  * or point at valid memory.
 152  */
 153 struct v4l2_jpeg_header {
 154         struct v4l2_jpeg_reference sof;
 155         struct v4l2_jpeg_reference sos;
 156         unsigned int num_dht;
 157         struct v4l2_jpeg_reference dht[V4L2_JPEG_MAX_TABLES];
 158         unsigned int num_dqt;
 159         struct v4l2_jpeg_reference dqt[V4L2_JPEG_MAX_TABLES];
 160
 161         struct v4l2_jpeg_frame_header frame;
 162         struct v4l2_jpeg_scan_header *scan;
 163         struct v4l2_jpeg_reference *quantization_tables;
 164         struct v4l2_jpeg_reference *huffman_tables;
 165         u16 restart_interval;
 166         size_t ecs_offset;
 167         enum v4l2_jpeg_app14_tf app14_tf;
 168 };
 169
 170 int v4l2_jpeg_parse_header(void *buf, size_t len, struct v4l2_jpeg_header *out);
 171
 172 int v4l2_jpeg_parse_frame_header(void *buf, size_t len,
 173                                  struct v4l2_jpeg_frame_header *frame_header);
 174 int v4l2_jpeg_parse_scan_header(void *buf, size_t len,
 175                                 struct v4l2_jpeg_scan_header *scan_header);
 176 int v4l2_jpeg_parse_quantization_tables(void *buf, size_t len, u8 precision,
 177                                         struct v4l2_jpeg_reference *q_tables);
 178 int v4l2_jpeg_parse_huffman_tables(void *buf, size_t len,
 179                                    struct v4l2_jpeg_reference *huffman_tables);
 180
 181 extern const u8 v4l2_jpeg_zigzag_scan_index[V4L2_JPEG_PIXELS_IN_BLOCK];
 182 extern const u8 v4l2_jpeg_ref_table_luma_qt[V4L2_JPEG_PIXELS_IN_BLOCK];
 183 extern const u8 v4l2_jpeg_ref_table_chroma_qt[V4L2_JPEG_PIXELS_IN_BLOCK];
 184 extern const u8 v4l2_jpeg_ref_table_luma_dc_ht[V4L2_JPEG_REF_HT_DC_LEN];
 185 extern const u8 v4l2_jpeg_ref_table_luma_ac_ht[V4L2_JPEG_REF_HT_AC_LEN];
 186 extern const u8 v4l2_jpeg_ref_table_chroma_dc_ht[V4L2_JPEG_REF_HT_DC_LEN];
 187 extern const u8 v4l2_jpeg_ref_table_chroma_ac_ht[V4L2_JPEG_REF_HT_AC_LEN];
 188
 189 #endif