[deliverable/linux.git] / drivers / media / video / sn9c102 / sn9c102_sensor.h

/***************************************************************************
 * API for image sensors connected to the SN9C1xx PC Camera Controllers    *
 *                                                                         *
 * Copyright (C) 2004-2007 by Luca Risolia <luca.risolia@studio.unibo.it>  *
 *                                                                         *
 * 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/videodev2.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 SN9C1XX 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 in sn9c102_devtable.h;
   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.
*/

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

enum sn9c102_bridge {
	BRIDGE_SN9C101 = 0x01,
	BRIDGE_SN9C102 = 0x02,
	BRIDGE_SN9C103 = 0x04,
	BRIDGE_SN9C105 = 0x08,
	BRIDGE_SN9C120 = 0x10,
};

/* Return the bridge name */
enum sn9c102_bridge sn9c102_get_bridge(struct sn9c102_device* cam);

/* Return a pointer the sensor struct attached to the camera */
struct sn9c102_sensor* sn9c102_get_sensor(struct sn9c102_device* cam);

/* Identify a device */
extern struct sn9c102_device*
sn9c102_match_id(struct sn9c102_device* cam, const struct usb_device_id *id);

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

/*
   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 SN9C1XX
   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_read(struct sn9c102_device*,
				const 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 SN9C1XX
   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,
				     const 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,
				    const 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_read_reg(struct sn9c102_device*, u16 index);
extern int sn9c102_pread_reg(struct sn9c102_device*, u16 index);
extern int sn9c102_write_reg(struct sn9c102_device*, u8 value, u16 index);
extern int sn9c102_write_regs(struct sn9c102_device*, const u8 valreg[][2],
			      int count);
/*
   Write multiple registers with constant values. For example:
   sn9c102_write_const_regs(cam, {0x00, 0x14}, {0x60, 0x17}, {0x0f, 0x18});
   Register addresses must be < 256.
*/
#define sn9c102_write_const_regs(sn9c102_device, data...)                     \
	({ static const u8 _valreg[][2] = {data};                             \
	sn9c102_write_regs(sn9c102_device, _valreg, ARRAY_SIZE(_valreg)); })

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

enum sn9c102_i2c_sysfs_ops {
	SN9C102_I2C_READ = 0x01,
	SN9C102_I2C_WRITE = 0x02,
};

enum sn9c102_i2c_frequency { /* sensors may support both the frequencies */
	SN9C102_I2C_100KHZ = 0x01,
	SN9C102_I2C_400KHZ = 0x02,
};

enum sn9c102_i2c_interface {
	SN9C102_I2C_2WIRES,
	SN9C102_I2C_3WIRES,
};

#define SN9C102_MAX_CTRLS (V4L2_CID_LASTP1-V4L2_CID_BASE+10)

struct sn9c102_sensor {
	char name[32], /* sensor name */
	     maintainer[64]; /* name of the maintainer <email> */

	enum sn9c102_bridge supported_bridge; /* supported SN9C1xx bridges */

	/* Supported operations through the 'sysfs' interface */
	enum sn9c102_i2c_sysfs_ops sysfs_ops;

	/*
	   These sensor capabilities must be provided if the SN9C1XX controller
	   needs to communicate through the sensor serial interface by using
	   at least one of the i2c functions available.
	*/
	enum sn9c102_i2c_frequency frequency;
	enum sn9c102_i2c_interface interface;

	/*
	   This identifier must be provided if the image sensor implements
	   the standard I2C protocol.
	*/
	u8 i2c_slave_id; /* reg. 0x09 */

	/*
	   NOTE: Where not noted,most of the functions below are not mandatory.
		 Set to null if you do not implement them. If implemented,
		 they must return 0 on success, the proper error otherwise.
	*/

	int (*init)(struct sn9c102_device* cam);
	/*
	   This function will be called after the sensor has been attached.
	   It should be used to initialize the sensor only, but may also
	   configure part of the SN9C1XX chip if necessary. You don't need to
	   setup picture settings like brightness, contrast, etc.. here, if
	   the corresponding controls are implemented (see below), since
	   they are adjusted in the core driver by calling the set_ctrl()
	   method after init(), where the arguments are the default values
	   specified in the v4l2_queryctrl list of supported controls;
	   Same suggestions apply for other settings, _if_ the corresponding
	   methods are present; if not, the initialization must configure the
	   sensor according to the default configuration structures below.
	*/

	struct v4l2_queryctrl qctrl[SN9C102_MAX_CTRLS];
	/*
	   Optional list of default controls, defined as indicated in the
	   V4L2 API. Menu type controls are not handled by this interface.
	*/

	int (*get_ctrl)(struct sn9c102_device* cam, struct v4l2_control* ctrl);
	int (*set_ctrl)(struct sn9c102_device* cam,
			const struct v4l2_control* ctrl);
	/*
	   You must implement at least the set_ctrl method if you have defined
	   the list above. The returned value must follow the V4L2
	   specifications for the VIDIOC_G|C_CTRL ioctls. V4L2_CID_H|VCENTER
	   are not supported by this driver, so do not implement them. Also,
	   you don't have to check whether the passed values are out of bounds,
	   given that this is done by the core module.
	*/

	struct v4l2_cropcap cropcap;
	/*
	   Think the image sensor as a grid of R,G,B monochromatic pixels
	   disposed according to a particular Bayer pattern, which describes
	   the complete array of pixels, from (0,0) to (xmax, ymax). We will
	   use this coordinate system from now on. It is assumed the sensor
	   chip can be programmed to capture/transmit a subsection of that
	   array of pixels: we will call this subsection "active window".
	   It is not always true that the largest achievable active window can
	   cover the whole array of pixels. The V4L2 API defines another
	   area called "source rectangle", which, in turn, is a subrectangle of
	   the active window. The SN9C1XX chip is always programmed to read the
	   source rectangle.
	   The bounds of both the active window and the source rectangle are
	   specified in the cropcap substructures 'bounds' and 'defrect'.
	   By default, the source rectangle should cover the largest possible
	   area. Again, it is not always true that the largest source rectangle
	   can cover the entire active window, although it is a rare case for
	   the hardware we have. The bounds of the source rectangle _must_ be
	   multiple of 16 and must use the same coordinate system as indicated
	   before; their centers shall align initially.
	   If necessary, the sensor chip must be initialized during init() to
	   set the bounds of the active sensor window; however, by default, it
	   usually covers the largest achievable area (maxwidth x maxheight)
	   of pixels, so no particular initialization is needed, if you have
	   defined the correct default bounds in the structures.
	   See the V4L2 API for further details.
	   NOTE: once you have defined the bounds of the active window
		 (struct cropcap.bounds) you must not change them.anymore.
	   Only 'bounds' and 'defrect' fields are mandatory, other fields
	   will be ignored.
	*/

	int (*set_crop)(struct sn9c102_device* cam,
			const struct v4l2_rect* rect);
	/*
	   To be called on VIDIOC_C_SETCROP. The core module always calls a
	   default routine which configures the appropriate SN9C1XX regs (also
	   scaling), but you may need to override/adjust specific stuff.
	   'rect' contains width and height values that are multiple of 16: in
	   case you override the default function, you always have to program
	   the chip to match those values; on error return the corresponding
	   error code without rolling back.
	   NOTE: in case, you must program the SN9C1XX chip to get rid of
		 blank pixels or blank lines at the _start_ of each line or
		 frame after each HSYNC or VSYNC, so that the image starts with
		 real RGB data (see regs 0x12, 0x13) (having set H_SIZE and,
		 V_SIZE you don't have to care about blank pixels or blank
		 lines at the end of each line or frame).
	*/

	struct v4l2_pix_format pix_format;
	/*
	   What you have to define here are: 1) initial 'width' and 'height' of
	   the target rectangle 2) the initial 'pixelformat', which can be
	   either V4L2_PIX_FMT_SN9C10X, V4L2_PIX_FMT_JPEG (for ompressed video)
	   or V4L2_PIX_FMT_SBGGR8 3) 'priv', which we'll be used to indicate
	   the number of bits per pixel for uncompressed video, 8 or 9 (despite
	   the current value of 'pixelformat').
	   NOTE 1: both 'width' and 'height' _must_ be either 1/1 or 1/2 or 1/4
		   of cropcap.defrect.width and cropcap.defrect.height. I
		   suggest 1/1.
	   NOTE 2: The initial compression quality is defined by the first bit
		   of reg 0x17 during the initialization of the image sensor.
	   NOTE 3: as said above, you have to program the SN9C1XX chip to get
		   rid of any blank pixels, so that the output of the sensor
		   matches the RGB bayer sequence (i.e. BGBGBG...GRGRGR).
	*/

	int (*set_pix_format)(struct sn9c102_device* cam,
			      const struct v4l2_pix_format* pix);
	/*
	   To be called on VIDIOC_S_FMT, when switching from the SBGGR8 to
	   SN9C10X pixel format or viceversa. On error return the corresponding
	   error code without rolling back.
	*/

	/*
	   Do NOT write to the data below, it's READ ONLY. It is used by the
	   core module to store successfully updated values of the above
	   settings, for rollbacks..etc..in case of errors during atomic I/O
	*/
	struct v4l2_queryctrl _qctrl[SN9C102_MAX_CTRLS];
	struct v4l2_rect _rect;
};

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

/* Private ioctl's for control settings supported by some image sensors */
#define SN9C102_V4L2_CID_DAC_MAGNITUDE (V4L2_CID_PRIVATE_BASE + 0)
#define SN9C102_V4L2_CID_GREEN_BALANCE (V4L2_CID_PRIVATE_BASE + 1)
#define SN9C102_V4L2_CID_RESET_LEVEL (V4L2_CID_PRIVATE_BASE + 2)
#define SN9C102_V4L2_CID_PIXEL_BIAS_VOLTAGE (V4L2_CID_PRIVATE_BASE + 3)
#define SN9C102_V4L2_CID_GAMMA (V4L2_CID_PRIVATE_BASE + 4)
#define SN9C102_V4L2_CID_BAND_FILTER (V4L2_CID_PRIVATE_BASE + 5)
#define SN9C102_V4L2_CID_BRIGHT_LEVEL (V4L2_CID_PRIVATE_BASE + 6)

#endif /* _SN9C102_SENSOR_H_ */
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	};
1da177e4 LT	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	/*
1da177e4 LT	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*,
480b55c2 LR	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,
d56410e0 MCC	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,
480b55c2 LR	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:
480b55c2 LR	122	sn9c102_write_const_regs(cam, {0x00, 0x14}, {0x60, 0x17}, {0x0f, 0x18});
3ad2f3fb	123	Register addresses must be < 256.
480b55c2 LR	124	*/
480b55c2 LR	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 {
1da177e4 LT	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 */
f327ebbd LR	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,
d56410e0 MCC	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
25985edc	183	the corresponding 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	/*
1da177e4 LT	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
d56410e0 MCC	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
d56410e0 MCC	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
1da177e4 LT	307	#endif /* _SN9C102_SENSOR_H_ */