drivers/media/video/videocodec.h

   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  * 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 fuctions are just for convenience, as they are for sure used by
  60    most/all of the codecs. The last ones may be ommited, 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 \f
  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 videodev.h (VIDEO_MODE_*)
 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 \f
 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 \f
 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 \f
 219
 220 /* ========================= */
 221 /* the structures itself ... */
 222 /* ========================= */
 223
 224 struct vfe_polarity {
 225         int vsync_pol:1;
 226         int hsync_pol:1;
 227         int field_pol:1;
 228         int blank_pol:1;
 229         int subimg_pol:1;
 230         int poe_pol:1;
 231         int pvalid_pol:1;
 232         int vclk_pol:1;
 233 };
 234
 235 struct 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
 247 struct tvnorm {
 248         u16 Wt, Wa, HStart, HSyncStart, Ht, Ha, VStart;
 249 };
 250
 251 struct jpeg_com_marker {
 252         int len; /* number of usable bytes in data */
 253         char data[60];
 254 };
 255
 256 struct jpeg_app_marker {
 257         int appn; /* number app segment */
 258         int len; /* number of usable bytes in data */
 259         char data[60];
 260 };
 261
 262 struct 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
 321 struct 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 \f
 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
 346 extern struct videocodec *videocodec_attach(struct videocodec_master *);
 347 // * 0 on success, <0 (errno) on failure
 348 extern int videocodec_detach(struct videocodec *);
 349
 350 /* register and unregister commands for the slaves */
 351 // * 0 on success, <0 (errno) on failure
 352 extern int videocodec_register(const struct videocodec *);
 353 // * 0 on success, <0 (errno) on failure
 354 extern 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 */