sn9c102_sensor.h

linux-2.6.15.6

/***************************************************************************
 * API for image sensors connected to the SN9C10x PC Camera Controllers    *
 *                                                                         *
 * Copyright (C) 2004-2005 by Luca Risolia <[e-mail]>  *
 *                                                                         *
 * This program is free software; you can redistribute it and/or modify    *
 * it under the terms of the GNU General Public License as published by    *
 * the Free Software Foundation; either version 2 of the License, or       *
 * (at your option) any later version.                                     *
 *                                                                         *
 * This program is distributed in the hope that it will be useful,         *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of          *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           *
 * GNU General Public License for more details.                            *
 *                                                                         *
 * You should have received a copy of the GNU General Public License       *
 * along with this program; if not, write to the Free Software             *
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.               *
 ***************************************************************************/

#ifndef _SN9C102_SENSOR_H_
#define _SN9C102_SENSOR_H_

#include <linux/usb.h>
#include <linux/videodev.h>
#include <linux/device.h>
#include <linux/stddef.h>
#include <linux/errno.h>
#include <asm/types.h>

struct sn9c102_device;
struct sn9c102_sensor;

/*****************************************************************************/

/*
   OVERVIEW.
   This is a small interface that allows you to add support for any CCD/CMOS
   image sensors connected to the SN9C10X bridges. The entire API is documented
   below. In the most general case, to support a sensor there are three steps
   you have to follow:
   1) define the main "sn9c102_sensor" structure by setting the basic fields;
   2) write a probing function to be called by the core module when the USB
      camera is recognized, then add both the USB ids and the name of that
      function to the two corresponding tables SENSOR_TABLE and ID_TABLE (see
      below);
   3) implement the methods that you want/need (and fill the rest of the main
      structure accordingly).
   "sn9c102_pas106b.c" is an example of all this stuff. Remember that you do
   NOT need to touch the source code of the core module for the things to work
   properly, unless you find bugs or flaws in it. Finally, do not forget to
   read the V4L2 API for completeness.
*/

/*****************************************************************************/

/*
   Probing functions: on success, you must attach the sensor to the camera
   by calling sn9c102_attach_sensor() provided below.
   To enable the I2C communication, you might need to perform a really basic
   initialization of the SN9C10X chip by using the write function declared 
   ahead.
   Functions must return 0 on success, the appropriate error otherwise.
*/
extern int sn9c102_probe_hv7131d(struct sn9c102_device* cam);
extern int sn9c102_probe_mi0343(struct sn9c102_device* cam);
extern int sn9c102_probe_ov7630(struct sn9c102_device* cam);
extern int sn9c102_probe_pas106b(struct sn9c102_device* cam);
extern int sn9c102_probe_pas202bcb(struct sn9c102_device* cam);
extern int sn9c102_probe_tas5110c1b(struct sn9c102_device* cam);
extern int sn9c102_probe_tas5130d1b(struct sn9c102_device* cam);

/*
   Add the above entries to this table. Be sure to add the entry in the right
   place, since, on failure, the next probing routine is called according to 
   the order of the list below, from top to bottom.
*/
#define SN9C102_SENSOR_TABLE                                                  \
static int (*sn9c102_sensor_table[])(struct sn9c102_device*) = {              \
	&sn9c102_probe_mi0343, /* strong detection based on SENSOR ids */     \
	&sn9c102_probe_pas106b, /* strong detection based on SENSOR ids */    \
	&sn9c102_probe_pas202bcb, /* strong detection based on SENSOR ids */  \
	&sn9c102_probe_hv7131d, /* strong detection based on SENSOR ids */    \
	&sn9c102_probe_ov7630, /* detection mostly based on USB pid/vid */    \
	&sn9c102_probe_tas5110c1b, /* detection based on USB pid/vid */       \
	&sn9c102_probe_tas5130d1b, /* detection based on USB pid/vid */       \
	NULL,                                                                 \
};

/* Attach a probed sensor to the camera. */
extern void 
sn9c102_attach_sensor(struct sn9c102_device* cam,
                      struct sn9c102_sensor* sensor);

/* Each SN9C10X camera has proper PID/VID identifiers. Add them here in case.*/
#define SN9C102_ID_TABLE                                                      \
static const struct usb_device_id sn9c102_id_table[] = {                      \
	{ USB_DEVICE(0x0c45, 0x6001), }, /* TAS5110C1B */                     \
	{ USB_DEVICE(0x0c45, 0x6005), }, /* TAS5110C1B */                     \
	{ USB_DEVICE(0x0c45, 0x6009), }, /* PAS106B */                        \
	{ USB_DEVICE(0x0c45, 0x600d), }, /* PAS106B */                        \
	{ USB_DEVICE(0x0c45, 0x6024), },                                      \
	{ USB_DEVICE(0x0c45, 0x6025), }, /* TAS5130D1B and TAS5110C1B */      \
	{ USB_DEVICE(0x0c45, 0x6028), }, /* PAS202BCB */                      \
	{ USB_DEVICE(0x0c45, 0x6029), }, /* PAS106B */                        \
	{ USB_DEVICE(0x0c45, 0x602a), }, /* HV7131D */                        \
	{ USB_DEVICE(0x0c45, 0x602b), }, /* MI-0343 */                        \
	{ USB_DEVICE(0x0c45, 0x602c), }, /* OV7630 */                         \
	{ USB_DEVICE(0x0c45, 0x602d), },                                      \
	{ USB_DEVICE(0x0c45, 0x6030), }, /* MI03x */                          \
	{ USB_DEVICE(0x0c45, 0x6080), },                                      \
	{ USB_DEVICE(0x0c45, 0x6082), }, /* MI0343 and MI0360 */              \
	{ USB_DEVICE(0x0c45, 0x6083), }, /* HV7131[D|E1] */                   \
	{ USB_DEVICE(0x0c45, 0x6088), },                                      \
	{ USB_DEVICE(0x0c45, 0x608a), },                                      \
	{ USB_DEVICE(0x0c45, 0x608b), },                                      \
	{ USB_DEVICE(0x0c45, 0x608c), }, /* HV7131x */                        \
	{ USB_DEVICE(0x0c45, 0x608e), }, /* CIS-VF10 */                       \
	{ USB_DEVICE(0x0c45, 0x608f), }, /* OV7630 */                         \
	{ USB_DEVICE(0x0c45, 0x60a0), },                                      \
	{ USB_DEVICE(0x0c45, 0x60a2), },                                      \
	{ USB_DEVICE(0x0c45, 0x60a3), },                                      \
	{ USB_DEVICE(0x0c45, 0x60a8), }, /* PAS106B */                        \
	{ USB_DEVICE(0x0c45, 0x60aa), }, /* TAS5130D1B */                     \
	{ USB_DEVICE(0x0c45, 0x60ab), }, /* TAS5110C1B */                     \
	{ USB_DEVICE(0x0c45, 0x60ac), },                                      \
	{ USB_DEVICE(0x0c45, 0x60ae), },                                      \
	{ USB_DEVICE(0x0c45, 0x60af), }, /* PAS202BCB */                      \
	{ USB_DEVICE(0x0c45, 0x60b0), },                                      \
	{ USB_DEVICE(0x0c45, 0x60b2), },                                      \
	{ USB_DEVICE(0x0c45, 0x60b3), },                                      \
	{ USB_DEVICE(0x0c45, 0x60b8), },                                      \
	{ USB_DEVICE(0x0c45, 0x60ba), },                                      \
	{ USB_DEVICE(0x0c45, 0x60bb), },                                      \
	{ USB_DEVICE(0x0c45, 0x60bc), },                                      \
	{ USB_DEVICE(0x0c45, 0x60be), },                                      \
	{ }                                                                   \
};

/*****************************************************************************/

/*
   Read/write routines: they always return -1 on error, 0 or the read value
   otherwise. NOTE that a real read operation is not supported by the SN9C10X
   chip for some of its registers. To work around this problem, a pseudo-read
   call is provided instead: it returns the last successfully written value 
   on the register (0 if it has never been written), the usual -1 on error.
*/

/* The "try" I2C I/O versions are used when probing the sensor */
extern int sn9c102_i2c_try_write(struct sn9c102_device*,struct sn9c102_sensor*,
                                 u8 address, u8 value);
extern int sn9c102_i2c_try_read(struct sn9c102_device*,struct sn9c102_sensor*,
                                u8 address);

/*
   These must be used if and only if the sensor doesn't implement the standard
   I2C protocol. There are a number of good reasons why you must use the 
   single-byte versions of these functions: do not abuse. The first function
   writes n bytes, from data0 to datan, to registers 0x09 - 0x09+n of SN9C10X
   chip. The second one programs the registers 0x09 and 0x10 with data0 and
   data1, and places the n bytes read from the sensor register table in the
   buffer pointed by 'buffer'. Both the functions return -1 on error; the write
   version returns 0 on success, while the read version returns the first read
   byte.
*/
extern int sn9c102_i2c_try_raw_write(struct sn9c102_device* cam,
                                     struct sn9c102_sensor* sensor, u8 n, 
                                     u8 data0, u8 data1, u8 data2, u8 data3,
                                     u8 data4, u8 data5);
extern int sn9c102_i2c_try_raw_read(struct sn9c102_device* cam,
                                    struct sn9c102_sensor* sensor, u8 data0,
                                    u8 data1, u8 n, u8 buffer[]);

/* To be used after the sensor struct has been attached to the camera struct */
extern int sn9c102_i2c_write(struct sn9c102_device*, u8 address, u8 value);
extern int sn9c102_i2c_read(struct sn9c102_device*, u8 address);

/* I/O on registers in the bridge. Could be used by the sensor methods too */
extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);

/*
   NOTE: there are no exported debugging functions. To uniform the output you
   must use the dev_info()/dev_warn()/dev_err() macros defined in device.h,
   already included here, the argument being the struct device 'dev' of the
   sensor structure. Do NOT use these macros before the sensor is attached or
   the kernel will crash! However, you should not need to notify the user about
   common errors or other messages, since this is done by the master module.
*/