drivers/usb/media/sn9c102_sensor.h

   1 /***************************************************************************
   2  * API for image sensors connected to the SN9C10x PC Camera Controllers    *
   3  *                                                                         *
   4  * Copyright (C) 2004-2006 by Luca Risolia <luca.risolia@studio.unibo.it>  *
   5  *                                                                         *
   6  * This program is free software; you can redistribute it and/or modify    *
   7  * it under the terms of the GNU General Public License as published by    *
   8  * the Free Software Foundation; either version 2 of the License, or       *
   9  * (at your option) any later version.                                     *
  10  *                                                                         *
  11  * This program is distributed in the hope that it will be useful,         *
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of          *
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           *
  14  * GNU General Public License for more details.                            *
  15  *                                                                         *
  16  * You should have received a copy of the GNU General Public License       *
  17  * along with this program; if not, write to the Free Software             *
  18  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.               *
  19  ***************************************************************************/
  20
  21 #ifndef _SN9C102_SENSOR_H_
  22 #define _SN9C102_SENSOR_H_
  23
  24 #include <linux/usb.h>
  25 #include <linux/videodev.h>
  26 #include <linux/device.h>
  27 #include <linux/stddef.h>
  28 #include <linux/errno.h>
  29 #include <asm/types.h>
  30
  31 struct sn9c102_device;
  32 struct sn9c102_sensor;
  33
  34 /*****************************************************************************/
  35
  36 /*
  37    OVERVIEW.
  38    This is a small interface that allows you to add support for any CCD/CMOS
  39    image sensors connected to the SN9C10X bridges. The entire API is documented
  40    below. In the most general case, to support a sensor there are three steps
  41    you have to follow:
  42    1) define the main "sn9c102_sensor" structure by setting the basic fields;
  43    2) write a probing function to be called by the core module when the USB
  44       camera is recognized, then add both the USB ids and the name of that
  45       function to the two corresponding tables SENSOR_TABLE and ID_TABLE (see
  46       below);
  47    3) implement the methods that you want/need (and fill the rest of the main
  48       structure accordingly).
  49    "sn9c102_pas106b.c" is an example of all this stuff. Remember that you do
  50    NOT need to touch the source code of the core module for the things to work
  51    properly, unless you find bugs or flaws in it. Finally, do not forget to
  52    read the V4L2 API for completeness.
  53 */
  54
  55 /*****************************************************************************/
  56
  57 /*
  58    Probing functions: on success, you must attach the sensor to the camera
  59    by calling sn9c102_attach_sensor() provided below.
  60    To enable the I2C communication, you might need to perform a really basic
  61    initialization of the SN9C10X chip by using the write function declared
  62    ahead.
  63    Functions must return 0 on success, the appropriate error otherwise.
  64 */
  65 extern int sn9c102_probe_hv7131d(struct sn9c102_device* cam);
  66 extern int sn9c102_probe_mi0343(struct sn9c102_device* cam);
  67 extern int sn9c102_probe_ov7630(struct sn9c102_device* cam);
  68 extern int sn9c102_probe_pas106b(struct sn9c102_device* cam);
  69 extern int sn9c102_probe_pas202bcb(struct sn9c102_device* cam);
  70 extern int sn9c102_probe_tas5110c1b(struct sn9c102_device* cam);
  71 extern int sn9c102_probe_tas5130d1b(struct sn9c102_device* cam);
  72
  73 /*
  74    Add the above entries to this table. Be sure to add the entry in the right
  75    place, since, on failure, the next probing routine is called according to
  76    the order of the list below, from top to bottom.
  77 */
  78 #define SN9C102_SENSOR_TABLE                                                  \
  79 static int (*sn9c102_sensor_table[])(struct sn9c102_device*) = {              \
  80         &sn9c102_probe_mi0343, /* strong detection based on SENSOR ids */     \
  81         &sn9c102_probe_pas106b, /* strong detection based on SENSOR ids */    \
  82         &sn9c102_probe_pas202bcb, /* strong detection based on SENSOR ids */  \
  83         &sn9c102_probe_hv7131d, /* strong detection based on SENSOR ids */    \
  84         &sn9c102_probe_ov7630, /* detection mostly based on USB pid/vid */    \
  85         &sn9c102_probe_tas5110c1b, /* detection based on USB pid/vid */       \
  86         &sn9c102_probe_tas5130d1b, /* detection based on USB pid/vid */       \
  87         NULL,                                                                 \
  88 };
  89
  90 /* Attach a probed sensor to the camera. */
  91 extern void
  92 sn9c102_attach_sensor(struct sn9c102_device* cam,
  93                       struct sn9c102_sensor* sensor);
  94
  95 /*
  96    Each SN9C10x camera has proper PID/VID identifiers.
  97    SN9C103 supports multiple interfaces, but we only handle the video class
  98    interface.
  99 */
 100 #define SN9C102_USB_DEVICE(vend, prod, intclass)                              \
 101         .match_flags = USB_DEVICE_ID_MATCH_DEVICE |                           \
 102                        USB_DEVICE_ID_MATCH_INT_CLASS,                         \
 103         .idVendor = (vend),                                                   \
 104         .idProduct = (prod),                                                  \
 105         .bInterfaceClass = (intclass)
 106
 107 #define SN9C102_ID_TABLE                                                      \
 108 static const struct usb_device_id sn9c102_id_table[] = {                      \
 109         { USB_DEVICE(0x0c45, 0x6001), }, /* TAS5110C1B */                     \
 110         { USB_DEVICE(0x0c45, 0x6005), }, /* TAS5110C1B */                     \
 111         { USB_DEVICE(0x0c45, 0x6009), }, /* PAS106B */                        \
 112         { USB_DEVICE(0x0c45, 0x600d), }, /* PAS106B */                        \
 113         { USB_DEVICE(0x0c45, 0x6024), },                                      \
 114         { USB_DEVICE(0x0c45, 0x6025), }, /* TAS5130D1B and TAS5110C1B */      \
 115         { USB_DEVICE(0x0c45, 0x6028), }, /* PAS202BCB */                      \
 116         { USB_DEVICE(0x0c45, 0x6029), }, /* PAS106B */                        \
 117         { USB_DEVICE(0x0c45, 0x602a), }, /* HV7131D */                        \
 118         { USB_DEVICE(0x0c45, 0x602b), }, /* MI-0343 */                        \
 119         { USB_DEVICE(0x0c45, 0x602c), }, /* OV7630 */                         \
 120         { USB_DEVICE(0x0c45, 0x602d), },                                      \
 121         { USB_DEVICE(0x0c45, 0x602e), }, /* OV7630 */                         \
 122         { USB_DEVICE(0x0c45, 0x6030), }, /* MI03x */                          \
 123         { SN9C102_USB_DEVICE(0x0c45, 0x6080, 0xff), },                        \
 124         { SN9C102_USB_DEVICE(0x0c45, 0x6082, 0xff), }, /* MI0343 & MI0360 */  \
 125         { SN9C102_USB_DEVICE(0x0c45, 0x6083, 0xff), }, /* HV7131[D|E1] */     \
 126         { SN9C102_USB_DEVICE(0x0c45, 0x6088, 0xff), },                        \
 127         { SN9C102_USB_DEVICE(0x0c45, 0x608a, 0xff), },                        \
 128         { SN9C102_USB_DEVICE(0x0c45, 0x608b, 0xff), },                        \
 129         { SN9C102_USB_DEVICE(0x0c45, 0x608c, 0xff), }, /* HV7131x */          \
 130         { SN9C102_USB_DEVICE(0x0c45, 0x608e, 0xff), }, /* CIS-VF10 */         \
 131         { SN9C102_USB_DEVICE(0x0c45, 0x608f, 0xff), }, /* OV7630 */           \
 132         { SN9C102_USB_DEVICE(0x0c45, 0x60a0, 0xff), },                        \
 133         { SN9C102_USB_DEVICE(0x0c45, 0x60a2, 0xff), },                        \
 134         { SN9C102_USB_DEVICE(0x0c45, 0x60a3, 0xff), },                        \
 135         { SN9C102_USB_DEVICE(0x0c45, 0x60a8, 0xff), }, /* PAS106B */          \
 136         { SN9C102_USB_DEVICE(0x0c45, 0x60aa, 0xff), }, /* TAS5130D1B */       \
 137         { SN9C102_USB_DEVICE(0x0c45, 0x60ab, 0xff), }, /* TAS5110C1B */       \
 138         { SN9C102_USB_DEVICE(0x0c45, 0x60ac, 0xff), },                        \
 139         { SN9C102_USB_DEVICE(0x0c45, 0x60ae, 0xff), },                        \
 140         { SN9C102_USB_DEVICE(0x0c45, 0x60af, 0xff), }, /* PAS202BCB */        \
 141         { SN9C102_USB_DEVICE(0x0c45, 0x60b0, 0xff), }, /* OV7630 (?) */       \
 142         { SN9C102_USB_DEVICE(0x0c45, 0x60b2, 0xff), },                        \
 143         { SN9C102_USB_DEVICE(0x0c45, 0x60b3, 0xff), },                        \
 144         { SN9C102_USB_DEVICE(0x0c45, 0x60b8, 0xff), },                        \
 145         { SN9C102_USB_DEVICE(0x0c45, 0x60ba, 0xff), },                        \
 146         { SN9C102_USB_DEVICE(0x0c45, 0x60bb, 0xff), },                        \
 147         { SN9C102_USB_DEVICE(0x0c45, 0x60bc, 0xff), },                        \
 148         { SN9C102_USB_DEVICE(0x0c45, 0x60be, 0xff), },                        \
 149         { }                                                                   \
 150 };
 151
 152 /*****************************************************************************/
 153
 154 /*
 155    Read/write routines: they always return -1 on error, 0 or the read value
 156    otherwise. NOTE that a real read operation is not supported by the SN9C10X
 157    chip for some of its registers. To work around this problem, a pseudo-read
 158    call is provided instead: it returns the last successfully written value
 159    on the register (0 if it has never been written), the usual -1 on error.
 160 */
 161
 162 /* The "try" I2C I/O versions are used when probing the sensor */
 163 extern int sn9c102_i2c_try_write(struct sn9c102_device*,struct sn9c102_sensor*,
 164                                  u8 address, u8 value);
 165 extern int sn9c102_i2c_try_read(struct sn9c102_device*,struct sn9c102_sensor*,
 166                                 u8 address);
 167
 168 /*
 169    These must be used if and only if the sensor doesn't implement the standard
 170    I2C protocol. There are a number of good reasons why you must use the
 171    single-byte versions of these functions: do not abuse. The first function
 172    writes n bytes, from data0 to datan, to registers 0x09 - 0x09+n of SN9C10X
 173    chip. The second one programs the registers 0x09 and 0x10 with data0 and
 174    data1, and places the n bytes read from the sensor register table in the
 175    buffer pointed by 'buffer'. Both the functions return -1 on error; the write
 176    version returns 0 on success, while the read version returns the first read
 177    byte.
 178 */
 179 extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam,
 180                                      struct sn9c102_sensor* sensor, u8 n,
 181                                      u8 data0, u8 data1, u8 data2, u8 data3,
 182                                      u8 data4, u8 data5);
 183 extern int sn9c102_i2c_try_raw_read(struct sn9c102_device* cam,
 184                                     struct sn9c102_sensor* sensor, u8 data0,
 185                                     u8 data1, u8 n, u8 buffer[]);
 186
 187 /* To be used after the sensor struct has been attached to the camera struct */
 188 extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value);
 189 extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address);
 190
 191 /* I/O on registers in the bridge. Could be used by the sensor methods too */
 192 extern int sn9c102_write_regs(struct sn9c102_device*, u8* buff, u16 index);
 193 extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
 194 extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);
 195
 196 /*
 197    NOTE: there are no exported debugging functions. To uniform the output you
 198    must use the dev_info()/dev_warn()/dev_err() macros defined in device.h,
 199    already included here, the argument being the struct device 'dev' of the
 200    sensor structure. Do NOT use these macros before the sensor is attached or
 201    the kernel will crash! However, you should not need to notify the user about
 202    common errors or other messages, since this is done by the master module.
 203 */
 204
 205 /*****************************************************************************/
 206
 207 enum sn9c102_i2c_sysfs_ops {
 208         SN9C102_I2C_READ = 0x01,
 209         SN9C102_I2C_WRITE = 0x02,
 210 };
 211
 212 enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */
 213         SN9C102_I2C_100KHZ = 0x01,
 214         SN9C102_I2C_400KHZ = 0x02,
 215 };
 216
 217 enum sn9c102_i2c_interface {
 218         SN9C102_I2C_2WIRES,
 219         SN9C102_I2C_3WIRES,
 220 };
 221
 222 #define SN9C102_MAX_CTRLS V4L2_CID_LASTP1-V4L2_CID_BASE+10
 223
 224 struct sn9c102_sensor {
 225         char name[32], /* sensor name */
 226              maintainer[64]; /* name of the mantainer <email> */
 227
 228         /* Supported operations through the 'sysfs' interface */
 229         enum sn9c102_i2c_sysfs_ops sysfs_ops;
 230
 231         /*
 232            These sensor capabilities must be provided if the SN9C10X controller
 233            needs to communicate through the sensor serial interface by using
 234            at least one of the i2c functions available.
 235         */
 236         enum sn9c102_i2c_frequency frequency;
 237         enum sn9c102_i2c_interface interface;
 238
 239         /*
 240            This identifier must be provided if the image sensor implements
 241            the standard I2C protocol.
 242         */
 243         u8 i2c_slave_id; /* reg. 0x09 */
 244
 245         /*
 246            NOTE: Where not noted,most of the functions below are not mandatory.
 247                  Set to null if you do not implement them. If implemented,
 248                  they must return 0 on success, the proper error otherwise.
 249         */
 250
 251         int (*init)(struct sn9c102_device* cam);
 252         /*
 253            This function will be called after the sensor has been attached.
 254            It should be used to initialize the sensor only, but may also
 255            configure part of the SN9C10X chip if necessary. You don't need to
 256            setup picture settings like brightness, contrast, etc.. here, if
 257            the corrisponding controls are implemented (see below), since
 258            they are adjusted in the core driver by calling the set_ctrl()
 259            method after init(), where the arguments are the default values
 260            specified in the v4l2_queryctrl list of supported controls;
 261            Same suggestions apply for other settings, _if_ the corresponding
 262            methods are present; if not, the initialization must configure the
 263            sensor according to the default configuration structures below.
 264         */
 265
 266         struct v4l2_queryctrl qctrl[SN9C102_MAX_CTRLS];
 267         /*
 268            Optional list of default controls, defined as indicated in the
 269            V4L2 API. Menu type controls are not handled by this interface.
 270         */
 271
 272         int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl);
 273         int (*set_ctrl)(struct sn9c102_device* cam,
 274                         const struct v4l2_control* ctrl);
 275         /*
 276            You must implement at least the set_ctrl method if you have defined
 277            the list above. The returned value must follow the V4L2
 278            specifications for the VIDIOC_G|C_CTRL ioctls. V4L2_CID_H|VCENTER
 279            are not supported by this driver, so do not implement them. Also,
 280            you don't have to check whether the passed values are out of bounds,
 281            given that this is done by the core module.
 282         */
 283
 284         struct v4l2_cropcap cropcap;
 285         /*
 286            Think the image sensor as a grid of R,G,B monochromatic pixels
 287            disposed according to a particular Bayer pattern, which describes
 288            the complete array of pixels, from (0,0) to (xmax, ymax). We will
 289            use this coordinate system from now on. It is assumed the sensor
 290            chip can be programmed to capture/transmit a subsection of that
 291            array of pixels: we will call this subsection "active window".
 292            It is not always true that the largest achievable active window can
 293            cover the whole array of pixels. The V4L2 API defines another
 294            area called "source rectangle", which, in turn, is a subrectangle of
 295            the active window. The SN9C10X chip is always programmed to read the
 296            source rectangle.
 297            The bounds of both the active window and the source rectangle are
 298            specified in the cropcap substructures 'bounds' and 'defrect'.
 299            By default, the source rectangle should cover the largest possible
 300            area. Again, it is not always true that the largest source rectangle
 301            can cover the entire active window, although it is a rare case for
 302            the hardware we have. The bounds of the source rectangle _must_ be
 303            multiple of 16 and must use the same coordinate system as indicated
 304            before; their centers shall align initially.
 305            If necessary, the sensor chip must be initialized during init() to
 306            set the bounds of the active sensor window; however, by default, it
 307            usually covers the largest achievable area (maxwidth x maxheight)
 308            of pixels, so no particular initialization is needed, if you have
 309            defined the correct default bounds in the structures.
 310            See the V4L2 API for further details.
 311            NOTE: once you have defined the bounds of the active window
 312                  (struct cropcap.bounds) you must not change them.anymore.
 313            Only 'bounds' and 'defrect' fields are mandatory, other fields
 314            will be ignored.
 315         */
 316
 317         int (*set_crop)(struct sn9c102_device* cam,
 318                         const struct v4l2_rect* rect);
 319         /*
 320            To be called on VIDIOC_C_SETCROP. The core module always calls a
 321            default routine which configures the appropriate SN9C10X regs (also
 322            scaling), but you may need to override/adjust specific stuff.
 323            'rect' contains width and height values that are multiple of 16: in
 324            case you override the default function, you always have to program
 325            the chip to match those values; on error return the corresponding
 326            error code without rolling back.
 327            NOTE: in case, you must program the SN9C10X chip to get rid of
 328                  blank pixels or blank lines at the _start_ of each line or
 329                  frame after each HSYNC or VSYNC, so that the image starts with
 330                  real RGB data (see regs 0x12, 0x13) (having set H_SIZE and,
 331                  V_SIZE you don't have to care about blank pixels or blank
 332                  lines at the end of each line or frame).
 333         */
 334
 335         struct v4l2_pix_format pix_format;
 336         /*
 337            What you have to define here are: 1) initial 'width' and 'height' of
 338            the target rectangle 2) the initial 'pixelformat', which can be
 339            either V4L2_PIX_FMT_SN9C10X (for compressed video) or
 340            V4L2_PIX_FMT_SBGGR8 3) 'priv', which we'll be used to indicate the
 341            number of bits per pixel for uncompressed video, 8 or 9 (despite the
 342            current value of 'pixelformat').
 343            NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4
 344                    of cropcap.defrect.width and cropcap.defrect.height. I
 345                    suggest 1/1.
 346            NOTE 2: The initial compression quality is defined by the first bit
 347                    of reg 0x17 during the initialization of the image sensor.
 348            NOTE 3: as said above, you have to program the SN9C10X chip to get
 349                    rid of any blank pixels, so that the output of the sensor
 350                    matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR).
 351         */
 352
 353         int (*set_pix_format)(struct sn9c102_device* cam,
 354                               const struct v4l2_pix_format* pix);
 355         /*
 356            To be called on VIDIOC_S_FMT, when switching from the SBGGR8 to
 357            SN9C10X pixel format or viceversa. On error return the corresponding
 358            error code without rolling back.
 359         */
 360
 361         const struct device* dev;
 362         /*
 363            This is the argument for dev_err(), dev_info() and dev_warn(). It
 364            is used for debugging purposes. You must not access the struct
 365            before the sensor is attached.
 366         */
 367
 368         const struct usb_device* usbdev;
 369         /*
 370            Points to the usb_device struct after the sensor is attached.
 371            Do not touch unless you know what you are doing.
 372         */
 373
 374         /*
 375            Do NOT write to the data below, it's READ ONLY. It is used by the
 376            core module to store successfully updated values of the above
 377            settings, for rollbacks..etc..in case of errors during atomic I/O
 378         */
 379         struct v4l2_queryctrl _qctrl[SN9C102_MAX_CTRLS];
 380         struct v4l2_rect _rect;
 381 };
 382
 383 /*****************************************************************************/
 384
 385 /* Private ioctl's for control settings supported by some image sensors */
 386 #define SN9C102_V4L2_CID_DAC_MAGNITUDE V4L2_CID_PRIVATE_BASE
 387 #define SN9C102_V4L2_CID_GREEN_BALANCE V4L2_CID_PRIVATE_BASE + 1
 388 #define SN9C102_V4L2_CID_RESET_LEVEL V4L2_CID_PRIVATE_BASE + 2
 389 #define SN9C102_V4L2_CID_PIXEL_BIAS_VOLTAGE V4L2_CID_PRIVATE_BASE + 3
 390 #define SN9C102_V4L2_CID_GAMMA V4L2_CID_PRIVATE_BASE + 4
 391 #define SN9C102_V4L2_CID_BAND_FILTER V4L2_CID_PRIVATE_BASE + 5
 392 #define SN9C102_V4L2_CID_BRIGHT_LEVEL V4L2_CID_PRIVATE_BASE + 6
 393
 394 #endif /* _SN9C102_SENSOR_H_ */