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

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