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
  12 .. cssclass:: longtable
  13
  14 .. flat-table:: Media entity functions
  15     :header-rows:  0
  16     :stub-columns: 0
  17
  18
  19     -  .. row 1
  20
  21        .. _MEDIA-ENT-F-UNKNOWN:
  22        .. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN:
  23
  24        -  ``MEDIA_ENT_F_UNKNOWN`` and
  25
  26           ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
  27
  28        -  Unknown entity. That generally indicates that a driver didn't
  29           initialize properly the entity, which is a Kernel bug
  30
  31     -  .. row 2
  32
  33        ..  _MEDIA-ENT-F-IO-V4L:
  34
  35        -  ``MEDIA_ENT_F_IO_V4L``
  36
  37        -  Data streaming input and/or output entity.
  38
  39     -  .. row 3
  40
  41        ..  _MEDIA-ENT-F-IO-VBI:
  42
  43        -  ``MEDIA_ENT_F_IO_VBI``
  44
  45        -  V4L VBI streaming input or output entity
  46
  47     -  .. row 4
  48
  49        ..  _MEDIA-ENT-F-IO-SWRADIO:
  50
  51        -  ``MEDIA_ENT_F_IO_SWRADIO``
  52
  53        -  V4L Software Digital Radio (SDR) streaming input or output entity
  54
  55     -  .. row 5
  56
  57        ..  _MEDIA-ENT-F-IO-DTV:
  58
  59        -  ``MEDIA_ENT_F_IO_DTV``
  60
  61        -  DVB Digital TV streaming input or output entity
  62
  63     -  .. row 6
  64
  65        ..  _MEDIA-ENT-F-DTV-DEMOD:
  66
  67        -  ``MEDIA_ENT_F_DTV_DEMOD``
  68
  69        -  Digital TV demodulator entity.
  70
  71     -  .. row 7
  72
  73        ..  _MEDIA-ENT-F-TS-DEMUX:
  74
  75        -  ``MEDIA_ENT_F_TS_DEMUX``
  76
  77        -  MPEG Transport stream demux entity. Could be implemented on
  78           hardware or in Kernelspace by the Linux DVB subsystem.
  79
  80     -  .. row 8
  81
  82        ..  _MEDIA-ENT-F-DTV-CA:
  83
  84        -  ``MEDIA_ENT_F_DTV_CA``
  85
  86        -  Digital TV Conditional Access module (CAM) entity
  87
  88     -  .. row 9
  89
  90        ..  _MEDIA-ENT-F-DTV-NET-DECAP:
  91
  92        -  ``MEDIA_ENT_F_DTV_NET_DECAP``
  93
  94        -  Digital TV network ULE/MLE desencapsulation entity. Could be
  95           implemented on hardware or in Kernelspace
  96
  97     -  .. row 10
  98
  99        ..  _MEDIA-ENT-F-CONN-RF:
 100
 101        -  ``MEDIA_ENT_F_CONN_RF``
 102
 103        -  Connector for a Radio Frequency (RF) signal.
 104
 105     -  .. row 11
 106
 107        ..  _MEDIA-ENT-F-CONN-SVIDEO:
 108
 109        -  ``MEDIA_ENT_F_CONN_SVIDEO``
 110
 111        -  Connector for a S-Video signal.
 112
 113     -  .. row 12
 114
 115        ..  _MEDIA-ENT-F-CONN-COMPOSITE:
 116
 117        -  ``MEDIA_ENT_F_CONN_COMPOSITE``
 118
 119        -  Connector for a RGB composite signal.
 120
 121     -  .. row 13
 122
 123        ..  _MEDIA-ENT-F-CAM-SENSOR:
 124
 125        -  ``MEDIA_ENT_F_CAM_SENSOR``
 126
 127        -  Camera video sensor entity.
 128
 129     -  .. row 14
 130
 131        ..  _MEDIA-ENT-F-FLASH:
 132
 133        -  ``MEDIA_ENT_F_FLASH``
 134
 135        -  Flash controller entity.
 136
 137     -  .. row 15
 138
 139        ..  _MEDIA-ENT-F-LENS:
 140
 141        -  ``MEDIA_ENT_F_LENS``
 142
 143        -  Lens controller entity.
 144
 145     -  .. row 16
 146
 147        ..  _MEDIA-ENT-F-ATV-DECODER:
 148
 149        -  ``MEDIA_ENT_F_ATV_DECODER``
 150
 151        -  Analog video decoder, the basic function of the video decoder is
 152           to accept analogue video from a wide variety of sources such as
 153           broadcast, DVD players, cameras and video cassette recorders, in
 154           either NTSC, PAL, SECAM or HD format, separating the stream into
 155           its component parts, luminance and chrominance, and output it in
 156           some digital video standard, with appropriate timing signals.
 157
 158     -  .. row 17
 159
 160        ..  _MEDIA-ENT-F-TUNER:
 161
 162        -  ``MEDIA_ENT_F_TUNER``
 163
 164        -  Digital TV, analog TV, radio and/or software radio tuner, with
 165           consists on a PLL tuning stage that converts radio frequency (RF)
 166           signal into an Intermediate Frequency (IF). Modern tuners have
 167           internally IF-PLL decoders for audio and video, but older models
 168           have those stages implemented on separate entities.
 169
 170     -  .. row 18
 171
 172        ..  _MEDIA-ENT-F-IF-VID-DECODER:
 173
 174        -  ``MEDIA_ENT_F_IF_VID_DECODER``
 175
 176        -  IF-PLL video decoder. It receives the IF from a PLL and decodes
 177           the analog TV video signal. This is commonly found on some very
 178           old analog tuners, like Philips MK3 designs. They all contain a
 179           tda9887 (or some software compatible similar chip, like tda9885).
 180           Those devices use a different I2C address than the tuner PLL.
 181
 182     -  .. row 19
 183
 184        ..  _MEDIA-ENT-F-IF-AUD-DECODER:
 185
 186        -  ``MEDIA_ENT_F_IF_AUD_DECODER``
 187
 188        -  IF-PLL sound decoder. It receives the IF from a PLL and decodes
 189           the analog TV audio signal. This is commonly found on some very
 190           old analog hardware, like Micronas msp3400, Philips tda9840,
 191           tda985x, etc. Those devices use a different I2C address than the
 192           tuner PLL and should be controlled together with the IF-PLL video
 193           decoder.
 194
 195     -  .. row 20
 196
 197        ..  _MEDIA-ENT-F-AUDIO-CAPTURE:
 198
 199        -  ``MEDIA_ENT_F_AUDIO_CAPTURE``
 200
 201        -  Audio Capture Function Entity.
 202
 203     -  .. row 21
 204
 205        ..  _MEDIA-ENT-F-AUDIO-PLAYBACK:
 206
 207        -  ``MEDIA_ENT_F_AUDIO_PLAYBACK``
 208
 209        -  Audio Playback Function Entity.
 210
 211     -  .. row 22
 212
 213        ..  _MEDIA-ENT-F-AUDIO-MIXER:
 214
 215        -  ``MEDIA_ENT_F_AUDIO_MIXER``
 216
 217        -  Audio Mixer Function Entity.
 218
 219     -  .. row 23
 220
 221        ..  _MEDIA-ENT-F-PROC-VIDEO-COMPOSER:
 222
 223        -  ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER``
 224
 225        -  Video composer (blender). An entity capable of video
 226           composing must have at least two sink pads and one source
 227           pad, and composes input video frames onto output video
 228           frames. Composition can be performed using alpha blending,
 229           color keying, raster operations (ROP), stitching or any other
 230           means.
 231
 232     -  ..  row 24
 233
 234        ..  _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER:
 235
 236        -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
 237
 238        -  Video pixel formatter. An entity capable of pixel formatting
 239           must have at least one sink pad and one source pad. Read
 240           pixel formatters read pixels from memory and perform a subset
 241           of unpacking, cropping, color keying, alpha multiplication
 242           and pixel encoding conversion. Write pixel formatters perform
 243           a subset of dithering, pixel encoding conversion and packing
 244           and write pixels to memory.
 245
 246     -  ..  row 25
 247
 248        ..  _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV:
 249
 250        -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV``
 251
 252        -  Video pixel encoding converter. An entity capable of pixel
 253           enconding conversion must have at least one sink pad and one
 254           source pad, and convert the encoding of pixels received on
 255           its sink pad(s) to a different encoding output on its source
 256           pad(s). Pixel encoding conversion includes but isn't limited
 257           to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB
 258           conversions.
 259
 260     -  ..  row 26
 261
 262        ..  _MEDIA-ENT-F-PROC-VIDEO-LUT:
 263
 264        -  ``MEDIA_ENT_F_PROC_VIDEO_LUT``
 265
 266        -  Video look-up table. An entity capable of video lookup table
 267           processing must have one sink pad and one source pad. It uses
 268           the values of the pixels received on its sink pad to look up
 269           entries in internal tables and output them on its source pad.
 270           The lookup processing can be performed on all components
 271           separately or combine them for multi-dimensional table
 272           lookups.
 273
 274     -  ..  row 27
 275
 276        ..  _MEDIA-ENT-F-PROC-VIDEO-SCALER:
 277
 278        -  ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
 279
 280        -  Video scaler. An entity capable of video scaling must have
 281           at least one sink pad and one source pad, and scale the
 282           video frame(s) received on its sink pad(s) to a different
 283           resolution output on its source pad(s). The range of
 284           supported scaling ratios is entity-specific and can differ
 285           between the horizontal and vertical directions (in particular
 286           scaling can be supported in one direction only). Binning and
 287           sub-sampling (occasionally also referred to as skipping) are
 288           considered as scaling.
 289
 290     -  ..  row 28
 291
 292        ..  _MEDIA-ENT-F-PROC-VIDEO-STATISTICS:
 293
 294        -  ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
 295
 296        -  Video statistics computation (histogram, 3A, etc.). An entity
 297           capable of statistics computation must have one sink pad and
 298           one source pad. It computes statistics over the frames
 299           received on its sink pad and outputs the statistics data on
 300           its source pad.
 301
 302     -  ..  row 29
 303
 304        ..  _MEDIA-ENT-F-VID-MUX:
 305
 306        -  ``MEDIA_ENT_F_VID_MUX``
 307
 308        - Video multiplexer. An entity capable of multiplexing must have at
 309          least two sink pads and one source pad, and must pass the video
 310          frame(s) received from the active sink pad to the source pad.
 311
 312     -  ..  row 30
 313
 314        ..  _MEDIA-ENT-F-VID-IF-BRIDGE:
 315
 316        -  ``MEDIA_ENT_F_VID_IF_BRIDGE``
 317
 318        - Video interface bridge. A video interface bridge entity must have at
 319          least one sink pad and at least one source pad. It receives video
 320          frames on its sink pad from an input video bus of one type (HDMI, eDP,
 321          MIPI CSI-2, etc.), and outputs them on its source pad to an output
 322          video bus of another type (eDP, MIPI CSI-2, parallel, etc.).
 323
 324     -  ..  row 31
 325
 326        ..  _MEDIA-ENT-F-DTV-DECODER:
 327
 328        -  ``MEDIA_ENT_F_DTV_DECODER``
 329
 330        -  Digital video decoder. The basic function of the video decoder is
 331           to accept digital video from a wide variety of sources
 332           and output it in some digital video standard, with appropriate
 333           timing signals.
 334
 335 ..  tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 336
 337 .. _media-entity-flag:
 338
 339 .. flat-table:: Media entity flags
 340     :header-rows:  0
 341     :stub-columns: 0
 342
 343
 344     -  .. row 1
 345
 346        ..  _MEDIA-ENT-FL-DEFAULT:
 347
 348        -  ``MEDIA_ENT_FL_DEFAULT``
 349
 350        -  Default entity for its type. Used to discover the default audio,
 351           VBI and video devices, the default camera sensor, etc.
 352
 353     -  .. row 2
 354
 355        ..  _MEDIA-ENT-FL-CONNECTOR:
 356
 357        -  ``MEDIA_ENT_FL_CONNECTOR``
 358
 359        -  The entity represents a connector.
 360
 361
 362 ..  tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}|
 363
 364 .. _media-intf-type:
 365
 366 .. flat-table:: Media interface types
 367     :header-rows:  0
 368     :stub-columns: 0
 369
 370
 371     -  .. row 1
 372
 373        ..  _MEDIA-INTF-T-DVB-FE:
 374
 375        -  ``MEDIA_INTF_T_DVB_FE``
 376
 377        -  Device node interface for the Digital TV frontend
 378
 379        -  typically, /dev/dvb/adapter?/frontend?
 380
 381     -  .. row 2
 382
 383        ..  _MEDIA-INTF-T-DVB-DEMUX:
 384
 385        -  ``MEDIA_INTF_T_DVB_DEMUX``
 386
 387        -  Device node interface for the Digital TV demux
 388
 389        -  typically, /dev/dvb/adapter?/demux?
 390
 391     -  .. row 3
 392
 393        ..  _MEDIA-INTF-T-DVB-DVR:
 394
 395        -  ``MEDIA_INTF_T_DVB_DVR``
 396
 397        -  Device node interface for the Digital TV DVR
 398
 399        -  typically, /dev/dvb/adapter?/dvr?
 400
 401     -  .. row 4
 402
 403        ..  _MEDIA-INTF-T-DVB-CA:
 404
 405        -  ``MEDIA_INTF_T_DVB_CA``
 406
 407        -  Device node interface for the Digital TV Conditional Access
 408
 409        -  typically, /dev/dvb/adapter?/ca?
 410
 411     -  .. row 5
 412
 413        ..  _MEDIA-INTF-T-DVB-NET:
 414
 415        -  ``MEDIA_INTF_T_DVB_NET``
 416
 417        -  Device node interface for the Digital TV network control
 418
 419        -  typically, /dev/dvb/adapter?/net?
 420
 421     -  .. row 6
 422
 423        ..  _MEDIA-INTF-T-V4L-VIDEO:
 424
 425        -  ``MEDIA_INTF_T_V4L_VIDEO``
 426
 427        -  Device node interface for video (V4L)
 428
 429        -  typically, /dev/video?
 430
 431     -  .. row 7
 432
 433        ..  _MEDIA-INTF-T-V4L-VBI:
 434
 435        -  ``MEDIA_INTF_T_V4L_VBI``
 436
 437        -  Device node interface for VBI (V4L)
 438
 439        -  typically, /dev/vbi?
 440
 441     -  .. row 8
 442
 443        ..  _MEDIA-INTF-T-V4L-RADIO:
 444
 445        -  ``MEDIA_INTF_T_V4L_RADIO``
 446
 447        -  Device node interface for radio (V4L)
 448
 449        -  typically, /dev/radio?
 450
 451     -  .. row 9
 452
 453        ..  _MEDIA-INTF-T-V4L-SUBDEV:
 454
 455        -  ``MEDIA_INTF_T_V4L_SUBDEV``
 456
 457        -  Device node interface for a V4L subdevice
 458
 459        -  typically, /dev/v4l-subdev?
 460
 461     -  .. row 10
 462
 463        ..  _MEDIA-INTF-T-V4L-SWRADIO:
 464
 465        -  ``MEDIA_INTF_T_V4L_SWRADIO``
 466
 467        -  Device node interface for Software Defined Radio (V4L)
 468
 469        -  typically, /dev/swradio?
 470
 471     -  .. row 11
 472
 473        ..  _MEDIA-INTF-T-V4L-TOUCH:
 474
 475        -  ``MEDIA_INTF_T_V4L_TOUCH``
 476
 477        -  Device node interface for Touch device (V4L)
 478
 479        -  typically, /dev/v4l-touch?
 480
 481     -  .. row 12
 482
 483        ..  _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
 484
 485        -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
 486
 487        -  Device node interface for ALSA PCM Capture
 488
 489        -  typically, /dev/snd/pcmC?D?c
 490
 491     -  .. row 13
 492
 493        ..  _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
 494
 495        -  ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
 496
 497        -  Device node interface for ALSA PCM Playback
 498
 499        -  typically, /dev/snd/pcmC?D?p
 500
 501     -  .. row 14
 502
 503        ..  _MEDIA-INTF-T-ALSA-CONTROL:
 504
 505        -  ``MEDIA_INTF_T_ALSA_CONTROL``
 506
 507        -  Device node interface for ALSA Control
 508
 509        -  typically, /dev/snd/controlC?
 510
 511     -  .. row 15
 512
 513        ..  _MEDIA-INTF-T-ALSA-COMPRESS:
 514
 515        -  ``MEDIA_INTF_T_ALSA_COMPRESS``
 516
 517        -  Device node interface for ALSA Compress
 518
 519        -  typically, /dev/snd/compr?
 520
 521     -  .. row 16
 522
 523        ..  _MEDIA-INTF-T-ALSA-RAWMIDI:
 524
 525        -  ``MEDIA_INTF_T_ALSA_RAWMIDI``
 526
 527        -  Device node interface for ALSA Raw MIDI
 528
 529        -  typically, /dev/snd/midi?
 530
 531     -  .. row 17
 532
 533        ..  _MEDIA-INTF-T-ALSA-HWDEP:
 534
 535        -  ``MEDIA_INTF_T_ALSA_HWDEP``
 536
 537        -  Device node interface for ALSA Hardware Dependent
 538
 539        -  typically, /dev/snd/hwC?D?
 540
 541     -  .. row 18
 542
 543        ..  _MEDIA-INTF-T-ALSA-SEQUENCER:
 544
 545        -  ``MEDIA_INTF_T_ALSA_SEQUENCER``
 546
 547        -  Device node interface for ALSA Sequencer
 548
 549        -  typically, /dev/snd/seq
 550
 551     -  .. row 19
 552
 553        ..  _MEDIA-INTF-T-ALSA-TIMER:
 554
 555        -  ``MEDIA_INTF_T_ALSA_TIMER``
 556
 557        -  Device node interface for ALSA Timer
 558
 559        -  typically, /dev/snd/timer
 560
 561
 562 .. tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 563
 564 .. _media-pad-flag:
 565
 566 .. flat-table:: Media pad flags
 567     :header-rows:  0
 568     :stub-columns: 0
 569
 570
 571     -  .. row 1
 572
 573        ..  _MEDIA-PAD-FL-SINK:
 574
 575        -  ``MEDIA_PAD_FL_SINK``
 576
 577        -  Input pad, relative to the entity. Input pads sink data and are
 578           targets of links.
 579
 580     -  .. row 2
 581
 582        ..  _MEDIA-PAD-FL-SOURCE:
 583
 584        -  ``MEDIA_PAD_FL_SOURCE``
 585
 586        -  Output pad, relative to the entity. Output pads source data and
 587           are origins of links.
 588
 589     -  .. row 3
 590
 591        ..  _MEDIA-PAD-FL-MUST-CONNECT:
 592
 593        -  ``MEDIA_PAD_FL_MUST_CONNECT``
 594
 595        -  If this flag is set and the pad is linked to any other pad, then
 596           at least one of those links must be enabled for the entity to be
 597           able to stream. There could be temporary reasons (e.g. device
 598           configuration dependent) for the pad to need enabled links even
 599           when this flag isn't set; the absence of the flag doesn't imply
 600           there is none.
 601
 602
 603 One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
 604 must be set for every pad.
 605
 606 .. tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 607
 608 .. _media-link-flag:
 609
 610 .. flat-table:: Media link flags
 611     :header-rows:  0
 612     :stub-columns: 0
 613
 614
 615     -  .. row 1
 616
 617        ..  _MEDIA-LNK-FL-ENABLED:
 618
 619        -  ``MEDIA_LNK_FL_ENABLED``
 620
 621        -  The link is enabled and can be used to transfer media data. When
 622           two or more links target a sink pad, only one of them can be
 623           enabled at a time.
 624
 625     -  .. row 2
 626
 627        ..  _MEDIA-LNK-FL-IMMUTABLE:
 628
 629        -  ``MEDIA_LNK_FL_IMMUTABLE``
 630
 631        -  The link enabled state can't be modified at runtime. An immutable
 632           link is always enabled.
 633
 634     -  .. row 3
 635
 636        ..  _MEDIA-LNK-FL-DYNAMIC:
 637
 638        -  ``MEDIA_LNK_FL_DYNAMIC``
 639
 640        -  The link enabled state can be modified during streaming. This flag
 641           is set by drivers and is read-only for applications.
 642
 643     -  .. row 4
 644
 645        ..  _MEDIA-LNK-FL-LINK-TYPE:
 646
 647        -  ``MEDIA_LNK_FL_LINK_TYPE``
 648
 649        -  This is a bitmask that defines the type of the link. Currently,
 650           two types of links are supported:
 651
 652           .. _MEDIA-LNK-FL-DATA-LINK:
 653
 654           ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
 655
 656           .. _MEDIA-LNK-FL-INTERFACE-LINK:
 657
 658           ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
 659           interface and an entity