Documentation/media/uapi/mediactl/media-types.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media-controller-types:
   4
   5 Types and flags used to represent the media graph elements
   6 ==========================================================
   7
   8 ..  tabularcolumns:: |p{8.2cm}|p{10.3cm}|
   9
  10 .. _media-entity-functions:
  11 .. _MEDIA-ENT-F-UNKNOWN:
  12 .. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN:
  13 .. _MEDIA-ENT-F-IO-V4L:
  14 .. _MEDIA-ENT-F-IO-VBI:
  15 .. _MEDIA-ENT-F-IO-SWRADIO:
  16 .. _MEDIA-ENT-F-IO-DTV:
  17 .. _MEDIA-ENT-F-DTV-DEMOD:
  18 .. _MEDIA-ENT-F-TS-DEMUX:
  19 .. _MEDIA-ENT-F-DTV-CA:
  20 .. _MEDIA-ENT-F-DTV-NET-DECAP:
  21 .. _MEDIA-ENT-F-CONN-RF:
  22 .. _MEDIA-ENT-F-CONN-SVIDEO:
  23 .. _MEDIA-ENT-F-CONN-COMPOSITE:
  24 .. _MEDIA-ENT-F-CAM-SENSOR:
  25 .. _MEDIA-ENT-F-FLASH:
  26 .. _MEDIA-ENT-F-LENS:
  27 .. _MEDIA-ENT-F-ATV-DECODER:
  28 .. _MEDIA-ENT-F-TUNER:
  29 .. _MEDIA-ENT-F-IF-VID-DECODER:
  30 .. _MEDIA-ENT-F-IF-AUD-DECODER:
  31 .. _MEDIA-ENT-F-AUDIO-CAPTURE:
  32 .. _MEDIA-ENT-F-AUDIO-PLAYBACK:
  33 .. _MEDIA-ENT-F-AUDIO-MIXER:
  34 .. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER:
  35 .. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER:
  36 .. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV:
  37 .. _MEDIA-ENT-F-PROC-VIDEO-LUT:
  38 .. _MEDIA-ENT-F-PROC-VIDEO-SCALER:
  39 .. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS:
  40 .. _MEDIA-ENT-F-PROC-VIDEO-ENCODER:
  41 .. _MEDIA-ENT-F-PROC-VIDEO-DECODER:
  42 .. _MEDIA-ENT-F-VID-MUX:
  43 .. _MEDIA-ENT-F-VID-IF-BRIDGE:
  44 .. _MEDIA-ENT-F-DV-DECODER:
  45 .. _MEDIA-ENT-F-DV-ENCODER:
  46
  47 .. cssclass:: longtable
  48
  49 .. flat-table:: Media entity functions
  50     :header-rows:  0
  51     :stub-columns: 0
  52
  53     *  -  ``MEDIA_ENT_F_UNKNOWN`` and
  54           ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
  55        -  Unknown entity. That generally indicates that a driver didn't
  56           initialize properly the entity, which is a Kernel bug
  57
  58     *  -  ``MEDIA_ENT_F_IO_V4L``
  59        -  Data streaming input and/or output entity.
  60
  61     *  -  ``MEDIA_ENT_F_IO_VBI``
  62        -  V4L VBI streaming input or output entity
  63
  64     *  -  ``MEDIA_ENT_F_IO_SWRADIO``
  65        -  V4L Software Digital Radio (SDR) streaming input or output entity
  66
  67     *  -  ``MEDIA_ENT_F_IO_DTV``
  68        -  DVB Digital TV streaming input or output entity
  69
  70     *  -  ``MEDIA_ENT_F_DTV_DEMOD``
  71        -  Digital TV demodulator entity.
  72
  73     *  -  ``MEDIA_ENT_F_TS_DEMUX``
  74        -  MPEG Transport stream demux entity. Could be implemented on
  75           hardware or in Kernelspace by the Linux DVB subsystem.
  76
  77     *  -  ``MEDIA_ENT_F_DTV_CA``
  78        -  Digital TV Conditional Access module (CAM) entity
  79
  80     *  -  ``MEDIA_ENT_F_DTV_NET_DECAP``
  81        -  Digital TV network ULE/MLE desencapsulation entity. Could be
  82           implemented on hardware or in Kernelspace
  83
  84     *  -  ``MEDIA_ENT_F_CONN_RF``
  85        -  Connector for a Radio Frequency (RF) signal.
  86
  87     *  -  ``MEDIA_ENT_F_CONN_SVIDEO``
  88        -  Connector for a S-Video signal.
  89
  90     *  -  ``MEDIA_ENT_F_CONN_COMPOSITE``
  91        -  Connector for a RGB composite signal.
  92
  93     *  -  ``MEDIA_ENT_F_CAM_SENSOR``
  94        -  Camera video sensor entity.
  95
  96     *  -  ``MEDIA_ENT_F_FLASH``
  97        -  Flash controller entity.
  98
  99     *  -  ``MEDIA_ENT_F_LENS``
 100        -  Lens controller entity.
 101
 102     *  -  ``MEDIA_ENT_F_ATV_DECODER``
 103        -  Analog video decoder, the basic function of the video decoder is
 104           to accept analogue video from a wide variety of sources such as
 105           broadcast, DVD players, cameras and video cassette recorders, in
 106           either NTSC, PAL, SECAM or HD format, separating the stream into
 107           its component parts, luminance and chrominance, and output it in
 108           some digital video standard, with appropriate timing signals.
 109
 110     *  -  ``MEDIA_ENT_F_TUNER``
 111        -  Digital TV, analog TV, radio and/or software radio tuner, with
 112           consists on a PLL tuning stage that converts radio frequency (RF)
 113           signal into an Intermediate Frequency (IF). Modern tuners have
 114           internally IF-PLL decoders for audio and video, but older models
 115           have those stages implemented on separate entities.
 116
 117     *  -  ``MEDIA_ENT_F_IF_VID_DECODER``
 118        -  IF-PLL video decoder. It receives the IF from a PLL and decodes
 119           the analog TV video signal. This is commonly found on some very
 120           old analog tuners, like Philips MK3 designs. They all contain a
 121           tda9887 (or some software compatible similar chip, like tda9885).
 122           Those devices use a different I2C address than the tuner PLL.
 123
 124     *  -  ``MEDIA_ENT_F_IF_AUD_DECODER``
 125        -  IF-PLL sound decoder. It receives the IF from a PLL and decodes
 126           the analog TV audio signal. This is commonly found on some very
 127           old analog hardware, like Micronas msp3400, Philips tda9840,
 128           tda985x, etc. Those devices use a different I2C address than the
 129           tuner PLL and should be controlled together with the IF-PLL video
 130           decoder.
 131
 132     *  -  ``MEDIA_ENT_F_AUDIO_CAPTURE``
 133        -  Audio Capture Function Entity.
 134
 135     *  -  ``MEDIA_ENT_F_AUDIO_PLAYBACK``
 136        -  Audio Playback Function Entity.
 137
 138     *  -  ``MEDIA_ENT_F_AUDIO_MIXER``
 139        -  Audio Mixer Function Entity.
 140
 141     *  -  ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER``
 142        -  Video composer (blender). An entity capable of video
 143           composing must have at least two sink pads and one source
 144           pad, and composes input video frames onto output video
 145           frames. Composition can be performed using alpha blending,
 146           color keying, raster operations (ROP), stitching or any other
 147           means.
 148
 149     *  -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
 150        -  Video pixel formatter. An entity capable of pixel formatting
 151           must have at least one sink pad and one source pad. Read
 152           pixel formatters read pixels from memory and perform a subset
 153           of unpacking, cropping, color keying, alpha multiplication
 154           and pixel encoding conversion. Write pixel formatters perform
 155           a subset of dithering, pixel encoding conversion and packing
 156           and write pixels to memory.
 157
 158     *  -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV``
 159        -  Video pixel encoding converter. An entity capable of pixel
 160           enconding conversion must have at least one sink pad and one
 161           source pad, and convert the encoding of pixels received on
 162           its sink pad(s) to a different encoding output on its source
 163           pad(s). Pixel encoding conversion includes but isn't limited
 164           to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB
 165           conversions.
 166
 167     *  -  ``MEDIA_ENT_F_PROC_VIDEO_LUT``
 168        -  Video look-up table. An entity capable of video lookup table
 169           processing must have one sink pad and one source pad. It uses
 170           the values of the pixels received on its sink pad to look up
 171           entries in internal tables and output them on its source pad.
 172           The lookup processing can be performed on all components
 173           separately or combine them for multi-dimensional table
 174           lookups.
 175
 176     *  -  ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
 177        -  Video scaler. An entity capable of video scaling must have
 178           at least one sink pad and one source pad, and scale the
 179           video frame(s) received on its sink pad(s) to a different
 180           resolution output on its source pad(s). The range of
 181           supported scaling ratios is entity-specific and can differ
 182           between the horizontal and vertical directions (in particular
 183           scaling can be supported in one direction only). Binning and
 184           sub-sampling (occasionally also referred to as skipping) are
 185           considered as scaling.
 186
 187     *  -  ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
 188        -  Video statistics computation (histogram, 3A, etc.). An entity
 189           capable of statistics computation must have one sink pad and
 190           one source pad. It computes statistics over the frames
 191           received on its sink pad and outputs the statistics data on
 192           its source pad.
 193
 194     *  -  ``MEDIA_ENT_F_PROC_VIDEO_ENCODER``
 195        -  Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of
 196           compressing video frames. Must have one sink pad and at least
 197           one source pad.
 198
 199     *  -  ``MEDIA_ENT_F_PROC_VIDEO_DECODER``
 200        -  Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of
 201           decompressing a compressed video stream into uncompressed video
 202           frames. Must have one sink pad and at least one source pad.
 203
 204     *  -  ``MEDIA_ENT_F_VID_MUX``
 205        - Video multiplexer. An entity capable of multiplexing must have at
 206          least two sink pads and one source pad, and must pass the video
 207          frame(s) received from the active sink pad to the source pad.
 208
 209     *  -  ``MEDIA_ENT_F_VID_IF_BRIDGE``
 210        - Video interface bridge. A video interface bridge entity must have at
 211          least one sink pad and at least one source pad. It receives video
 212          frames on its sink pad from an input video bus of one type (HDMI, eDP,
 213          MIPI CSI-2, etc.), and outputs them on its source pad to an output
 214          video bus of another type (eDP, MIPI CSI-2, parallel, etc.).
 215
 216     *  -  ``MEDIA_ENT_F_DV_DECODER``
 217        -  Digital video decoder. The basic function of the video decoder is
 218           to accept digital video from a wide variety of sources
 219           and output it in some digital video standard, with appropriate
 220           timing signals.
 221
 222     *  -  ``MEDIA_ENT_F_DV_ENCODER``
 223        -  Digital video encoder. The basic function of the video encoder is
 224           to accept digital video from some digital video standard with
 225           appropriate timing signals (usually a parallel video bus with sync
 226           signals) and output this to a digital video output connector such
 227           as HDMI or DisplayPort.
 228
 229 ..  tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 230
 231 .. _media-entity-flag:
 232 .. _MEDIA-ENT-FL-DEFAULT:
 233 .. _MEDIA-ENT-FL-CONNECTOR:
 234
 235 .. flat-table:: Media entity flags
 236     :header-rows:  0
 237     :stub-columns: 0
 238
 239     *  -  ``MEDIA_ENT_FL_DEFAULT``
 240        -  Default entity for its type. Used to discover the default audio,
 241           VBI and video devices, the default camera sensor, etc.
 242
 243     *  -  ``MEDIA_ENT_FL_CONNECTOR``
 244        -  The entity represents a connector.
 245
 246
 247 ..  tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}|
 248
 249 .. _media-intf-type:
 250 .. _MEDIA-INTF-T-DVB-FE:
 251 .. _MEDIA-INTF-T-DVB-DEMUX:
 252 .. _MEDIA-INTF-T-DVB-DVR:
 253 .. _MEDIA-INTF-T-DVB-CA:
 254 .. _MEDIA-INTF-T-DVB-NET:
 255 .. _MEDIA-INTF-T-V4L-VIDEO:
 256 .. _MEDIA-INTF-T-V4L-VBI:
 257 .. _MEDIA-INTF-T-V4L-RADIO:
 258 .. _MEDIA-INTF-T-V4L-SUBDEV:
 259 .. _MEDIA-INTF-T-V4L-SWRADIO:
 260 .. _MEDIA-INTF-T-V4L-TOUCH:
 261 .. _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
 262 .. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
 263 .. _MEDIA-INTF-T-ALSA-CONTROL:
 264 .. _MEDIA-INTF-T-ALSA-COMPRESS:
 265 .. _MEDIA-INTF-T-ALSA-RAWMIDI:
 266 .. _MEDIA-INTF-T-ALSA-HWDEP:
 267 .. _MEDIA-INTF-T-ALSA-SEQUENCER:
 268 .. _MEDIA-INTF-T-ALSA-TIMER:
 269
 270 .. flat-table:: Media interface types
 271     :header-rows:  0
 272     :stub-columns: 0
 273
 274     *  -  ``MEDIA_INTF_T_DVB_FE``
 275        -  Device node interface for the Digital TV frontend
 276        -  typically, /dev/dvb/adapter?/frontend?
 277
 278     *  -  ``MEDIA_INTF_T_DVB_DEMUX``
 279        -  Device node interface for the Digital TV demux
 280        -  typically, /dev/dvb/adapter?/demux?
 281
 282     *  -  ``MEDIA_INTF_T_DVB_DVR``
 283        -  Device node interface for the Digital TV DVR
 284        -  typically, /dev/dvb/adapter?/dvr?
 285
 286     *  -  ``MEDIA_INTF_T_DVB_CA``
 287        -  Device node interface for the Digital TV Conditional Access
 288        -  typically, /dev/dvb/adapter?/ca?
 289
 290     *  -  ``MEDIA_INTF_T_DVB_NET``
 291        -  Device node interface for the Digital TV network control
 292        -  typically, /dev/dvb/adapter?/net?
 293
 294     *  -  ``MEDIA_INTF_T_V4L_VIDEO``
 295        -  Device node interface for video (V4L)
 296        -  typically, /dev/video?
 297
 298     *  -  ``MEDIA_INTF_T_V4L_VBI``
 299        -  Device node interface for VBI (V4L)
 300        -  typically, /dev/vbi?
 301
 302     *  -  ``MEDIA_INTF_T_V4L_RADIO``
 303        -  Device node interface for radio (V4L)
 304        -  typically, /dev/radio?
 305
 306     *  -  ``MEDIA_INTF_T_V4L_SUBDEV``
 307        -  Device node interface for a V4L subdevice
 308        -  typically, /dev/v4l-subdev?
 309
 310     *  -  ``MEDIA_INTF_T_V4L_SWRADIO``
 311        -  Device node interface for Software Defined Radio (V4L)
 312        -  typically, /dev/swradio?
 313
 314     *  -  ``MEDIA_INTF_T_V4L_TOUCH``
 315        -  Device node interface for Touch device (V4L)
 316        -  typically, /dev/v4l-touch?
 317
 318     *  -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
 319        -  Device node interface for ALSA PCM Capture
 320        -  typically, /dev/snd/pcmC?D?c
 321
 322     *  -  ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
 323        -  Device node interface for ALSA PCM Playback
 324        -  typically, /dev/snd/pcmC?D?p
 325
 326     *  -  ``MEDIA_INTF_T_ALSA_CONTROL``
 327        -  Device node interface for ALSA Control
 328        -  typically, /dev/snd/controlC?
 329
 330     *  -  ``MEDIA_INTF_T_ALSA_COMPRESS``
 331        -  Device node interface for ALSA Compress
 332        -  typically, /dev/snd/compr?
 333
 334     *  -  ``MEDIA_INTF_T_ALSA_RAWMIDI``
 335        -  Device node interface for ALSA Raw MIDI
 336        -  typically, /dev/snd/midi?
 337
 338     *  -  ``MEDIA_INTF_T_ALSA_HWDEP``
 339        -  Device node interface for ALSA Hardware Dependent
 340        -  typically, /dev/snd/hwC?D?
 341
 342     *  -  ``MEDIA_INTF_T_ALSA_SEQUENCER``
 343        -  Device node interface for ALSA Sequencer
 344        -  typically, /dev/snd/seq
 345
 346     *  -  ``MEDIA_INTF_T_ALSA_TIMER``
 347        -  Device node interface for ALSA Timer
 348        -  typically, /dev/snd/timer
 349
 350
 351 .. tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 352
 353 .. _media-pad-flag:
 354 .. _MEDIA-PAD-FL-SINK:
 355 .. _MEDIA-PAD-FL-SOURCE:
 356 .. _MEDIA-PAD-FL-MUST-CONNECT:
 357
 358 .. flat-table:: Media pad flags
 359     :header-rows:  0
 360     :stub-columns: 0
 361
 362     *  -  ``MEDIA_PAD_FL_SINK``
 363        -  Input pad, relative to the entity. Input pads sink data and are
 364           targets of links.
 365
 366     *  -  ``MEDIA_PAD_FL_SOURCE``
 367        -  Output pad, relative to the entity. Output pads source data and
 368           are origins of links.
 369
 370     *  -  ``MEDIA_PAD_FL_MUST_CONNECT``
 371        -  If this flag is set and the pad is linked to any other pad, then
 372           at least one of those links must be enabled for the entity to be
 373           able to stream. There could be temporary reasons (e.g. device
 374           configuration dependent) for the pad to need enabled links even
 375           when this flag isn't set; the absence of the flag doesn't imply
 376           there is none.
 377
 378
 379 One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
 380 must be set for every pad.
 381
 382 .. tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 383
 384 .. _media-link-flag:
 385 .. _MEDIA-LNK-FL-ENABLED:
 386 .. _MEDIA-LNK-FL-IMMUTABLE:
 387 .. _MEDIA-LNK-FL-DYNAMIC:
 388 .. _MEDIA-LNK-FL-LINK-TYPE:
 389
 390 .. flat-table:: Media link flags
 391     :header-rows:  0
 392     :stub-columns: 0
 393
 394     *  -  ``MEDIA_LNK_FL_ENABLED``
 395        -  The link is enabled and can be used to transfer media data. When
 396           two or more links target a sink pad, only one of them can be
 397           enabled at a time.
 398
 399     *  -  ``MEDIA_LNK_FL_IMMUTABLE``
 400        -  The link enabled state can't be modified at runtime. An immutable
 401           link is always enabled.
 402
 403     *  -  ``MEDIA_LNK_FL_DYNAMIC``
 404        -  The link enabled state can be modified during streaming. This flag
 405           is set by drivers and is read-only for applications.
 406
 407     *  -  ``MEDIA_LNK_FL_LINK_TYPE``
 408        -  This is a bitmask that defines the type of the link. Currently,
 409           two types of links are supported:
 410
 411           .. _MEDIA-LNK-FL-DATA-LINK:
 412
 413           ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
 414
 415           .. _MEDIA-LNK-FL-INTERFACE-LINK:
 416
 417           ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
 418           interface and an entity