blob: 97a3bbeda5056acfa1a9fed0f05b836d6ce08269 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/*
2 * VIDEO MOTION CODECs internal API for video devices
3 *
4 * Interface for MJPEG (and maybe later MPEG/WAVELETS) codec's
5 * bound to a master device.
6 *
7 * (c) 2002 Wolfgang Scherr <scherr@net4you.at>
8 *
9 * $Id: videocodec.h,v 1.1.2.4 2003/01/14 21:15:03 rbultje Exp $
10 *
11 * ------------------------------------------------------------------------
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
26 *
27 * ------------------------------------------------------------------------
28 */
29
30/* =================== */
31/* general description */
32/* =================== */
33
34/* Should ease the (re-)usage of drivers supporting cards with (different)
35 video codecs. The codecs register to this module their functionality,
36 and the processors (masters) can attach to them if they fit.
37
38 The codecs are typically have a "strong" binding to their master - so I
39 don't think it makes sense to have a full blown interfacing as with e.g.
40 i2c. If you have an other opinion, let's discuss & implement it :-)))
41
42 Usage:
43
44 The slave has just to setup the videocodec structure and use two functions:
45 videocodec_register(codecdata);
46 videocodec_unregister(codecdata);
47 The best is just calling them at module (de-)initialisation.
48
49 The master sets up the structure videocodec_master and calls:
50 codecdata=videocodec_attach(master_codecdata);
51 videocodec_detach(codecdata);
52
53 The slave is called during attach/detach via functions setup previously
54 during register. At that time, the master_data pointer is set up
55 and the slave can access any io registers of the master device (in the case
56 the slave is bound to it). Otherwise it doesn't need this functions and
57 therfor they may not be initialized.
58
Alexey Dobriyan8a598222006-03-07 22:20:23 -030059 The other fuctions are just for convenience, as they are for sure used by
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030060 most/all of the codecs. The last ones may be ommited, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -070061
62 See the structure declaration below for more information and which data has
63 to be set up for the master and the slave.
64
65 ----------------------------------------------------------------------------
66 The master should have "knowledge" of the slave and vice versa. So the data
67 structures sent to/from slave via set_data/get_data set_image/get_image are
68 device dependent and vary between MJPEG/MPEG/WAVELET/... devices. (!!!!)
69 ----------------------------------------------------------------------------
70*/
71
72
73/* ========================================== */
74/* description of the videocodec_io structure */
75/* ========================================== */
76
77/*
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030078 ==== master setup ====
Linus Torvalds1da177e2005-04-16 15:20:36 -070079 name -> name of the device structure for reference and debugging
80 master_data -> data ref. for the master (e.g. the zr36055,57,67)
81 readreg -> ref. to read-fn from register (setup by master, used by slave)
82 writereg -> ref. to write-fn to register (setup by master, used by slave)
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030083 this two functions do the lowlevel I/O job
Linus Torvalds1da177e2005-04-16 15:20:36 -070084
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030085 ==== slave functionality setup ====
86 slave_data -> data ref. for the slave (e.g. the zr36050,60)
Linus Torvalds1da177e2005-04-16 15:20:36 -070087 check -> fn-ref. checks availability of an device, returns -EIO on failure or
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030088 the type on success
89 this makes espcecially sense if a driver module supports more than
90 one codec which may be quite similar to access, nevertheless it
91 is good for a first functionality check
Linus Torvalds1da177e2005-04-16 15:20:36 -070092
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030093 -- main functions you always need for compression/decompression --
Linus Torvalds1da177e2005-04-16 15:20:36 -070094
95 set_mode -> this fn-ref. resets the entire codec, and sets up the mode
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030096 with the last defined norm/size (or device default if not
97 available) - it returns 0 if the mode is possible
Linus Torvalds1da177e2005-04-16 15:20:36 -070098 set_size -> this fn-ref. sets the norm and image size for
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030099 compression/decompression (returns 0 on success)
100 the norm param is defined in videodev.h (VIDEO_MODE_*)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101
102 additional setup may be available, too - but the codec should work with
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300103 some default values even without this
Linus Torvalds1da177e2005-04-16 15:20:36 -0700104
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300105 set_data -> sets device-specific data (tables, quality etc.)
106 get_data -> query device-specific data (tables, quality etc.)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700107
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300108 if the device delivers interrupts, they may be setup/handled here
109 setup_interrupt -> codec irq setup (not needed for 36050/60)
110 handle_interrupt -> codec irq handling (not needed for 36050/60)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700111
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300112 if the device delivers pictures, they may be handled here
113 put_image -> puts image data to the codec (not needed for 36050/60)
114 get_image -> gets image data from the codec (not needed for 36050/60)
115 the calls include frame numbers and flags (even/odd/...)
116 if needed and a flag which allows blocking until its ready
Linus Torvalds1da177e2005-04-16 15:20:36 -0700117*/
118
119/* ============== */
120/* user interface */
121/* ============== */
122
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300123/*
Linus Torvalds1da177e2005-04-16 15:20:36 -0700124 Currently there is only a information display planned, as the layer
125 is not visible for the user space at all.
126
127 Information is available via procfs. The current entry is "/proc/videocodecs"
128 but it makes sense to "hide" it in the /proc/video tree of v4l(2) --TODO--.
129
130A example for such an output is:
131
132<S>lave or attached <M>aster name type flags magic (connected as)
133S zr36050 0002 0000d001 00000000 (TEMPLATE)
134M zr36055[0] 0001 0000c001 00000000 (zr36050[0])
135M zr36055[1] 0001 0000c001 00000000 (zr36050[1])
136
137*/
138
139
140/* =============================================== */
141/* special defines for the videocodec_io structure */
142/* =============================================== */
143
144#ifndef __LINUX_VIDEOCODEC_H
145#define __LINUX_VIDEOCODEC_H
146
147#include <linux/videodev.h>
148
149//should be in videodev.h ??? (VID_DO_....)
150#define CODEC_DO_COMPRESSION 0
151#define CODEC_DO_EXPANSION 1
152
153/* this are the current codec flags I think they are needed */
154/* -> type value in structure */
155#define CODEC_FLAG_JPEG 0x00000001L // JPEG codec
156#define CODEC_FLAG_MPEG 0x00000002L // MPEG1/2/4 codec
157#define CODEC_FLAG_DIVX 0x00000004L // DIVX codec
158#define CODEC_FLAG_WAVELET 0x00000008L // WAVELET codec
159 // room for other types
160
161#define CODEC_FLAG_MAGIC 0x00000800L // magic key must match
162#define CODEC_FLAG_HARDWARE 0x00001000L // is a hardware codec
163#define CODEC_FLAG_VFE 0x00002000L // has direct video frontend
164#define CODEC_FLAG_ENCODER 0x00004000L // compression capability
165#define CODEC_FLAG_DECODER 0x00008000L // decompression capability
166#define CODEC_FLAG_NEEDIRQ 0x00010000L // needs irq handling
167#define CODEC_FLAG_RDWRPIC 0x00020000L // handles picture I/O
168
169/* a list of modes, some are just examples (is there any HW?) */
170#define CODEC_MODE_BJPG 0x0001 // Baseline JPEG
171#define CODEC_MODE_LJPG 0x0002 // Lossless JPEG
172#define CODEC_MODE_MPEG1 0x0003 // MPEG 1
173#define CODEC_MODE_MPEG2 0x0004 // MPEG 2
174#define CODEC_MODE_MPEG4 0x0005 // MPEG 4
175#define CODEC_MODE_MSDIVX 0x0006 // MS DivX
176#define CODEC_MODE_ODIVX 0x0007 // Open DivX
177#define CODEC_MODE_WAVELET 0x0008 // Wavelet
178
179/* this are the current codec types I want to implement */
180/* -> type value in structure */
181#define CODEC_TYPE_NONE 0
182#define CODEC_TYPE_L64702 1
183#define CODEC_TYPE_ZR36050 2
184#define CODEC_TYPE_ZR36016 3
185#define CODEC_TYPE_ZR36060 4
186
187/* the type of data may be enhanced by future implementations (data-fn.'s) */
188/* -> used in command */
189#define CODEC_G_STATUS 0x0000 /* codec status (query only) */
190#define CODEC_S_CODEC_MODE 0x0001 /* codec mode (baseline JPEG, MPEG1,... */
191#define CODEC_G_CODEC_MODE 0x8001
192#define CODEC_S_VFE 0x0002 /* additional video frontend setup */
193#define CODEC_G_VFE 0x8002
194#define CODEC_S_MMAP 0x0003 /* MMAP setup (if available) */
195
196#define CODEC_S_JPEG_TDS_BYTE 0x0010 /* target data size in bytes */
197#define CODEC_G_JPEG_TDS_BYTE 0x8010
198#define CODEC_S_JPEG_SCALE 0x0011 /* scaling factor for quant. tables */
199#define CODEC_G_JPEG_SCALE 0x8011
200#define CODEC_S_JPEG_HDT_DATA 0x0018 /* huffman-tables */
201#define CODEC_G_JPEG_HDT_DATA 0x8018
202#define CODEC_S_JPEG_QDT_DATA 0x0019 /* quantizing-tables */
203#define CODEC_G_JPEG_QDT_DATA 0x8019
204#define CODEC_S_JPEG_APP_DATA 0x001A /* APP marker */
205#define CODEC_G_JPEG_APP_DATA 0x801A
206#define CODEC_S_JPEG_COM_DATA 0x001B /* COM marker */
207#define CODEC_G_JPEG_COM_DATA 0x801B
208
209#define CODEC_S_PRIVATE 0x1000 /* "private" commands start here */
210#define CODEC_G_PRIVATE 0x9000
211
212#define CODEC_G_FLAG 0x8000 /* this is how 'get' is detected */
213
214/* types of transfer, directly user space or a kernel buffer (image-fn.'s) */
215/* -> used in get_image, put_image */
216#define CODEC_TRANSFER_KERNEL 0 /* use "memcopy" */
217#define CODEC_TRANSFER_USER 1 /* use "to/from_user" */
218
219
220/* ========================= */
221/* the structures itself ... */
222/* ========================= */
223
224struct vfe_polarity {
Randy Dunlap0a115372006-06-28 15:05:11 -0300225 unsigned int vsync_pol:1;
226 unsigned int hsync_pol:1;
227 unsigned int field_pol:1;
228 unsigned int blank_pol:1;
229 unsigned int subimg_pol:1;
230 unsigned int poe_pol:1;
231 unsigned int pvalid_pol:1;
232 unsigned int vclk_pol:1;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233};
234
235struct vfe_settings {
236 __u32 x, y; /* Offsets into image */
237 __u32 width, height; /* Area to capture */
238 __u16 decimation; /* Decimation divider */
239 __u16 flags; /* Flags for capture */
240/* flags are the same as in struct video_capture - see videodev.h:
241#define VIDEO_CAPTURE_ODD 0
242#define VIDEO_CAPTURE_EVEN 1
243*/
244 __u16 quality; /* quality of the video */
245};
246
247struct tvnorm {
248 u16 Wt, Wa, HStart, HSyncStart, Ht, Ha, VStart;
249};
250
251struct jpeg_com_marker {
252 int len; /* number of usable bytes in data */
253 char data[60];
254};
255
256struct jpeg_app_marker {
257 int appn; /* number app segment */
258 int len; /* number of usable bytes in data */
259 char data[60];
260};
261
262struct videocodec {
263 struct module *owner;
264 /* -- filled in by slave device during register -- */
265 char name[32];
266 unsigned long magic; /* may be used for client<->master attaching */
267 unsigned long flags; /* functionality flags */
268 unsigned int type; /* codec type */
269
270 /* -- these is filled in later during master device attach -- */
271
272 struct videocodec_master *master_data;
273
274 /* -- these are filled in by the slave device during register -- */
275
276 void *data; /* private slave data */
277
278 /* attach/detach client functions (indirect call) */
279 int (*setup) (struct videocodec * codec);
280 int (*unset) (struct videocodec * codec);
281
282 /* main functions, every client needs them for sure! */
283 // set compression or decompression (or freeze, stop, standby, etc)
284 int (*set_mode) (struct videocodec * codec,
285 int mode);
286 // setup picture size and norm (for the codec's video frontend)
287 int (*set_video) (struct videocodec * codec,
288 struct tvnorm * norm,
289 struct vfe_settings * cap,
290 struct vfe_polarity * pol);
291 // other control commands, also mmap setup etc.
292 int (*control) (struct videocodec * codec,
293 int type,
294 int size,
295 void *data);
296
297 /* additional setup/query/processing (may be NULL pointer) */
298 // interrupt setup / handling (for irq's delivered by master)
299 int (*setup_interrupt) (struct videocodec * codec,
300 long mode);
301 int (*handle_interrupt) (struct videocodec * codec,
302 int source,
303 long flag);
304 // picture interface (if any)
305 long (*put_image) (struct videocodec * codec,
306 int tr_type,
307 int block,
308 long *fr_num,
309 long *flag,
310 long size,
311 void *buf);
312 long (*get_image) (struct videocodec * codec,
313 int tr_type,
314 int block,
315 long *fr_num,
316 long *flag,
317 long size,
318 void *buf);
319};
320
321struct videocodec_master {
322 /* -- filled in by master device for registration -- */
323 char name[32];
324 unsigned long magic; /* may be used for client<->master attaching */
325 unsigned long flags; /* functionality flags */
326 unsigned int type; /* master type */
327
328 void *data; /* private master data */
329
330 __u32(*readreg) (struct videocodec * codec,
331 __u16 reg);
332 void (*writereg) (struct videocodec * codec,
333 __u16 reg,
334 __u32 value);
335};
336
337
338/* ================================================= */
339/* function prototypes of the master/slave interface */
340/* ================================================= */
341
342/* attach and detach commands for the master */
343// * master structure needs to be kmalloc'ed before calling attach
344// and free'd after calling detach
345// * returns pointer on success, NULL on failure
346extern struct videocodec *videocodec_attach(struct videocodec_master *);
347// * 0 on success, <0 (errno) on failure
348extern int videocodec_detach(struct videocodec *);
349
350/* register and unregister commands for the slaves */
351// * 0 on success, <0 (errno) on failure
352extern int videocodec_register(const struct videocodec *);
353// * 0 on success, <0 (errno) on failure
354extern int videocodec_unregister(const struct videocodec *);
355
356/* the other calls are directly done via the videocodec structure! */
357
358#endif /*ifndef __LINUX_VIDEOCODEC_H */