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