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 26 /* generic v4l2_device notify callback notification values */ 27 #define V4L2_SUBDEV_IR_RX_NOTIFY _IOW('v', 0, u32) 28 #define V4L2_SUBDEV_IR_RX_FIFO_SERVICE_REQ 0x00000001 29 #define V4L2_SUBDEV_IR_RX_END_OF_RX_DETECTED 0x00000002 30 #define V4L2_SUBDEV_IR_RX_HW_FIFO_OVERRUN 0x00000004 31 #define V4L2_SUBDEV_IR_RX_SW_FIFO_OVERRUN 0x00000008 32 33 #define V4L2_SUBDEV_IR_TX_NOTIFY _IOW('v', 1, u32) 34 #define V4L2_SUBDEV_IR_TX_FIFO_SERVICE_REQ 0x00000001 35 36 struct v4l2_device; 37 struct v4l2_subdev; 38 struct tuner_setup; 39 40 /* decode_vbi_line */ 41 struct v4l2_decode_vbi_line { 42 u32 is_second_field; /* Set to 0 for the first (odd) field, 43 set to 1 for the second (even) field. */ 44 u8 *p; /* Pointer to the sliced VBI data from the decoder. 45 On exit points to the start of the payload. */ 46 u32 line; /* Line number of the sliced VBI data (1-23) */ 47 u32 type; /* VBI service type (V4L2_SLICED_*). 0 if no service found */ 48 }; 49 50 /* Sub-devices are devices that are connected somehow to the main bridge 51 device. These devices are usually audio/video muxers/encoders/decoders or 52 sensors and webcam controllers. 53 54 Usually these devices are controlled through an i2c bus, but other busses 55 may also be used. 56 57 The v4l2_subdev struct provides a way of accessing these devices in a 58 generic manner. Most operations that these sub-devices support fall in 59 a few categories: core ops, audio ops, video ops and tuner ops. 60 61 More categories can be added if needed, although this should remain a 62 limited set (no more than approx. 8 categories). 63 64 Each category has its own set of ops that subdev drivers can implement. 65 66 A subdev driver can leave the pointer to the category ops NULL if 67 it does not implement them (e.g. an audio subdev will generally not 68 implement the video category ops). The exception is the core category: 69 this must always be present. 70 71 These ops are all used internally so it is no problem to change, remove 72 or add ops or move ops from one to another category. Currently these 73 ops are based on the original ioctls, but since ops are not limited to 74 one argument there is room for improvement here once all i2c subdev 75 drivers are converted to use these ops. 76 */ 77 78 /* Core ops: it is highly recommended to implement at least these ops: 79 80 g_chip_ident 81 log_status 82 g_register 83 s_register 84 85 This provides basic debugging support. 86 87 The ioctl ops is meant for generic ioctl-like commands. Depending on 88 the use-case it might be better to use subdev-specific ops (currently 89 not yet implemented) since ops provide proper type-checking. 90 */ 91 92 /* s_config: if set, then it is always called by the v4l2_i2c_new_subdev* 93 functions after the v4l2_subdev was registered. It is used to pass 94 platform data to the subdev which can be used during initialization. 95 96 init: initialize the sensor registors to some sort of reasonable default 97 values. Do not use for new drivers and should be removed in existing 98 drivers. 99 100 load_fw: load firmware. 101 102 reset: generic reset command. The argument selects which subsystems to 103 reset. Passing 0 will always reset the whole chip. Do not use for new 104 drivers without discussing this first on the linux-media mailinglist. 105 There should be no reason normally to reset a device. 106 107 s_gpio: set GPIO pins. Very simple right now, might need to be extended with 108 a direction argument if needed. 109 110 s_power: puts subdevice in power saving mode (on == 0) or normal operation 111 mode (on == 1). 112 */ 113 struct v4l2_subdev_core_ops { 114 int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip); 115 int (*log_status)(struct v4l2_subdev *sd); 116 int (*s_config)(struct v4l2_subdev *sd, int irq, void *platform_data); 117 int (*init)(struct v4l2_subdev *sd, u32 val); 118 int (*load_fw)(struct v4l2_subdev *sd); 119 int (*reset)(struct v4l2_subdev *sd, u32 val); 120 int (*s_gpio)(struct v4l2_subdev *sd, u32 val); 121 int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc); 122 int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); 123 int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); 124 int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); 125 int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); 126 int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); 127 int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm); 128 int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm); 129 long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg); 130 #ifdef CONFIG_VIDEO_ADV_DEBUG 131 int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg); 132 int (*s_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg); 133 #endif 134 int (*s_power)(struct v4l2_subdev *sd, int on); 135 }; 136 137 /* s_mode: switch the tuner to a specific tuner mode. Replacement of s_radio. 138 139 s_radio: v4l device was opened in Radio mode, to be replaced by s_mode. 140 141 s_type_addr: sets tuner type and its I2C addr. 142 143 s_config: sets tda9887 specific stuff, like port1, port2 and qss 144 */ 145 struct v4l2_subdev_tuner_ops { 146 int (*s_mode)(struct v4l2_subdev *sd, enum v4l2_tuner_type); 147 int (*s_radio)(struct v4l2_subdev *sd); 148 int (*s_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq); 149 int (*g_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq); 150 int (*g_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt); 151 int (*s_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt); 152 int (*g_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm); 153 int (*s_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm); 154 int (*s_type_addr)(struct v4l2_subdev *sd, struct tuner_setup *type); 155 int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config); 156 }; 157 158 /* s_clock_freq: set the frequency (in Hz) of the audio clock output. 159 Used to slave an audio processor to the video decoder, ensuring that 160 audio and video remain synchronized. Usual values for the frequency 161 are 48000, 44100 or 32000 Hz. If the frequency is not supported, then 162 -EINVAL is returned. 163 164 s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard 165 way to select I2S clock used by driving digital audio streams at some 166 board designs. Usual values for the frequency are 1024000 and 2048000. 167 If the frequency is not supported, then -EINVAL is returned. 168 169 s_routing: used to define the input and/or output pins of an audio chip, 170 and any additional configuration data. 171 Never attempt to use user-level input IDs (e.g. Composite, S-Video, 172 Tuner) at this level. An i2c device shouldn't know about whether an 173 input pin is connected to a Composite connector, become on another 174 board or platform it might be connected to something else entirely. 175 The calling driver is responsible for mapping a user-level input to 176 the right pins on the i2c device. 177 */ 178 struct v4l2_subdev_audio_ops { 179 int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq); 180 int (*s_i2s_clock_freq)(struct v4l2_subdev *sd, u32 freq); 181 int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config); 182 }; 183 184 /* 185 decode_vbi_line: video decoders that support sliced VBI need to implement 186 this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the 187 start of the VBI data that was generated by the decoder. The driver 188 then parses the sliced VBI data and sets the other fields in the 189 struct accordingly. The pointer p is updated to point to the start of 190 the payload which can be copied verbatim into the data field of the 191 v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the 192 type field is set to 0 on return. 193 194 s_vbi_data: used to generate VBI signals on a video signal. 195 v4l2_sliced_vbi_data is filled with the data packets that should be 196 output. Note that if you set the line field to 0, then that VBI signal 197 is disabled. If no valid VBI data was found, then the type field is 198 set to 0 on return. 199 200 g_vbi_data: used to obtain the sliced VBI packet from a readback register. 201 Not all video decoders support this. If no data is available because 202 the readback register contains invalid or erroneous data -EIO is 203 returned. Note that you must fill in the 'id' member and the 'field' 204 member (to determine whether CC data from the first or second field 205 should be obtained). 206 207 s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by 208 video input devices. 209 210 s_crystal_freq: sets the frequency of the crystal used to generate the 211 clocks in Hz. An extra flags field allows device specific configuration 212 regarding clock frequency dividers, etc. If not used, then set flags 213 to 0. If the frequency is not supported, then -EINVAL is returned. 214 215 g_input_status: get input status. Same as the status field in the v4l2_input 216 struct. 217 218 s_routing: see s_routing in audio_ops, except this version is for video 219 devices. 220 */ 221 struct v4l2_subdev_video_ops { 222 int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config); 223 int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags); 224 int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line); 225 int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data); 226 int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data); 227 int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap); 228 int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std); 229 int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std); 230 int (*g_input_status)(struct v4l2_subdev *sd, u32 *status); 231 int (*s_stream)(struct v4l2_subdev *sd, int enable); 232 int (*enum_fmt)(struct v4l2_subdev *sd, struct v4l2_fmtdesc *fmtdesc); 233 int (*g_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt); 234 int (*try_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt); 235 int (*s_fmt)(struct v4l2_subdev *sd, struct v4l2_format *fmt); 236 int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc); 237 int (*g_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop); 238 int (*s_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop); 239 int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); 240 int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param); 241 int (*enum_framesizes)(struct v4l2_subdev *sd, struct v4l2_frmsizeenum *fsize); 242 int (*enum_frameintervals)(struct v4l2_subdev *sd, struct v4l2_frmivalenum *fival); 243 }; 244 245 /* 246 interrupt_service_routine: Called by the bridge chip's interrupt service 247 handler, when an IR interrupt status has be raised due to this subdev, 248 so that this subdev can handle the details. It may schedule work to be 249 performed later. It must not sleep. *Called from an IRQ context*. 250 251 [rt]x_g_parameters: Get the current operating parameters and state of the 252 the IR receiver or transmitter. 253 254 [rt]x_s_parameters: Set the current operating parameters and state of the 255 the IR receiver or transmitter. It is recommended to call 256 [rt]x_g_parameters first to fill out the current state, and only change 257 the fields that need to be changed. Upon return, the actual device 258 operating parameters and state will be returned. Note that hardware 259 limitations may prevent the actual settings from matching the requested 260 settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz 261 was requested. An exception is when the shutdown parameter is true. 262 The last used operational parameters will be returned, but the actual 263 state of the hardware be different to minimize power consumption and 264 processing when shutdown is true. 265 266 rx_read: Reads received codes or pulse width data. 267 The semantics are similar to a non-blocking read() call. 268 269 tx_write: Writes codes or pulse width data for transmission. 270 The semantics are similar to a non-blocking write() call. 271 */ 272 273 enum v4l2_subdev_ir_mode { 274 V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* space & mark widths in nanosecs */ 275 }; 276 277 /* Data format of data read or written for V4L2_SUBDEV_IR_MODE_PULSE_WIDTH */ 278 #define V4L2_SUBDEV_IR_PULSE_MAX_WIDTH_NS 0x7fffffff 279 #define V4L2_SUBDEV_IR_PULSE_LEVEL_MASK 0x80000000 280 #define V4L2_SUBDEV_IR_PULSE_RX_SEQ_END 0xffffffff 281 282 struct v4l2_subdev_ir_parameters { 283 /* Either Rx or Tx */ 284 unsigned int bytes_per_data_element; /* of data in read or write call */ 285 enum v4l2_subdev_ir_mode mode; 286 287 bool enable; 288 bool interrupt_enable; 289 bool shutdown; /* true: set hardware to low/no power, false: normal */ 290 291 bool modulation; /* true: uses carrier, false: baseband */ 292 u32 max_pulse_width; /* ns, valid only for baseband signal */ 293 unsigned int carrier_freq; /* Hz, valid only for modulated signal*/ 294 unsigned int duty_cycle; /* percent, valid only for modulated signal*/ 295 bool invert; /* logically invert sense of mark/space */ 296 297 /* Rx only */ 298 u32 noise_filter_min_width; /* ns, min time of a valid pulse */ 299 unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */ 300 unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */ 301 u32 resolution; /* ns */ 302 }; 303 304 struct v4l2_subdev_ir_ops { 305 /* Common to receiver and transmitter */ 306 int (*interrupt_service_routine)(struct v4l2_subdev *sd, 307 u32 status, bool *handled); 308 309 /* Receiver */ 310 int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count, 311 ssize_t *num); 312 313 int (*rx_g_parameters)(struct v4l2_subdev *sd, 314 struct v4l2_subdev_ir_parameters *params); 315 int (*rx_s_parameters)(struct v4l2_subdev *sd, 316 struct v4l2_subdev_ir_parameters *params); 317 318 /* Transmitter */ 319 int (*tx_write)(struct v4l2_subdev *sd, u8 *buf, size_t count, 320 ssize_t *num); 321 322 int (*tx_g_parameters)(struct v4l2_subdev *sd, 323 struct v4l2_subdev_ir_parameters *params); 324 int (*tx_s_parameters)(struct v4l2_subdev *sd, 325 struct v4l2_subdev_ir_parameters *params); 326 }; 327 328 struct v4l2_subdev_ops { 329 const struct v4l2_subdev_core_ops *core; 330 const struct v4l2_subdev_tuner_ops *tuner; 331 const struct v4l2_subdev_audio_ops *audio; 332 const struct v4l2_subdev_video_ops *video; 333 const struct v4l2_subdev_ir_ops *ir; 334 }; 335 336 #define V4L2_SUBDEV_NAME_SIZE 32 337 338 /* Set this flag if this subdev is a i2c device. */ 339 #define V4L2_SUBDEV_FL_IS_I2C (1U << 0) 340 341 /* Each instance of a subdev driver should create this struct, either 342 stand-alone or embedded in a larger struct. 343 */ 344 struct v4l2_subdev { 345 struct list_head list; 346 struct module *owner; 347 u32 flags; 348 struct v4l2_device *v4l2_dev; 349 const struct v4l2_subdev_ops *ops; 350 /* name must be unique */ 351 char name[V4L2_SUBDEV_NAME_SIZE]; 352 /* can be used to group similar subdevs, value is driver-specific */ 353 u32 grp_id; 354 /* pointer to private data */ 355 void *priv; 356 }; 357 358 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p) 359 { 360 sd->priv = p; 361 } 362 363 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd) 364 { 365 return sd->priv; 366 } 367 368 static inline void v4l2_subdev_init(struct v4l2_subdev *sd, 369 const struct v4l2_subdev_ops *ops) 370 { 371 INIT_LIST_HEAD(&sd->list); 372 /* ops->core MUST be set */ 373 BUG_ON(!ops || !ops->core); 374 sd->ops = ops; 375 sd->v4l2_dev = NULL; 376 sd->flags = 0; 377 sd->name[0] = '\0'; 378 sd->grp_id = 0; 379 sd->priv = NULL; 380 } 381 382 /* Call an ops of a v4l2_subdev, doing the right checks against 383 NULL pointers. 384 385 Example: err = v4l2_subdev_call(sd, core, g_chip_ident, &chip); 386 */ 387 #define v4l2_subdev_call(sd, o, f, args...) \ 388 (!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ? \ 389 (sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD)) 390 391 /* Send a notification to v4l2_device. */ 392 #define v4l2_subdev_notify(sd, notification, arg) \ 393 ((!(sd) || !(sd)->v4l2_dev || !(sd)->v4l2_dev->notify) ? -ENODEV : \ 394 (sd)->v4l2_dev->notify((sd), (notification), (arg))) 395 396 #endif 397