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