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 <linux/types.h>
  25 #include <linux/v4l2-subdev.h>
  26 #include <media/media-entity.h>
  27 #include <media/v4l2-async.h>
  28 #include <media/v4l2-common.h>
  29 #include <media/v4l2-dev.h>
  30 #include <media/v4l2-fh.h>
  31 #include <media/v4l2-mediabus.h>
  32
  33 /* generic v4l2_device notify callback notification values */
  34 #define V4L2_SUBDEV_IR_RX_NOTIFY                _IOW('v', 0, u32)
  35 #define V4L2_SUBDEV_IR_RX_FIFO_SERVICE_REQ      0x00000001
  36 #define V4L2_SUBDEV_IR_RX_END_OF_RX_DETECTED    0x00000002
  37 #define V4L2_SUBDEV_IR_RX_HW_FIFO_OVERRUN       0x00000004
  38 #define V4L2_SUBDEV_IR_RX_SW_FIFO_OVERRUN       0x00000008
  39
  40 #define V4L2_SUBDEV_IR_TX_NOTIFY                _IOW('v', 1, u32)
  41 #define V4L2_SUBDEV_IR_TX_FIFO_SERVICE_REQ      0x00000001
  42
  43 struct v4l2_device;
  44 struct v4l2_ctrl_handler;
  45 struct v4l2_event_subscription;
  46 struct v4l2_fh;
  47 struct v4l2_subdev;
  48 struct v4l2_subdev_fh;
  49 struct tuner_setup;
  50 struct v4l2_mbus_frame_desc;
  51
  52 /* decode_vbi_line */
  53 struct v4l2_decode_vbi_line {
  54         u32 is_second_field;    /* Set to 0 for the first (odd) field,
  55                                    set to 1 for the second (even) field. */
  56         u8 *p;                  /* Pointer to the sliced VBI data from the decoder.
  57                                    On exit points to the start of the payload. */
  58         u32 line;               /* Line number of the sliced VBI data (1-23) */
  59         u32 type;               /* VBI service type (V4L2_SLICED_*). 0 if no service found */
  60 };
  61
  62 /* Sub-devices are devices that are connected somehow to the main bridge
  63    device. These devices are usually audio/video muxers/encoders/decoders or
  64    sensors and webcam controllers.
  65
  66    Usually these devices are controlled through an i2c bus, but other busses
  67    may also be used.
  68
  69    The v4l2_subdev struct provides a way of accessing these devices in a
  70    generic manner. Most operations that these sub-devices support fall in
  71    a few categories: core ops, audio ops, video ops and tuner ops.
  72
  73    More categories can be added if needed, although this should remain a
  74    limited set (no more than approx. 8 categories).
  75
  76    Each category has its own set of ops that subdev drivers can implement.
  77
  78    A subdev driver can leave the pointer to the category ops NULL if
  79    it does not implement them (e.g. an audio subdev will generally not
  80    implement the video category ops). The exception is the core category:
  81    this must always be present.
  82
  83    These ops are all used internally so it is no problem to change, remove
  84    or add ops or move ops from one to another category. Currently these
  85    ops are based on the original ioctls, but since ops are not limited to
  86    one argument there is room for improvement here once all i2c subdev
  87    drivers are converted to use these ops.
  88  */
  89
  90 /* Core ops: it is highly recommended to implement at least these ops:
  91
  92    log_status
  93    g_register
  94    s_register
  95
  96    This provides basic debugging support.
  97
  98    The ioctl ops is meant for generic ioctl-like commands. Depending on
  99    the use-case it might be better to use subdev-specific ops (currently
 100    not yet implemented) since ops provide proper type-checking.
 101  */
 102
 103 /* Subdevice external IO pin configuration */
 104 #define V4L2_SUBDEV_IO_PIN_DISABLE      (1 << 0) /* ENABLE assumed */
 105 #define V4L2_SUBDEV_IO_PIN_OUTPUT       (1 << 1)
 106 #define V4L2_SUBDEV_IO_PIN_INPUT        (1 << 2)
 107 #define V4L2_SUBDEV_IO_PIN_SET_VALUE    (1 << 3) /* Set output value */
 108 #define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW   (1 << 4) /* ACTIVE HIGH assumed */
 109
 110 struct v4l2_subdev_io_pin_config {
 111         u32 flags;      /* V4L2_SUBDEV_IO_PIN_* flags for this pin's config */
 112         u8 pin;         /* Chip external IO pin to configure */
 113         u8 function;    /* Internal signal pad/function to route to IO pin */
 114         u8 value;       /* Initial value for pin - e.g. GPIO output value */
 115         u8 strength;    /* Pin drive strength */
 116 };
 117
 118 /*
 119    s_io_pin_config: configure one or more chip I/O pins for chips that
 120         multiplex different internal signal pads out to IO pins.  This function
 121         takes a pointer to an array of 'n' pin configuration entries, one for
 122         each pin being configured.  This function could be called at times
 123         other than just subdevice initialization.
 124
 125    init: initialize the sensor registers to some sort of reasonable default
 126         values. Do not use for new drivers and should be removed in existing
 127         drivers.
 128
 129    load_fw: load firmware.
 130
 131    reset: generic reset command. The argument selects which subsystems to
 132         reset. Passing 0 will always reset the whole chip. Do not use for new
 133         drivers without discussing this first on the linux-media mailinglist.
 134         There should be no reason normally to reset a device.
 135
 136    s_gpio: set GPIO pins. Very simple right now, might need to be extended with
 137         a direction argument if needed.
 138
 139    s_power: puts subdevice in power saving mode (on == 0) or normal operation
 140         mode (on == 1).
 141
 142    interrupt_service_routine: Called by the bridge chip's interrupt service
 143         handler, when an interrupt status has be raised due to this subdev,
 144         so that this subdev can handle the details.  It may schedule work to be
 145         performed later.  It must not sleep.  *Called from an IRQ context*.
 146  */
 147 struct v4l2_subdev_core_ops {
 148         int (*log_status)(struct v4l2_subdev *sd);
 149         int (*s_io_pin_config)(struct v4l2_subdev *sd, size_t n,
 150                                       struct v4l2_subdev_io_pin_config *pincfg);
 151         int (*init)(struct v4l2_subdev *sd, u32 val);
 152         int (*load_fw)(struct v4l2_subdev *sd);
 153         int (*reset)(struct v4l2_subdev *sd, u32 val);
 154         int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
 155         int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
 156         int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
 157         int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
 158         int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
 159         int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
 160         int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
 161         int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
 162         int (*g_std)(struct v4l2_subdev *sd, v4l2_std_id *norm);
 163         int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm);
 164         long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
 165 #ifdef CONFIG_VIDEO_ADV_DEBUG
 166         int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
 167         int (*s_register)(struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg);
 168 #endif
 169         int (*s_power)(struct v4l2_subdev *sd, int on);
 170         int (*interrupt_service_routine)(struct v4l2_subdev *sd,
 171                                                 u32 status, bool *handled);
 172         int (*subscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
 173                                struct v4l2_event_subscription *sub);
 174         int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
 175                                  struct v4l2_event_subscription *sub);
 176 };
 177
 178 /* s_radio: v4l device was opened in radio mode.
 179
 180    g_frequency: freq->type must be filled in. Normally done by video_ioctl2
 181         or the bridge driver.
 182
 183    g_tuner:
 184    s_tuner: vt->type must be filled in. Normally done by video_ioctl2 or the
 185         bridge driver.
 186
 187    s_type_addr: sets tuner type and its I2C addr.
 188
 189    s_config: sets tda9887 specific stuff, like port1, port2 and qss
 190  */
 191 struct v4l2_subdev_tuner_ops {
 192         int (*s_radio)(struct v4l2_subdev *sd);
 193         int (*s_frequency)(struct v4l2_subdev *sd, const struct v4l2_frequency *freq);
 194         int (*g_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq);
 195         int (*g_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt);
 196         int (*s_tuner)(struct v4l2_subdev *sd, const struct v4l2_tuner *vt);
 197         int (*g_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm);
 198         int (*s_modulator)(struct v4l2_subdev *sd, const struct v4l2_modulator *vm);
 199         int (*s_type_addr)(struct v4l2_subdev *sd, struct tuner_setup *type);
 200         int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
 201 };
 202
 203 /* s_clock_freq: set the frequency (in Hz) of the audio clock output.
 204         Used to slave an audio processor to the video decoder, ensuring that
 205         audio and video remain synchronized. Usual values for the frequency
 206         are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
 207         -EINVAL is returned.
 208
 209    s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
 210         way to select I2S clock used by driving digital audio streams at some
 211         board designs. Usual values for the frequency are 1024000 and 2048000.
 212         If the frequency is not supported, then -EINVAL is returned.
 213
 214    s_routing: used to define the input and/or output pins of an audio chip,
 215         and any additional configuration data.
 216         Never attempt to use user-level input IDs (e.g. Composite, S-Video,
 217         Tuner) at this level. An i2c device shouldn't know about whether an
 218         input pin is connected to a Composite connector, become on another
 219         board or platform it might be connected to something else entirely.
 220         The calling driver is responsible for mapping a user-level input to
 221         the right pins on the i2c device.
 222  */
 223 struct v4l2_subdev_audio_ops {
 224         int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
 225         int (*s_i2s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
 226         int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
 227         int (*s_stream)(struct v4l2_subdev *sd, int enable);
 228 };
 229
 230 /* Indicates the @length field specifies maximum data length. */
 231 #define V4L2_MBUS_FRAME_DESC_FL_LEN_MAX         (1U << 0)
 232 /* Indicates user defined data format, i.e. non standard frame format. */
 233 #define V4L2_MBUS_FRAME_DESC_FL_BLOB            (1U << 1)
 234
 235 /**
 236  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
 237  * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags
 238  * @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
 239  * @length: number of octets per frame, valid for compressed or unspecified
 240  *          formats
 241  */
 242 struct v4l2_mbus_frame_desc_entry {
 243         u16 flags;
 244         u32 pixelcode;
 245         u32 length;
 246 };
 247
 248 #define V4L2_FRAME_DESC_ENTRY_MAX       4
 249
 250 /**
 251  * struct v4l2_mbus_frame_desc - media bus data frame description
 252  * @entry: frame descriptors array
 253  * @num_entries: number of entries in @entry array
 254  */
 255 struct v4l2_mbus_frame_desc {
 256         struct v4l2_mbus_frame_desc_entry entry[V4L2_FRAME_DESC_ENTRY_MAX];
 257         unsigned short num_entries;
 258 };
 259
 260 /*
 261    s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
 262         video input devices.
 263
 264    g_std_output: get current standard for video OUTPUT devices. This is ignored
 265         by video input devices.
 266
 267    g_tvnorms_output: get v4l2_std_id with all standards supported by video
 268         OUTPUT device. This is ignored by video input devices.
 269
 270    s_crystal_freq: sets the frequency of the crystal used to generate the
 271         clocks in Hz. An extra flags field allows device specific configuration
 272         regarding clock frequency dividers, etc. If not used, then set flags
 273         to 0. If the frequency is not supported, then -EINVAL is returned.
 274
 275    g_input_status: get input status. Same as the status field in the v4l2_input
 276         struct.
 277
 278    s_routing: see s_routing in audio_ops, except this version is for video
 279         devices.
 280
 281    s_dv_timings(): Set custom dv timings in the sub device. This is used
 282         when sub device is capable of setting detailed timing information
 283         in the hardware to generate/detect the video signal.
 284
 285    g_dv_timings(): Get custom dv timings in the sub device.
 286
 287    enum_mbus_fmt: enumerate pixel formats, provided by a video data source
 288
 289    g_mbus_fmt: get the current pixel format, provided by a video data source
 290
 291    try_mbus_fmt: try to set a pixel format on a video data source
 292
 293    s_mbus_fmt: set a pixel format on a video data source
 294
 295    g_mbus_config: get supported mediabus configurations
 296
 297    s_mbus_config: set a certain mediabus configuration. This operation is added
 298         for compatibility with soc-camera drivers and should not be used by new
 299         software.
 300
 301    s_rx_buffer: set a host allocated memory buffer for the subdev. The subdev
 302         can adjust @size to a lower value and must not write more data to the
 303         buffer starting at @data than the original value of @size.
 304  */
 305 struct v4l2_subdev_video_ops {
 306         int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
 307         int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags);
 308         int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std);
 309         int (*g_std_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
 310         int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std);
 311         int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
 312         int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
 313         int (*s_stream)(struct v4l2_subdev *sd, int enable);
 314         int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc);
 315         int (*g_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop);
 316         int (*s_crop)(struct v4l2_subdev *sd, const struct v4l2_crop *crop);
 317         int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
 318         int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
 319         int (*g_frame_interval)(struct v4l2_subdev *sd,
 320                                 struct v4l2_subdev_frame_interval *interval);
 321         int (*s_frame_interval)(struct v4l2_subdev *sd,
 322                                 struct v4l2_subdev_frame_interval *interval);
 323         int (*enum_framesizes)(struct v4l2_subdev *sd, struct v4l2_frmsizeenum *fsize);
 324         int (*enum_frameintervals)(struct v4l2_subdev *sd, struct v4l2_frmivalenum *fival);
 325         int (*s_dv_timings)(struct v4l2_subdev *sd,
 326                         struct v4l2_dv_timings *timings);
 327         int (*g_dv_timings)(struct v4l2_subdev *sd,
 328                         struct v4l2_dv_timings *timings);
 329         int (*enum_dv_timings)(struct v4l2_subdev *sd,
 330                         struct v4l2_enum_dv_timings *timings);
 331         int (*query_dv_timings)(struct v4l2_subdev *sd,
 332                         struct v4l2_dv_timings *timings);
 333         int (*dv_timings_cap)(struct v4l2_subdev *sd,
 334                         struct v4l2_dv_timings_cap *cap);
 335         int (*enum_mbus_fmt)(struct v4l2_subdev *sd, unsigned int index,
 336                              enum v4l2_mbus_pixelcode *code);
 337         int (*enum_mbus_fsizes)(struct v4l2_subdev *sd,
 338                              struct v4l2_frmsizeenum *fsize);
 339         int (*g_mbus_fmt)(struct v4l2_subdev *sd,
 340                           struct v4l2_mbus_framefmt *fmt);
 341         int (*try_mbus_fmt)(struct v4l2_subdev *sd,
 342                             struct v4l2_mbus_framefmt *fmt);
 343         int (*s_mbus_fmt)(struct v4l2_subdev *sd,
 344                           struct v4l2_mbus_framefmt *fmt);
 345         int (*g_mbus_config)(struct v4l2_subdev *sd,
 346                              struct v4l2_mbus_config *cfg);
 347         int (*s_mbus_config)(struct v4l2_subdev *sd,
 348                              const struct v4l2_mbus_config *cfg);
 349         int (*s_rx_buffer)(struct v4l2_subdev *sd, void *buf,
 350                            unsigned int *size);
 351 };
 352
 353 /*
 354    decode_vbi_line: video decoders that support sliced VBI need to implement
 355         this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
 356         start of the VBI data that was generated by the decoder. The driver
 357         then parses the sliced VBI data and sets the other fields in the
 358         struct accordingly. The pointer p is updated to point to the start of
 359         the payload which can be copied verbatim into the data field of the
 360         v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
 361         type field is set to 0 on return.
 362
 363    s_vbi_data: used to generate VBI signals on a video signal.
 364         v4l2_sliced_vbi_data is filled with the data packets that should be
 365         output. Note that if you set the line field to 0, then that VBI signal
 366         is disabled. If no valid VBI data was found, then the type field is
 367         set to 0 on return.
 368
 369    g_vbi_data: used to obtain the sliced VBI packet from a readback register.
 370         Not all video decoders support this. If no data is available because
 371         the readback register contains invalid or erroneous data -EIO is
 372         returned. Note that you must fill in the 'id' member and the 'field'
 373         member (to determine whether CC data from the first or second field
 374         should be obtained).
 375
 376    s_raw_fmt: setup the video encoder/decoder for raw VBI.
 377
 378    g_sliced_fmt: retrieve the current sliced VBI settings.
 379
 380    s_sliced_fmt: setup the sliced VBI settings.
 381  */
 382 struct v4l2_subdev_vbi_ops {
 383         int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
 384         int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
 385         int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
 386         int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
 387         int (*s_raw_fmt)(struct v4l2_subdev *sd, struct v4l2_vbi_format *fmt);
 388         int (*g_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
 389         int (*s_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
 390 };
 391
 392 /**
 393  * struct v4l2_subdev_sensor_ops - v4l2-subdev sensor operations
 394  * @g_skip_top_lines: number of lines at the top of the image to be skipped.
 395  *                    This is needed for some sensors, which always corrupt
 396  *                    several top lines of the output image, or which send their
 397  *                    metadata in them.
 398  * @g_skip_frames: number of frames to skip at stream start. This is needed for
 399  *                 buggy sensors that generate faulty frames when they are
 400  *                 turned on.
 401  */
 402 struct v4l2_subdev_sensor_ops {
 403         int (*g_skip_top_lines)(struct v4l2_subdev *sd, u32 *lines);
 404         int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
 405 };
 406
 407 /*
 408    [rt]x_g_parameters: Get the current operating parameters and state of the
 409         the IR receiver or transmitter.
 410
 411    [rt]x_s_parameters: Set the current operating parameters and state of the
 412         the IR receiver or transmitter.  It is recommended to call
 413         [rt]x_g_parameters first to fill out the current state, and only change
 414         the fields that need to be changed.  Upon return, the actual device
 415         operating parameters and state will be returned.  Note that hardware
 416         limitations may prevent the actual settings from matching the requested
 417         settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
 418         was requested.  An exception is when the shutdown parameter is true.
 419         The last used operational parameters will be returned, but the actual
 420         state of the hardware be different to minimize power consumption and
 421         processing when shutdown is true.
 422
 423    rx_read: Reads received codes or pulse width data.
 424         The semantics are similar to a non-blocking read() call.
 425
 426    tx_write: Writes codes or pulse width data for transmission.
 427         The semantics are similar to a non-blocking write() call.
 428  */
 429
 430 enum v4l2_subdev_ir_mode {
 431         V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* uses struct ir_raw_event records */
 432 };
 433
 434 struct v4l2_subdev_ir_parameters {
 435         /* Either Rx or Tx */
 436         unsigned int bytes_per_data_element; /* of data in read or write call */
 437         enum v4l2_subdev_ir_mode mode;
 438
 439         bool enable;
 440         bool interrupt_enable;
 441         bool shutdown; /* true: set hardware to low/no power, false: normal */
 442
 443         bool modulation;           /* true: uses carrier, false: baseband */
 444         u32 max_pulse_width;       /* ns,      valid only for baseband signal */
 445         unsigned int carrier_freq; /* Hz,      valid only for modulated signal*/
 446         unsigned int duty_cycle;   /* percent, valid only for modulated signal*/
 447         bool invert_level;         /* invert signal level */
 448
 449         /* Tx only */
 450         bool invert_carrier_sense; /* Send 0/space as a carrier burst */
 451
 452         /* Rx only */
 453         u32 noise_filter_min_width;       /* ns, min time of a valid pulse */
 454         unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */
 455         unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */
 456         u32 resolution;                   /* ns */
 457 };
 458
 459 struct v4l2_subdev_ir_ops {
 460         /* Receiver */
 461         int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
 462                                 ssize_t *num);
 463
 464         int (*rx_g_parameters)(struct v4l2_subdev *sd,
 465                                 struct v4l2_subdev_ir_parameters *params);
 466         int (*rx_s_parameters)(struct v4l2_subdev *sd,
 467                                 struct v4l2_subdev_ir_parameters *params);
 468
 469         /* Transmitter */
 470         int (*tx_write)(struct v4l2_subdev *sd, u8 *buf, size_t count,
 471                                 ssize_t *num);
 472
 473         int (*tx_g_parameters)(struct v4l2_subdev *sd,
 474                                 struct v4l2_subdev_ir_parameters *params);
 475         int (*tx_s_parameters)(struct v4l2_subdev *sd,
 476                                 struct v4l2_subdev_ir_parameters *params);
 477 };
 478
 479 /**
 480  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
 481  * @get_frame_desc: get the current low level media bus frame parameters.
 482  * @get_frame_desc: set the low level media bus frame parameters, @fd array
 483  *                  may be adjusted by the subdev driver to device capabilities.
 484  */
 485 struct v4l2_subdev_pad_ops {
 486         int (*enum_mbus_code)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 487                               struct v4l2_subdev_mbus_code_enum *code);
 488         int (*enum_frame_size)(struct v4l2_subdev *sd,
 489                                struct v4l2_subdev_fh *fh,
 490                                struct v4l2_subdev_frame_size_enum *fse);
 491         int (*enum_frame_interval)(struct v4l2_subdev *sd,
 492                                    struct v4l2_subdev_fh *fh,
 493                                    struct v4l2_subdev_frame_interval_enum *fie);
 494         int (*get_fmt)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 495                        struct v4l2_subdev_format *format);
 496         int (*set_fmt)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 497                        struct v4l2_subdev_format *format);
 498         int (*set_crop)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 499                        struct v4l2_subdev_crop *crop);
 500         int (*get_crop)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 501                        struct v4l2_subdev_crop *crop);
 502         int (*get_selection)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 503                              struct v4l2_subdev_selection *sel);
 504         int (*set_selection)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh,
 505                              struct v4l2_subdev_selection *sel);
 506         int (*get_edid)(struct v4l2_subdev *sd, struct v4l2_subdev_edid *edid);
 507         int (*set_edid)(struct v4l2_subdev *sd, struct v4l2_subdev_edid *edid);
 508 #ifdef CONFIG_MEDIA_CONTROLLER
 509         int (*link_validate)(struct v4l2_subdev *sd, struct media_link *link,
 510                              struct v4l2_subdev_format *source_fmt,
 511                              struct v4l2_subdev_format *sink_fmt);
 512 #endif /* CONFIG_MEDIA_CONTROLLER */
 513         int (*get_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
 514                               struct v4l2_mbus_frame_desc *fd);
 515         int (*set_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
 516                               struct v4l2_mbus_frame_desc *fd);
 517 };
 518
 519 struct v4l2_subdev_ops {
 520         const struct v4l2_subdev_core_ops       *core;
 521         const struct v4l2_subdev_tuner_ops      *tuner;
 522         const struct v4l2_subdev_audio_ops      *audio;
 523         const struct v4l2_subdev_video_ops      *video;
 524         const struct v4l2_subdev_vbi_ops        *vbi;
 525         const struct v4l2_subdev_ir_ops         *ir;
 526         const struct v4l2_subdev_sensor_ops     *sensor;
 527         const struct v4l2_subdev_pad_ops        *pad;
 528 };
 529
 530 /*
 531  * Internal ops. Never call this from drivers, only the v4l2 framework can call
 532  * these ops.
 533  *
 534  * registered: called when this subdev is registered. When called the v4l2_dev
 535  *      field is set to the correct v4l2_device.
 536  *
 537  * unregistered: called when this subdev is unregistered. When called the
 538  *      v4l2_dev field is still set to the correct v4l2_device.
 539  *
 540  * open: called when the subdev device node is opened by an application.
 541  *
 542  * close: called when the subdev device node is closed.
 543  */
 544 struct v4l2_subdev_internal_ops {
 545         int (*registered)(struct v4l2_subdev *sd);
 546         void (*unregistered)(struct v4l2_subdev *sd);
 547         int (*open)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
 548         int (*close)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
 549 };
 550
 551 #define V4L2_SUBDEV_NAME_SIZE 32
 552
 553 /* Set this flag if this subdev is a i2c device. */
 554 #define V4L2_SUBDEV_FL_IS_I2C                   (1U << 0)
 555 /* Set this flag if this subdev is a spi device. */
 556 #define V4L2_SUBDEV_FL_IS_SPI                   (1U << 1)
 557 /* Set this flag if this subdev needs a device node. */
 558 #define V4L2_SUBDEV_FL_HAS_DEVNODE              (1U << 2)
 559 /* Set this flag if this subdev generates events. */
 560 #define V4L2_SUBDEV_FL_HAS_EVENTS               (1U << 3)
 561
 562 /* Each instance of a subdev driver should create this struct, either
 563    stand-alone or embedded in a larger struct.
 564  */
 565 struct v4l2_subdev {
 566 #if defined(CONFIG_MEDIA_CONTROLLER)
 567         struct media_entity entity;
 568 #endif
 569         struct list_head list;
 570         struct module *owner;
 571         u32 flags;
 572         struct v4l2_device *v4l2_dev;
 573         const struct v4l2_subdev_ops *ops;
 574         /* Never call these internal ops from within a driver! */
 575         const struct v4l2_subdev_internal_ops *internal_ops;
 576         /* The control handler of this subdev. May be NULL. */
 577         struct v4l2_ctrl_handler *ctrl_handler;
 578         /* name must be unique */
 579         char name[V4L2_SUBDEV_NAME_SIZE];
 580         /* can be used to group similar subdevs, value is driver-specific */
 581         u32 grp_id;
 582         /* pointer to private data */
 583         void *dev_priv;
 584         void *host_priv;
 585         /* subdev device node */
 586         struct video_device *devnode;
 587         /* pointer to the physical device, if any */
 588         struct device *dev;
 589         /* Links this subdev to a global subdev_list or @notifier->done list. */
 590         struct list_head async_list;
 591         /* Pointer to respective struct v4l2_async_subdev. */
 592         struct v4l2_async_subdev *asd;
 593         /* Pointer to the managing notifier. */
 594         struct v4l2_async_notifier *notifier;
 595 };
 596
 597 #define media_entity_to_v4l2_subdev(ent) \
 598         container_of(ent, struct v4l2_subdev, entity)
 599 #define vdev_to_v4l2_subdev(vdev) \
 600         ((struct v4l2_subdev *)video_get_drvdata(vdev))
 601
 602 /*
 603  * Used for storing subdev information per file handle
 604  */
 605 struct v4l2_subdev_fh {
 606         struct v4l2_fh vfh;
 607 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
 608         struct {
 609                 struct v4l2_mbus_framefmt try_fmt;
 610                 struct v4l2_rect try_crop;
 611                 struct v4l2_rect try_compose;
 612         } *pad;
 613 #endif
 614 };
 615
 616 #define to_v4l2_subdev_fh(fh)   \
 617         container_of(fh, struct v4l2_subdev_fh, vfh)
 618
 619 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
 620 #define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)           \
 621         static inline struct rtype *                                    \
 622         v4l2_subdev_get_try_##fun_name(struct v4l2_subdev_fh *fh,       \
 623                                        unsigned int pad)                \
 624         {                                                               \
 625                 BUG_ON(unlikely(pad >= vdev_to_v4l2_subdev(             \
 626                                         fh->vfh.vdev)->entity.num_pads)); \
 627                 return &fh->pad[pad].field_name;                        \
 628         }
 629
 630 __V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, format, try_fmt)
 631 __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, crop, try_compose)
 632 __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, compose, try_compose)
 633 #endif
 634
 635 extern const struct v4l2_file_operations v4l2_subdev_fops;
 636
 637 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
 638 {
 639         sd->dev_priv = p;
 640 }
 641
 642 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
 643 {
 644         return sd->dev_priv;
 645 }
 646
 647 static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
 648 {
 649         sd->host_priv = p;
 650 }
 651
 652 static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)
 653 {
 654         return sd->host_priv;
 655 }
 656
 657 #ifdef CONFIG_MEDIA_CONTROLLER
 658 int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
 659                                       struct media_link *link,
 660                                       struct v4l2_subdev_format *source_fmt,
 661                                       struct v4l2_subdev_format *sink_fmt);
 662 int v4l2_subdev_link_validate(struct media_link *link);
 663 #endif /* CONFIG_MEDIA_CONTROLLER */
 664 void v4l2_subdev_init(struct v4l2_subdev *sd,
 665                       const struct v4l2_subdev_ops *ops);
 666
 667 /* Call an ops of a v4l2_subdev, doing the right checks against
 668    NULL pointers.
 669
 670    Example: err = v4l2_subdev_call(sd, core, s_std, norm);
 671  */
 672 #define v4l2_subdev_call(sd, o, f, args...)                             \
 673         (!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ? \
 674                 (sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD))
 675
 676 /* Send a notification to v4l2_device. */
 677 #define v4l2_subdev_notify(sd, notification, arg)                          \
 678         ((!(sd) || !(sd)->v4l2_dev || !(sd)->v4l2_dev->notify) ? -ENODEV : \
 679          (sd)->v4l2_dev->notify((sd), (notification), (arg)))
 680
 681 #define v4l2_subdev_has_op(sd, o, f) \
 682         ((sd)->ops->o && (sd)->ops->o->f)
 683
 684 #endif