xref: /linux/drivers/media/pci/zoran/videocodec.h (revision 4f2c0a4acffbec01079c28f839422e64ddeff004)
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3  * VIDEO MOTION CODECs internal API for video devices
4  *
5  * Interface for MJPEG (and maybe later MPEG/WAVELETS) codec's
6  * bound to a master device.
7  *
8  * (c) 2002 Wolfgang Scherr <scherr@net4you.at>
9  */
10 
11 /* =================== */
12 /* general description */
13 /* =================== */
14 
15 /*
16  * Should ease the (re-)usage of drivers supporting cards with (different)
17  * video codecs. The codecs register to this module their functionality,
18  * and the processors (masters) can attach to them if they fit.
19  *
20  * The codecs are typically have a "strong" binding to their master - so I
21  * don't think it makes sense to have a full blown interfacing as with e.g.
22  * i2c. If you have an other opinion, let's discuss & implement it :-)))
23  *
24  * Usage:
25  *
26  * The slave has just to setup the videocodec structure and use two functions:
27  * videocodec_register(codecdata);
28  * videocodec_unregister(codecdata);
29  * The best is just calling them at module (de-)initialisation.
30  *
31  * The master sets up the structure videocodec_master and calls:
32  * codecdata=videocodec_attach(master_codecdata);
33  * videocodec_detach(codecdata);
34  *
35  * The slave is called during attach/detach via functions setup previously
36  * during register. At that time, the master_data pointer is set up
37  * and the slave can access any io registers of the master device (in the case
38  * the slave is bound to it). Otherwise it doesn't need this functions and
39  * therefor they may not be initialized.
40  *
41  * The other functions are just for convenience, as they are for sure used by
42  * most/all of the codecs. The last ones may be omitted, too.
43  *
44  * See the structure declaration below for more information and which data has
45  * to be set up for the master and the slave.
46  *
47  * ----------------------------------------------------------------------------
48  * The master should have "knowledge" of the slave and vice versa.  So the data
49  * structures sent to/from slave via set_data/get_data set_image/get_image are
50  * device dependent and vary between MJPEG/MPEG/WAVELET/... devices. (!!!!)
51  * ----------------------------------------------------------------------------
52  */
53 
54 /* ========================================== */
55 /* description of the videocodec_io structure */
56 /* ========================================== */
57 
58 /*
59  * ==== master setup ====
60  * name -> name of the device structure for reference and debugging
61  * master_data ->  data ref. for the master (e.g. the zr36055,57,67)
62  * readreg -> ref. to read-fn from register (setup by master, used by slave)
63  * writereg -> ref. to write-fn to register (setup by master, used by slave)
64  *	       this two functions do the lowlevel I/O job
65  *
66  * ==== slave functionality setup ====
67  * slave_data -> data ref. for the slave (e.g. the zr36050,60)
68  * check -> fn-ref. checks availability of an device, returns -EIO on failure or
69  *	    the type on success
70  *	    this makes espcecially sense if a driver module supports more than
71  *	    one codec which may be quite similar to access, nevertheless it
72  *	    is good for a first functionality check
73  *
74  * -- main functions you always need for compression/decompression --
75  *
76  * set_mode -> this fn-ref. resets the entire codec, and sets up the mode
77  *	       with the last defined norm/size (or device default if not
78  *	       available) - it returns 0 if the mode is possible
79  * set_size -> this fn-ref. sets the norm and image size for
80  *	       compression/decompression (returns 0 on success)
81  *	       the norm param is defined in videodev2.h (V4L2_STD_*)
82  *
83  * additional setup may be available, too - but the codec should work with
84  * some default values even without this
85  *
86  * set_data -> sets device-specific data (tables, quality etc.)
87  * get_data -> query device-specific data (tables, quality etc.)
88  *
89  * if the device delivers interrupts, they may be setup/handled here
90  * setup_interrupt -> codec irq setup (not needed for 36050/60)
91  * handle_interrupt -> codec irq handling (not needed for 36050/60)
92 
93  * if the device delivers pictures, they may be handled here
94  * put_image -> puts image data to the codec (not needed for 36050/60)
95  * get_image -> gets image data from the codec (not needed for 36050/60)
96  *		the calls include frame numbers and flags (even/odd/...)
97  *		if needed and a flag which allows blocking until its ready
98  */
99 
100 /* ============== */
101 /* user interface */
102 /* ============== */
103 
104 /*
105  * Currently there is only a information display planned, as the layer
106  * is not visible for the user space at all.
107  *
108  * Information is available via procfs. The current entry is "/proc/videocodecs"
109  * but it makes sense to "hide" it in the /proc/video tree of v4l(2) --TODO--.
110  *
111  * A example for such an output is:
112  *
113  * <S>lave or attached <M>aster name  type flags    magic    (connected as)
114  * S                          zr36050 0002 0000d001 00000000 (TEMPLATE)
115  * M                       zr36055[0] 0001 0000c001 00000000 (zr36050[0])
116  * M                       zr36055[1] 0001 0000c001 00000000 (zr36050[1])
117  */
118 
119 /* =============================================== */
120 /* special defines for the videocodec_io structure */
121 /* =============================================== */
122 
123 #ifndef __LINUX_VIDEOCODEC_H
124 #define __LINUX_VIDEOCODEC_H
125 
126 #include <linux/debugfs.h>
127 #include <linux/videodev2.h>
128 
129 #define CODEC_DO_COMPRESSION 0
130 #define CODEC_DO_EXPANSION   1
131 
132 /* this are the current codec flags I think they are needed */
133 /*  -> type value in structure */
134 #define CODEC_FLAG_JPEG      0x00000001L	// JPEG codec
135 #define CODEC_FLAG_MPEG      0x00000002L	// MPEG1/2/4 codec
136 #define CODEC_FLAG_DIVX      0x00000004L	// DIVX codec
137 #define CODEC_FLAG_WAVELET   0x00000008L	// WAVELET codec
138 					  // room for other types
139 
140 #define CODEC_FLAG_MAGIC     0x00000800L	// magic key must match
141 #define CODEC_FLAG_HARDWARE  0x00001000L	// is a hardware codec
142 #define CODEC_FLAG_VFE       0x00002000L	// has direct video frontend
143 #define CODEC_FLAG_ENCODER   0x00004000L	// compression capability
144 #define CODEC_FLAG_DECODER   0x00008000L	// decompression capability
145 #define CODEC_FLAG_NEEDIRQ   0x00010000L	// needs irq handling
146 #define CODEC_FLAG_RDWRPIC   0x00020000L	// handles picture I/O
147 
148 /* a list of modes, some are just examples (is there any HW?) */
149 #define CODEC_MODE_BJPG      0x0001	// Baseline JPEG
150 #define CODEC_MODE_LJPG      0x0002	// Lossless JPEG
151 #define CODEC_MODE_MPEG1     0x0003	// MPEG 1
152 #define CODEC_MODE_MPEG2     0x0004	// MPEG 2
153 #define CODEC_MODE_MPEG4     0x0005	// MPEG 4
154 #define CODEC_MODE_MSDIVX    0x0006	// MS DivX
155 #define CODEC_MODE_ODIVX     0x0007	// Open DivX
156 #define CODEC_MODE_WAVELET   0x0008	// Wavelet
157 
158 /* this are the current codec types I want to implement */
159 /*  -> type value in structure */
160 #define CODEC_TYPE_NONE    0
161 #define CODEC_TYPE_L64702  1
162 #define CODEC_TYPE_ZR36050 2
163 #define CODEC_TYPE_ZR36016 3
164 #define CODEC_TYPE_ZR36060 4
165 
166 /* the type of data may be enhanced by future implementations (data-fn.'s) */
167 /*  -> used in command                                                     */
168 #define CODEC_G_STATUS         0x0000	/* codec status (query only) */
169 #define CODEC_S_CODEC_MODE     0x0001	/* codec mode (baseline JPEG, MPEG1,... */
170 #define CODEC_G_CODEC_MODE     0x8001
171 #define CODEC_S_VFE            0x0002	/* additional video frontend setup */
172 #define CODEC_G_VFE            0x8002
173 #define CODEC_S_MMAP           0x0003	/* MMAP setup (if available) */
174 
175 #define CODEC_S_JPEG_TDS_BYTE  0x0010	/* target data size in bytes */
176 #define CODEC_G_JPEG_TDS_BYTE  0x8010
177 #define CODEC_S_JPEG_SCALE     0x0011	/* scaling factor for quant. tables */
178 #define CODEC_G_JPEG_SCALE     0x8011
179 #define CODEC_S_JPEG_HDT_DATA  0x0018	/* huffman-tables */
180 #define CODEC_G_JPEG_HDT_DATA  0x8018
181 #define CODEC_S_JPEG_QDT_DATA  0x0019	/* quantizing-tables */
182 #define CODEC_G_JPEG_QDT_DATA  0x8019
183 #define CODEC_S_JPEG_APP_DATA  0x001A	/* APP marker */
184 #define CODEC_G_JPEG_APP_DATA  0x801A
185 #define CODEC_S_JPEG_COM_DATA  0x001B	/* COM marker */
186 #define CODEC_G_JPEG_COM_DATA  0x801B
187 
188 #define CODEC_S_PRIVATE        0x1000	/* "private" commands start here */
189 #define CODEC_G_PRIVATE        0x9000
190 
191 #define CODEC_G_FLAG           0x8000	/* this is how 'get' is detected */
192 
193 /* types of transfer, directly user space or a kernel buffer (image-fn.'s) */
194 /*  -> used in get_image, put_image */
195 #define CODEC_TRANSFER_KERNEL 0	/* use "memcopy" */
196 #define CODEC_TRANSFER_USER   1	/* use "to/from_user" */
197 
198 /* ========================= */
199 /* the structures itself ... */
200 /* ========================= */
201 
202 struct vfe_polarity {
203 	unsigned int vsync_pol:1;
204 	unsigned int hsync_pol:1;
205 	unsigned int field_pol:1;
206 	unsigned int blank_pol:1;
207 	unsigned int subimg_pol:1;
208 	unsigned int poe_pol:1;
209 	unsigned int pvalid_pol:1;
210 	unsigned int vclk_pol:1;
211 };
212 
213 struct vfe_settings {
214 	__u32 x, y;		/* Offsets into image */
215 	__u32 width, height;	/* Area to capture */
216 	__u16 decimation;	/* Decimation divider */
217 	__u16 flags;		/* Flags for capture */
218 	__u16 quality;		/* quality of the video */
219 };
220 
221 struct tvnorm {
222 	u16 wt, wa, h_start, h_sync_start, ht, ha, v_start;
223 };
224 
225 struct jpeg_com_marker {
226 	int len; /* number of usable bytes in data */
227 	char data[60];
228 };
229 
230 struct jpeg_app_marker {
231 	int appn; /* number app segment */
232 	int len; /* number of usable bytes in data */
233 	char data[60];
234 };
235 
236 struct videocodec {
237 	/* -- filled in by slave device during register -- */
238 	char name[32];
239 	unsigned long magic;	/* may be used for client<->master attaching */
240 	unsigned long flags;	/* functionality flags */
241 	unsigned int type;	/* codec type */
242 
243 	/* -- these is filled in later during master device attach -- */
244 
245 	struct videocodec_master *master_data;
246 
247 	/* -- these are filled in by the slave device during register -- */
248 
249 	void *data;		/* private slave data */
250 
251 	/* attach/detach client functions (indirect call) */
252 	int (*setup)(struct videocodec *codec);
253 	int (*unset)(struct videocodec *codec);
254 
255 	/* main functions, every client needs them for sure! */
256 	// set compression or decompression (or freeze, stop, standby, etc)
257 	int (*set_mode)(struct videocodec *codec, int mode);
258 	// setup picture size and norm (for the codec's video frontend)
259 	int (*set_video)(struct videocodec *codec, const struct tvnorm *norm,
260 			 struct vfe_settings *cap, struct vfe_polarity *pol);
261 	// other control commands, also mmap setup etc.
262 	int (*control)(struct videocodec *codec, int type, int size, void *data);
263 
264 	/* additional setup/query/processing (may be NULL pointer) */
265 	// interrupt setup / handling (for irq's delivered by master)
266 	int (*setup_interrupt)(struct videocodec *codec, long mode);
267 	int (*handle_interrupt)(struct videocodec *codec, int source, long flag);
268 	// picture interface (if any)
269 	long (*put_image)(struct videocodec *codec, int tr_type, int block,
270 			  long *fr_num, long *flag, long size, void *buf);
271 	long (*get_image)(struct videocodec *codec, int tr_type, int block,
272 			  long *fr_num, long *flag, long size, void *buf);
273 };
274 
275 struct videocodec_master {
276 	/* -- filled in by master device for registration -- */
277 	char name[32];
278 	unsigned long magic;	/* may be used for client<->master attaching */
279 	unsigned long flags;	/* functionality flags */
280 	unsigned int type;	/* master type */
281 
282 	void *data;		/* private master data */
283 
284 	__u32 (*readreg)(struct videocodec *codec, __u16 reg);
285 	void (*writereg)(struct videocodec *codec, __u16 reg, __u32 value);
286 };
287 
288 /* ================================================= */
289 /* function prototypes of the master/slave interface */
290 /* ================================================= */
291 
292 /* attach and detach commands for the master */
293 // * master structure needs to be kmalloc'ed before calling attach
294 //   and free'd after calling detach
295 // * returns pointer on success, NULL on failure
296 struct videocodec *videocodec_attach(struct videocodec_master *master);
297 // * 0 on success, <0 (errno) on failure
298 int videocodec_detach(struct videocodec *codec);
299 
300 /* register and unregister commands for the slaves */
301 // * 0 on success, <0 (errno) on failure
302 int videocodec_register(const struct videocodec *codec);
303 // * 0 on success, <0 (errno) on failure
304 int videocodec_unregister(const struct videocodec *codec);
305 
306 /* the other calls are directly done via the videocodec structure! */
307 
308 int videocodec_debugfs_show(struct seq_file *m);
309 
310 #include "zoran.h"
videocodec_master_to_zoran(struct videocodec_master * master)311 static inline struct zoran *videocodec_master_to_zoran(struct videocodec_master *master)
312 {
313 	struct zoran *zr = master->data;
314 
315 	return zr;
316 }
317 
videocodec_to_zoran(struct videocodec * codec)318 static inline struct zoran *videocodec_to_zoran(struct videocodec *codec)
319 {
320 	struct videocodec_master *master = codec->master_data;
321 
322 	return videocodec_master_to_zoran(master);
323 }
324 
325 #endif				/*ifndef __LINUX_VIDEOCODEC_H */
326