include/media/v4l2-common.h

   1 /*
   2     v4l2 common internal API header
   3
   4     This header contains internal shared ioctl definitions for use by the
   5     internal low-level v4l2 drivers.
   6     Each ioctl begins with VIDIOC_INT_ to clearly mark that it is an internal
   7     define,
   8
   9     Copyright (C) 2005  Hans Verkuil <hverkuil@xs4all.nl>
  10
  11     This program is free software; you can redistribute it and/or modify
  12     it under the terms of the GNU General Public License as published by
  13     the Free Software Foundation; either version 2 of the License, or
  14     (at your option) any later version.
  15
  16     This program is distributed in the hope that it will be useful,
  17     but WITHOUT ANY WARRANTY; without even the implied warranty of
  18     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19     GNU General Public License for more details.
  20
  21     You should have received a copy of the GNU General Public License
  22     along with this program; if not, write to the Free Software
  23     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24  */
  25
  26 #ifndef V4L2_COMMON_H_
  27 #define V4L2_COMMON_H_
  28
  29 #include <media/v4l2-dev.h>
  30
  31 /* Common printk constucts for v4l-i2c drivers. These macros create a unique
  32    prefix consisting of the driver name, the adapter number and the i2c
  33    address. */
  34 #define v4l_printk(level, name, adapter, addr, fmt, arg...) \
  35         printk(level "%s %d-%04x: " fmt, name, i2c_adapter_id(adapter), addr , ## arg)
  36
  37 #define v4l_client_printk(level, client, fmt, arg...)                       \
  38         v4l_printk(level, (client)->driver->driver.name, (client)->adapter, \
  39                    (client)->addr, fmt , ## arg)
  40
  41 #define v4l_err(client, fmt, arg...) \
  42         v4l_client_printk(KERN_ERR, client, fmt , ## arg)
  43
  44 #define v4l_warn(client, fmt, arg...) \
  45         v4l_client_printk(KERN_WARNING, client, fmt , ## arg)
  46
  47 #define v4l_info(client, fmt, arg...) \
  48         v4l_client_printk(KERN_INFO, client, fmt , ## arg)
  49
  50 /* These three macros assume that the debug level is set with a module
  51    parameter called 'debug'. */
  52 #define v4l_dbg(level, debug, client, fmt, arg...)                           \
  53         do {                                                                 \
  54                 if (debug >= (level))                                        \
  55                         v4l_client_printk(KERN_DEBUG, client, fmt , ## arg); \
  56         } while (0)
  57
  58 /* ------------------------------------------------------------------------- */
  59
  60 /* These printk constructs can be used with v4l2_device and v4l2_subdev */
  61 #define v4l2_printk(level, dev, fmt, arg...) \
  62         printk(level "%s: " fmt, (dev)->name , ## arg)
  63
  64 #define v4l2_err(dev, fmt, arg...) \
  65         v4l2_printk(KERN_ERR, dev, fmt , ## arg)
  66
  67 #define v4l2_warn(dev, fmt, arg...) \
  68         v4l2_printk(KERN_WARNING, dev, fmt , ## arg)
  69
  70 #define v4l2_info(dev, fmt, arg...) \
  71         v4l2_printk(KERN_INFO, dev, fmt , ## arg)
  72
  73 /* These three macros assume that the debug level is set with a module
  74    parameter called 'debug'. */
  75 #define v4l2_dbg(level, debug, dev, fmt, arg...)                        \
  76         do {                                                            \
  77                 if (debug >= (level))                                   \
  78                         v4l2_printk(KERN_DEBUG, dev, fmt , ## arg);     \
  79         } while (0)
  80
  81 /* ------------------------------------------------------------------------- */
  82
  83 /* Priority helper functions */
  84
  85 struct v4l2_prio_state {
  86         atomic_t prios[4];
  87 };
  88 int v4l2_prio_init(struct v4l2_prio_state *global);
  89 int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
  90                      enum v4l2_priority new);
  91 int v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local);
  92 int v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority *local);
  93 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
  94 int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority *local);
  95
  96 /* ------------------------------------------------------------------------- */
  97
  98 /* Control helper functions */
  99
 100 int v4l2_ctrl_check(struct v4l2_ext_control *ctrl, struct v4l2_queryctrl *qctrl,
 101                 const char **menu_items);
 102 const char *v4l2_ctrl_get_name(u32 id);
 103 const char **v4l2_ctrl_get_menu(u32 id);
 104 int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def);
 105 int v4l2_ctrl_query_menu(struct v4l2_querymenu *qmenu,
 106                 struct v4l2_queryctrl *qctrl, const char **menu_items);
 107 #define V4L2_CTRL_MENU_IDS_END (0xffffffff)
 108 int v4l2_ctrl_query_menu_valid_items(struct v4l2_querymenu *qmenu, const u32 *ids);
 109
 110 /* Note: ctrl_classes points to an array of u32 pointers. Each u32 array is a
 111    0-terminated array of control IDs. Each array must be sorted low to high
 112    and belong to the same control class. The array of u32 pointers must also
 113    be sorted, from low class IDs to high class IDs. */
 114 u32 v4l2_ctrl_next(const u32 * const *ctrl_classes, u32 id);
 115
 116 /* ------------------------------------------------------------------------- */
 117
 118 /* Register/chip ident helper function */
 119
 120 struct i2c_client; /* forward reference */
 121 int v4l2_chip_match_i2c_client(struct i2c_client *c, const struct v4l2_dbg_match *match);
 122 int v4l2_chip_ident_i2c_client(struct i2c_client *c, struct v4l2_dbg_chip_ident *chip,
 123                 u32 ident, u32 revision);
 124 int v4l2_chip_match_host(const struct v4l2_dbg_match *match);
 125
 126 /* ------------------------------------------------------------------------- */
 127
 128 /* Helper function for I2C legacy drivers */
 129
 130 struct i2c_driver;
 131 struct i2c_adapter;
 132 struct i2c_client;
 133 struct i2c_device_id;
 134 struct v4l2_device;
 135 struct v4l2_subdev;
 136 struct v4l2_subdev_ops;
 137
 138 int v4l2_i2c_attach(struct i2c_adapter *adapter, int address, struct i2c_driver *driver,
 139                 const char *name,
 140                 int (*probe)(struct i2c_client *, const struct i2c_device_id *));
 141
 142 /* Load an i2c module and return an initialized v4l2_subdev struct.
 143    Only call request_module if module_name != NULL.
 144    The client_type argument is the name of the chip that's on the adapter. */
 145 struct v4l2_subdev *v4l2_i2c_new_subdev(struct i2c_adapter *adapter,
 146                 const char *module_name, const char *client_type, u8 addr);
 147 /* Probe and load an i2c module and return an initialized v4l2_subdev struct.
 148    Only call request_module if module_name != NULL.
 149    The client_type argument is the name of the chip that's on the adapter. */
 150 struct v4l2_subdev *v4l2_i2c_new_probed_subdev(struct i2c_adapter *adapter,
 151                 const char *module_name, const char *client_type,
 152                 const unsigned short *addrs);
 153 /* Initialize an v4l2_subdev with data from an i2c_client struct */
 154 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
 155                 const struct v4l2_subdev_ops *ops);
 156 /* Return i2c client address of v4l2_subdev. */
 157 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd);
 158
 159 enum v4l2_i2c_tuner_type {
 160         ADDRS_RADIO,    /* Radio tuner addresses */
 161         ADDRS_DEMOD,    /* Demod tuner addresses */
 162         ADDRS_TV,       /* TV tuner addresses */
 163         /* TV tuner addresses if demod is present, this excludes
 164            addresses used by the demodulator from the list of
 165            candidates. */
 166         ADDRS_TV_WITH_DEMOD,
 167 };
 168 /* Return a list of I2C tuner addresses to probe. Use only if the tuner
 169    addresses are unknown. */
 170 const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type);
 171
 172 /* ------------------------------------------------------------------------- */
 173
 174 /* Internal ioctls */
 175
 176 /* VIDIOC_INT_DECODE_VBI_LINE */
 177 struct v4l2_decode_vbi_line {
 178         u32 is_second_field;    /* Set to 0 for the first (odd) field,
 179                                    set to 1 for the second (even) field. */
 180         u8 *p;                  /* Pointer to the sliced VBI data from the decoder.
 181                                    On exit points to the start of the payload. */
 182         u32 line;               /* Line number of the sliced VBI data (1-23) */
 183         u32 type;               /* VBI service type (V4L2_SLICED_*). 0 if no service found */
 184 };
 185
 186 struct v4l2_priv_tun_config {
 187         int tuner;
 188         void *priv;
 189 };
 190
 191 /* audio ioctls */
 192
 193 /* v4l device was opened in Radio mode, to be replaced by VIDIOC_INT_S_TUNER_MODE */
 194 #define AUDC_SET_RADIO        _IO('d',88)
 195
 196 /* tuner ioctls */
 197
 198 /* Sets tuner type and its I2C addr */
 199 #define TUNER_SET_TYPE_ADDR          _IOW('d', 90, int)
 200
 201 /* Puts tuner on powersaving state, disabling it, except for i2c. To be replaced
 202    by VIDIOC_INT_S_STANDBY. */
 203 #define TUNER_SET_STANDBY            _IOW('d', 91, int)
 204
 205 /* Sets tda9887 specific stuff, like port1, port2 and qss */
 206 #define TUNER_SET_CONFIG           _IOW('d', 92, struct v4l2_priv_tun_config)
 207
 208 /* Switch the tuner to a specific tuner mode. Replacement of AUDC_SET_RADIO */
 209 #define VIDIOC_INT_S_TUNER_MODE      _IOW('d', 93, enum v4l2_tuner_type)
 210
 211 /* Generic standby command. Passing -1 (all bits set to 1) will put the whole
 212    chip into standby mode, value 0 will make the chip fully active. Specific
 213    bits can be used by certain chips to enable/disable specific subsystems.
 214    Replacement of TUNER_SET_STANDBY. */
 215 #define VIDIOC_INT_S_STANDBY         _IOW('d', 94, u32)
 216
 217 /* 100, 101 used by  VIDIOC_DBG_[SG]_REGISTER */
 218
 219 /* Generic reset command. The argument selects which subsystems to reset.
 220    Passing 0 will always reset the whole chip. */
 221 #define VIDIOC_INT_RESET                _IOW ('d', 102, u32)
 222
 223 /* Set the frequency (in Hz) of the audio clock output.
 224    Used to slave an audio processor to the video decoder, ensuring that audio
 225    and video remain synchronized.
 226    Usual values for the frequency are 48000, 44100 or 32000 Hz.
 227    If the frequency is not supported, then -EINVAL is returned. */
 228 #define VIDIOC_INT_AUDIO_CLOCK_FREQ     _IOW ('d', 103, u32)
 229
 230 /* Video decoders that support sliced VBI need to implement this ioctl.
 231    Field p of the v4l2_sliced_vbi_line struct is set to the start of the VBI
 232    data that was generated by the decoder. The driver then parses the sliced
 233    VBI data and sets the other fields in the struct accordingly. The pointer p
 234    is updated to point to the start of the payload which can be copied
 235    verbatim into the data field of the v4l2_sliced_vbi_data struct. If no
 236    valid VBI data was found, then the type field is set to 0 on return. */
 237 #define VIDIOC_INT_DECODE_VBI_LINE      _IOWR('d', 104, struct v4l2_decode_vbi_line)
 238
 239 /* Used to generate VBI signals on a video signal. v4l2_sliced_vbi_data is
 240    filled with the data packets that should be output. Note that if you set
 241    the line field to 0, then that VBI signal is disabled. If no
 242    valid VBI data was found, then the type field is set to 0 on return. */
 243 #define VIDIOC_INT_S_VBI_DATA           _IOW ('d', 105, struct v4l2_sliced_vbi_data)
 244
 245 /* Used to obtain the sliced VBI packet from a readback register. Not all
 246    video decoders support this. If no data is available because the readback
 247    register contains invalid or erroneous data -EIO is returned. Note that
 248    you must fill in the 'id' member and the 'field' member (to determine
 249    whether CC data from the first or second field should be obtained). */
 250 #define VIDIOC_INT_G_VBI_DATA           _IOWR('d', 106, struct v4l2_sliced_vbi_data)
 251
 252 /* Sets I2S speed in bps. This is used to provide a standard way to select I2S
 253    clock used by driving digital audio streams at some board designs.
 254    Usual values for the frequency are 1024000 and 2048000.
 255    If the frequency is not supported, then -EINVAL is returned. */
 256 #define VIDIOC_INT_I2S_CLOCK_FREQ       _IOW ('d', 108, u32)
 257
 258 /* Routing definition, device dependent. It specifies which inputs (if any)
 259    should be routed to which outputs (if any). */
 260 struct v4l2_routing {
 261         u32 input;
 262         u32 output;
 263 };
 264
 265 /* These internal commands should be used to define the inputs and outputs
 266    of an audio/video chip. They will replace the v4l2 API commands
 267    VIDIOC_S/G_INPUT, VIDIOC_S/G_OUTPUT, VIDIOC_S/G_AUDIO and VIDIOC_S/G_AUDOUT
 268    that are meant to be used by the user.
 269    The internal commands should be used to switch inputs/outputs
 270    because only the driver knows how to map a 'Television' input to the precise
 271    input/output routing of an A/D converter, or a DSP, or a video digitizer.
 272    These four commands should only be sent directly to an i2c device, they
 273    should not be broadcast as the routing is very device specific. */
 274 #define VIDIOC_INT_S_AUDIO_ROUTING      _IOW ('d', 109, struct v4l2_routing)
 275 #define VIDIOC_INT_G_AUDIO_ROUTING      _IOR ('d', 110, struct v4l2_routing)
 276 #define VIDIOC_INT_S_VIDEO_ROUTING      _IOW ('d', 111, struct v4l2_routing)
 277 #define VIDIOC_INT_G_VIDEO_ROUTING      _IOR ('d', 112, struct v4l2_routing)
 278
 279 struct v4l2_crystal_freq {
 280         u32 freq;       /* frequency in Hz of the crystal */
 281         u32 flags;      /* device specific flags */
 282 };
 283
 284 /* Sets the frequency of the crystal used to generate the clocks.
 285    An extra flags field allows device specific configuration regarding
 286    clock frequency dividers, etc. If not used, then set flags to 0.
 287    If the frequency is not supported, then -EINVAL is returned. */
 288 #define VIDIOC_INT_S_CRYSTAL_FREQ       _IOW('d', 113, struct v4l2_crystal_freq)
 289
 290 /* Initialize the sensor registors to some sort of reasonable
 291    default values. */
 292 #define VIDIOC_INT_INIT                 _IOW('d', 114, u32)
 293
 294 /* Set v4l2_std_id for video OUTPUT devices. This is ignored by
 295    video input devices. */
 296 #define VIDIOC_INT_S_STD_OUTPUT         _IOW('d', 115, v4l2_std_id)
 297
 298 /* Get v4l2_std_id for video OUTPUT devices. This is ignored by
 299    video input devices. */
 300 #define VIDIOC_INT_G_STD_OUTPUT         _IOW('d', 116, v4l2_std_id)
 301
 302 /* Set GPIO pins. Very simple right now, might need to be extended with
 303    a v4l2_gpio struct if a direction is also needed. */
 304 #define VIDIOC_INT_S_GPIO               _IOW('d', 117, u32)
 305
 306 /* Get input status. Same as the status field in the v4l2_input struct. */
 307 #define VIDIOC_INT_G_INPUT_STATUS       _IOR('d', 118, u32)
 308
 309 #endif /* V4L2_COMMON_H_ */