drivers/staging/media/zoran/videocodec.h

   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 /* Should ease the (re-)usage of drivers supporting cards with (different)
  16    video codecs. The codecs register to this module their functionality,
  17    and the processors (masters) can attach to them if they fit.
  18
  19    The codecs are typically have a "strong" binding to their master - so I
  20    don't think it makes sense to have a full blown interfacing as with e.g.
  21    i2c. If you have an other opinion, let's discuss & implement it :-)))
  22
  23    Usage:
  24
  25    The slave has just to setup the videocodec structure and use two functions:
  26    videocodec_register(codecdata);
  27    videocodec_unregister(codecdata);
  28    The best is just calling them at module (de-)initialisation.
  29
  30    The master sets up the structure videocodec_master and calls:
  31    codecdata=videocodec_attach(master_codecdata);
  32    videocodec_detach(codecdata);
  33
  34    The slave is called during attach/detach via functions setup previously
  35    during register. At that time, the master_data pointer is set up
  36    and the slave can access any io registers of the master device (in the case
  37    the slave is bound to it). Otherwise it doesn't need this functions and
  38    therfor they may not be initialized.
  39
  40    The other functions are just for convenience, as they are for sure used by
  41    most/all of the codecs. The last ones may be omitted, too.
  42
  43    See the structure declaration below for more information and which data has
  44    to be set up for the master and the slave.
  45
  46    ----------------------------------------------------------------------------
  47    The master should have "knowledge" of the slave and vice versa.  So the data
  48    structures sent to/from slave via set_data/get_data set_image/get_image are
  49    device dependent and vary between MJPEG/MPEG/WAVELET/... devices. (!!!!)
  50    ----------------------------------------------------------------------------
  51 */
  52
  53 /* ========================================== */
  54 /* description of the videocodec_io structure */
  55 /* ========================================== */
  56
  57 /*
  58    ==== master setup ====
  59    name -> name of the device structure for reference and debugging
  60    master_data ->  data ref. for the master (e.g. the zr36055,57,67)
  61    readreg -> ref. to read-fn from register (setup by master, used by slave)
  62    writereg -> ref. to write-fn to register (setup by master, used by slave)
  63                this two functions do the lowlevel I/O job
  64
  65    ==== slave functionality setup ====
  66    slave_data -> data ref. for the slave (e.g. the zr36050,60)
  67    check -> fn-ref. checks availability of an device, returns -EIO on failure or
  68             the type on success
  69             this makes espcecially sense if a driver module supports more than
  70             one codec which may be quite similar to access, nevertheless it
  71             is good for a first functionality check
  72
  73    -- main functions you always need for compression/decompression --
  74
  75    set_mode -> this fn-ref. resets the entire codec, and sets up the mode
  76                with the last defined norm/size (or device default if not
  77                available) - it returns 0 if the mode is possible
  78    set_size -> this fn-ref. sets the norm and image size for
  79                compression/decompression (returns 0 on success)
  80                the norm param is defined in videodev2.h (V4L2_STD_*)
  81
  82    additional setup may be available, too - but the codec should work with
  83    some default values even without this
  84
  85    set_data -> sets device-specific data (tables, quality etc.)
  86    get_data -> query device-specific data (tables, quality etc.)
  87
  88    if the device delivers interrupts, they may be setup/handled here
  89    setup_interrupt -> codec irq setup (not needed for 36050/60)
  90    handle_interrupt -> codec irq handling (not needed for 36050/60)
  91
  92    if the device delivers pictures, they may be handled here
  93    put_image -> puts image data to the codec (not needed for 36050/60)
  94    get_image -> gets image data from the codec (not needed for 36050/60)
  95                 the calls include frame numbers and flags (even/odd/...)
  96                 if needed and a flag which allows blocking until its ready
  97 */
  98
  99 /* ============== */
 100 /* user interface */
 101 /* ============== */
 102
 103 /*
 104    Currently there is only a information display planned, as the layer
 105    is not visible for the user space at all.
 106
 107    Information is available via procfs. The current entry is "/proc/videocodecs"
 108    but it makes sense to "hide" it in the /proc/video tree of v4l(2) --TODO--.
 109
 110 A example for such an output is:
 111
 112 <S>lave or attached <M>aster name  type flags    magic    (connected as)
 113 S                          zr36050 0002 0000d001 00000000 (TEMPLATE)
 114 M                       zr36055[0] 0001 0000c001 00000000 (zr36050[0])
 115 M                       zr36055[1] 0001 0000c001 00000000 (zr36050[1])
 116
 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 extern struct videocodec *videocodec_attach(struct videocodec_master *);
 297 // * 0 on success, <0 (errno) on failure
 298 extern int videocodec_detach(struct videocodec *);
 299
 300 /* register and unregister commands for the slaves */
 301 // * 0 on success, <0 (errno) on failure
 302 extern int videocodec_register(const struct videocodec *);
 303 // * 0 on success, <0 (errno) on failure
 304 extern int videocodec_unregister(const struct videocodec *);
 305
 306 /* the other calls are directly done via the videocodec structure! */
 307
 308 int videocodec_debugfs_show(struct seq_file *m);
 309
 310 #endif                          /*ifndef __LINUX_VIDEOCODEC_H */