drivers/media/video/sn9c102/sn9c102_sensor.h

   1 /***************************************************************************
   2  * API for image sensors connected to the SN9C1xx PC Camera Controllers    *
   3  *                                                                         *
   4  * Copyright (C) 2004-2007 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/videodev2.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 SN9C1XX 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 in sn9c102_devtable.h;
  46    3) implement the methods that you want/need (and fill the rest of the main
  47       structure accordingly).
  48    "sn9c102_pas106b.c" is an example of all this stuff. Remember that you do
  49    NOT need to touch the source code of the core module for the things to work
  50    properly, unless you find bugs or flaws in it. Finally, do not forget to
  51    read the V4L2 API for completeness.
  52 */
  53
  54 /*****************************************************************************/
  55
  56 enum sn9c102_bridge {
  57         BRIDGE_SN9C101 = 0x01,
  58         BRIDGE_SN9C102 = 0x02,
  59         BRIDGE_SN9C103 = 0x04,
  60         BRIDGE_SN9C105 = 0x08,
  61         BRIDGE_SN9C120 = 0x10,
  62 };
  63
  64 /* Return the bridge name */
  65 enum sn9c102_bridge sn9c102_get_bridge(struct sn9c102_device* cam);
  66
  67 /* Return a pointer the sensor struct attached to the camera */
  68 struct sn9c102_sensor* sn9c102_get_sensor(struct sn9c102_device* cam);
  69
  70 /* Identify a device */
  71 extern struct sn9c102_device*
  72 sn9c102_match_id(struct sn9c102_device* cam, const struct usb_device_id *id);
  73
  74 /* Attach a probed sensor to the camera. */
  75 extern void
  76 sn9c102_attach_sensor(struct sn9c102_device* cam,
  77                       const struct sn9c102_sensor* sensor);
  78
  79 /*
  80    Read/write routines: they always return -1 on error, 0 or the read value
  81    otherwise. NOTE that a real read operation is not supported by the SN9C1XX
  82    chip for some of its registers. To work around this problem, a pseudo-read
  83    call is provided instead: it returns the last successfully written value
  84    on the register (0 if it has never been written), the usual -1 on error.
  85 */
  86
  87 /* The "try" I2C I/O versions are used when probing the sensor */
  88 extern int sn9c102_i2c_try_write(struct sn9c102_device*,
  89                                  const struct sn9c102_sensor*, u8 address,
  90                                  u8 value);
  91 extern int sn9c102_i2c_try_read(struct sn9c102_device*,
  92                                 const struct sn9c102_sensor*, u8 address);
  93
  94 /*
  95    These must be used if and only if the sensor doesn't implement the standard
  96    I2C protocol. There are a number of good reasons why you must use the
  97    single-byte versions of these functions: do not abuse. The first function
  98    writes n bytes, from data0 to datan, to registers 0x09 - 0x09+n of SN9C1XX
  99    chip. The second one programs the registers 0x09 and 0x10 with data0 and
 100    data1, and places the n bytes read from the sensor register table in the
 101    buffer pointed by 'buffer'. Both the functions return -1 on error; the write
 102    version returns 0 on success, while the read version returns the first read
 103    byte.
 104 */
 105 extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam,
 106                                      const struct sn9c102_sensor* sensor, u8 n,
 107                                      u8 data0, u8 data1, u8 data2, u8 data3,
 108                                      u8 data4, u8 data5);
 109 extern int sn9c102_i2c_try_raw_read(struct sn9c102_device* cam,
 110                                     const struct sn9c102_sensor* sensor,
 111                                     u8 data0, u8 data1, u8 n, u8 buffer[]);
 112
 113 /* To be used after the sensor struct has been attached to the camera struct */
 114 extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value);
 115 extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address);
 116
 117 /* I/O on registers in the bridge. Could be used by the sensor methods too */
 118 extern int sn9c102_read_reg(struct sn9c102_device*, u16 index);
 119 extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);
 120 extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
 121 extern int sn9c102_write_regs(struct sn9c102_device*, const u8 valreg[][2],
 122                               int count);
 123 /*
 124    Write multiple registers with constant values. For example:
 125    sn9c102_write_const_regs(cam, {0x00, 0x14}, {0x60, 0x17}, {0x0f, 0x18});
 126    Register adresses must be < 256.
 127 */
 128 #define sn9c102_write_const_regs(sn9c102_device, data...)                     \
 129         ({ const static u8 _valreg[][2] = {data};                             \
 130         sn9c102_write_regs(sn9c102_device, _valreg, ARRAY_SIZE(_valreg)); })
 131
 132 /*****************************************************************************/
 133
 134 enum sn9c102_i2c_sysfs_ops {
 135         SN9C102_I2C_READ = 0x01,
 136         SN9C102_I2C_WRITE = 0x02,
 137 };
 138
 139 enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */
 140         SN9C102_I2C_100KHZ = 0x01,
 141         SN9C102_I2C_400KHZ = 0x02,
 142 };
 143
 144 enum sn9c102_i2c_interface {
 145         SN9C102_I2C_2WIRES,
 146         SN9C102_I2C_3WIRES,
 147 };
 148
 149 #define SN9C102_MAX_CTRLS (V4L2_CID_LASTP1-V4L2_CID_BASE+10)
 150
 151 struct sn9c102_sensor {
 152         char name[32], /* sensor name */
 153              maintainer[64]; /* name of the mantainer <email> */
 154
 155         enum sn9c102_bridge supported_bridge; /* supported SN9C1xx bridges */
 156
 157         /* Supported operations through the 'sysfs' interface */
 158         enum sn9c102_i2c_sysfs_ops sysfs_ops;
 159
 160         /*
 161            These sensor capabilities must be provided if the SN9C1XX controller
 162            needs to communicate through the sensor serial interface by using
 163            at least one of the i2c functions available.
 164         */
 165         enum sn9c102_i2c_frequency frequency;
 166         enum sn9c102_i2c_interface interface;
 167
 168         /*
 169            This identifier must be provided if the image sensor implements
 170            the standard I2C protocol.
 171         */
 172         u8 i2c_slave_id; /* reg. 0x09 */
 173
 174         /*
 175            NOTE: Where not noted,most of the functions below are not mandatory.
 176                  Set to null if you do not implement them. If implemented,
 177                  they must return 0 on success, the proper error otherwise.
 178         */
 179
 180         int (*init)(struct sn9c102_device* cam);
 181         /*
 182            This function will be called after the sensor has been attached.
 183            It should be used to initialize the sensor only, but may also
 184            configure part of the SN9C1XX chip if necessary. You don't need to
 185            setup picture settings like brightness, contrast, etc.. here, if
 186            the corrisponding controls are implemented (see below), since
 187            they are adjusted in the core driver by calling the set_ctrl()
 188            method after init(), where the arguments are the default values
 189            specified in the v4l2_queryctrl list of supported controls;
 190            Same suggestions apply for other settings, _if_ the corresponding
 191            methods are present; if not, the initialization must configure the
 192            sensor according to the default configuration structures below.
 193         */
 194
 195         struct v4l2_queryctrl qctrl[SN9C102_MAX_CTRLS];
 196         /*
 197            Optional list of default controls, defined as indicated in the
 198            V4L2 API. Menu type controls are not handled by this interface.
 199         */
 200
 201         int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl);
 202         int (*set_ctrl)(struct sn9c102_device* cam,
 203                         const struct v4l2_control* ctrl);
 204         /*
 205            You must implement at least the set_ctrl method if you have defined
 206            the list above. The returned value must follow the V4L2
 207            specifications for the VIDIOC_G|C_CTRL ioctls. V4L2_CID_H|VCENTER
 208            are not supported by this driver, so do not implement them. Also,
 209            you don't have to check whether the passed values are out of bounds,
 210            given that this is done by the core module.
 211         */
 212
 213         struct v4l2_cropcap cropcap;
 214         /*
 215            Think the image sensor as a grid of R,G,B monochromatic pixels
 216            disposed according to a particular Bayer pattern, which describes
 217            the complete array of pixels, from (0,0) to (xmax, ymax). We will
 218            use this coordinate system from now on. It is assumed the sensor
 219            chip can be programmed to capture/transmit a subsection of that
 220            array of pixels: we will call this subsection "active window".
 221            It is not always true that the largest achievable active window can
 222            cover the whole array of pixels. The V4L2 API defines another
 223            area called "source rectangle", which, in turn, is a subrectangle of
 224            the active window. The SN9C1XX chip is always programmed to read the
 225            source rectangle.
 226            The bounds of both the active window and the source rectangle are
 227            specified in the cropcap substructures 'bounds' and 'defrect'.
 228            By default, the source rectangle should cover the largest possible
 229            area. Again, it is not always true that the largest source rectangle
 230            can cover the entire active window, although it is a rare case for
 231            the hardware we have. The bounds of the source rectangle _must_ be
 232            multiple of 16 and must use the same coordinate system as indicated
 233            before; their centers shall align initially.
 234            If necessary, the sensor chip must be initialized during init() to
 235            set the bounds of the active sensor window; however, by default, it
 236            usually covers the largest achievable area (maxwidth x maxheight)
 237            of pixels, so no particular initialization is needed, if you have
 238            defined the correct default bounds in the structures.
 239            See the V4L2 API for further details.
 240            NOTE: once you have defined the bounds of the active window
 241                  (struct cropcap.bounds) you must not change them.anymore.
 242            Only 'bounds' and 'defrect' fields are mandatory, other fields
 243            will be ignored.
 244         */
 245
 246         int (*set_crop)(struct sn9c102_device* cam,
 247                         const struct v4l2_rect* rect);
 248         /*
 249            To be called on VIDIOC_C_SETCROP. The core module always calls a
 250            default routine which configures the appropriate SN9C1XX regs (also
 251            scaling), but you may need to override/adjust specific stuff.
 252            'rect' contains width and height values that are multiple of 16: in
 253            case you override the default function, you always have to program
 254            the chip to match those values; on error return the corresponding
 255            error code without rolling back.
 256            NOTE: in case, you must program the SN9C1XX chip to get rid of
 257                  blank pixels or blank lines at the _start_ of each line or
 258                  frame after each HSYNC or VSYNC, so that the image starts with
 259                  real RGB data (see regs 0x12, 0x13) (having set H_SIZE and,
 260                  V_SIZE you don't have to care about blank pixels or blank
 261                  lines at the end of each line or frame).
 262         */
 263
 264         struct v4l2_pix_format pix_format;
 265         /*
 266            What you have to define here are: 1) initial 'width' and 'height' of
 267            the target rectangle 2) the initial 'pixelformat', which can be
 268            either V4L2_PIX_FMT_SN9C10X, V4L2_PIX_FMT_JPEG (for ompressed video)
 269            or V4L2_PIX_FMT_SBGGR8 3) 'priv', which we'll be used to indicate
 270            the number of bits per pixel for uncompressed video, 8 or 9 (despite
 271            the current value of 'pixelformat').
 272            NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4
 273                    of cropcap.defrect.width and cropcap.defrect.height. I
 274                    suggest 1/1.
 275            NOTE 2: The initial compression quality is defined by the first bit
 276                    of reg 0x17 during the initialization of the image sensor.
 277            NOTE 3: as said above, you have to program the SN9C1XX chip to get
 278                    rid of any blank pixels, so that the output of the sensor
 279                    matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR).
 280         */
 281
 282         int (*set_pix_format)(struct sn9c102_device* cam,
 283                               const struct v4l2_pix_format* pix);
 284         /*
 285            To be called on VIDIOC_S_FMT, when switching from the SBGGR8 to
 286            SN9C10X pixel format or viceversa. On error return the corresponding
 287            error code without rolling back.
 288         */
 289
 290         /*
 291            Do NOT write to the data below, it's READ ONLY. It is used by the
 292            core module to store successfully updated values of the above
 293            settings, for rollbacks..etc..in case of errors during atomic I/O
 294         */
 295         struct v4l2_queryctrl _qctrl[SN9C102_MAX_CTRLS];
 296         struct v4l2_rect _rect;
 297 };
 298
 299 /*****************************************************************************/
 300
 301 /* Private ioctl's for control settings supported by some image sensors */
 302 #define SN9C102_V4L2_CID_DAC_MAGNITUDE (V4L2_CID_PRIVATE_BASE + 0)
 303 #define SN9C102_V4L2_CID_GREEN_BALANCE (V4L2_CID_PRIVATE_BASE + 1)
 304 #define SN9C102_V4L2_CID_RESET_LEVEL (V4L2_CID_PRIVATE_BASE + 2)
 305 #define SN9C102_V4L2_CID_PIXEL_BIAS_VOLTAGE (V4L2_CID_PRIVATE_BASE + 3)
 306 #define SN9C102_V4L2_CID_GAMMA (V4L2_CID_PRIVATE_BASE + 4)
 307 #define SN9C102_V4L2_CID_BAND_FILTER (V4L2_CID_PRIVATE_BASE + 5)
 308 #define SN9C102_V4L2_CID_BRIGHT_LEVEL (V4L2_CID_PRIVATE_BASE + 6)
 309
 310 #endif /* _SN9C102_SENSOR_H_ */