Root/include/media/v4l2-subdev.h

1/*
2    V4L2 sub-device support header.
3
4    Copyright (C) 2008 Hans Verkuil <hverkuil@xs4all.nl>
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20
21#ifndef _V4L2_SUBDEV_H
22#define _V4L2_SUBDEV_H
23
24#include <media/v4l2-common.h>
25
26struct v4l2_device;
27struct v4l2_subdev;
28struct tuner_setup;
29
30/* decode_vbi_line */
31struct v4l2_decode_vbi_line {
32    u32 is_second_field; /* Set to 0 for the first (odd) field,
33                   set to 1 for the second (even) field. */
34    u8 *p; /* Pointer to the sliced VBI data from the decoder.
35                   On exit points to the start of the payload. */
36    u32 line; /* Line number of the sliced VBI data (1-23) */
37    u32 type; /* VBI service type (V4L2_SLICED_*). 0 if no service found */
38};
39
40/* Sub-devices are devices that are connected somehow to the main bridge
41   device. These devices are usually audio/video muxers/encoders/decoders or
42   sensors and webcam controllers.
43
44   Usually these devices are controlled through an i2c bus, but other busses
45   may also be used.
46
47   The v4l2_subdev struct provides a way of accessing these devices in a
48   generic manner. Most operations that these sub-devices support fall in
49   a few categories: core ops, audio ops, video ops and tuner ops.
50
51   More categories can be added if needed, although this should remain a
52   limited set (no more than approx. 8 categories).
53
54   Each category has its own set of ops that subdev drivers can implement.
55
56   A subdev driver can leave the pointer to the category ops NULL if
57   it does not implement them (e.g. an audio subdev will generally not
58   implement the video category ops). The exception is the core category:
59   this must always be present.
60
61   These ops are all used internally so it is no problem to change, remove
62   or add ops or move ops from one to another category. Currently these
63   ops are based on the original ioctls, but since ops are not limited to
64   one argument there is room for improvement here once all i2c subdev
65   drivers are converted to use these ops.
66 */
67
68/* Core ops: it is highly recommended to implement at least these ops:
69
70   g_chip_ident
71   log_status
72   g_register
73   s_register
74
75   This provides basic debugging support.
76
77   The ioctl ops is meant for generic ioctl-like commands. Depending on
78   the use-case it might be better to use subdev-specific ops (currently
79   not yet implemented) since ops provide proper type-checking.
80 */
81
82/* s_config: if set, then it is always called by the v4l2_i2c_new_subdev*
83    functions after the v4l2_subdev was registered. It is used to pass
84    platform data to the subdev which can be used during initialization.
85
86   init: initialize the sensor registors to some sort of reasonable default
87    values. Do not use for new drivers and should be removed in existing
88    drivers.
89
90   load_fw: load firmware.
91
92   reset: generic reset command. The argument selects which subsystems to
93    reset. Passing 0 will always reset the whole chip. Do not use for new
94    drivers without discussing this first on the linux-media mailinglist.
95    There should be no reason normally to reset a device.
96
97   s_gpio: set GPIO pins. Very simple right now, might need to be extended with
98    a direction argument if needed.
99 */
100struct v4l2_subdev_core_ops {
101    int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip);
102    int (*log_status)(struct v4l2_subdev *sd);
103    int (*s_config)(struct v4l2_subdev *sd, int irq, void *platform_data);
104    int (*init)(struct v4l2_subdev *sd, u32 val);
105    int (*load_fw)(struct v4l2_subdev *sd);
106    int (*reset)(struct v4l2_subdev *sd, u32 val);
107    int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
108    int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
109    int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
110    int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
111    int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
112    int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
113    int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
114    int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
115    int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm);
116    long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
117#ifdef CONFIG_VIDEO_ADV_DEBUG
118    int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
119    int (*s_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
120#endif
121};
122
123/* s_mode: switch the tuner to a specific tuner mode. Replacement of s_radio.
124
125   s_radio: v4l device was opened in Radio mode, to be replaced by s_mode.
126
127   s_type_addr: sets tuner type and its I2C addr.
128
129   s_config: sets tda9887 specific stuff, like port1, port2 and qss
130
131   s_standby: puts tuner on powersaving state, disabling it, except for i2c.
132 */
133struct v4l2_subdev_tuner_ops {
134    int (*s_mode)(struct v4l2_subdev *sd, enum v4l2_tuner_type);
135    int (*s_radio)(struct v4l2_subdev *sd);
136    int (*s_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq);
137    int (*g_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq);
138    int (*g_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt);
139    int (*s_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt);
140    int (*g_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm);
141    int (*s_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm);
142    int (*s_type_addr)(struct v4l2_subdev *sd, struct tuner_setup *type);
143    int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
144    int (*s_standby)(struct v4l2_subdev *sd);
145};
146
147/* s_clock_freq: set the frequency (in Hz) of the audio clock output.
148    Used to slave an audio processor to the video decoder, ensuring that
149    audio and video remain synchronized. Usual values for the frequency
150    are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
151    -EINVAL is returned.
152
153   s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
154    way to select I2S clock used by driving digital audio streams at some
155    board designs. Usual values for the frequency are 1024000 and 2048000.
156    If the frequency is not supported, then -EINVAL is returned.
157
158   s_routing: used to define the input and/or output pins of an audio chip,
159    and any additional configuration data.
160    Never attempt to use user-level input IDs (e.g. Composite, S-Video,
161    Tuner) at this level. An i2c device shouldn't know about whether an
162    input pin is connected to a Composite connector, become on another
163    board or platform it might be connected to something else entirely.
164    The calling driver is responsible for mapping a user-level input to
165    the right pins on the i2c device.
166 */
167struct v4l2_subdev_audio_ops {
168    int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
169    int (*s_i2s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
170    int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
171};
172
173/*
174   decode_vbi_line: video decoders that support sliced VBI need to implement
175    this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
176    start of the VBI data that was generated by the decoder. The driver
177    then parses the sliced VBI data and sets the other fields in the
178    struct accordingly. The pointer p is updated to point to the start of
179    the payload which can be copied verbatim into the data field of the
180    v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
181    type field is set to 0 on return.
182
183   s_vbi_data: used to generate VBI signals on a video signal.
184    v4l2_sliced_vbi_data is filled with the data packets that should be
185    output. Note that if you set the line field to 0, then that VBI signal
186    is disabled. If no valid VBI data was found, then the type field is
187    set to 0 on return.
188
189   g_vbi_data: used to obtain the sliced VBI packet from a readback register.
190    Not all video decoders support this. If no data is available because
191    the readback register contains invalid or erroneous data -EIO is
192    returned. Note that you must fill in the 'id' member and the 'field'
193    member (to determine whether CC data from the first or second field
194    should be obtained).
195
196   s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
197    video input devices.
198
199  s_crystal_freq: sets the frequency of the crystal used to generate the
200    clocks in Hz. An extra flags field allows device specific configuration
201    regarding clock frequency dividers, etc. If not used, then set flags
202    to 0. If the frequency is not supported, then -EINVAL is returned.
203
204   g_input_status: get input status. Same as the status field in the v4l2_input
205    struct.
206
207   s_routing: see s_routing in audio_ops, except this version is for video
208    devices.
209 */
210struct v4l2_subdev_video_ops {
211    int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
212    int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags);
213    int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
214    int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
215    int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
216    int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
217    int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std);
218    int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std);
219    int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
220    int (*s_stream)(struct v4l2_subdev *sd, int enable);
221    int (*enum_fmt)(struct v4l2_subdev *sd, struct v4l2_fmtdesc *fmtdesc);
222    int (*g_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt);
223    int (*try_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt);
224    int (*s_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt);
225    int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc);
226    int (*g_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop);
227    int (*s_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop);
228    int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
229    int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
230    int (*enum_framesizes)(struct v4l2_subdev *sd, struct v4l2_frmsizeenum *fsize);
231    int (*enum_frameintervals)(struct v4l2_subdev *sd, struct v4l2_frmivalenum *fival);
232};
233
234struct v4l2_subdev_ops {
235    const struct v4l2_subdev_core_ops *core;
236    const struct v4l2_subdev_tuner_ops *tuner;
237    const struct v4l2_subdev_audio_ops *audio;
238    const struct v4l2_subdev_video_ops *video;
239};
240
241#define V4L2_SUBDEV_NAME_SIZE 32
242
243/* Set this flag if this subdev is a i2c device. */
244#define V4L2_SUBDEV_FL_IS_I2C (1U << 0)
245
246/* Each instance of a subdev driver should create this struct, either
247   stand-alone or embedded in a larger struct.
248 */
249struct v4l2_subdev {
250    struct list_head list;
251    struct module *owner;
252    u32 flags;
253    struct v4l2_device *v4l2_dev;
254    const struct v4l2_subdev_ops *ops;
255    /* name must be unique */
256    char name[V4L2_SUBDEV_NAME_SIZE];
257    /* can be used to group similar subdevs, value is driver-specific */
258    u32 grp_id;
259    /* pointer to private data */
260    void *priv;
261};
262
263static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
264{
265    sd->priv = p;
266}
267
268static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
269{
270    return sd->priv;
271}
272
273static inline void v4l2_subdev_init(struct v4l2_subdev *sd,
274                    const struct v4l2_subdev_ops *ops)
275{
276    INIT_LIST_HEAD(&sd->list);
277    /* ops->core MUST be set */
278    BUG_ON(!ops || !ops->core);
279    sd->ops = ops;
280    sd->v4l2_dev = NULL;
281    sd->flags = 0;
282    sd->name[0] = '\0';
283    sd->grp_id = 0;
284    sd->priv = NULL;
285}
286
287/* Call an ops of a v4l2_subdev, doing the right checks against
288   NULL pointers.
289
290   Example: err = v4l2_subdev_call(sd, core, g_chip_ident, &chip);
291 */
292#define v4l2_subdev_call(sd, o, f, args...) \
293    (!(sd) ? -ENODEV : (((sd) && (sd)->ops->o && (sd)->ops->o->f) ? \
294        (sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD))
295
296/* Send a notification to v4l2_device. */
297#define v4l2_subdev_notify(sd, notification, arg) \
298    ((!(sd) || !(sd)->v4l2_dev || !(sd)->v4l2_dev->notify) ? -ENODEV : \
299     (sd)->v4l2_dev->notify((sd), (notification), (arg)))
300
301#endif
302

Archive Download this file

Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master

Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9



interactive