LCOV - code coverage report
Current view: top level - include/media - v4l2-subdev.h (source / functions) Hit Total Coverage
Test: Real Lines: 0 2 0.0 %
Date: 2020-10-17 15:46:43 Functions: 0 0 -
Legend: Neither, QEMU, Real, Both Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /* SPDX-License-Identifier: GPL-2.0-or-later */
       2                 :            : /*
       3                 :            :  *  V4L2 sub-device support header.
       4                 :            :  *
       5                 :            :  *  Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
       6                 :            :  */
       7                 :            : 
       8                 :            : #ifndef _V4L2_SUBDEV_H
       9                 :            : #define _V4L2_SUBDEV_H
      10                 :            : 
      11                 :            : #include <linux/types.h>
      12                 :            : #include <linux/v4l2-subdev.h>
      13                 :            : #include <media/media-entity.h>
      14                 :            : #include <media/v4l2-async.h>
      15                 :            : #include <media/v4l2-common.h>
      16                 :            : #include <media/v4l2-dev.h>
      17                 :            : #include <media/v4l2-fh.h>
      18                 :            : #include <media/v4l2-mediabus.h>
      19                 :            : 
      20                 :            : /* generic v4l2_device notify callback notification values */
      21                 :            : #define V4L2_SUBDEV_IR_RX_NOTIFY                _IOW('v', 0, u32)
      22                 :            : #define V4L2_SUBDEV_IR_RX_FIFO_SERVICE_REQ      0x00000001
      23                 :            : #define V4L2_SUBDEV_IR_RX_END_OF_RX_DETECTED    0x00000002
      24                 :            : #define V4L2_SUBDEV_IR_RX_HW_FIFO_OVERRUN       0x00000004
      25                 :            : #define V4L2_SUBDEV_IR_RX_SW_FIFO_OVERRUN       0x00000008
      26                 :            : 
      27                 :            : #define V4L2_SUBDEV_IR_TX_NOTIFY                _IOW('v', 1, u32)
      28                 :            : #define V4L2_SUBDEV_IR_TX_FIFO_SERVICE_REQ      0x00000001
      29                 :            : 
      30                 :            : #define V4L2_DEVICE_NOTIFY_EVENT                _IOW('v', 2, struct v4l2_event)
      31                 :            : 
      32                 :            : struct v4l2_device;
      33                 :            : struct v4l2_ctrl_handler;
      34                 :            : struct v4l2_event;
      35                 :            : struct v4l2_event_subscription;
      36                 :            : struct v4l2_fh;
      37                 :            : struct v4l2_subdev;
      38                 :            : struct v4l2_subdev_fh;
      39                 :            : struct tuner_setup;
      40                 :            : struct v4l2_mbus_frame_desc;
      41                 :            : 
      42                 :            : /**
      43                 :            :  * struct v4l2_decode_vbi_line - used to decode_vbi_line
      44                 :            :  *
      45                 :            :  * @is_second_field: Set to 0 for the first (odd) field;
      46                 :            :  *      set to 1 for the second (even) field.
      47                 :            :  * @p: Pointer to the sliced VBI data from the decoder. On exit, points to
      48                 :            :  *      the start of the payload.
      49                 :            :  * @line: Line number of the sliced VBI data (1-23)
      50                 :            :  * @type: VBI service type (V4L2_SLICED_*). 0 if no service found
      51                 :            :  */
      52                 :            : struct v4l2_decode_vbi_line {
      53                 :            :         u32 is_second_field;
      54                 :            :         u8 *p;
      55                 :            :         u32 line;
      56                 :            :         u32 type;
      57                 :            : };
      58                 :            : 
      59                 :            : /*
      60                 :            :  * Sub-devices are devices that are connected somehow to the main bridge
      61                 :            :  * device. These devices are usually audio/video muxers/encoders/decoders or
      62                 :            :  * sensors and webcam controllers.
      63                 :            :  *
      64                 :            :  * Usually these devices are controlled through an i2c bus, but other buses
      65                 :            :  * may also be used.
      66                 :            :  *
      67                 :            :  * The v4l2_subdev struct provides a way of accessing these devices in a
      68                 :            :  * generic manner. Most operations that these sub-devices support fall in
      69                 :            :  * a few categories: core ops, audio ops, video ops and tuner ops.
      70                 :            :  *
      71                 :            :  * More categories can be added if needed, although this should remain a
      72                 :            :  * limited set (no more than approx. 8 categories).
      73                 :            :  *
      74                 :            :  * Each category has its own set of ops that subdev drivers can implement.
      75                 :            :  *
      76                 :            :  * A subdev driver can leave the pointer to the category ops NULL if
      77                 :            :  * it does not implement them (e.g. an audio subdev will generally not
      78                 :            :  * implement the video category ops). The exception is the core category:
      79                 :            :  * this must always be present.
      80                 :            :  *
      81                 :            :  * These ops are all used internally so it is no problem to change, remove
      82                 :            :  * or add ops or move ops from one to another category. Currently these
      83                 :            :  * ops are based on the original ioctls, but since ops are not limited to
      84                 :            :  * one argument there is room for improvement here once all i2c subdev
      85                 :            :  * drivers are converted to use these ops.
      86                 :            :  */
      87                 :            : 
      88                 :            : /*
      89                 :            :  * Core ops: it is highly recommended to implement at least these ops:
      90                 :            :  *
      91                 :            :  * log_status
      92                 :            :  * g_register
      93                 :            :  * s_register
      94                 :            :  *
      95                 :            :  * This provides basic debugging support.
      96                 :            :  *
      97                 :            :  * The ioctl ops is meant for generic ioctl-like commands. Depending on
      98                 :            :  * the use-case it might be better to use subdev-specific ops (currently
      99                 :            :  * not yet implemented) since ops provide proper type-checking.
     100                 :            :  */
     101                 :            : 
     102                 :            : /**
     103                 :            :  * enum v4l2_subdev_io_pin_bits - Subdevice external IO pin configuration
     104                 :            :  *      bits
     105                 :            :  *
     106                 :            :  * @V4L2_SUBDEV_IO_PIN_DISABLE: disables a pin config. ENABLE assumed.
     107                 :            :  * @V4L2_SUBDEV_IO_PIN_OUTPUT: set it if pin is an output.
     108                 :            :  * @V4L2_SUBDEV_IO_PIN_INPUT: set it if pin is an input.
     109                 :            :  * @V4L2_SUBDEV_IO_PIN_SET_VALUE: to set the output value via
     110                 :            :  *                                &struct v4l2_subdev_io_pin_config->value.
     111                 :            :  * @V4L2_SUBDEV_IO_PIN_ACTIVE_LOW: pin active is bit 0.
     112                 :            :  *                                 Otherwise, ACTIVE HIGH is assumed.
     113                 :            :  */
     114                 :            : enum v4l2_subdev_io_pin_bits {
     115                 :            :         V4L2_SUBDEV_IO_PIN_DISABLE      = 0,
     116                 :            :         V4L2_SUBDEV_IO_PIN_OUTPUT       = 1,
     117                 :            :         V4L2_SUBDEV_IO_PIN_INPUT        = 2,
     118                 :            :         V4L2_SUBDEV_IO_PIN_SET_VALUE    = 3,
     119                 :            :         V4L2_SUBDEV_IO_PIN_ACTIVE_LOW   = 4,
     120                 :            : };
     121                 :            : 
     122                 :            : /**
     123                 :            :  * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
     124                 :            :  *
     125                 :            :  * @flags: bitmask with flags for this pin's config, whose bits are defined by
     126                 :            :  *         &enum v4l2_subdev_io_pin_bits.
     127                 :            :  * @pin: Chip external IO pin to configure
     128                 :            :  * @function: Internal signal pad/function to route to IO pin
     129                 :            :  * @value: Initial value for pin - e.g. GPIO output value
     130                 :            :  * @strength: Pin drive strength
     131                 :            :  */
     132                 :            : struct v4l2_subdev_io_pin_config {
     133                 :            :         u32 flags;
     134                 :            :         u8 pin;
     135                 :            :         u8 function;
     136                 :            :         u8 value;
     137                 :            :         u8 strength;
     138                 :            : };
     139                 :            : 
     140                 :            : /**
     141                 :            :  * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
     142                 :            :  *
     143                 :            :  * @log_status: callback for VIDIOC_LOG_STATUS() ioctl handler code.
     144                 :            :  *
     145                 :            :  * @s_io_pin_config: configure one or more chip I/O pins for chips that
     146                 :            :  *      multiplex different internal signal pads out to IO pins.  This function
     147                 :            :  *      takes a pointer to an array of 'n' pin configuration entries, one for
     148                 :            :  *      each pin being configured.  This function could be called at times
     149                 :            :  *      other than just subdevice initialization.
     150                 :            :  *
     151                 :            :  * @init: initialize the sensor registers to some sort of reasonable default
     152                 :            :  *      values. Do not use for new drivers and should be removed in existing
     153                 :            :  *      drivers.
     154                 :            :  *
     155                 :            :  * @load_fw: load firmware.
     156                 :            :  *
     157                 :            :  * @reset: generic reset command. The argument selects which subsystems to
     158                 :            :  *      reset. Passing 0 will always reset the whole chip. Do not use for new
     159                 :            :  *      drivers without discussing this first on the linux-media mailinglist.
     160                 :            :  *      There should be no reason normally to reset a device.
     161                 :            :  *
     162                 :            :  * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with
     163                 :            :  *      a direction argument if needed.
     164                 :            :  *
     165                 :            :  * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core.
     166                 :            :  *         used to provide support for private ioctls used on the driver.
     167                 :            :  *
     168                 :            :  * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
     169                 :            :  *                  in order to fix data passed from/to userspace.
     170                 :            :  *
     171                 :            :  * @g_register: callback for VIDIOC_DBG_G_REGISTER() ioctl handler code.
     172                 :            :  *
     173                 :            :  * @s_register: callback for VIDIOC_DBG_S_REGISTER() ioctl handler code.
     174                 :            :  *
     175                 :            :  * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
     176                 :            :  *      mode (on == 1).
     177                 :            :  *
     178                 :            :  * @interrupt_service_routine: Called by the bridge chip's interrupt service
     179                 :            :  *      handler, when an interrupt status has be raised due to this subdev,
     180                 :            :  *      so that this subdev can handle the details.  It may schedule work to be
     181                 :            :  *      performed later.  It must not sleep. **Called from an IRQ context**.
     182                 :            :  *
     183                 :            :  * @subscribe_event: used by the drivers to request the control framework that
     184                 :            :  *                   for it to be warned when the value of a control changes.
     185                 :            :  *
     186                 :            :  * @unsubscribe_event: remove event subscription from the control framework.
     187                 :            :  */
     188                 :            : struct v4l2_subdev_core_ops {
     189                 :            :         int (*log_status)(struct v4l2_subdev *sd);
     190                 :            :         int (*s_io_pin_config)(struct v4l2_subdev *sd, size_t n,
     191                 :            :                                       struct v4l2_subdev_io_pin_config *pincfg);
     192                 :            :         int (*init)(struct v4l2_subdev *sd, u32 val);
     193                 :            :         int (*load_fw)(struct v4l2_subdev *sd);
     194                 :            :         int (*reset)(struct v4l2_subdev *sd, u32 val);
     195                 :            :         int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
     196                 :            :         long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
     197                 :            : #ifdef CONFIG_COMPAT
     198                 :            :         long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd,
     199                 :            :                                unsigned long arg);
     200                 :            : #endif
     201                 :            : #ifdef CONFIG_VIDEO_ADV_DEBUG
     202                 :            :         int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
     203                 :            :         int (*s_register)(struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg);
     204                 :            : #endif
     205                 :            :         int (*s_power)(struct v4l2_subdev *sd, int on);
     206                 :            :         int (*interrupt_service_routine)(struct v4l2_subdev *sd,
     207                 :            :                                                 u32 status, bool *handled);
     208                 :            :         int (*subscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
     209                 :            :                                struct v4l2_event_subscription *sub);
     210                 :            :         int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
     211                 :            :                                  struct v4l2_event_subscription *sub);
     212                 :            : };
     213                 :            : 
     214                 :            : /**
     215                 :            :  * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
     216                 :            :  *      in radio mode.
     217                 :            :  *
     218                 :            :  * @standby: puts the tuner in standby mode. It will be woken up
     219                 :            :  *           automatically the next time it is used.
     220                 :            :  *
     221                 :            :  * @s_radio: callback that switches the tuner to radio mode.
     222                 :            :  *           drivers should explicitly call it when a tuner ops should
     223                 :            :  *           operate on radio mode, before being able to handle it.
     224                 :            :  *           Used on devices that have both AM/FM radio receiver and TV.
     225                 :            :  *
     226                 :            :  * @s_frequency: callback for VIDIOC_S_FREQUENCY() ioctl handler code.
     227                 :            :  *
     228                 :            :  * @g_frequency: callback for VIDIOC_G_FREQUENCY() ioctl handler code.
     229                 :            :  *               freq->type must be filled in. Normally done by video_ioctl2()
     230                 :            :  *               or the bridge driver.
     231                 :            :  *
     232                 :            :  * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS() ioctl handler code.
     233                 :            :  *
     234                 :            :  * @g_tuner: callback for VIDIOC_G_TUNER() ioctl handler code.
     235                 :            :  *
     236                 :            :  * @s_tuner: callback for VIDIOC_S_TUNER() ioctl handler code. @vt->type must be
     237                 :            :  *           filled in. Normally done by video_ioctl2 or the
     238                 :            :  *           bridge driver.
     239                 :            :  *
     240                 :            :  * @g_modulator: callback for VIDIOC_G_MODULATOR() ioctl handler code.
     241                 :            :  *
     242                 :            :  * @s_modulator: callback for VIDIOC_S_MODULATOR() ioctl handler code.
     243                 :            :  *
     244                 :            :  * @s_type_addr: sets tuner type and its I2C addr.
     245                 :            :  *
     246                 :            :  * @s_config: sets tda9887 specific stuff, like port1, port2 and qss
     247                 :            :  *
     248                 :            :  * .. note::
     249                 :            :  *
     250                 :            :  *      On devices that have both AM/FM and TV, it is up to the driver
     251                 :            :  *      to explicitly call s_radio when the tuner should be switched to
     252                 :            :  *      radio mode, before handling other &struct v4l2_subdev_tuner_ops
     253                 :            :  *      that would require it. An example of such usage is::
     254                 :            :  *
     255                 :            :  *        static void s_frequency(void *priv, const struct v4l2_frequency *f)
     256                 :            :  *        {
     257                 :            :  *              ...
     258                 :            :  *              if (f.type == V4L2_TUNER_RADIO)
     259                 :            :  *                      v4l2_device_call_all(v4l2_dev, 0, tuner, s_radio);
     260                 :            :  *              ...
     261                 :            :  *              v4l2_device_call_all(v4l2_dev, 0, tuner, s_frequency);
     262                 :            :  *        }
     263                 :            :  */
     264                 :            : struct v4l2_subdev_tuner_ops {
     265                 :            :         int (*standby)(struct v4l2_subdev *sd);
     266                 :            :         int (*s_radio)(struct v4l2_subdev *sd);
     267                 :            :         int (*s_frequency)(struct v4l2_subdev *sd, const struct v4l2_frequency *freq);
     268                 :            :         int (*g_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq);
     269                 :            :         int (*enum_freq_bands)(struct v4l2_subdev *sd, struct v4l2_frequency_band *band);
     270                 :            :         int (*g_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt);
     271                 :            :         int (*s_tuner)(struct v4l2_subdev *sd, const struct v4l2_tuner *vt);
     272                 :            :         int (*g_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm);
     273                 :            :         int (*s_modulator)(struct v4l2_subdev *sd, const struct v4l2_modulator *vm);
     274                 :            :         int (*s_type_addr)(struct v4l2_subdev *sd, struct tuner_setup *type);
     275                 :            :         int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
     276                 :            : };
     277                 :            : 
     278                 :            : /**
     279                 :            :  * struct v4l2_subdev_audio_ops - Callbacks used for audio-related settings
     280                 :            :  *
     281                 :            :  * @s_clock_freq: set the frequency (in Hz) of the audio clock output.
     282                 :            :  *      Used to slave an audio processor to the video decoder, ensuring that
     283                 :            :  *      audio and video remain synchronized. Usual values for the frequency
     284                 :            :  *      are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
     285                 :            :  *      -EINVAL is returned.
     286                 :            :  *
     287                 :            :  * @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
     288                 :            :  *      way to select I2S clock used by driving digital audio streams at some
     289                 :            :  *      board designs. Usual values for the frequency are 1024000 and 2048000.
     290                 :            :  *      If the frequency is not supported, then %-EINVAL is returned.
     291                 :            :  *
     292                 :            :  * @s_routing: used to define the input and/or output pins of an audio chip,
     293                 :            :  *      and any additional configuration data.
     294                 :            :  *      Never attempt to use user-level input IDs (e.g. Composite, S-Video,
     295                 :            :  *      Tuner) at this level. An i2c device shouldn't know about whether an
     296                 :            :  *      input pin is connected to a Composite connector, become on another
     297                 :            :  *      board or platform it might be connected to something else entirely.
     298                 :            :  *      The calling driver is responsible for mapping a user-level input to
     299                 :            :  *      the right pins on the i2c device.
     300                 :            :  *
     301                 :            :  * @s_stream: used to notify the audio code that stream will start or has
     302                 :            :  *      stopped.
     303                 :            :  */
     304                 :            : struct v4l2_subdev_audio_ops {
     305                 :            :         int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
     306                 :            :         int (*s_i2s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
     307                 :            :         int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
     308                 :            :         int (*s_stream)(struct v4l2_subdev *sd, int enable);
     309                 :            : };
     310                 :            : 
     311                 :            : /**
     312                 :            :  * enum v4l2_mbus_frame_desc_entry - media bus frame description flags
     313                 :            :  *
     314                 :            :  * @V4L2_MBUS_FRAME_DESC_FL_LEN_MAX:
     315                 :            :  *      Indicates that &struct v4l2_mbus_frame_desc_entry->length field
     316                 :            :  *      specifies maximum data length.
     317                 :            :  * @V4L2_MBUS_FRAME_DESC_FL_BLOB:
     318                 :            :  *      Indicates that the format does not have line offsets, i.e.
     319                 :            :  *      the receiver should use 1D DMA.
     320                 :            :  */
     321                 :            : enum v4l2_mbus_frame_desc_flags {
     322                 :            :         V4L2_MBUS_FRAME_DESC_FL_LEN_MAX = BIT(0),
     323                 :            :         V4L2_MBUS_FRAME_DESC_FL_BLOB    = BIT(1),
     324                 :            : };
     325                 :            : 
     326                 :            : /**
     327                 :            :  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
     328                 :            :  *
     329                 :            :  * @flags:      bitmask flags, as defined by &enum v4l2_mbus_frame_desc_flags.
     330                 :            :  * @pixelcode:  media bus pixel code, valid if @flags
     331                 :            :  *              %FRAME_DESC_FL_BLOB is not set.
     332                 :            :  * @length:     number of octets per frame, valid if @flags
     333                 :            :  *              %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX is set.
     334                 :            :  */
     335                 :            : struct v4l2_mbus_frame_desc_entry {
     336                 :            :         enum v4l2_mbus_frame_desc_flags flags;
     337                 :            :         u32 pixelcode;
     338                 :            :         u32 length;
     339                 :            : };
     340                 :            : 
     341                 :            : #define V4L2_FRAME_DESC_ENTRY_MAX       4
     342                 :            : 
     343                 :            : /**
     344                 :            :  * struct v4l2_mbus_frame_desc - media bus data frame description
     345                 :            :  * @entry: frame descriptors array
     346                 :            :  * @num_entries: number of entries in @entry array
     347                 :            :  */
     348                 :            : struct v4l2_mbus_frame_desc {
     349                 :            :         struct v4l2_mbus_frame_desc_entry entry[V4L2_FRAME_DESC_ENTRY_MAX];
     350                 :            :         unsigned short num_entries;
     351                 :            : };
     352                 :            : 
     353                 :            : /**
     354                 :            :  * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
     355                 :            :  *                                in video mode.
     356                 :            :  *
     357                 :            :  * @s_routing: see s_routing in audio_ops, except this version is for video
     358                 :            :  *      devices.
     359                 :            :  *
     360                 :            :  * @s_crystal_freq: sets the frequency of the crystal used to generate the
     361                 :            :  *      clocks in Hz. An extra flags field allows device specific configuration
     362                 :            :  *      regarding clock frequency dividers, etc. If not used, then set flags
     363                 :            :  *      to 0. If the frequency is not supported, then -EINVAL is returned.
     364                 :            :  *
     365                 :            :  * @g_std: callback for VIDIOC_G_STD() ioctl handler code.
     366                 :            :  *
     367                 :            :  * @s_std: callback for VIDIOC_S_STD() ioctl handler code.
     368                 :            :  *
     369                 :            :  * @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
     370                 :            :  *      video input devices.
     371                 :            :  *
     372                 :            :  * @g_std_output: get current standard for video OUTPUT devices. This is ignored
     373                 :            :  *      by video input devices.
     374                 :            :  *
     375                 :            :  * @querystd: callback for VIDIOC_QUERYSTD() ioctl handler code.
     376                 :            :  *
     377                 :            :  * @g_tvnorms: get &v4l2_std_id with all standards supported by the video
     378                 :            :  *      CAPTURE device. This is ignored by video output devices.
     379                 :            :  *
     380                 :            :  * @g_tvnorms_output: get v4l2_std_id with all standards supported by the video
     381                 :            :  *      OUTPUT device. This is ignored by video capture devices.
     382                 :            :  *
     383                 :            :  * @g_input_status: get input status. Same as the status field in the
     384                 :            :  *      &struct &v4l2_input
     385                 :            :  *
     386                 :            :  * @s_stream: used to notify the driver that a video stream will start or has
     387                 :            :  *      stopped.
     388                 :            :  *
     389                 :            :  * @g_pixelaspect: callback to return the pixelaspect ratio.
     390                 :            :  *
     391                 :            :  * @g_frame_interval: callback for VIDIOC_SUBDEV_G_FRAME_INTERVAL()
     392                 :            :  *                    ioctl handler code.
     393                 :            :  *
     394                 :            :  * @s_frame_interval: callback for VIDIOC_SUBDEV_S_FRAME_INTERVAL()
     395                 :            :  *                    ioctl handler code.
     396                 :            :  *
     397                 :            :  * @s_dv_timings: Set custom dv timings in the sub device. This is used
     398                 :            :  *      when sub device is capable of setting detailed timing information
     399                 :            :  *      in the hardware to generate/detect the video signal.
     400                 :            :  *
     401                 :            :  * @g_dv_timings: Get custom dv timings in the sub device.
     402                 :            :  *
     403                 :            :  * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS() ioctl handler code.
     404                 :            :  *
     405                 :            :  * @s_rx_buffer: set a host allocated memory buffer for the subdev. The subdev
     406                 :            :  *      can adjust @size to a lower value and must not write more data to the
     407                 :            :  *      buffer starting at @data than the original value of @size.
     408                 :            :  */
     409                 :            : struct v4l2_subdev_video_ops {
     410                 :            :         int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
     411                 :            :         int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags);
     412                 :            :         int (*g_std)(struct v4l2_subdev *sd, v4l2_std_id *norm);
     413                 :            :         int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm);
     414                 :            :         int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std);
     415                 :            :         int (*g_std_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
     416                 :            :         int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std);
     417                 :            :         int (*g_tvnorms)(struct v4l2_subdev *sd, v4l2_std_id *std);
     418                 :            :         int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
     419                 :            :         int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
     420                 :            :         int (*s_stream)(struct v4l2_subdev *sd, int enable);
     421                 :            :         int (*g_pixelaspect)(struct v4l2_subdev *sd, struct v4l2_fract *aspect);
     422                 :            :         int (*g_frame_interval)(struct v4l2_subdev *sd,
     423                 :            :                                 struct v4l2_subdev_frame_interval *interval);
     424                 :            :         int (*s_frame_interval)(struct v4l2_subdev *sd,
     425                 :            :                                 struct v4l2_subdev_frame_interval *interval);
     426                 :            :         int (*s_dv_timings)(struct v4l2_subdev *sd,
     427                 :            :                         struct v4l2_dv_timings *timings);
     428                 :            :         int (*g_dv_timings)(struct v4l2_subdev *sd,
     429                 :            :                         struct v4l2_dv_timings *timings);
     430                 :            :         int (*query_dv_timings)(struct v4l2_subdev *sd,
     431                 :            :                         struct v4l2_dv_timings *timings);
     432                 :            :         int (*s_rx_buffer)(struct v4l2_subdev *sd, void *buf,
     433                 :            :                            unsigned int *size);
     434                 :            : };
     435                 :            : 
     436                 :            : /**
     437                 :            :  * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
     438                 :            :  *                                in video mode via the vbi device node.
     439                 :            :  *
     440                 :            :  *  @decode_vbi_line: video decoders that support sliced VBI need to implement
     441                 :            :  *      this ioctl. Field p of the &struct v4l2_decode_vbi_line is set to the
     442                 :            :  *      start of the VBI data that was generated by the decoder. The driver
     443                 :            :  *      then parses the sliced VBI data and sets the other fields in the
     444                 :            :  *      struct accordingly. The pointer p is updated to point to the start of
     445                 :            :  *      the payload which can be copied verbatim into the data field of the
     446                 :            :  *      &struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the
     447                 :            :  *      type field is set to 0 on return.
     448                 :            :  *
     449                 :            :  * @s_vbi_data: used to generate VBI signals on a video signal.
     450                 :            :  *      &struct v4l2_sliced_vbi_data is filled with the data packets that
     451                 :            :  *      should be output. Note that if you set the line field to 0, then that
     452                 :            :  *      VBI signal is disabled. If no valid VBI data was found, then the type
     453                 :            :  *      field is set to 0 on return.
     454                 :            :  *
     455                 :            :  * @g_vbi_data: used to obtain the sliced VBI packet from a readback register.
     456                 :            :  *      Not all video decoders support this. If no data is available because
     457                 :            :  *      the readback register contains invalid or erroneous data %-EIO is
     458                 :            :  *      returned. Note that you must fill in the 'id' member and the 'field'
     459                 :            :  *      member (to determine whether CC data from the first or second field
     460                 :            :  *      should be obtained).
     461                 :            :  *
     462                 :            :  * @g_sliced_vbi_cap: callback for VIDIOC_G_SLICED_VBI_CAP() ioctl handler
     463                 :            :  *                    code.
     464                 :            :  *
     465                 :            :  * @s_raw_fmt: setup the video encoder/decoder for raw VBI.
     466                 :            :  *
     467                 :            :  * @g_sliced_fmt: retrieve the current sliced VBI settings.
     468                 :            :  *
     469                 :            :  * @s_sliced_fmt: setup the sliced VBI settings.
     470                 :            :  */
     471                 :            : struct v4l2_subdev_vbi_ops {
     472                 :            :         int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
     473                 :            :         int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
     474                 :            :         int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
     475                 :            :         int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
     476                 :            :         int (*s_raw_fmt)(struct v4l2_subdev *sd, struct v4l2_vbi_format *fmt);
     477                 :            :         int (*g_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
     478                 :            :         int (*s_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
     479                 :            : };
     480                 :            : 
     481                 :            : /**
     482                 :            :  * struct v4l2_subdev_sensor_ops - v4l2-subdev sensor operations
     483                 :            :  * @g_skip_top_lines: number of lines at the top of the image to be skipped.
     484                 :            :  *                    This is needed for some sensors, which always corrupt
     485                 :            :  *                    several top lines of the output image, or which send their
     486                 :            :  *                    metadata in them.
     487                 :            :  * @g_skip_frames: number of frames to skip at stream start. This is needed for
     488                 :            :  *                 buggy sensors that generate faulty frames when they are
     489                 :            :  *                 turned on.
     490                 :            :  */
     491                 :            : struct v4l2_subdev_sensor_ops {
     492                 :            :         int (*g_skip_top_lines)(struct v4l2_subdev *sd, u32 *lines);
     493                 :            :         int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
     494                 :            : };
     495                 :            : 
     496                 :            : /**
     497                 :            :  * enum v4l2_subdev_ir_mode- describes the type of IR supported
     498                 :            :  *
     499                 :            :  * @V4L2_SUBDEV_IR_MODE_PULSE_WIDTH: IR uses struct ir_raw_event records
     500                 :            :  */
     501                 :            : enum v4l2_subdev_ir_mode {
     502                 :            :         V4L2_SUBDEV_IR_MODE_PULSE_WIDTH,
     503                 :            : };
     504                 :            : 
     505                 :            : /**
     506                 :            :  * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
     507                 :            :  *
     508                 :            :  * @bytes_per_data_element: bytes per data element of data in read or
     509                 :            :  *      write call.
     510                 :            :  * @mode: IR mode as defined by &enum v4l2_subdev_ir_mode.
     511                 :            :  * @enable: device is active if true
     512                 :            :  * @interrupt_enable: IR interrupts are enabled if true
     513                 :            :  * @shutdown: if true: set hardware to low/no power, false: normal mode
     514                 :            :  *
     515                 :            :  * @modulation: if true, it uses carrier, if false: baseband
     516                 :            :  * @max_pulse_width:  maximum pulse width in ns, valid only for baseband signal
     517                 :            :  * @carrier_freq: carrier frequency in Hz, valid only for modulated signal
     518                 :            :  * @duty_cycle: duty cycle percentage, valid only for modulated signal
     519                 :            :  * @invert_level: invert signal level
     520                 :            :  *
     521                 :            :  * @invert_carrier_sense: Send 0/space as a carrier burst. used only in TX.
     522                 :            :  *
     523                 :            :  * @noise_filter_min_width: min time of a valid pulse, in ns. Used only for RX.
     524                 :            :  * @carrier_range_lower: Lower carrier range, in Hz, valid only for modulated
     525                 :            :  *      signal. Used only for RX.
     526                 :            :  * @carrier_range_upper: Upper carrier range, in Hz, valid only for modulated
     527                 :            :  *      signal. Used only for RX.
     528                 :            :  * @resolution: The receive resolution, in ns . Used only for RX.
     529                 :            :  */
     530                 :            : struct v4l2_subdev_ir_parameters {
     531                 :            :         unsigned int bytes_per_data_element;
     532                 :            :         enum v4l2_subdev_ir_mode mode;
     533                 :            : 
     534                 :            :         bool enable;
     535                 :            :         bool interrupt_enable;
     536                 :            :         bool shutdown;
     537                 :            : 
     538                 :            :         bool modulation;
     539                 :            :         u32 max_pulse_width;
     540                 :            :         unsigned int carrier_freq;
     541                 :            :         unsigned int duty_cycle;
     542                 :            :         bool invert_level;
     543                 :            : 
     544                 :            :         /* Tx only */
     545                 :            :         bool invert_carrier_sense;
     546                 :            : 
     547                 :            :         /* Rx only */
     548                 :            :         u32 noise_filter_min_width;
     549                 :            :         unsigned int carrier_range_lower;
     550                 :            :         unsigned int carrier_range_upper;
     551                 :            :         u32 resolution;
     552                 :            : };
     553                 :            : 
     554                 :            : /**
     555                 :            :  * struct v4l2_subdev_ir_ops - operations for IR subdevices
     556                 :            :  *
     557                 :            :  * @rx_read: Reads received codes or pulse width data.
     558                 :            :  *      The semantics are similar to a non-blocking read() call.
     559                 :            :  * @rx_g_parameters: Get the current operating parameters and state of the
     560                 :            :  *      the IR receiver.
     561                 :            :  * @rx_s_parameters: Set the current operating parameters and state of the
     562                 :            :  *      the IR receiver.  It is recommended to call
     563                 :            :  *      [rt]x_g_parameters first to fill out the current state, and only change
     564                 :            :  *      the fields that need to be changed.  Upon return, the actual device
     565                 :            :  *      operating parameters and state will be returned.  Note that hardware
     566                 :            :  *      limitations may prevent the actual settings from matching the requested
     567                 :            :  *      settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
     568                 :            :  *      was requested.  An exception is when the shutdown parameter is true.
     569                 :            :  *      The last used operational parameters will be returned, but the actual
     570                 :            :  *      state of the hardware be different to minimize power consumption and
     571                 :            :  *      processing when shutdown is true.
     572                 :            :  *
     573                 :            :  * @tx_write: Writes codes or pulse width data for transmission.
     574                 :            :  *      The semantics are similar to a non-blocking write() call.
     575                 :            :  * @tx_g_parameters: Get the current operating parameters and state of the
     576                 :            :  *      the IR transmitter.
     577                 :            :  * @tx_s_parameters: Set the current operating parameters and state of the
     578                 :            :  *      the IR transmitter.  It is recommended to call
     579                 :            :  *      [rt]x_g_parameters first to fill out the current state, and only change
     580                 :            :  *      the fields that need to be changed.  Upon return, the actual device
     581                 :            :  *      operating parameters and state will be returned.  Note that hardware
     582                 :            :  *      limitations may prevent the actual settings from matching the requested
     583                 :            :  *      settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
     584                 :            :  *      was requested.  An exception is when the shutdown parameter is true.
     585                 :            :  *      The last used operational parameters will be returned, but the actual
     586                 :            :  *      state of the hardware be different to minimize power consumption and
     587                 :            :  *      processing when shutdown is true.
     588                 :            :  */
     589                 :            : struct v4l2_subdev_ir_ops {
     590                 :            :         /* Receiver */
     591                 :            :         int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
     592                 :            :                                 ssize_t *num);
     593                 :            : 
     594                 :            :         int (*rx_g_parameters)(struct v4l2_subdev *sd,
     595                 :            :                                 struct v4l2_subdev_ir_parameters *params);
     596                 :            :         int (*rx_s_parameters)(struct v4l2_subdev *sd,
     597                 :            :                                 struct v4l2_subdev_ir_parameters *params);
     598                 :            : 
     599                 :            :         /* Transmitter */
     600                 :            :         int (*tx_write)(struct v4l2_subdev *sd, u8 *buf, size_t count,
     601                 :            :                                 ssize_t *num);
     602                 :            : 
     603                 :            :         int (*tx_g_parameters)(struct v4l2_subdev *sd,
     604                 :            :                                 struct v4l2_subdev_ir_parameters *params);
     605                 :            :         int (*tx_s_parameters)(struct v4l2_subdev *sd,
     606                 :            :                                 struct v4l2_subdev_ir_parameters *params);
     607                 :            : };
     608                 :            : 
     609                 :            : /**
     610                 :            :  * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
     611                 :            :  *
     612                 :            :  * @try_fmt: &struct v4l2_mbus_framefmt
     613                 :            :  * @try_crop: &struct v4l2_rect to be used for crop
     614                 :            :  * @try_compose: &struct v4l2_rect to be used for compose
     615                 :            :  *
     616                 :            :  * This structure only needs to be passed to the pad op if the 'which' field
     617                 :            :  * of the main argument is set to %V4L2_SUBDEV_FORMAT_TRY. For
     618                 :            :  * %V4L2_SUBDEV_FORMAT_ACTIVE it is safe to pass %NULL.
     619                 :            :  */
     620                 :            : struct v4l2_subdev_pad_config {
     621                 :            :         struct v4l2_mbus_framefmt try_fmt;
     622                 :            :         struct v4l2_rect try_crop;
     623                 :            :         struct v4l2_rect try_compose;
     624                 :            : };
     625                 :            : 
     626                 :            : /**
     627                 :            :  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
     628                 :            :  *
     629                 :            :  * @init_cfg: initialize the pad config to default values
     630                 :            :  * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE() ioctl handler
     631                 :            :  *                  code.
     632                 :            :  * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE() ioctl handler
     633                 :            :  *                   code.
     634                 :            :  *
     635                 :            :  * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL() ioctl
     636                 :            :  *                       handler code.
     637                 :            :  *
     638                 :            :  * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT() ioctl handler code.
     639                 :            :  *
     640                 :            :  * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT() ioctl handler code.
     641                 :            :  *
     642                 :            :  * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION() ioctl handler code.
     643                 :            :  *
     644                 :            :  * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION() ioctl handler code.
     645                 :            :  *
     646                 :            :  * @get_edid: callback for VIDIOC_SUBDEV_G_EDID() ioctl handler code.
     647                 :            :  *
     648                 :            :  * @set_edid: callback for VIDIOC_SUBDEV_S_EDID() ioctl handler code.
     649                 :            :  *
     650                 :            :  * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP() ioctl handler
     651                 :            :  *                  code.
     652                 :            :  *
     653                 :            :  * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS() ioctl handler
     654                 :            :  *                   code.
     655                 :            :  *
     656                 :            :  * @link_validate: used by the media controller code to check if the links
     657                 :            :  *                 that belongs to a pipeline can be used for stream.
     658                 :            :  *
     659                 :            :  * @get_frame_desc: get the current low level media bus frame parameters.
     660                 :            :  *
     661                 :            :  * @set_frame_desc: set the low level media bus frame parameters, @fd array
     662                 :            :  *                  may be adjusted by the subdev driver to device capabilities.
     663                 :            :  *
     664                 :            :  * @get_mbus_config: get the media bus configuration of a remote sub-device.
     665                 :            :  *                   The media bus configuration is usually retrieved from the
     666                 :            :  *                   firmware interface at sub-device probe time, immediately
     667                 :            :  *                   applied to the hardware and eventually adjusted by the
     668                 :            :  *                   driver. Remote sub-devices (usually video receivers) shall
     669                 :            :  *                   use this operation to query the transmitting end bus
     670                 :            :  *                   configuration in order to adjust their own one accordingly.
     671                 :            :  *                   Callers should make sure they get the most up-to-date as
     672                 :            :  *                   possible configuration from the remote end, likely calling
     673                 :            :  *                   this operation as close as possible to stream on time. The
     674                 :            :  *                   operation shall fail if the pad index it has been called on
     675                 :            :  *                   is not valid.
     676                 :            :  *
     677                 :            :  * @set_mbus_config: set the media bus configuration of a remote sub-device.
     678                 :            :  *                   This operations is intended to allow, in combination with
     679                 :            :  *                   the get_mbus_config operation, the negotiation of media bus
     680                 :            :  *                   configuration parameters between media sub-devices. The
     681                 :            :  *                   operation shall not fail if the requested configuration is
     682                 :            :  *                   not supported, but the driver shall update the content of
     683                 :            :  *                   the %config argument to reflect what has been actually
     684                 :            :  *                   applied to the hardware. The operation shall fail if the
     685                 :            :  *                   pad index it has been called on is not valid.
     686                 :            :  */
     687                 :            : struct v4l2_subdev_pad_ops {
     688                 :            :         int (*init_cfg)(struct v4l2_subdev *sd,
     689                 :            :                         struct v4l2_subdev_pad_config *cfg);
     690                 :            :         int (*enum_mbus_code)(struct v4l2_subdev *sd,
     691                 :            :                               struct v4l2_subdev_pad_config *cfg,
     692                 :            :                               struct v4l2_subdev_mbus_code_enum *code);
     693                 :            :         int (*enum_frame_size)(struct v4l2_subdev *sd,
     694                 :            :                                struct v4l2_subdev_pad_config *cfg,
     695                 :            :                                struct v4l2_subdev_frame_size_enum *fse);
     696                 :            :         int (*enum_frame_interval)(struct v4l2_subdev *sd,
     697                 :            :                                    struct v4l2_subdev_pad_config *cfg,
     698                 :            :                                    struct v4l2_subdev_frame_interval_enum *fie);
     699                 :            :         int (*get_fmt)(struct v4l2_subdev *sd,
     700                 :            :                        struct v4l2_subdev_pad_config *cfg,
     701                 :            :                        struct v4l2_subdev_format *format);
     702                 :            :         int (*set_fmt)(struct v4l2_subdev *sd,
     703                 :            :                        struct v4l2_subdev_pad_config *cfg,
     704                 :            :                        struct v4l2_subdev_format *format);
     705                 :            :         int (*get_selection)(struct v4l2_subdev *sd,
     706                 :            :                              struct v4l2_subdev_pad_config *cfg,
     707                 :            :                              struct v4l2_subdev_selection *sel);
     708                 :            :         int (*set_selection)(struct v4l2_subdev *sd,
     709                 :            :                              struct v4l2_subdev_pad_config *cfg,
     710                 :            :                              struct v4l2_subdev_selection *sel);
     711                 :            :         int (*get_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
     712                 :            :         int (*set_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
     713                 :            :         int (*dv_timings_cap)(struct v4l2_subdev *sd,
     714                 :            :                               struct v4l2_dv_timings_cap *cap);
     715                 :            :         int (*enum_dv_timings)(struct v4l2_subdev *sd,
     716                 :            :                                struct v4l2_enum_dv_timings *timings);
     717                 :            : #ifdef CONFIG_MEDIA_CONTROLLER
     718                 :            :         int (*link_validate)(struct v4l2_subdev *sd, struct media_link *link,
     719                 :            :                              struct v4l2_subdev_format *source_fmt,
     720                 :            :                              struct v4l2_subdev_format *sink_fmt);
     721                 :            : #endif /* CONFIG_MEDIA_CONTROLLER */
     722                 :            :         int (*get_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
     723                 :            :                               struct v4l2_mbus_frame_desc *fd);
     724                 :            :         int (*set_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
     725                 :            :                               struct v4l2_mbus_frame_desc *fd);
     726                 :            :         int (*get_mbus_config)(struct v4l2_subdev *sd, unsigned int pad,
     727                 :            :                                struct v4l2_mbus_config *config);
     728                 :            :         int (*set_mbus_config)(struct v4l2_subdev *sd, unsigned int pad,
     729                 :            :                                struct v4l2_mbus_config *config);
     730                 :            : };
     731                 :            : 
     732                 :            : /**
     733                 :            :  * struct v4l2_subdev_ops - Subdev operations
     734                 :            :  *
     735                 :            :  * @core: pointer to &struct v4l2_subdev_core_ops. Can be %NULL
     736                 :            :  * @tuner: pointer to &struct v4l2_subdev_tuner_ops. Can be %NULL
     737                 :            :  * @audio: pointer to &struct v4l2_subdev_audio_ops. Can be %NULL
     738                 :            :  * @video: pointer to &struct v4l2_subdev_video_ops. Can be %NULL
     739                 :            :  * @vbi: pointer to &struct v4l2_subdev_vbi_ops. Can be %NULL
     740                 :            :  * @ir: pointer to &struct v4l2_subdev_ir_ops. Can be %NULL
     741                 :            :  * @sensor: pointer to &struct v4l2_subdev_sensor_ops. Can be %NULL
     742                 :            :  * @pad: pointer to &struct v4l2_subdev_pad_ops. Can be %NULL
     743                 :            :  */
     744                 :            : struct v4l2_subdev_ops {
     745                 :            :         const struct v4l2_subdev_core_ops       *core;
     746                 :            :         const struct v4l2_subdev_tuner_ops      *tuner;
     747                 :            :         const struct v4l2_subdev_audio_ops      *audio;
     748                 :            :         const struct v4l2_subdev_video_ops      *video;
     749                 :            :         const struct v4l2_subdev_vbi_ops        *vbi;
     750                 :            :         const struct v4l2_subdev_ir_ops         *ir;
     751                 :            :         const struct v4l2_subdev_sensor_ops     *sensor;
     752                 :            :         const struct v4l2_subdev_pad_ops        *pad;
     753                 :            : };
     754                 :            : 
     755                 :            : /**
     756                 :            :  * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
     757                 :            :  *
     758                 :            :  * @registered: called when this subdev is registered. When called the v4l2_dev
     759                 :            :  *      field is set to the correct v4l2_device.
     760                 :            :  *
     761                 :            :  * @unregistered: called when this subdev is unregistered. When called the
     762                 :            :  *      v4l2_dev field is still set to the correct v4l2_device.
     763                 :            :  *
     764                 :            :  * @open: called when the subdev device node is opened by an application.
     765                 :            :  *
     766                 :            :  * @close: called when the subdev device node is closed. Please note that
     767                 :            :  *      it is possible for @close to be called after @unregistered!
     768                 :            :  *
     769                 :            :  * @release: called when the last user of the subdev device is gone. This
     770                 :            :  *      happens after the @unregistered callback and when the last open
     771                 :            :  *      filehandle to the v4l-subdevX device node was closed. If no device
     772                 :            :  *      node was created for this sub-device, then the @release callback
     773                 :            :  *      is called right after the @unregistered callback.
     774                 :            :  *      The @release callback is typically used to free the memory containing
     775                 :            :  *      the v4l2_subdev structure. It is almost certainly required for any
     776                 :            :  *      sub-device that sets the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
     777                 :            :  *
     778                 :            :  * .. note::
     779                 :            :  *      Never call this from drivers, only the v4l2 framework can call
     780                 :            :  *      these ops.
     781                 :            :  */
     782                 :            : struct v4l2_subdev_internal_ops {
     783                 :            :         int (*registered)(struct v4l2_subdev *sd);
     784                 :            :         void (*unregistered)(struct v4l2_subdev *sd);
     785                 :            :         int (*open)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
     786                 :            :         int (*close)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
     787                 :            :         void (*release)(struct v4l2_subdev *sd);
     788                 :            : };
     789                 :            : 
     790                 :            : #define V4L2_SUBDEV_NAME_SIZE 32
     791                 :            : 
     792                 :            : /* Set this flag if this subdev is a i2c device. */
     793                 :            : #define V4L2_SUBDEV_FL_IS_I2C                   (1U << 0)
     794                 :            : /* Set this flag if this subdev is a spi device. */
     795                 :            : #define V4L2_SUBDEV_FL_IS_SPI                   (1U << 1)
     796                 :            : /* Set this flag if this subdev needs a device node. */
     797                 :            : #define V4L2_SUBDEV_FL_HAS_DEVNODE              (1U << 2)
     798                 :            : /*
     799                 :            :  * Set this flag if this subdev generates events.
     800                 :            :  * Note controls can send events, thus drivers exposing controls
     801                 :            :  * should set this flag.
     802                 :            :  */
     803                 :            : #define V4L2_SUBDEV_FL_HAS_EVENTS               (1U << 3)
     804                 :            : 
     805                 :            : struct regulator_bulk_data;
     806                 :            : 
     807                 :            : /**
     808                 :            :  * struct v4l2_subdev_platform_data - regulators config struct
     809                 :            :  *
     810                 :            :  * @regulators: Optional regulators used to power on/off the subdevice
     811                 :            :  * @num_regulators: Number of regululators
     812                 :            :  * @host_priv: Per-subdevice data, specific for a certain video host device
     813                 :            :  */
     814                 :            : struct v4l2_subdev_platform_data {
     815                 :            :         struct regulator_bulk_data *regulators;
     816                 :            :         int num_regulators;
     817                 :            : 
     818                 :            :         void *host_priv;
     819                 :            : };
     820                 :            : 
     821                 :            : /**
     822                 :            :  * struct v4l2_subdev - describes a V4L2 sub-device
     823                 :            :  *
     824                 :            :  * @entity: pointer to &struct media_entity
     825                 :            :  * @list: List of sub-devices
     826                 :            :  * @owner: The owner is the same as the driver's &struct device owner.
     827                 :            :  * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
     828                 :            :  *      owner. Initialized by v4l2_device_register_subdev().
     829                 :            :  * @flags: subdev flags. Can be:
     830                 :            :  *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
     831                 :            :  *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
     832                 :            :  *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
     833                 :            :  *   device node;
     834                 :            :  *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
     835                 :            :  *   events.
     836                 :            :  *
     837                 :            :  * @v4l2_dev: pointer to struct &v4l2_device
     838                 :            :  * @ops: pointer to struct &v4l2_subdev_ops
     839                 :            :  * @internal_ops: pointer to struct &v4l2_subdev_internal_ops.
     840                 :            :  *      Never call these internal ops from within a driver!
     841                 :            :  * @ctrl_handler: The control handler of this subdev. May be NULL.
     842                 :            :  * @name: Name of the sub-device. Please notice that the name must be unique.
     843                 :            :  * @grp_id: can be used to group similar subdevs. Value is driver-specific
     844                 :            :  * @dev_priv: pointer to private data
     845                 :            :  * @host_priv: pointer to private data used by the device where the subdev
     846                 :            :  *      is attached.
     847                 :            :  * @devnode: subdev device node
     848                 :            :  * @dev: pointer to the physical device, if any
     849                 :            :  * @fwnode: The fwnode_handle of the subdev, usually the same as
     850                 :            :  *          either dev->of_node->fwnode or dev->fwnode (whichever is non-NULL).
     851                 :            :  * @async_list: Links this subdev to a global subdev_list or @notifier->done
     852                 :            :  *      list.
     853                 :            :  * @asd: Pointer to respective &struct v4l2_async_subdev.
     854                 :            :  * @notifier: Pointer to the managing notifier.
     855                 :            :  * @subdev_notifier: A sub-device notifier implicitly registered for the sub-
     856                 :            :  *                   device using v4l2_device_register_sensor_subdev().
     857                 :            :  * @pdata: common part of subdevice platform data
     858                 :            :  *
     859                 :            :  * Each instance of a subdev driver should create this struct, either
     860                 :            :  * stand-alone or embedded in a larger struct.
     861                 :            :  *
     862                 :            :  * This structure should be initialized by v4l2_subdev_init() or one of
     863                 :            :  * its variants: v4l2_spi_subdev_init(), v4l2_i2c_subdev_init().
     864                 :            :  */
     865                 :            : struct v4l2_subdev {
     866                 :            : #if defined(CONFIG_MEDIA_CONTROLLER)
     867                 :            :         struct media_entity entity;
     868                 :            : #endif
     869                 :            :         struct list_head list;
     870                 :            :         struct module *owner;
     871                 :            :         bool owner_v4l2_dev;
     872                 :            :         u32 flags;
     873                 :            :         struct v4l2_device *v4l2_dev;
     874                 :            :         const struct v4l2_subdev_ops *ops;
     875                 :            :         const struct v4l2_subdev_internal_ops *internal_ops;
     876                 :            :         struct v4l2_ctrl_handler *ctrl_handler;
     877                 :            :         char name[V4L2_SUBDEV_NAME_SIZE];
     878                 :            :         u32 grp_id;
     879                 :            :         void *dev_priv;
     880                 :            :         void *host_priv;
     881                 :            :         struct video_device *devnode;
     882                 :            :         struct device *dev;
     883                 :            :         struct fwnode_handle *fwnode;
     884                 :            :         struct list_head async_list;
     885                 :            :         struct v4l2_async_subdev *asd;
     886                 :            :         struct v4l2_async_notifier *notifier;
     887                 :            :         struct v4l2_async_notifier *subdev_notifier;
     888                 :            :         struct v4l2_subdev_platform_data *pdata;
     889                 :            : };
     890                 :            : 
     891                 :            : 
     892                 :            : /**
     893                 :            :  * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from
     894                 :            :  *    the &struct media_entity embedded in it.
     895                 :            :  *
     896                 :            :  * @ent: pointer to &struct media_entity.
     897                 :            :  */
     898                 :            : #define media_entity_to_v4l2_subdev(ent)                                \
     899                 :            : ({                                                                      \
     900                 :            :         typeof(ent) __me_sd_ent = (ent);                                \
     901                 :            :                                                                         \
     902                 :            :         __me_sd_ent ?                                                   \
     903                 :            :                 container_of(__me_sd_ent, struct v4l2_subdev, entity) : \
     904                 :            :                 NULL;                                                   \
     905                 :            : })
     906                 :            : 
     907                 :            : /**
     908                 :            :  * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from
     909                 :            :  *      the &struct video_device embedded on it.
     910                 :            :  *
     911                 :            :  * @vdev: pointer to &struct video_device
     912                 :            :  */
     913                 :            : #define vdev_to_v4l2_subdev(vdev) \
     914                 :            :         ((struct v4l2_subdev *)video_get_drvdata(vdev))
     915                 :            : 
     916                 :            : /**
     917                 :            :  * struct v4l2_subdev_fh - Used for storing subdev information per file handle
     918                 :            :  *
     919                 :            :  * @vfh: pointer to &struct v4l2_fh
     920                 :            :  * @pad: pointer to &struct v4l2_subdev_pad_config
     921                 :            :  * @owner: module pointer to the owner of this file handle
     922                 :            :  */
     923                 :            : struct v4l2_subdev_fh {
     924                 :            :         struct v4l2_fh vfh;
     925                 :            :         struct module *owner;
     926                 :            : #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
     927                 :            :         struct v4l2_subdev_pad_config *pad;
     928                 :            : #endif
     929                 :            : };
     930                 :            : 
     931                 :            : /**
     932                 :            :  * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from
     933                 :            :  *      the &struct v4l2_fh embedded on it.
     934                 :            :  *
     935                 :            :  * @fh: pointer to &struct v4l2_fh
     936                 :            :  */
     937                 :            : #define to_v4l2_subdev_fh(fh)   \
     938                 :            :         container_of(fh, struct v4l2_subdev_fh, vfh)
     939                 :            : 
     940                 :            : #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
     941                 :            : 
     942                 :            : /**
     943                 :            :  * v4l2_subdev_get_try_format - ancillary routine to call
     944                 :            :  *      &struct v4l2_subdev_pad_config->try_fmt
     945                 :            :  *
     946                 :            :  * @sd: pointer to &struct v4l2_subdev
     947                 :            :  * @cfg: pointer to &struct v4l2_subdev_pad_config array.
     948                 :            :  * @pad: index of the pad in the @cfg array.
     949                 :            :  */
     950                 :            : static inline struct v4l2_mbus_framefmt
     951                 :            : *v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
     952                 :            :                             struct v4l2_subdev_pad_config *cfg,
     953                 :            :                             unsigned int pad)
     954                 :            : {
     955                 :            :         if (WARN_ON(pad >= sd->entity.num_pads))
     956                 :            :                 pad = 0;
     957                 :            :         return &cfg[pad].try_fmt;
     958                 :            : }
     959                 :            : 
     960                 :            : /**
     961                 :            :  * v4l2_subdev_get_try_crop - ancillary routine to call
     962                 :            :  *      &struct v4l2_subdev_pad_config->try_crop
     963                 :            :  *
     964                 :            :  * @sd: pointer to &struct v4l2_subdev
     965                 :            :  * @cfg: pointer to &struct v4l2_subdev_pad_config array.
     966                 :            :  * @pad: index of the pad in the @cfg array.
     967                 :            :  */
     968                 :            : static inline struct v4l2_rect
     969                 :            : *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
     970                 :            :                           struct v4l2_subdev_pad_config *cfg,
     971                 :            :                           unsigned int pad)
     972                 :            : {
     973                 :            :         if (WARN_ON(pad >= sd->entity.num_pads))
     974                 :            :                 pad = 0;
     975                 :            :         return &cfg[pad].try_crop;
     976                 :            : }
     977                 :            : 
     978                 :            : /**
     979                 :            :  * v4l2_subdev_get_try_crop - ancillary routine to call
     980                 :            :  *      &struct v4l2_subdev_pad_config->try_compose
     981                 :            :  *
     982                 :            :  * @sd: pointer to &struct v4l2_subdev
     983                 :            :  * @cfg: pointer to &struct v4l2_subdev_pad_config array.
     984                 :            :  * @pad: index of the pad in the @cfg array.
     985                 :            :  */
     986                 :            : static inline struct v4l2_rect
     987                 :            : *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
     988                 :            :                              struct v4l2_subdev_pad_config *cfg,
     989                 :            :                              unsigned int pad)
     990                 :            : {
     991                 :            :         if (WARN_ON(pad >= sd->entity.num_pads))
     992                 :            :                 pad = 0;
     993                 :            :         return &cfg[pad].try_compose;
     994                 :            : }
     995                 :            : #endif
     996                 :            : 
     997                 :            : extern const struct v4l2_file_operations v4l2_subdev_fops;
     998                 :            : 
     999                 :            : /**
    1000                 :            :  * v4l2_set_subdevdata - Sets V4L2 dev private device data
    1001                 :            :  *
    1002                 :            :  * @sd: pointer to &struct v4l2_subdev
    1003                 :            :  * @p: pointer to the private device data to be stored.
    1004                 :            :  */
    1005                 :            : static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
    1006                 :            : {
    1007                 :          0 :         sd->dev_priv = p;
    1008                 :            : }
    1009                 :            : 
    1010                 :            : /**
    1011                 :            :  * v4l2_get_subdevdata - Gets V4L2 dev private device data
    1012                 :            :  *
    1013                 :            :  * @sd: pointer to &struct v4l2_subdev
    1014                 :            :  *
    1015                 :            :  * Returns the pointer to the private device data to be stored.
    1016                 :            :  */
    1017                 :            : static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
    1018                 :            : {
    1019                 :          0 :         return sd->dev_priv;
    1020                 :            : }
    1021                 :            : 
    1022                 :            : /**
    1023                 :            :  * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data
    1024                 :            :  *
    1025                 :            :  * @sd: pointer to &struct v4l2_subdev
    1026                 :            :  * @p: pointer to the private data to be stored.
    1027                 :            :  */
    1028                 :            : static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
    1029                 :            : {
    1030                 :            :         sd->host_priv = p;
    1031                 :            : }
    1032                 :            : 
    1033                 :            : /**
    1034                 :            :  * v4l2_get_subdev_hostdata - Gets V4L2 dev private data
    1035                 :            :  *
    1036                 :            :  * @sd: pointer to &struct v4l2_subdev
    1037                 :            :  *
    1038                 :            :  * Returns the pointer to the private host data to be stored.
    1039                 :            :  */
    1040                 :            : static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)
    1041                 :            : {
    1042                 :            :         return sd->host_priv;
    1043                 :            : }
    1044                 :            : 
    1045                 :            : #ifdef CONFIG_MEDIA_CONTROLLER
    1046                 :            : 
    1047                 :            : /**
    1048                 :            :  * v4l2_subdev_link_validate_default - validates a media link
    1049                 :            :  *
    1050                 :            :  * @sd: pointer to &struct v4l2_subdev
    1051                 :            :  * @link: pointer to &struct media_link
    1052                 :            :  * @source_fmt: pointer to &struct v4l2_subdev_format
    1053                 :            :  * @sink_fmt: pointer to &struct v4l2_subdev_format
    1054                 :            :  *
    1055                 :            :  * This function ensures that width, height and the media bus pixel
    1056                 :            :  * code are equal on both source and sink of the link.
    1057                 :            :  */
    1058                 :            : int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
    1059                 :            :                                       struct media_link *link,
    1060                 :            :                                       struct v4l2_subdev_format *source_fmt,
    1061                 :            :                                       struct v4l2_subdev_format *sink_fmt);
    1062                 :            : 
    1063                 :            : /**
    1064                 :            :  * v4l2_subdev_link_validate - validates a media link
    1065                 :            :  *
    1066                 :            :  * @link: pointer to &struct media_link
    1067                 :            :  *
    1068                 :            :  * This function calls the subdev's link_validate ops to validate
    1069                 :            :  * if a media link is valid for streaming. It also internally
    1070                 :            :  * calls v4l2_subdev_link_validate_default() to ensure that
    1071                 :            :  * width, height and the media bus pixel code are equal on both
    1072                 :            :  * source and sink of the link.
    1073                 :            :  */
    1074                 :            : int v4l2_subdev_link_validate(struct media_link *link);
    1075                 :            : 
    1076                 :            : /**
    1077                 :            :  * v4l2_subdev_alloc_pad_config - Allocates memory for pad config
    1078                 :            :  *
    1079                 :            :  * @sd: pointer to struct v4l2_subdev
    1080                 :            :  */
    1081                 :            : struct
    1082                 :            : v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
    1083                 :            : 
    1084                 :            : /**
    1085                 :            :  * v4l2_subdev_free_pad_config - Frees memory allocated by
    1086                 :            :  *      v4l2_subdev_alloc_pad_config().
    1087                 :            :  *
    1088                 :            :  * @cfg: pointer to &struct v4l2_subdev_pad_config
    1089                 :            :  */
    1090                 :            : void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
    1091                 :            : #endif /* CONFIG_MEDIA_CONTROLLER */
    1092                 :            : 
    1093                 :            : /**
    1094                 :            :  * v4l2_subdev_init - initializes the sub-device struct
    1095                 :            :  *
    1096                 :            :  * @sd: pointer to the &struct v4l2_subdev to be initialized
    1097                 :            :  * @ops: pointer to &struct v4l2_subdev_ops.
    1098                 :            :  */
    1099                 :            : void v4l2_subdev_init(struct v4l2_subdev *sd,
    1100                 :            :                       const struct v4l2_subdev_ops *ops);
    1101                 :            : 
    1102                 :            : extern const struct v4l2_subdev_ops v4l2_subdev_call_wrappers;
    1103                 :            : 
    1104                 :            : /**
    1105                 :            :  * v4l2_subdev_call - call an operation of a v4l2_subdev.
    1106                 :            :  *
    1107                 :            :  * @sd: pointer to the &struct v4l2_subdev
    1108                 :            :  * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
    1109                 :            :  *     Each element there groups a set of callbacks functions.
    1110                 :            :  * @f: callback function that will be called if @cond matches.
    1111                 :            :  *     The callback functions are defined in groups, according to
    1112                 :            :  *     each element at &struct v4l2_subdev_ops.
    1113                 :            :  * @args...: arguments for @f.
    1114                 :            :  *
    1115                 :            :  * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
    1116                 :            :  */
    1117                 :            : #define v4l2_subdev_call(sd, o, f, args...)                             \
    1118                 :            :         ({                                                              \
    1119                 :            :                 struct v4l2_subdev *__sd = (sd);                        \
    1120                 :            :                 int __result;                                           \
    1121                 :            :                 if (!__sd)                                              \
    1122                 :            :                         __result = -ENODEV;                             \
    1123                 :            :                 else if (!(__sd->ops->o && __sd->ops->o->f))             \
    1124                 :            :                         __result = -ENOIOCTLCMD;                        \
    1125                 :            :                 else if (v4l2_subdev_call_wrappers.o &&                 \
    1126                 :            :                          v4l2_subdev_call_wrappers.o->f)             \
    1127                 :            :                         __result = v4l2_subdev_call_wrappers.o->f(   \
    1128                 :            :                                                         __sd, ##args);  \
    1129                 :            :                 else                                                    \
    1130                 :            :                         __result = __sd->ops->o->f(__sd, ##args);      \
    1131                 :            :                 __result;                                               \
    1132                 :            :         })
    1133                 :            : 
    1134                 :            : /**
    1135                 :            :  * v4l2_subdev_has_op - Checks if a subdev defines a certain operation.
    1136                 :            :  *
    1137                 :            :  * @sd: pointer to the &struct v4l2_subdev
    1138                 :            :  * @o: The group of callback functions in &struct v4l2_subdev_ops
    1139                 :            :  * which @f is a part of.
    1140                 :            :  * @f: callback function to be checked for its existence.
    1141                 :            :  */
    1142                 :            : #define v4l2_subdev_has_op(sd, o, f) \
    1143                 :            :         ((sd)->ops->o && (sd)->ops->o->f)
    1144                 :            : 
    1145                 :            : /**
    1146                 :            :  * v4l2_subdev_notify_event() - Delivers event notification for subdevice
    1147                 :            :  * @sd: The subdev for which to deliver the event
    1148                 :            :  * @ev: The event to deliver
    1149                 :            :  *
    1150                 :            :  * Will deliver the specified event to all userspace event listeners which are
    1151                 :            :  * subscribed to the v42l subdev event queue as well as to the bridge driver
    1152                 :            :  * using the notify callback. The notification type for the notify callback
    1153                 :            :  * will be %V4L2_DEVICE_NOTIFY_EVENT.
    1154                 :            :  */
    1155                 :            : void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
    1156                 :            :                               const struct v4l2_event *ev);
    1157                 :            : 
    1158                 :            : #endif
    

Generated by: LCOV version 1.14