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