Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
videocodec.h
Go to the documentation of this file.
1 /*
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 <[email protected]>
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 
59  The other functions are just for convenience, as they are for sure used by
60  most/all of the codecs. The last ones may be omitted, too.
61 
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 /*
78  ==== master setup ====
79  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)
83  this two functions do the lowlevel I/O job
84 
85  ==== slave functionality setup ====
86  slave_data -> data ref. for the slave (e.g. the zr36050,60)
87  check -> fn-ref. checks availability of an device, returns -EIO on failure or
88  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
92 
93  -- main functions you always need for compression/decompression --
94 
95  set_mode -> this fn-ref. resets the entire codec, and sets up the mode
96  with the last defined norm/size (or device default if not
97  available) - it returns 0 if the mode is possible
98  set_size -> this fn-ref. sets the norm and image size for
99  compression/decompression (returns 0 on success)
100  the norm param is defined in videodev2.h (V4L2_STD_*)
101 
102  additional setup may be available, too - but the codec should work with
103  some default values even without this
104 
105  set_data -> sets device-specific data (tables, quality etc.)
106  get_data -> query device-specific data (tables, quality etc.)
107 
108  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)
111 
112  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
117 */
118 
119 /* ============== */
120 /* user interface */
121 /* ============== */
122 
123 /*
124  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 
130 A example for such an output is:
131 
132 <S>lave or attached <M>aster name type flags magic (connected as)
133 S zr36050 0002 0000d001 00000000 (TEMPLATE)
134 M zr36055[0] 0001 0000c001 00000000 (zr36050[0])
135 M 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/videodev2.h>
148 
149 #define CODEC_DO_COMPRESSION 0
150 #define CODEC_DO_EXPANSION 1
151 
152 /* this are the current codec flags I think they are needed */
153 /* -> type value in structure */
154 #define CODEC_FLAG_JPEG 0x00000001L // JPEG codec
155 #define CODEC_FLAG_MPEG 0x00000002L // MPEG1/2/4 codec
156 #define CODEC_FLAG_DIVX 0x00000004L // DIVX codec
157 #define CODEC_FLAG_WAVELET 0x00000008L // WAVELET codec
158  // room for other types
159 
160 #define CODEC_FLAG_MAGIC 0x00000800L // magic key must match
161 #define CODEC_FLAG_HARDWARE 0x00001000L // is a hardware codec
162 #define CODEC_FLAG_VFE 0x00002000L // has direct video frontend
163 #define CODEC_FLAG_ENCODER 0x00004000L // compression capability
164 #define CODEC_FLAG_DECODER 0x00008000L // decompression capability
165 #define CODEC_FLAG_NEEDIRQ 0x00010000L // needs irq handling
166 #define CODEC_FLAG_RDWRPIC 0x00020000L // handles picture I/O
167 
168 /* a list of modes, some are just examples (is there any HW?) */
169 #define CODEC_MODE_BJPG 0x0001 // Baseline JPEG
170 #define CODEC_MODE_LJPG 0x0002 // Lossless JPEG
171 #define CODEC_MODE_MPEG1 0x0003 // MPEG 1
172 #define CODEC_MODE_MPEG2 0x0004 // MPEG 2
173 #define CODEC_MODE_MPEG4 0x0005 // MPEG 4
174 #define CODEC_MODE_MSDIVX 0x0006 // MS DivX
175 #define CODEC_MODE_ODIVX 0x0007 // Open DivX
176 #define CODEC_MODE_WAVELET 0x0008 // Wavelet
177 
178 /* this are the current codec types I want to implement */
179 /* -> type value in structure */
180 #define CODEC_TYPE_NONE 0
181 #define CODEC_TYPE_L64702 1
182 #define CODEC_TYPE_ZR36050 2
183 #define CODEC_TYPE_ZR36016 3
184 #define CODEC_TYPE_ZR36060 4
185 
186 /* the type of data may be enhanced by future implementations (data-fn.'s) */
187 /* -> used in command */
188 #define CODEC_G_STATUS 0x0000 /* codec status (query only) */
189 #define CODEC_S_CODEC_MODE 0x0001 /* codec mode (baseline JPEG, MPEG1,... */
190 #define CODEC_G_CODEC_MODE 0x8001
191 #define CODEC_S_VFE 0x0002 /* additional video frontend setup */
192 #define CODEC_G_VFE 0x8002
193 #define CODEC_S_MMAP 0x0003 /* MMAP setup (if available) */
194 
195 #define CODEC_S_JPEG_TDS_BYTE 0x0010 /* target data size in bytes */
196 #define CODEC_G_JPEG_TDS_BYTE 0x8010
197 #define CODEC_S_JPEG_SCALE 0x0011 /* scaling factor for quant. tables */
198 #define CODEC_G_JPEG_SCALE 0x8011
199 #define CODEC_S_JPEG_HDT_DATA 0x0018 /* huffman-tables */
200 #define CODEC_G_JPEG_HDT_DATA 0x8018
201 #define CODEC_S_JPEG_QDT_DATA 0x0019 /* quantizing-tables */
202 #define CODEC_G_JPEG_QDT_DATA 0x8019
203 #define CODEC_S_JPEG_APP_DATA 0x001A /* APP marker */
204 #define CODEC_G_JPEG_APP_DATA 0x801A
205 #define CODEC_S_JPEG_COM_DATA 0x001B /* COM marker */
206 #define CODEC_G_JPEG_COM_DATA 0x801B
207 
208 #define CODEC_S_PRIVATE 0x1000 /* "private" commands start here */
209 #define CODEC_G_PRIVATE 0x9000
210 
211 #define CODEC_G_FLAG 0x8000 /* this is how 'get' is detected */
212 
213 /* types of transfer, directly user space or a kernel buffer (image-fn.'s) */
214 /* -> used in get_image, put_image */
215 #define CODEC_TRANSFER_KERNEL 0 /* use "memcopy" */
216 #define CODEC_TRANSFER_USER 1 /* use "to/from_user" */
217 
218 
219 /* ========================= */
220 /* the structures itself ... */
221 /* ========================= */
222 
223 struct vfe_polarity {
224  unsigned int vsync_pol:1;
225  unsigned int hsync_pol:1;
226  unsigned int field_pol:1;
227  unsigned int blank_pol:1;
228  unsigned int subimg_pol:1;
229  unsigned int poe_pol:1;
230  unsigned int pvalid_pol:1;
231  unsigned int vclk_pol:1;
232 };
233 
234 struct vfe_settings {
235  __u32 x, y; /* Offsets into image */
236  __u32 width, height; /* Area to capture */
237  __u16 decimation; /* Decimation divider */
238  __u16 flags; /* Flags for capture */
239  __u16 quality; /* quality of the video */
240 };
241 
242 struct tvnorm {
244 };
245 
247  int len; /* number of usable bytes in data */
248  char data[60];
249 };
250 
252  int appn; /* number app segment */
253  int len; /* number of usable bytes in data */
254  char data[60];
255 };
256 
257 struct videocodec {
258  struct module *owner;
259  /* -- filled in by slave device during register -- */
260  char name[32];
261  unsigned long magic; /* may be used for client<->master attaching */
262  unsigned long flags; /* functionality flags */
263  unsigned int type; /* codec type */
264 
265  /* -- these is filled in later during master device attach -- */
266 
268 
269  /* -- these are filled in by the slave device during register -- */
270 
271  void *data; /* private slave data */
272 
273  /* attach/detach client functions (indirect call) */
274  int (*setup) (struct videocodec * codec);
275  int (*unset) (struct videocodec * codec);
276 
277  /* main functions, every client needs them for sure! */
278  // set compression or decompression (or freeze, stop, standby, etc)
279  int (*set_mode) (struct videocodec * codec,
280  int mode);
281  // setup picture size and norm (for the codec's video frontend)
283  struct tvnorm * norm,
284  struct vfe_settings * cap,
285  struct vfe_polarity * pol);
286  // other control commands, also mmap setup etc.
287  int (*control) (struct videocodec * codec,
288  int type,
289  int size,
290  void *data);
291 
292  /* additional setup/query/processing (may be NULL pointer) */
293  // interrupt setup / handling (for irq's delivered by master)
295  long mode);
297  int source,
298  long flag);
299  // picture interface (if any)
301  int tr_type,
302  int block,
303  long *fr_num,
304  long *flag,
305  long size,
306  void *buf);
308  int tr_type,
309  int block,
310  long *fr_num,
311  long *flag,
312  long size,
313  void *buf);
314 };
315 
317  /* -- filled in by master device for registration -- */
318  char name[32];
319  unsigned long magic; /* may be used for client<->master attaching */
320  unsigned long flags; /* functionality flags */
321  unsigned int type; /* master type */
322 
323  void *data; /* private master data */
324 
326  __u16 reg);
328  __u16 reg,
329  __u32 value);
330 };
331 
332 
333 /* ================================================= */
334 /* function prototypes of the master/slave interface */
335 /* ================================================= */
336 
337 /* attach and detach commands for the master */
338 // * master structure needs to be kmalloc'ed before calling attach
339 // and free'd after calling detach
340 // * returns pointer on success, NULL on failure
341 extern struct videocodec *videocodec_attach(struct videocodec_master *);
342 // * 0 on success, <0 (errno) on failure
343 extern int videocodec_detach(struct videocodec *);
344 
345 /* register and unregister commands for the slaves */
346 // * 0 on success, <0 (errno) on failure
347 extern int videocodec_register(const struct videocodec *);
348 // * 0 on success, <0 (errno) on failure
349 extern int videocodec_unregister(const struct videocodec *);
350 
351 /* the other calls are directly done via the videocodec structure! */
352 
353 #endif /*ifndef __LINUX_VIDEOCODEC_H */