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