drivers/usb/media/sn9c102_sensor.h

   1 /***************************************************************************
   2  * API for image sensors connected to the SN9C10[12] PC Camera Controllers *
   3  *                                                                         *
   4  * Copyright (C) 2004 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_pas106b(struct sn9c102_device* cam);
  66 extern int sn9c102_probe_pas202bcb(struct sn9c102_device* cam);
  67 extern int sn9c102_probe_tas5110c1b(struct sn9c102_device* cam);
  68 extern int sn9c102_probe_tas5130d1b(struct sn9c102_device* cam);
  69
  70 /*
  71    Add the above entries to this table. Be sure to add the entry in the right
  72    place, since, on failure, the next probing routine is called according to
  73    the order of the list below, from top to bottom.
  74 */
  75 #define SN9C102_SENSOR_TABLE                                                  \
  76 static int (*sn9c102_sensor_table[])(struct sn9c102_device*) = {              \
  77         &sn9c102_probe_pas106b, /* strong detection based on SENSOR ids */    \
  78         &sn9c102_probe_pas202bcb, /* strong detection based on SENSOR ids */  \
  79         &sn9c102_probe_tas5110c1b, /* detection based on USB pid/vid */       \
  80         &sn9c102_probe_tas5130d1b, /* detection based on USB pid/vid */       \
  81         NULL,                                                                 \
  82 };
  83
  84 /* Attach a probed sensor to the camera. */
  85 extern void
  86 sn9c102_attach_sensor(struct sn9c102_device* cam,
  87                       struct sn9c102_sensor* sensor);
  88
  89 /* Each SN9C10X camera has proper PID/VID identifiers. Add them here in case.*/
  90 #define SN9C102_ID_TABLE                                                      \
  91 static const struct usb_device_id sn9c102_id_table[] = {                      \
  92         { USB_DEVICE(0xc45, 0x6001), }, /* TAS5110C1B */                      \
  93         { USB_DEVICE(0xc45, 0x6005), }, /* TAS5110C1B */                      \
  94         { USB_DEVICE(0xc45, 0x6009), }, /* PAS106B */                         \
  95         { USB_DEVICE(0xc45, 0x600d), }, /* PAS106B */                         \
  96         { USB_DEVICE(0xc45, 0x6024), },                                       \
  97         { USB_DEVICE(0xc45, 0x6025), }, /* TAS5130D1B and TAS5110C1B */       \
  98         { USB_DEVICE(0xc45, 0x6028), }, /* PAS202BCB */                       \
  99         { USB_DEVICE(0xc45, 0x6029), }, /* PAS106B */                         \
 100         { USB_DEVICE(0xc45, 0x602a), }, /* HV7131[D|E1] */                    \
 101         { USB_DEVICE(0xc45, 0x602c), }, /* OV7620 */                          \
 102         { USB_DEVICE(0xc45, 0x6030), }, /* MI03 */                            \
 103         { }                                                                   \
 104 };
 105
 106 /*****************************************************************************/
 107
 108 /*
 109    Read/write routines: they always return -1 on error, 0 or the read value
 110    otherwise. NOTE that a real read operation is not supported by the SN9C10X
 111    chip for some of its registers. To work around this problem, a pseudo-read
 112    call is provided instead: it returns the last successfully written value
 113    on the register (0 if it has never been written), the usual -1 on error.
 114 */
 115
 116 /* The "try" I2C I/O versions are used when probing the sensor */
 117 extern int sn9c102_i2c_try_write(struct sn9c102_device*,struct sn9c102_sensor*,
 118                                  u8 address, u8 value);
 119 extern int sn9c102_i2c_try_read(struct sn9c102_device*,struct sn9c102_sensor*,
 120                                 u8 address);
 121
 122 /*
 123    This must be used if and only if the sensor doesn't implement the standard
 124    I2C protocol. There a number of good reasons why you must use the
 125    single-byte versions of this function: do not abuse. It writes n bytes,
 126    from data0 to datan, (registers 0x09 - 0x09+n of SN9C10X chip).
 127 */
 128 extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam,
 129                                      struct sn9c102_sensor* sensor, u8 n,
 130                                      u8 data0, u8 data1, u8 data2, u8 data3,
 131                                      u8 data4, u8 data5);
 132
 133 /* To be used after the sensor struct has been attached to the camera struct */
 134 extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value);
 135 extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address);
 136
 137 /* I/O on registers in the bridge. Could be used by the sensor methods too */
 138 extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
 139 extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);
 140
 141 /*
 142    NOTE: there are no debugging functions here. To uniform the output you must
 143    use the dev_info()/dev_warn()/dev_err() macros defined in device.h, already
 144    included here, the argument being the struct device 'dev' of the sensor
 145    structure. Do NOT use these macros before the sensor is attached or the
 146    kernel will crash! However you should not need to notify the user about
 147    common errors or other messages, since this is done by the master module.
 148 */
 149
 150 /*****************************************************************************/
 151
 152 enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */
 153         SN9C102_I2C_100KHZ = 0x01,
 154         SN9C102_I2C_400KHZ = 0x02,
 155 };
 156
 157 enum sn9c102_i2c_interface {
 158         SN9C102_I2C_2WIRES,
 159         SN9C102_I2C_3WIRES,
 160 };
 161
 162 struct sn9c102_sensor {
 163         char name[32], /* sensor name */
 164              maintainer[64]; /* name of the mantainer <email> */
 165
 166         /*
 167            These sensor capabilities must be provided if the SN9C10X controller
 168            needs to communicate through the sensor serial interface by using
 169            at least one of the i2c functions available.
 170         */
 171         enum sn9c102_i2c_frequency frequency;
 172         enum sn9c102_i2c_interface interface;
 173
 174         /*
 175            These identifiers must be provided if the image sensor implements
 176            the standard I2C protocol. TASC sensors don't, although they have a
 177            serial interface: so this is a case where the "raw" I2C version
 178            could be helpful.
 179         */
 180         u8 slave_read_id, slave_write_id; /* reg. 0x09 */
 181
 182         /*
 183            NOTE: Where not noted,most of the functions below are not mandatory.
 184                  Set to null if you do not implement them. If implemented,
 185                  they must return 0 on success, the proper error otherwise.
 186         */
 187
 188         int (*init)(struct sn9c102_device* cam);
 189         /*
 190            This function is called after the sensor has been attached.
 191            It should be used to initialize the sensor only, but may also
 192            configure part of the SN9C10X chip if necessary. You don't need to
 193            setup picture settings like brightness, contrast, etc.. here, if
 194            the corrisponding controls are implemented (see below), since
 195            they are adjusted in the core driver by calling the set_ctrl()
 196            method after init(), where the arguments are the default values
 197            specified in the v4l2_queryctrl list of supported controls;
 198            Same suggestions apply for other settings, _if_ the corresponding
 199            methods are present; if not, the initialization must configure the
 200            sensor according to the default configuration structures below.
 201         */
 202
 203         struct v4l2_queryctrl qctrl[V4L2_CID_LASTP1-V4L2_CID_BASE];
 204         /*
 205            Optional list of default controls, defined as indicated in the
 206            V4L2 API. Menu type controls are not handled by this interface.
 207         */
 208
 209         int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl);
 210         int (*set_ctrl)(struct sn9c102_device* cam,
 211                         const struct v4l2_control* ctrl);
 212         /*
 213            You must implement at least the set_ctrl method if you have defined
 214            the list above. The returned value must follow the V4L2
 215            specifications for the VIDIOC_G|C_CTRL ioctls. V4L2_CID_H|VCENTER
 216            are not supported by this driver, so do not implement them. Also,
 217            passed values are NOT checked to see if they are out of bounds.
 218         */
 219
 220         struct v4l2_cropcap cropcap;
 221         /*
 222            Think the image sensor as a grid of R,G,B monochromatic pixels
 223            disposed according to a particular Bayer pattern, which describes
 224            the complete array of pixels, from (0,0) to (xmax, ymax). We will
 225            use this coordinate system from now on. It is assumed the sensor
 226            chip can be programmed to capture/transmit a subsection of that
 227            array of pixels: we will call this subsection "active window".
 228            It is not always true that the largest achievable active window can
 229            cover the whole array of pixels. The V4L2 API defines another
 230            area called "source rectangle", which, in turn, is a subrectangle of
 231            the active window. The SN9C10X chip is always programmed to read the
 232            source rectangle.
 233            The bounds of both the active window and the source rectangle are
 234            specified in the cropcap substructures 'bounds' and 'defrect'.
 235            By default, the source rectangle should cover the largest possible
 236            area. Again, it is not always true that the largest source rectangle
 237            can cover the entire active window, although it is a rare case for
 238            the hardware we have. The bounds of the source rectangle _must_ be
 239            multiple of 16 and must use the same coordinate system as indicated
 240            before; their centers shall align initially.
 241            If necessary, the sensor chip must be initialized during init() to
 242            set the bounds of the active sensor window; however, by default, it
 243            usually covers the largest achievable area (maxwidth x maxheight)
 244            of pixels, so no particular initialization is needed, if you have
 245            defined the correct default bounds in the structures.
 246            See the V4L2 API for further details.
 247            NOTE: once you have defined the bounds of the active window
 248                  (struct cropcap.bounds) you must not change them.anymore.
 249            Only 'bounds' and 'defrect' fields are mandatory, other fields
 250            will be ignored.
 251         */
 252
 253         int (*set_crop)(struct sn9c102_device* cam,
 254                         const struct v4l2_rect* rect);
 255         /*
 256            To be called on VIDIOC_C_SETCROP. The core module always calls a
 257            default routine which configures the appropriate SN9C10X regs (also
 258            scaling), but you may need to override/adjust specific stuff.
 259            'rect' contains width and height values that are multiple of 16: in
 260            case you override the default function, you always have to program
 261            the chip to match those values; on error return the corresponding
 262            error code without rolling back.
 263            NOTE: in case, you must program the SN9C10X chip to get rid of
 264                  blank pixels or blank lines at the _start_ of each line or
 265                  frame after each HSYNC or VSYNC, so that the image starts with
 266                  real RGB data (see regs 0x12,0x13) (having set H_SIZE and,
 267                  V_SIZE you don't have to care about blank pixels or blank
 268                  lines at the end of each line or frame).
 269         */
 270
 271         struct v4l2_pix_format pix_format;
 272         /*
 273            What you have to define here are: initial 'width' and 'height' of
 274            the target rectangle, the bayer 'pixelformat' and 'priv' which we'll
 275            be used to indicate the number of bits per pixel, 8 or 9.
 276            Nothing more.
 277            NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4
 278                    of cropcap.defrect.width and cropcap.defrect.height. I
 279                    suggest 1/1.
 280            NOTE 2: as said above, you have to program the SN9C10X chip to get
 281                    rid of any blank pixels, so that the output of the sensor
 282                    matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR).
 283         */
 284
 285         const struct device* dev;
 286         /*
 287            This is the argument for dev_err(), dev_info() and dev_warn(). It
 288            is used for debugging purposes. You must not access the struct
 289            before the sensor is attached.
 290         */
 291
 292         const struct usb_device* usbdev;
 293         /*
 294            Points to the usb_device struct after the sensor is attached.
 295            Do not touch unless you know what you are doing.
 296         */
 297
 298         /*
 299            Do NOT write to the data below, it's READ ONLY. It is used by the
 300            core module to store successfully updated values of the above
 301            settings, for rollbacks..etc..in case of errors during atomic I/O
 302         */
 303         struct v4l2_queryctrl _qctrl[V4L2_CID_LASTP1-V4L2_CID_BASE];
 304         struct v4l2_rect _rect;
 305 };
 306
 307 #endif /* _SN9C102_SENSOR_H_ */