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