Documentation/userspace-api/media/mediactl/media-types.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   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{9.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-PROC-VIDEO-ISP:
  43 .. _MEDIA-ENT-F-VID-MUX:
  44 .. _MEDIA-ENT-F-VID-IF-BRIDGE:
  45 .. _MEDIA-ENT-F-DV-DECODER:
  46 .. _MEDIA-ENT-F-DV-ENCODER:
  47
  48 .. cssclass:: longtable
  49
  50 .. flat-table:: Media entity functions
  51     :header-rows:  0
  52     :stub-columns: 0
  53
  54     *  -  ``MEDIA_ENT_F_UNKNOWN`` and
  55           ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
  56        -  Unknown entity. That generally indicates that a driver didn't
  57           initialize properly the entity, which is a Kernel bug
  58
  59     *  -  ``MEDIA_ENT_F_IO_V4L``
  60        -  Data streaming input and/or output entity.
  61
  62     *  -  ``MEDIA_ENT_F_IO_VBI``
  63        -  V4L VBI streaming input or output entity
  64
  65     *  -  ``MEDIA_ENT_F_IO_SWRADIO``
  66        -  V4L Software Digital Radio (SDR) streaming input or output entity
  67
  68     *  -  ``MEDIA_ENT_F_IO_DTV``
  69        -  DVB Digital TV streaming input or output entity
  70
  71     *  -  ``MEDIA_ENT_F_DTV_DEMOD``
  72        -  Digital TV demodulator entity.
  73
  74     *  -  ``MEDIA_ENT_F_TS_DEMUX``
  75        -  MPEG Transport stream demux entity. Could be implemented on
  76           hardware or in Kernelspace by the Linux DVB subsystem.
  77
  78     *  -  ``MEDIA_ENT_F_DTV_CA``
  79        -  Digital TV Conditional Access module (CAM) entity
  80
  81     *  -  ``MEDIA_ENT_F_DTV_NET_DECAP``
  82        -  Digital TV network ULE/MLE desencapsulation entity. Could be
  83           implemented on hardware or in Kernelspace
  84
  85     *  -  ``MEDIA_ENT_F_CONN_RF``
  86        -  Connector for a Radio Frequency (RF) signal.
  87
  88     *  -  ``MEDIA_ENT_F_CONN_SVIDEO``
  89        -  Connector for a S-Video signal.
  90
  91     *  -  ``MEDIA_ENT_F_CONN_COMPOSITE``
  92        -  Connector for a RGB composite signal.
  93
  94     *  -  ``MEDIA_ENT_F_CAM_SENSOR``
  95        -  Camera video sensor entity.
  96
  97     *  -  ``MEDIA_ENT_F_FLASH``
  98        -  Flash controller entity.
  99
 100     *  -  ``MEDIA_ENT_F_LENS``
 101        -  Lens controller entity.
 102
 103     *  -  ``MEDIA_ENT_F_ATV_DECODER``
 104        -  Analog video decoder, the basic function of the video decoder is
 105           to accept analogue video from a wide variety of sources such as
 106           broadcast, DVD players, cameras and video cassette recorders, in
 107           either NTSC, PAL, SECAM or HD format, separating the stream into
 108           its component parts, luminance and chrominance, and output it in
 109           some digital video standard, with appropriate timing signals.
 110
 111     *  -  ``MEDIA_ENT_F_TUNER``
 112        -  Digital TV, analog TV, radio and/or software radio tuner, with
 113           consists on a PLL tuning stage that converts radio frequency (RF)
 114           signal into an Intermediate Frequency (IF). Modern tuners have
 115           internally IF-PLL decoders for audio and video, but older models
 116           have those stages implemented on separate entities.
 117
 118     *  -  ``MEDIA_ENT_F_IF_VID_DECODER``
 119        -  IF-PLL video decoder. It receives the IF from a PLL and decodes
 120           the analog TV video signal. This is commonly found on some very
 121           old analog tuners, like Philips MK3 designs. They all contain a
 122           tda9887 (or some software compatible similar chip, like tda9885).
 123           Those devices use a different I2C address than the tuner PLL.
 124
 125     *  -  ``MEDIA_ENT_F_IF_AUD_DECODER``
 126        -  IF-PLL sound decoder. It receives the IF from a PLL and decodes
 127           the analog TV audio signal. This is commonly found on some very
 128           old analog hardware, like Micronas msp3400, Philips tda9840,
 129           tda985x, etc. Those devices use a different I2C address than the
 130           tuner PLL and should be controlled together with the IF-PLL video
 131           decoder.
 132
 133     *  -  ``MEDIA_ENT_F_AUDIO_CAPTURE``
 134        -  Audio Capture Function Entity.
 135
 136     *  -  ``MEDIA_ENT_F_AUDIO_PLAYBACK``
 137        -  Audio Playback Function Entity.
 138
 139     *  -  ``MEDIA_ENT_F_AUDIO_MIXER``
 140        -  Audio Mixer Function Entity.
 141
 142     *  -  ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER``
 143        -  Video composer (blender). An entity capable of video
 144           composing must have at least two sink pads and one source
 145           pad, and composes input video frames onto output video
 146           frames. Composition can be performed using alpha blending,
 147           color keying, raster operations (ROP), stitching or any other
 148           means.
 149
 150     *  -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
 151        -  Video pixel formatter. An entity capable of pixel formatting
 152           must have at least one sink pad and one source pad. Read
 153           pixel formatters read pixels from memory and perform a subset
 154           of unpacking, cropping, color keying, alpha multiplication
 155           and pixel encoding conversion. Write pixel formatters perform
 156           a subset of dithering, pixel encoding conversion and packing
 157           and write pixels to memory.
 158
 159     *  -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV``
 160        -  Video pixel encoding converter. An entity capable of pixel
 161           encoding conversion must have at least one sink pad and one
 162           source pad, and convert the encoding of pixels received on
 163           its sink pad(s) to a different encoding output on its source
 164           pad(s). Pixel encoding conversion includes but isn't limited
 165           to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB
 166           conversions.
 167
 168     *  -  ``MEDIA_ENT_F_PROC_VIDEO_LUT``
 169        -  Video look-up table. An entity capable of video lookup table
 170           processing must have one sink pad and one source pad. It uses
 171           the values of the pixels received on its sink pad to look up
 172           entries in internal tables and output them on its source pad.
 173           The lookup processing can be performed on all components
 174           separately or combine them for multi-dimensional table
 175           lookups.
 176
 177     *  -  ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
 178        -  Video scaler. An entity capable of video scaling must have
 179           at least one sink pad and one source pad, and scale the
 180           video frame(s) received on its sink pad(s) to a different
 181           resolution output on its source pad(s). The range of
 182           supported scaling ratios is entity-specific and can differ
 183           between the horizontal and vertical directions (in particular
 184           scaling can be supported in one direction only). Binning and
 185           sub-sampling (occasionally also referred to as skipping) are
 186           considered as scaling.
 187
 188     *  -  ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
 189        -  Video statistics computation (histogram, 3A, etc.). An entity
 190           capable of statistics computation must have one sink pad and
 191           one source pad. It computes statistics over the frames
 192           received on its sink pad and outputs the statistics data on
 193           its source pad.
 194
 195     *  -  ``MEDIA_ENT_F_PROC_VIDEO_ENCODER``
 196        -  Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of
 197           compressing video frames. Must have one sink pad and at least
 198           one source pad.
 199
 200     *  -  ``MEDIA_ENT_F_PROC_VIDEO_DECODER``
 201        -  Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of
 202           decompressing a compressed video stream into uncompressed video
 203           frames. Must have one sink pad and at least one source pad.
 204
 205     *  -  ``MEDIA_ENT_F_PROC_VIDEO_ISP``
 206        -  An Image Signal Processor (ISP) device. ISPs generally are one of a
 207           kind devices that have their specific control interfaces using a
 208           combination of custom V4L2 controls and IOCTLs, and parameters
 209           supplied in a metadata buffer.
 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{4.8cm}|
 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, then for this pad to be able to stream, it must
 379           be connected by at least one enabled link. There could be temporary
 380           reasons (e.g. device configuration dependent) for the pad to need
 381           enabled links even when this flag isn't set; the absence of the flag
 382           doesn't imply there is none.
 383
 384
 385 One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
 386 must be set for every pad.
 387
 388 .. tabularcolumns:: |p{5.5cm}|p{12.0cm}|
 389
 390 .. _media-link-flag:
 391 .. _MEDIA-LNK-FL-ENABLED:
 392 .. _MEDIA-LNK-FL-IMMUTABLE:
 393 .. _MEDIA-LNK-FL-DYNAMIC:
 394 .. _MEDIA-LNK-FL-LINK-TYPE:
 395
 396 .. flat-table:: Media link flags
 397     :header-rows:  0
 398     :stub-columns: 0
 399
 400     *  -  ``MEDIA_LNK_FL_ENABLED``
 401        -  The link is enabled and can be used to transfer media data. When
 402           two or more links target a sink pad, only one of them can be
 403           enabled at a time.
 404
 405     *  -  ``MEDIA_LNK_FL_IMMUTABLE``
 406        -  The link enabled state can't be modified at runtime. An immutable
 407           link is always enabled.
 408
 409     *  -  ``MEDIA_LNK_FL_DYNAMIC``
 410        -  The link enabled state can be modified during streaming. This flag
 411           is set by drivers and is read-only for applications.
 412
 413     *  -  ``MEDIA_LNK_FL_LINK_TYPE``
 414        -  This is a bitmask that defines the type of the link. The following
 415           link types are currently supported:
 416
 417           .. _MEDIA-LNK-FL-DATA-LINK:
 418
 419           ``MEDIA_LNK_FL_DATA_LINK`` for links that represent a data connection
 420           between two pads.
 421
 422           .. _MEDIA-LNK-FL-INTERFACE-LINK:
 423
 424           ``MEDIA_LNK_FL_INTERFACE_LINK`` for links that associate an entity to its
 425           interface.
 426
 427           .. _MEDIA-LNK-FL-ANCILLARY-LINK:
 428
 429           ``MEDIA_LNK_FL_ANCILLARY_LINK`` for links that represent a physical
 430           relationship between two entities. The link may or may not be
 431           immutable, so applications must not assume either case.