]>
Commit | Line | Data |
---|---|---|
1da177e4 | 1 | /*************************************************************************** |
f327ebbd | 2 | * API for image sensors connected to the SN9C1xx PC Camera Controllers * |
1da177e4 | 3 | * * |
f327ebbd | 4 | * Copyright (C) 2004-2007 by Luca Risolia <luca.risolia@studio.unibo.it> * |
1da177e4 LT |
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> | |
480b55c2 | 25 | #include <linux/videodev2.h> |
1da177e4 LT |
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 | |
f327ebbd | 39 | image sensors connected to the SN9C1XX bridges. The entire API is documented |
1da177e4 LT |
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 | |
f327ebbd | 45 | function to the two corresponding tables in sn9c102_devtable.h; |
1da177e4 LT |
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 | ||
f327ebbd LR |
56 | enum sn9c102_bridge { |
57 | BRIDGE_SN9C101 = 0x01, | |
58 | BRIDGE_SN9C102 = 0x02, | |
59 | BRIDGE_SN9C103 = 0x04, | |
60 | BRIDGE_SN9C105 = 0x08, | |
61 | BRIDGE_SN9C120 = 0x10, | |
1da177e4 LT |
62 | }; |
63 | ||
f327ebbd LR |
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 */ | |
2ffab02f LR |
71 | extern struct sn9c102_device* |
72 | sn9c102_match_id(struct sn9c102_device* cam, const struct usb_device_id *id); | |
73 | ||
1da177e4 | 74 | /* Attach a probed sensor to the camera. */ |
d56410e0 | 75 | extern void |
1da177e4 | 76 | sn9c102_attach_sensor(struct sn9c102_device* cam, |
480b55c2 | 77 | const struct sn9c102_sensor* sensor); |
1da177e4 | 78 | |
1da177e4 LT |
79 | /* |
80 | Read/write routines: they always return -1 on error, 0 or the read value | |
f327ebbd | 81 | otherwise. NOTE that a real read operation is not supported by the SN9C1XX |
1da177e4 | 82 | chip for some of its registers. To work around this problem, a pseudo-read |
d56410e0 | 83 | call is provided instead: it returns the last successfully written value |
1da177e4 LT |
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 */ | |
480b55c2 LR |
88 | extern int sn9c102_i2c_try_read(struct sn9c102_device*, |
89 | const struct sn9c102_sensor*, u8 address); | |
1da177e4 LT |
90 | |
91 | /* | |
92 | These must be used if and only if the sensor doesn't implement the standard | |
d56410e0 | 93 | I2C protocol. There are a number of good reasons why you must use the |
1da177e4 | 94 | single-byte versions of these functions: do not abuse. The first function |
f327ebbd | 95 | writes n bytes, from data0 to datan, to registers 0x09 - 0x09+n of SN9C1XX |
1da177e4 LT |
96 | chip. The second one programs the registers 0x09 and 0x10 with data0 and |
97 | data1, and places the n bytes read from the sensor register table in the | |
98 | buffer pointed by 'buffer'. Both the functions return -1 on error; the write | |
99 | version returns 0 on success, while the read version returns the first read | |
100 | byte. | |
101 | */ | |
102 | extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam, | |
480b55c2 | 103 | const struct sn9c102_sensor* sensor, u8 n, |
d56410e0 MCC |
104 | u8 data0, u8 data1, u8 data2, u8 data3, |
105 | u8 data4, u8 data5); | |
1da177e4 | 106 | extern int sn9c102_i2c_try_raw_read(struct sn9c102_device* cam, |
480b55c2 LR |
107 | const struct sn9c102_sensor* sensor, |
108 | u8 data0, u8 data1, u8 n, u8 buffer[]); | |
1da177e4 LT |
109 | |
110 | /* To be used after the sensor struct has been attached to the camera struct */ | |
111 | extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value); | |
112 | extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address); | |
113 | ||
114 | /* I/O on registers in the bridge. Could be used by the sensor methods too */ | |
480b55c2 | 115 | extern int sn9c102_read_reg(struct sn9c102_device*, u16 index); |
1da177e4 | 116 | extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index); |
c680dd60 TP |
117 | extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index); |
118 | extern int sn9c102_write_regs(struct sn9c102_device*, const u8 valreg[][2], | |
119 | int count); | |
120 | /* | |
480b55c2 LR |
121 | Write multiple registers with constant values. For example: |
122 | sn9c102_write_const_regs(cam, {0x00, 0x14}, {0x60, 0x17}, {0x0f, 0x18}); | |
3ad2f3fb | 123 | Register addresses must be < 256. |
480b55c2 LR |
124 | */ |
125 | #define sn9c102_write_const_regs(sn9c102_device, data...) \ | |
22d56fce | 126 | ({ static const u8 _valreg[][2] = {data}; \ |
480b55c2 | 127 | sn9c102_write_regs(sn9c102_device, _valreg, ARRAY_SIZE(_valreg)); }) |
1da177e4 | 128 | |
1da177e4 LT |
129 | /*****************************************************************************/ |
130 | ||
131 | enum sn9c102_i2c_sysfs_ops { | |
132 | SN9C102_I2C_READ = 0x01, | |
133 | SN9C102_I2C_WRITE = 0x02, | |
134 | }; | |
135 | ||
136 | enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */ | |
137 | SN9C102_I2C_100KHZ = 0x01, | |
138 | SN9C102_I2C_400KHZ = 0x02, | |
139 | }; | |
140 | ||
141 | enum sn9c102_i2c_interface { | |
142 | SN9C102_I2C_2WIRES, | |
143 | SN9C102_I2C_3WIRES, | |
144 | }; | |
145 | ||
f327ebbd | 146 | #define SN9C102_MAX_CTRLS (V4L2_CID_LASTP1-V4L2_CID_BASE+10) |
b9df978f | 147 | |
1da177e4 LT |
148 | struct sn9c102_sensor { |
149 | char name[32], /* sensor name */ | |
b595076a | 150 | maintainer[64]; /* name of the maintainer <email> */ |
1da177e4 | 151 | |
f327ebbd LR |
152 | enum sn9c102_bridge supported_bridge; /* supported SN9C1xx bridges */ |
153 | ||
1da177e4 LT |
154 | /* Supported operations through the 'sysfs' interface */ |
155 | enum sn9c102_i2c_sysfs_ops sysfs_ops; | |
156 | ||
157 | /* | |
f327ebbd | 158 | These sensor capabilities must be provided if the SN9C1XX controller |
1da177e4 LT |
159 | needs to communicate through the sensor serial interface by using |
160 | at least one of the i2c functions available. | |
161 | */ | |
162 | enum sn9c102_i2c_frequency frequency; | |
163 | enum sn9c102_i2c_interface interface; | |
164 | ||
165 | /* | |
166 | This identifier must be provided if the image sensor implements | |
167 | the standard I2C protocol. | |
168 | */ | |
169 | u8 i2c_slave_id; /* reg. 0x09 */ | |
170 | ||
171 | /* | |
172 | NOTE: Where not noted,most of the functions below are not mandatory. | |
d56410e0 MCC |
173 | Set to null if you do not implement them. If implemented, |
174 | they must return 0 on success, the proper error otherwise. | |
1da177e4 LT |
175 | */ |
176 | ||
177 | int (*init)(struct sn9c102_device* cam); | |
178 | /* | |
d56410e0 | 179 | This function will be called after the sensor has been attached. |
1da177e4 | 180 | It should be used to initialize the sensor only, but may also |
f327ebbd | 181 | configure part of the SN9C1XX chip if necessary. You don't need to |
1da177e4 | 182 | setup picture settings like brightness, contrast, etc.. here, if |
d56410e0 | 183 | the corrisponding controls are implemented (see below), since |
1da177e4 LT |
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. | |
190 | */ | |
191 | ||
b9df978f | 192 | struct v4l2_queryctrl qctrl[SN9C102_MAX_CTRLS]; |
1da177e4 | 193 | /* |
d56410e0 | 194 | Optional list of default controls, defined as indicated in the |
1da177e4 LT |
195 | V4L2 API. Menu type controls are not handled by this interface. |
196 | */ | |
197 | ||
198 | int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl); | |
199 | int (*set_ctrl)(struct sn9c102_device* cam, | |
d56410e0 | 200 | const struct v4l2_control* ctrl); |
1da177e4 LT |
201 | /* |
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. | |
208 | */ | |
209 | ||
210 | struct v4l2_cropcap cropcap; | |
211 | /* | |
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 | |
f327ebbd | 221 | the active window. The SN9C1XX chip is always programmed to read the |
1da177e4 LT |
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 | |
d56410e0 | 227 | can cover the entire active window, although it is a rare case for |
1da177e4 LT |
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 | |
d56410e0 | 238 | (struct cropcap.bounds) you must not change them.anymore. |
1da177e4 LT |
239 | Only 'bounds' and 'defrect' fields are mandatory, other fields |
240 | will be ignored. | |
241 | */ | |
242 | ||
243 | int (*set_crop)(struct sn9c102_device* cam, | |
d56410e0 | 244 | const struct v4l2_rect* rect); |
1da177e4 LT |
245 | /* |
246 | To be called on VIDIOC_C_SETCROP. The core module always calls a | |
f327ebbd | 247 | default routine which configures the appropriate SN9C1XX regs (also |
1da177e4 LT |
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. | |
f327ebbd | 253 | NOTE: in case, you must program the SN9C1XX chip to get rid of |
d56410e0 MCC |
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). | |
1da177e4 LT |
259 | */ |
260 | ||
261 | struct v4l2_pix_format pix_format; | |
262 | /* | |
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 | |
f327ebbd LR |
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'). | |
1da177e4 | 269 | NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4 |
d56410e0 MCC |
270 | of cropcap.defrect.width and cropcap.defrect.height. I |
271 | suggest 1/1. | |
1da177e4 | 272 | NOTE 2: The initial compression quality is defined by the first bit |
d56410e0 | 273 | of reg 0x17 during the initialization of the image sensor. |
f327ebbd | 274 | NOTE 3: as said above, you have to program the SN9C1XX chip to get |
d56410e0 MCC |
275 | rid of any blank pixels, so that the output of the sensor |
276 | matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR). | |
1da177e4 LT |
277 | */ |
278 | ||
279 | int (*set_pix_format)(struct sn9c102_device* cam, | |
d56410e0 | 280 | const struct v4l2_pix_format* pix); |
1da177e4 LT |
281 | /* |
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. | |
285 | */ | |
286 | ||
1da177e4 LT |
287 | /* |
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 | |
291 | */ | |
b9df978f | 292 | struct v4l2_queryctrl _qctrl[SN9C102_MAX_CTRLS]; |
1da177e4 LT |
293 | struct v4l2_rect _rect; |
294 | }; | |
295 | ||
296 | /*****************************************************************************/ | |
297 | ||
298 | /* Private ioctl's for control settings supported by some image sensors */ | |
f327ebbd LR |
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) | |
1da177e4 LT |
306 | |
307 | #endif /* _SN9C102_SENSOR_H_ */ |