Documentation/userspace-api/media/drivers/cx2341x-uapi.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The cx2341x driver
   4 ==================
   5
   6 Non-compressed file format
   7 --------------------------
   8
   9 The cx23416 can produce (and the cx23415 can also read) raw YUV output. The
  10 format of a YUV frame is 16x16 linear tiled NV12 (V4L2_PIX_FMT_NV12_16L16).
  11
  12 The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per
  13 four pixels.
  14
  15 The data is encoded as two macroblock planes, the first containing the Y
  16 values, the second containing UV macroblocks.
  17
  18 The Y plane is divided into blocks of 16x16 pixels from left to right
  19 and from top to bottom. Each block is transmitted in turn, line-by-line.
  20
  21 So the first 16 bytes are the first line of the top-left block, the
  22 second 16 bytes are the second line of the top-left block, etc. After
  23 transmitting this block the first line of the block on the right to the
  24 first block is transmitted, etc.
  25
  26 The UV plane is divided into blocks of 16x8 UV values going from left
  27 to right, top to bottom. Each block is transmitted in turn, line-by-line.
  28
  29 So the first 16 bytes are the first line of the top-left block and
  30 contain 8 UV value pairs (16 bytes in total). The second 16 bytes are the
  31 second line of 8 UV pairs of the top-left block, etc. After transmitting
  32 this block the first line of the block on the right to the first block is
  33 transmitted, etc.
  34
  35 The code below is given as an example on how to convert V4L2_PIX_FMT_NV12_16L16
  36 to separate Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels.
  37
  38 The width of a frame is always 720 pixels, regardless of the actual specified
  39 width.
  40
  41 If the height is not a multiple of 32 lines, then the captured video is
  42 missing macroblocks at the end and is unusable. So the height must be a
  43 multiple of 32.
  44
  45 Raw format c example
  46 ~~~~~~~~~~~~~~~~~~~~
  47
  48 .. code-block:: c
  49
  50         #include <stdio.h>
  51         #include <stdlib.h>
  52         #include <string.h>
  53
  54         static unsigned char frame[576*720*3/2];
  55         static unsigned char framey[576*720];
  56         static unsigned char frameu[576*720 / 4];
  57         static unsigned char framev[576*720 / 4];
  58
  59         static void de_macro_y(unsigned char* dst, unsigned char *src, int dstride, int w, int h)
  60         {
  61         unsigned int y, x, i;
  62
  63         // descramble Y plane
  64         // dstride = 720 = w
  65         // The Y plane is divided into blocks of 16x16 pixels
  66         // Each block in transmitted in turn, line-by-line.
  67         for (y = 0; y < h; y += 16) {
  68                 for (x = 0; x < w; x += 16) {
  69                 for (i = 0; i < 16; i++) {
  70                         memcpy(dst + x + (y + i) * dstride, src, 16);
  71                         src += 16;
  72                 }
  73                 }
  74         }
  75         }
  76
  77         static void de_macro_uv(unsigned char *dstu, unsigned char *dstv, unsigned char *src, int dstride, int w, int h)
  78         {
  79         unsigned int y, x, i;
  80
  81         // descramble U/V plane
  82         // dstride = 720 / 2 = w
  83         // The U/V values are interlaced (UVUV...).
  84         // Again, the UV plane is divided into blocks of 16x16 UV values.
  85         // Each block in transmitted in turn, line-by-line.
  86         for (y = 0; y < h; y += 16) {
  87                 for (x = 0; x < w; x += 8) {
  88                 for (i = 0; i < 16; i++) {
  89                         int idx = x + (y + i) * dstride;
  90
  91                         dstu[idx+0] = src[0];  dstv[idx+0] = src[1];
  92                         dstu[idx+1] = src[2];  dstv[idx+1] = src[3];
  93                         dstu[idx+2] = src[4];  dstv[idx+2] = src[5];
  94                         dstu[idx+3] = src[6];  dstv[idx+3] = src[7];
  95                         dstu[idx+4] = src[8];  dstv[idx+4] = src[9];
  96                         dstu[idx+5] = src[10]; dstv[idx+5] = src[11];
  97                         dstu[idx+6] = src[12]; dstv[idx+6] = src[13];
  98                         dstu[idx+7] = src[14]; dstv[idx+7] = src[15];
  99                         src += 16;
 100                 }
 101                 }
 102         }
 103         }
 104
 105         /*************************************************************************/
 106         int main(int argc, char **argv)
 107         {
 108         FILE *fin;
 109         int i;
 110
 111         if (argc == 1) fin = stdin;
 112         else fin = fopen(argv[1], "r");
 113
 114         if (fin == NULL) {
 115                 fprintf(stderr, "cannot open input\n");
 116                 exit(-1);
 117         }
 118         while (fread(frame, sizeof(frame), 1, fin) == 1) {
 119                 de_macro_y(framey, frame, 720, 720, 576);
 120                 de_macro_uv(frameu, framev, frame + 720 * 576, 720 / 2, 720 / 2, 576 / 2);
 121                 fwrite(framey, sizeof(framey), 1, stdout);
 122                 fwrite(framev, sizeof(framev), 1, stdout);
 123                 fwrite(frameu, sizeof(frameu), 1, stdout);
 124         }
 125         fclose(fin);
 126         return 0;
 127         }
 128
 129
 130 Format of embedded V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data
 131 ---------------------------------------------------------
 132
 133 Author: Hans Verkuil <hverkuil@xs4all.nl>
 134
 135
 136 This section describes the V4L2_MPEG_STREAM_VBI_FMT_IVTV format of the VBI data
 137 embedded in an MPEG-2 program stream. This format is in part dictated by some
 138 hardware limitations of the ivtv driver (the driver for the Conexant cx23415/6
 139 chips), in particular a maximum size for the VBI data. Anything longer is cut
 140 off when the MPEG stream is played back through the cx23415.
 141
 142 The advantage of this format is it is very compact and that all VBI data for
 143 all lines can be stored while still fitting within the maximum allowed size.
 144
 145 The stream ID of the VBI data is 0xBD. The maximum size of the embedded data is
 146 4 + 43 * 36, which is 4 bytes for a header and 2 * 18 VBI lines with a 1 byte
 147 header and a 42 bytes payload each. Anything beyond this limit is cut off by
 148 the cx23415/6 firmware. Besides the data for the VBI lines we also need 36 bits
 149 for a bitmask determining which lines are captured and 4 bytes for a magic cookie,
 150 signifying that this data package contains V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data.
 151 If all lines are used, then there is no longer room for the bitmask. To solve this
 152 two different magic numbers were introduced:
 153
 154 'itv0': After this magic number two unsigned longs follow. Bits 0-17 of the first
 155 unsigned long denote which lines of the first field are captured. Bits 18-31 of
 156 the first unsigned long and bits 0-3 of the second unsigned long are used for the
 157 second field.
 158
 159 'ITV0': This magic number assumes all VBI lines are captured, i.e. it implicitly
 160 implies that the bitmasks are 0xffffffff and 0xf.
 161
 162 After these magic cookies (and the 8 byte bitmask in case of cookie 'itv0') the
 163 captured VBI lines start:
 164
 165 For each line the least significant 4 bits of the first byte contain the data type.
 166 Possible values are shown in the table below. The payload is in the following 42
 167 bytes.
 168
 169 Here is the list of possible data types:
 170
 171 .. code-block:: c
 172
 173         #define IVTV_SLICED_TYPE_TELETEXT       0x1     // Teletext (uses lines 6-22 for PAL)
 174         #define IVTV_SLICED_TYPE_CC             0x4     // Closed Captions (line 21 NTSC)
 175         #define IVTV_SLICED_TYPE_WSS            0x5     // Wide Screen Signal (line 23 PAL)
 176         #define IVTV_SLICED_TYPE_VPS            0x7     // Video Programming System (PAL) (line 16)
 177