aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/media/video/sn9c102/sn9c102_sensor.h
diff options
context:
space:
mode:
Diffstat (limited to 'drivers/media/video/sn9c102/sn9c102_sensor.h')
-rw-r--r--drivers/media/video/sn9c102/sn9c102_sensor.h389
1 files changed, 389 insertions, 0 deletions
diff --git a/drivers/media/video/sn9c102/sn9c102_sensor.h b/drivers/media/video/sn9c102/sn9c102_sensor.h
new file mode 100644
index 000000000000..2afd9e9d09bb
--- /dev/null
+++ b/drivers/media/video/sn9c102/sn9c102_sensor.h
@@ -0,0 +1,389 @@
1/***************************************************************************
2 * API for image sensors connected to the SN9C10x PC Camera Controllers *
3 * *
4 * Copyright (C) 2004-2006 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/videodev.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 SN9C10X 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 SENSOR_TABLE and ID_TABLE (see
46 below);
47 3) implement the methods that you want/need (and fill the rest of the main
48 structure accordingly).
49 "sn9c102_pas106b.c" is an example of all this stuff. Remember that you do
50 NOT need to touch the source code of the core module for the things to work
51 properly, unless you find bugs or flaws in it. Finally, do not forget to
52 read the V4L2 API for completeness.
53*/
54
55/*****************************************************************************/
56
57/*
58 Probing functions: on success, you must attach the sensor to the camera
59 by calling sn9c102_attach_sensor() provided below.
60 To enable the I2C communication, you might need to perform a really basic
61 initialization of the SN9C10X chip by using the write function declared
62 ahead.
63 Functions must return 0 on success, the appropriate error otherwise.
64*/
65extern int sn9c102_probe_hv7131d(struct sn9c102_device* cam);
66extern int sn9c102_probe_mi0343(struct sn9c102_device* cam);
67extern int sn9c102_probe_ov7630(struct sn9c102_device* cam);
68extern int sn9c102_probe_pas106b(struct sn9c102_device* cam);
69extern int sn9c102_probe_pas202bca(struct sn9c102_device* cam);
70extern int sn9c102_probe_pas202bcb(struct sn9c102_device* cam);
71extern int sn9c102_probe_tas5110c1b(struct sn9c102_device* cam);
72extern int sn9c102_probe_tas5130d1b(struct sn9c102_device* cam);
73
74/*
75 Add the above entries to this table. Be sure to add the entry in the right
76 place, since, on failure, the next probing routine is called according to
77 the order of the list below, from top to bottom.
78*/
79#define SN9C102_SENSOR_TABLE \
80static int (*sn9c102_sensor_table[])(struct sn9c102_device*) = { \
81 &sn9c102_probe_mi0343, /* strong detection based on SENSOR ids */ \
82 &sn9c102_probe_pas106b, /* strong detection based on SENSOR ids */ \
83 &sn9c102_probe_pas202bcb, /* strong detection based on SENSOR ids */ \
84 &sn9c102_probe_hv7131d, /* strong detection based on SENSOR ids */ \
85 &sn9c102_probe_pas202bca, /* detection mostly based on USB pid/vid */ \
86 &sn9c102_probe_ov7630, /* detection mostly based on USB pid/vid */ \
87 &sn9c102_probe_tas5110c1b, /* detection based on USB pid/vid */ \
88 &sn9c102_probe_tas5130d1b, /* detection based on USB pid/vid */ \
89 NULL, \
90};
91
92/* Device identification */
93extern struct sn9c102_device*
94sn9c102_match_id(struct sn9c102_device* cam, const struct usb_device_id *id);
95
96/* Attach a probed sensor to the camera. */
97extern void
98sn9c102_attach_sensor(struct sn9c102_device* cam,
99 struct sn9c102_sensor* sensor);
100
101/*
102 Each SN9C10x camera has proper PID/VID identifiers.
103 SN9C103 supports multiple interfaces, but we only handle the video class
104 interface.
105*/
106#define SN9C102_USB_DEVICE(vend, prod, intclass) \
107 .match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
108 USB_DEVICE_ID_MATCH_INT_CLASS, \
109 .idVendor = (vend), \
110 .idProduct = (prod), \
111 .bInterfaceClass = (intclass)
112
113#define SN9C102_ID_TABLE \
114static const struct usb_device_id sn9c102_id_table[] = { \
115 { USB_DEVICE(0x0c45, 0x6001), }, /* TAS5110C1B */ \
116 { USB_DEVICE(0x0c45, 0x6005), }, /* TAS5110C1B */ \
117 { USB_DEVICE(0x0c45, 0x6007), }, \
118 { USB_DEVICE(0x0c45, 0x6009), }, /* PAS106B */ \
119 { USB_DEVICE(0x0c45, 0x600d), }, /* PAS106B */ \
120 { USB_DEVICE(0x0c45, 0x6024), }, \
121 { USB_DEVICE(0x0c45, 0x6025), }, /* TAS5130D1B and TAS5110C1B */ \
122 { USB_DEVICE(0x0c45, 0x6028), }, /* PAS202BCB */ \
123 { USB_DEVICE(0x0c45, 0x6029), }, /* PAS106B */ \
124 { USB_DEVICE(0x0c45, 0x602a), }, /* HV7131D */ \
125 { USB_DEVICE(0x0c45, 0x602b), }, /* MI-0343 */ \
126 { USB_DEVICE(0x0c45, 0x602c), }, /* OV7630 */ \
127 { USB_DEVICE(0x0c45, 0x602d), }, \
128 { USB_DEVICE(0x0c45, 0x602e), }, /* OV7630 */ \
129 { USB_DEVICE(0x0c45, 0x6030), }, /* MI03x */ \
130 { SN9C102_USB_DEVICE(0x0c45, 0x6080, 0xff), }, \
131 { SN9C102_USB_DEVICE(0x0c45, 0x6082, 0xff), }, /* MI0343 & MI0360 */ \
132 { SN9C102_USB_DEVICE(0x0c45, 0x6083, 0xff), }, /* HV7131[D|E1] */ \
133 { SN9C102_USB_DEVICE(0x0c45, 0x6088, 0xff), }, \
134 { SN9C102_USB_DEVICE(0x0c45, 0x608a, 0xff), }, \
135 { SN9C102_USB_DEVICE(0x0c45, 0x608b, 0xff), }, \
136 { SN9C102_USB_DEVICE(0x0c45, 0x608c, 0xff), }, /* HV7131/R */ \
137 { SN9C102_USB_DEVICE(0x0c45, 0x608e, 0xff), }, /* CIS-VF10 */ \
138 { SN9C102_USB_DEVICE(0x0c45, 0x608f, 0xff), }, /* OV7630 */ \
139 { SN9C102_USB_DEVICE(0x0c45, 0x60a0, 0xff), }, \
140 { SN9C102_USB_DEVICE(0x0c45, 0x60a2, 0xff), }, \
141 { SN9C102_USB_DEVICE(0x0c45, 0x60a3, 0xff), }, \
142 { SN9C102_USB_DEVICE(0x0c45, 0x60a8, 0xff), }, /* PAS106B */ \
143 { SN9C102_USB_DEVICE(0x0c45, 0x60aa, 0xff), }, /* TAS5130D1B */ \
144 { SN9C102_USB_DEVICE(0x0c45, 0x60ab, 0xff), }, /* TAS5110C1B */ \
145 { SN9C102_USB_DEVICE(0x0c45, 0x60ac, 0xff), }, \
146 { SN9C102_USB_DEVICE(0x0c45, 0x60ae, 0xff), }, \
147 { SN9C102_USB_DEVICE(0x0c45, 0x60af, 0xff), }, /* PAS202BCB */ \
148 { SN9C102_USB_DEVICE(0x0c45, 0x60b0, 0xff), }, /* OV7630 (?) */ \
149 { SN9C102_USB_DEVICE(0x0c45, 0x60b2, 0xff), }, \
150 { SN9C102_USB_DEVICE(0x0c45, 0x60b3, 0xff), }, \
151 { SN9C102_USB_DEVICE(0x0c45, 0x60b8, 0xff), }, \
152 { SN9C102_USB_DEVICE(0x0c45, 0x60ba, 0xff), }, \
153 { SN9C102_USB_DEVICE(0x0c45, 0x60bb, 0xff), }, \
154 { SN9C102_USB_DEVICE(0x0c45, 0x60bc, 0xff), }, \
155 { SN9C102_USB_DEVICE(0x0c45, 0x60be, 0xff), }, \
156 { } \
157};
158
159/*****************************************************************************/
160
161/*
162 Read/write routines: they always return -1 on error, 0 or the read value
163 otherwise. NOTE that a real read operation is not supported by the SN9C10X
164 chip for some of its registers. To work around this problem, a pseudo-read
165 call is provided instead: it returns the last successfully written value
166 on the register (0 if it has never been written), the usual -1 on error.
167*/
168
169/* The "try" I2C I/O versions are used when probing the sensor */
170extern int sn9c102_i2c_try_write(struct sn9c102_device*,struct sn9c102_sensor*,
171 u8 address, u8 value);
172extern int sn9c102_i2c_try_read(struct sn9c102_device*,struct sn9c102_sensor*,
173 u8 address);
174
175/*
176 These must be used if and only if the sensor doesn't implement the standard
177 I2C protocol. There are a number of good reasons why you must use the
178 single-byte versions of these functions: do not abuse. The first function
179 writes n bytes, from data0 to datan, to registers 0x09 - 0x09+n of SN9C10X
180 chip. The second one programs the registers 0x09 and 0x10 with data0 and
181 data1, and places the n bytes read from the sensor register table in the
182 buffer pointed by 'buffer'. Both the functions return -1 on error; the write
183 version returns 0 on success, while the read version returns the first read
184 byte.
185*/
186extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam,
187 struct sn9c102_sensor* sensor, u8 n,
188 u8 data0, u8 data1, u8 data2, u8 data3,
189 u8 data4, u8 data5);
190extern int sn9c102_i2c_try_raw_read(struct sn9c102_device* cam,
191 struct sn9c102_sensor* sensor, u8 data0,
192 u8 data1, u8 n, u8 buffer[]);
193
194/* To be used after the sensor struct has been attached to the camera struct */
195extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value);
196extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address);
197
198/* I/O on registers in the bridge. Could be used by the sensor methods too */
199extern int sn9c102_write_regs(struct sn9c102_device*, u8* buff, u16 index);
200extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
201extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);
202
203/*
204 NOTE: there are no exported debugging functions. To uniform the output you
205 must use the dev_info()/dev_warn()/dev_err() macros defined in device.h,
206 already included here, the argument being the struct device '&usbdev->dev'
207 of the sensor structure. Do NOT use these macros before the sensor is
208 attached or the kernel will crash! However, you should not need to notify
209 the user about common errors or other messages, since this is done by the
210 master module.
211*/
212
213/*****************************************************************************/
214
215enum sn9c102_i2c_sysfs_ops {
216 SN9C102_I2C_READ = 0x01,
217 SN9C102_I2C_WRITE = 0x02,
218};
219
220enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */
221 SN9C102_I2C_100KHZ = 0x01,
222 SN9C102_I2C_400KHZ = 0x02,
223};
224
225enum sn9c102_i2c_interface {
226 SN9C102_I2C_2WIRES,
227 SN9C102_I2C_3WIRES,
228};
229
230#define SN9C102_MAX_CTRLS V4L2_CID_LASTP1-V4L2_CID_BASE+10
231
232struct sn9c102_sensor {
233 char name[32], /* sensor name */
234 maintainer[64]; /* name of the mantainer <email> */
235
236 /* Supported operations through the 'sysfs' interface */
237 enum sn9c102_i2c_sysfs_ops sysfs_ops;
238
239 /*
240 These sensor capabilities must be provided if the SN9C10X controller
241 needs to communicate through the sensor serial interface by using
242 at least one of the i2c functions available.
243 */
244 enum sn9c102_i2c_frequency frequency;
245 enum sn9c102_i2c_interface interface;
246
247 /*
248 This identifier must be provided if the image sensor implements
249 the standard I2C protocol.
250 */
251 u8 i2c_slave_id; /* reg. 0x09 */
252
253 /*
254 NOTE: Where not noted,most of the functions below are not mandatory.
255 Set to null if you do not implement them. If implemented,
256 they must return 0 on success, the proper error otherwise.
257 */
258
259 int (*init)(struct sn9c102_device* cam);
260 /*
261 This function will be called after the sensor has been attached.
262 It should be used to initialize the sensor only, but may also
263 configure part of the SN9C10X chip if necessary. You don't need to
264 setup picture settings like brightness, contrast, etc.. here, if
265 the corrisponding controls are implemented (see below), since
266 they are adjusted in the core driver by calling the set_ctrl()
267 method after init(), where the arguments are the default values
268 specified in the v4l2_queryctrl list of supported controls;
269 Same suggestions apply for other settings, _if_ the corresponding
270 methods are present; if not, the initialization must configure the
271 sensor according to the default configuration structures below.
272 */
273
274 struct v4l2_queryctrl qctrl[SN9C102_MAX_CTRLS];
275 /*
276 Optional list of default controls, defined as indicated in the
277 V4L2 API. Menu type controls are not handled by this interface.
278 */
279
280 int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl);
281 int (*set_ctrl)(struct sn9c102_device* cam,
282 const struct v4l2_control* ctrl);
283 /*
284 You must implement at least the set_ctrl method if you have defined
285 the list above. The returned value must follow the V4L2
286 specifications for the VIDIOC_G|C_CTRL ioctls. V4L2_CID_H|VCENTER
287 are not supported by this driver, so do not implement them. Also,
288 you don't have to check whether the passed values are out of bounds,
289 given that this is done by the core module.
290 */
291
292 struct v4l2_cropcap cropcap;
293 /*
294 Think the image sensor as a grid of R,G,B monochromatic pixels
295 disposed according to a particular Bayer pattern, which describes
296 the complete array of pixels, from (0,0) to (xmax, ymax). We will
297 use this coordinate system from now on. It is assumed the sensor
298 chip can be programmed to capture/transmit a subsection of that
299 array of pixels: we will call this subsection "active window".
300 It is not always true that the largest achievable active window can
301 cover the whole array of pixels. The V4L2 API defines another
302 area called "source rectangle", which, in turn, is a subrectangle of
303 the active window. The SN9C10X chip is always programmed to read the
304 source rectangle.
305 The bounds of both the active window and the source rectangle are
306 specified in the cropcap substructures 'bounds' and 'defrect'.
307 By default, the source rectangle should cover the largest possible
308 area. Again, it is not always true that the largest source rectangle
309 can cover the entire active window, although it is a rare case for
310 the hardware we have. The bounds of the source rectangle _must_ be
311 multiple of 16 and must use the same coordinate system as indicated
312 before; their centers shall align initially.
313 If necessary, the sensor chip must be initialized during init() to
314 set the bounds of the active sensor window; however, by default, it
315 usually covers the largest achievable area (maxwidth x maxheight)
316 of pixels, so no particular initialization is needed, if you have
317 defined the correct default bounds in the structures.
318 See the V4L2 API for further details.
319 NOTE: once you have defined the bounds of the active window
320 (struct cropcap.bounds) you must not change them.anymore.
321 Only 'bounds' and 'defrect' fields are mandatory, other fields
322 will be ignored.
323 */
324
325 int (*set_crop)(struct sn9c102_device* cam,
326 const struct v4l2_rect* rect);
327 /*
328 To be called on VIDIOC_C_SETCROP. The core module always calls a
329 default routine which configures the appropriate SN9C10X regs (also
330 scaling), but you may need to override/adjust specific stuff.
331 'rect' contains width and height values that are multiple of 16: in
332 case you override the default function, you always have to program
333 the chip to match those values; on error return the corresponding
334 error code without rolling back.
335 NOTE: in case, you must program the SN9C10X chip to get rid of
336 blank pixels or blank lines at the _start_ of each line or
337 frame after each HSYNC or VSYNC, so that the image starts with
338 real RGB data (see regs 0x12, 0x13) (having set H_SIZE and,
339 V_SIZE you don't have to care about blank pixels or blank
340 lines at the end of each line or frame).
341 */
342
343 struct v4l2_pix_format pix_format;
344 /*
345 What you have to define here are: 1) initial 'width' and 'height' of
346 the target rectangle 2) the initial 'pixelformat', which can be
347 either V4L2_PIX_FMT_SN9C10X (for compressed video) or
348 V4L2_PIX_FMT_SBGGR8 3) 'priv', which we'll be used to indicate the
349 number of bits per pixel for uncompressed video, 8 or 9 (despite the
350 current value of 'pixelformat').
351 NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4
352 of cropcap.defrect.width and cropcap.defrect.height. I
353 suggest 1/1.
354 NOTE 2: The initial compression quality is defined by the first bit
355 of reg 0x17 during the initialization of the image sensor.
356 NOTE 3: as said above, you have to program the SN9C10X chip to get
357 rid of any blank pixels, so that the output of the sensor
358 matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR).
359 */
360
361 int (*set_pix_format)(struct sn9c102_device* cam,
362 const struct v4l2_pix_format* pix);
363 /*
364 To be called on VIDIOC_S_FMT, when switching from the SBGGR8 to
365 SN9C10X pixel format or viceversa. On error return the corresponding
366 error code without rolling back.
367 */
368
369 /*
370 Do NOT write to the data below, it's READ ONLY. It is used by the
371 core module to store successfully updated values of the above
372 settings, for rollbacks..etc..in case of errors during atomic I/O
373 */
374 struct v4l2_queryctrl _qctrl[SN9C102_MAX_CTRLS];
375 struct v4l2_rect _rect;
376};
377
378/*****************************************************************************/
379
380/* Private ioctl's for control settings supported by some image sensors */
381#define SN9C102_V4L2_CID_DAC_MAGNITUDE V4L2_CID_PRIVATE_BASE
382#define SN9C102_V4L2_CID_GREEN_BALANCE V4L2_CID_PRIVATE_BASE + 1
383#define SN9C102_V4L2_CID_RESET_LEVEL V4L2_CID_PRIVATE_BASE + 2
384#define SN9C102_V4L2_CID_PIXEL_BIAS_VOLTAGE V4L2_CID_PRIVATE_BASE + 3
385#define SN9C102_V4L2_CID_GAMMA V4L2_CID_PRIVATE_BASE + 4
386#define SN9C102_V4L2_CID_BAND_FILTER V4L2_CID_PRIVATE_BASE + 5
387#define SN9C102_V4L2_CID_BRIGHT_LEVEL V4L2_CID_PRIVATE_BASE + 6
388
389#endif /* _SN9C102_SENSOR_H_ */
generated by cgit v1.2.2 (git 2.25.0) at 2025-01-12 14:24:08 -0500