1/*
2 * camera image capture (abstract) bus driver header
3 *
4 * Copyright (C) 2006, Sascha Hauer, Pengutronix
5 * Copyright (C) 2008, Guennadi Liakhovetski <kernel@pengutronix.de>
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License version 2 as
9 * published by the Free Software Foundation.
10 */
11
12#ifndef SOC_CAMERA_H
13#define SOC_CAMERA_H
14
15#include <linux/bitops.h>
16#include <linux/device.h>
17#include <linux/mutex.h>
18#include <linux/pm.h>
19#include <linux/videodev2.h>
20#include <media/videobuf-core.h>
21#include <media/videobuf2-core.h>
22#include <media/v4l2-async.h>
23#include <media/v4l2-ctrls.h>
24#include <media/v4l2-device.h>
25
26struct file;
27struct soc_camera_desc;
28struct soc_camera_async_client;
29
30struct soc_camera_device {
31	struct list_head list;		/* list of all registered devices */
32	struct soc_camera_desc *sdesc;
33	struct device *pdev;		/* Platform device */
34	struct device *parent;		/* Camera host device */
35	struct device *control;		/* E.g., the i2c client */
36	s32 user_width;
37	s32 user_height;
38	u32 bytesperline;		/* for padding, zero if unused */
39	u32 sizeimage;
40	enum v4l2_colorspace colorspace;
41	unsigned char iface;		/* Host number */
42	unsigned char devnum;		/* Device number per host */
43	struct soc_camera_sense *sense;	/* See comment in struct definition */
44	struct video_device *vdev;
45	struct v4l2_ctrl_handler ctrl_handler;
46	const struct soc_camera_format_xlate *current_fmt;
47	struct soc_camera_format_xlate *user_formats;
48	int num_user_formats;
49	enum v4l2_field field;		/* Preserve field over close() */
50	void *host_priv;		/* Per-device host private data */
51	/* soc_camera.c private count. Only accessed with .host_lock held */
52	int use_count;
53	struct file *streamer;		/* stream owner */
54	struct v4l2_clk *clk;
55	/* Asynchronous subdevice management */
56	struct soc_camera_async_client *sasc;
57	/* video buffer queue */
58	union {
59		struct videobuf_queue vb_vidq;
60		struct vb2_queue vb2_vidq;
61	};
62};
63
64/* Host supports programmable stride */
65#define SOCAM_HOST_CAP_STRIDE		(1 << 0)
66
67enum soc_camera_subdev_role {
68	SOCAM_SUBDEV_DATA_SOURCE = 1,
69	SOCAM_SUBDEV_DATA_SINK,
70	SOCAM_SUBDEV_DATA_PROCESSOR,
71};
72
73struct soc_camera_async_subdev {
74	struct v4l2_async_subdev asd;
75	enum soc_camera_subdev_role role;
76};
77
78struct soc_camera_host {
79	struct v4l2_device v4l2_dev;
80	struct list_head list;
81	struct mutex host_lock;		/* Main synchronisation lock */
82	struct mutex clk_lock;		/* Protect pipeline modifications */
83	unsigned char nr;		/* Host number */
84	u32 capabilities;
85	struct soc_camera_device *icd;	/* Currently attached client */
86	void *priv;
87	const char *drv_name;
88	struct soc_camera_host_ops *ops;
89	struct v4l2_async_subdev **asd;	/* Flat array, arranged in groups */
90	unsigned int *asd_sizes;	/* 0-terminated array of asd group sizes */
91};
92
93struct soc_camera_host_ops {
94	struct module *owner;
95	int (*add)(struct soc_camera_device *);
96	void (*remove)(struct soc_camera_device *);
97	int (*clock_start)(struct soc_camera_host *);
98	void (*clock_stop)(struct soc_camera_host *);
99	/*
100	 * .get_formats() is called for each client device format, but
101	 * .put_formats() is only called once. Further, if any of the calls to
102	 * .get_formats() fail, .put_formats() will not be called at all, the
103	 * failing .get_formats() must then clean up internally.
104	 */
105	int (*get_formats)(struct soc_camera_device *, unsigned int,
106			   struct soc_camera_format_xlate *);
107	void (*put_formats)(struct soc_camera_device *);
108	int (*cropcap)(struct soc_camera_device *, struct v4l2_cropcap *);
109	int (*get_crop)(struct soc_camera_device *, struct v4l2_crop *);
110	int (*set_crop)(struct soc_camera_device *, const struct v4l2_crop *);
111	int (*get_selection)(struct soc_camera_device *, struct v4l2_selection *);
112	int (*set_selection)(struct soc_camera_device *, struct v4l2_selection *);
113	/*
114	 * The difference to .set_crop() is, that .set_livecrop is not allowed
115	 * to change the output sizes
116	 */
117	int (*set_livecrop)(struct soc_camera_device *, const struct v4l2_crop *);
118	int (*set_fmt)(struct soc_camera_device *, struct v4l2_format *);
119	int (*try_fmt)(struct soc_camera_device *, struct v4l2_format *);
120	void (*init_videobuf)(struct videobuf_queue *,
121			      struct soc_camera_device *);
122	int (*init_videobuf2)(struct vb2_queue *,
123			      struct soc_camera_device *);
124	int (*reqbufs)(struct soc_camera_device *, struct v4l2_requestbuffers *);
125	int (*querycap)(struct soc_camera_host *, struct v4l2_capability *);
126	int (*set_bus_param)(struct soc_camera_device *);
127	int (*get_parm)(struct soc_camera_device *, struct v4l2_streamparm *);
128	int (*set_parm)(struct soc_camera_device *, struct v4l2_streamparm *);
129	int (*enum_framesizes)(struct soc_camera_device *, struct v4l2_frmsizeenum *);
130	unsigned int (*poll)(struct file *, poll_table *);
131};
132
133#define SOCAM_SENSOR_INVERT_PCLK	(1 << 0)
134#define SOCAM_SENSOR_INVERT_MCLK	(1 << 1)
135#define SOCAM_SENSOR_INVERT_HSYNC	(1 << 2)
136#define SOCAM_SENSOR_INVERT_VSYNC	(1 << 3)
137#define SOCAM_SENSOR_INVERT_DATA	(1 << 4)
138
139struct i2c_board_info;
140struct regulator_bulk_data;
141
142struct soc_camera_subdev_desc {
143	/* Per camera SOCAM_SENSOR_* bus flags */
144	unsigned long flags;
145
146	/* sensor driver private platform data */
147	void *drv_priv;
148
149	/*
150	 * Set unbalanced_power to true to deal with legacy drivers, failing to
151	 * balance their calls to subdevice's .s_power() method. clock_state is
152	 * then used internally by helper functions, it shouldn't be touched by
153	 * drivers or the platform code.
154	 */
155	bool unbalanced_power;
156	unsigned long clock_state;
157
158	/* Optional callbacks to power on or off and reset the sensor */
159	int (*power)(struct device *, int);
160	int (*reset)(struct device *);
161
162	/*
163	 * some platforms may support different data widths than the sensors
164	 * native ones due to different data line routing. Let the board code
165	 * overwrite the width flags.
166	 */
167	int (*set_bus_param)(struct soc_camera_subdev_desc *, unsigned long flags);
168	unsigned long (*query_bus_param)(struct soc_camera_subdev_desc *);
169	void (*free_bus)(struct soc_camera_subdev_desc *);
170
171	/* Optional regulators that have to be managed on power on/off events */
172	struct v4l2_subdev_platform_data sd_pdata;
173};
174
175struct soc_camera_host_desc {
176	/* Camera bus id, used to match a camera and a bus */
177	int bus_id;
178	int i2c_adapter_id;
179	struct i2c_board_info *board_info;
180	const char *module_name;
181
182	/*
183	 * For non-I2C devices platform has to provide methods to add a device
184	 * to the system and to remove it
185	 */
186	int (*add_device)(struct soc_camera_device *);
187	void (*del_device)(struct soc_camera_device *);
188};
189
190/*
191 * Platform data for "soc-camera-pdrv"
192 * This MUST be kept binary-identical to struct soc_camera_link below, until
193 * it is completely replaced by this one, after which we can split it into its
194 * two components.
195 */
196struct soc_camera_desc {
197	struct soc_camera_subdev_desc subdev_desc;
198	struct soc_camera_host_desc host_desc;
199};
200
201/* Prepare to replace this struct: don't change its layout any more! */
202struct soc_camera_link {
203	/*
204	 * Subdevice part - keep at top and compatible to
205	 * struct soc_camera_subdev_desc
206	 */
207
208	/* Per camera SOCAM_SENSOR_* bus flags */
209	unsigned long flags;
210
211	void *priv;
212
213	/* Set by platforms to handle misbehaving drivers */
214	bool unbalanced_power;
215	/* Used by soc-camera helper functions */
216	unsigned long clock_state;
217
218	/* Optional callbacks to power on or off and reset the sensor */
219	int (*power)(struct device *, int);
220	int (*reset)(struct device *);
221	/*
222	 * some platforms may support different data widths than the sensors
223	 * native ones due to different data line routing. Let the board code
224	 * overwrite the width flags.
225	 */
226	int (*set_bus_param)(struct soc_camera_link *, unsigned long flags);
227	unsigned long (*query_bus_param)(struct soc_camera_link *);
228	void (*free_bus)(struct soc_camera_link *);
229
230	/* Optional regulators that have to be managed on power on/off events */
231	struct regulator_bulk_data *regulators;
232	int num_regulators;
233
234	void *host_priv;
235
236	/*
237	 * Host part - keep at bottom and compatible to
238	 * struct soc_camera_host_desc
239	 */
240
241	/* Camera bus id, used to match a camera and a bus */
242	int bus_id;
243	int i2c_adapter_id;
244	struct i2c_board_info *board_info;
245	const char *module_name;
246
247	/*
248	 * For non-I2C devices platform has to provide methods to add a device
249	 * to the system and to remove it
250	 */
251	int (*add_device)(struct soc_camera_device *);
252	void (*del_device)(struct soc_camera_device *);
253};
254
255static inline struct soc_camera_host *to_soc_camera_host(
256	const struct device *dev)
257{
258	struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
259
260	return container_of(v4l2_dev, struct soc_camera_host, v4l2_dev);
261}
262
263static inline struct soc_camera_desc *to_soc_camera_desc(
264	const struct soc_camera_device *icd)
265{
266	return icd->sdesc;
267}
268
269static inline struct device *to_soc_camera_control(
270	const struct soc_camera_device *icd)
271{
272	return icd->control;
273}
274
275static inline struct v4l2_subdev *soc_camera_to_subdev(
276	const struct soc_camera_device *icd)
277{
278	struct device *control = to_soc_camera_control(icd);
279	return dev_get_drvdata(control);
280}
281
282int soc_camera_host_register(struct soc_camera_host *ici);
283void soc_camera_host_unregister(struct soc_camera_host *ici);
284
285const struct soc_camera_format_xlate *soc_camera_xlate_by_fourcc(
286	struct soc_camera_device *icd, unsigned int fourcc);
287
288/**
289 * struct soc_camera_format_xlate - match between host and sensor formats
290 * @code: code of a sensor provided format
291 * @host_fmt: host format after host translation from code
292 *
293 * Host and sensor translation structure. Used in table of host and sensor
294 * formats matchings in soc_camera_device. A host can override the generic list
295 * generation by implementing get_formats(), and use it for format checks and
296 * format setup.
297 */
298struct soc_camera_format_xlate {
299	u32 code;
300	const struct soc_mbus_pixelfmt *host_fmt;
301};
302
303#define SOCAM_SENSE_PCLK_CHANGED	(1 << 0)
304
305/**
306 * This struct can be attached to struct soc_camera_device by the host driver
307 * to request sense from the camera, for example, when calling .set_fmt(). The
308 * host then can check which flags are set and verify respective values if any.
309 * For example, if SOCAM_SENSE_PCLK_CHANGED is set, it means, pixclock has
310 * changed during this operation. After completion the host should detach sense.
311 *
312 * @flags		ored SOCAM_SENSE_* flags
313 * @master_clock	if the host wants to be informed about pixel-clock
314 *			change, it better set master_clock.
315 * @pixel_clock_max	maximum pixel clock frequency supported by the host,
316 *			camera is not allowed to exceed this.
317 * @pixel_clock		if the camera driver changed pixel clock during this
318 *			operation, it sets SOCAM_SENSE_PCLK_CHANGED, uses
319 *			master_clock to calculate the new pixel-clock and
320 *			sets this field.
321 */
322struct soc_camera_sense {
323	unsigned long flags;
324	unsigned long master_clock;
325	unsigned long pixel_clock_max;
326	unsigned long pixel_clock;
327};
328
329#define SOCAM_DATAWIDTH(x)	BIT((x) - 1)
330#define SOCAM_DATAWIDTH_4	SOCAM_DATAWIDTH(4)
331#define SOCAM_DATAWIDTH_8	SOCAM_DATAWIDTH(8)
332#define SOCAM_DATAWIDTH_9	SOCAM_DATAWIDTH(9)
333#define SOCAM_DATAWIDTH_10	SOCAM_DATAWIDTH(10)
334#define SOCAM_DATAWIDTH_12	SOCAM_DATAWIDTH(12)
335#define SOCAM_DATAWIDTH_15	SOCAM_DATAWIDTH(15)
336#define SOCAM_DATAWIDTH_16	SOCAM_DATAWIDTH(16)
337#define SOCAM_DATAWIDTH_18	SOCAM_DATAWIDTH(18)
338#define SOCAM_DATAWIDTH_24	SOCAM_DATAWIDTH(24)
339
340#define SOCAM_DATAWIDTH_MASK (SOCAM_DATAWIDTH_4 | SOCAM_DATAWIDTH_8 | \
341			      SOCAM_DATAWIDTH_9 | SOCAM_DATAWIDTH_10 | \
342			      SOCAM_DATAWIDTH_12 | SOCAM_DATAWIDTH_15 | \
343			      SOCAM_DATAWIDTH_16 | SOCAM_DATAWIDTH_18 | \
344			      SOCAM_DATAWIDTH_24)
345
346static inline void soc_camera_limit_side(int *start, int *length,
347		unsigned int start_min,
348		unsigned int length_min, unsigned int length_max)
349{
350	if (*length < length_min)
351		*length = length_min;
352	else if (*length > length_max)
353		*length = length_max;
354
355	if (*start < start_min)
356		*start = start_min;
357	else if (*start > start_min + length_max - *length)
358		*start = start_min + length_max - *length;
359}
360
361unsigned long soc_camera_apply_board_flags(struct soc_camera_subdev_desc *ssdd,
362					   const struct v4l2_mbus_config *cfg);
363
364int soc_camera_power_init(struct device *dev, struct soc_camera_subdev_desc *ssdd);
365int soc_camera_power_on(struct device *dev, struct soc_camera_subdev_desc *ssdd,
366			struct v4l2_clk *clk);
367int soc_camera_power_off(struct device *dev, struct soc_camera_subdev_desc *ssdd,
368			 struct v4l2_clk *clk);
369
370static inline int soc_camera_set_power(struct device *dev,
371		struct soc_camera_subdev_desc *ssdd, struct v4l2_clk *clk, bool on)
372{
373	return on ? soc_camera_power_on(dev, ssdd, clk)
374		  : soc_camera_power_off(dev, ssdd, clk);
375}
376
377/* This is only temporary here - until v4l2-subdev begins to link to video_device */
378#include <linux/i2c.h>
379static inline struct video_device *soc_camera_i2c_to_vdev(const struct i2c_client *client)
380{
381	struct v4l2_subdev *sd = i2c_get_clientdata(client);
382	struct soc_camera_device *icd = v4l2_get_subdev_hostdata(sd);
383	return icd ? icd->vdev : NULL;
384}
385
386static inline struct soc_camera_subdev_desc *soc_camera_i2c_to_desc(const struct i2c_client *client)
387{
388	return client->dev.platform_data;
389}
390
391static inline struct v4l2_subdev *soc_camera_vdev_to_subdev(struct video_device *vdev)
392{
393	struct soc_camera_device *icd = video_get_drvdata(vdev);
394	return soc_camera_to_subdev(icd);
395}
396
397static inline struct soc_camera_device *soc_camera_from_vb2q(const struct vb2_queue *vq)
398{
399	return container_of(vq, struct soc_camera_device, vb2_vidq);
400}
401
402static inline struct soc_camera_device *soc_camera_from_vbq(const struct videobuf_queue *vq)
403{
404	return container_of(vq, struct soc_camera_device, vb_vidq);
405}
406
407static inline u32 soc_camera_grp_id(const struct soc_camera_device *icd)
408{
409	return (icd->iface << 8) | (icd->devnum + 1);
410}
411
412void soc_camera_lock(struct vb2_queue *vq);
413void soc_camera_unlock(struct vb2_queue *vq);
414
415#endif
416