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