Media subsystem kernel internal API

This section contains usage information about media subsystem and its supported drivers.

Please see:

Documentation/admin-guide/media/index.rst

• for usage information about media subsystem and supported drivers;

Documentation/userspace-api/media/index.rst

• for the userspace APIs used on media devices.

Table of Contents

• 1. Media Subsystem Profile
  • 1.1. Overview
    • 1.1.1. Media maintainers
  • 1.2. Submit Checklist Addendum
    • 1.2.1. Style Cleanup Patches
    • 1.2.2. Coding Style Addendum
  • 1.3. Key Cycle Dates
  • 1.4. Review Cadence
• 2. Video4Linux devices
  • 2.1. Introduction
  • 2.2. Structure of a V4L driver
  • 2.3. Structure of the V4L2 framework
  • 2.4. Video device' s internal representation
    • 2.4.1. ioctls and locking
    • 2.4.2. Video device registration
    • 2.4.3. video device debugging
    • 2.4.4. Video device cleanup
    • 2.4.5. helper functions
    • 2.4.6. video_device functions and data structures
  • 2.5. V4L2 device instance
    • 2.5.1. v4l2_device functions and data structures
  • 2.6. V4L2 File handlers
    • 2.6.1. V4L2 fh functions and data structures
  • 2.7. V4L2 sub-devices
    • 2.7.1. Subdev registration
      • 2.7.1.1. Registering synchronous sub-devices
      • 2.7.1.2. Registering asynchronous sub-devices
      • 2.7.1.3. Asynchronous sub-device notifiers
      • 2.7.1.4. Asynchronous sub-device notifier for sub-devices
      • 2.7.1.5. Asynchronous sub-device registration helper for camera sensor drivers
      • 2.7.1.6. Asynchronous sub-device notifier example
      • 2.7.1.7. Asynchronous sub-device notifier callbacks
    • 2.7.2. Calling subdev operations
  • 2.8. V4L2 sub-device userspace API
  • 2.9. Read-only sub-device userspace API
  • 2.10. I2C sub-device drivers
  • 2.11. Centrally managed subdev active state
  • 2.12. Streams, multiplexed media pads and internal routing
  • 2.13. V4L2 sub-device functions and data structures
  • 2.14. V4L2 events
    • 2.14.1. Event subscription
    • 2.14.2. Unsubscribing an event
    • 2.14.3. Check if there's a pending event
    • 2.14.4. How events work
      • 2.14.4.1. V4L2 event functions and data structures
  • 2.15. V4L2 Controls
    • 2.15.1. Introduction
    • 2.15.2. Objects in the framework
    • 2.15.3. Basic usage for V4L2 and sub-device drivers
    • 2.15.4. Inheriting Sub-device Controls
    • 2.15.5. Accessing Control Values
    • 2.15.6. Menu Controls
    • 2.15.7. Custom Controls
    • 2.15.8. Active and Grabbed Controls
    • 2.15.9. Control Clusters
    • 2.15.10. Handling autogain/gain-type Controls with Auto Clusters
    • 2.15.11. VIDIOC_LOG_STATUS Support
    • 2.15.12. Different Handlers for Different Video Nodes
    • 2.15.13. Finding Controls
    • 2.15.14. Preventing Controls inheritance
    • 2.15.15. V4L2_CTRL_TYPE_CTRL_CLASS Controls
    • 2.15.16. Adding Notify Callbacks
    • 2.15.17. v4l2_ctrl functions and data structures
  • 2.16. V4L2 videobuf2 functions and data structures
  • 2.17. V4L2 DV Timings functions
  • 2.18. V4L2 flash functions and data structures
  • 2.19. V4L2 Media Controller functions and data structures
  • 2.20. V4L2 Media Bus functions and data structures
  • 2.21. V4L2 Memory to Memory functions and data structures
  • 2.22. V4L2 async kAPI
  • 2.23. V4L2 fwnode kAPI
  • 2.24. V4L2 CCI kAPI
  • 2.25. V4L2 rect helper functions
  • 2.26. Tuner functions and data structures
  • 2.27. V4L2 common functions and data structures
  • 2.28. Hauppauge TV EEPROM functions and data structures
• 3. Digital TV (DVB) devices
  • 3.1. Digital TV Common functions
    • 3.1.1. DVB devices
    • 3.1.2. Digital TV Ring buffer
    • 3.1.3. Digital TV VB2 handler
  • 3.2. Digital TV Frontend kABI
    • 3.2.1. Digital TV Frontend
      • 3.2.1.1. Demodulator driver
      • 3.2.1.2. Attaching frontend driver to the bridge driver
    • 3.2.2. Digital TV Frontend statistics
      • 3.2.2.1. Introduction
      • 3.2.2.2. Groups of statistics
      • 3.2.2.3. Statistics collection
        • 3.2.2.3.1. if the driver have a bit that indicates when a collected data is ready
        • 3.2.2.3.2. If the driver doesn't provide a statistics available check bit
    • 3.2.3. Digital TV Frontend functions and types
  • 3.3. Digital TV Demux kABI
    • 3.3.1. Digital TV Demux
    • 3.3.2. Demux Callback API
    • 3.3.3. Digital TV Demux device registration functions and data structures
    • 3.3.4. High-level Digital TV demux interface
    • 3.3.5. Driver-internal low-level hardware specific driver demux interface
  • 3.4. Digital TV Conditional Access kABI
  • 3.5. Digital TV Network kABI
• 4. Remote Controller devices
  • 4.1. Remote Controller core
    • 4.1.1. Remote controller data structures and functions
• 5. Media Controller devices
  • 5.1. Media Controller
    • 5.1.1. Abstract media device model
    • 5.1.2. Media device
    • 5.1.3. Entities
    • 5.1.4. Interfaces
    • 5.1.5. Pads
    • 5.1.6. Links
    • 5.1.7. Graph traversal
    • 5.1.8. Use count and power handling
    • 5.1.9. Links setup
    • 5.1.10. Pipelines and media streams
    • 5.1.11. Link validation
    • 5.1.12. Media Controller Device Allocator API
    • 5.1.13. API Definitions
• 6. CEC Kernel Support
  • 6.1. The CEC Protocol
  • 6.2. CEC Adapter Interface
  • 6.3. Implementing the Low-Level CEC Adapter
  • 6.4. Implementing the interrupt handler
  • 6.5. Optional: Implementing Error Injection Support
  • 6.6. Implementing the High-Level CEC Adapter
  • 6.7. CEC framework functions
  • 6.8. CEC Pin framework
  • 6.9. CEC Notifier framework
• 7. Pixel data transmitter and receiver drivers
  • 7.1. Bus types
    • 7.1.1. MIPI CSI-2
    • 7.1.2. Parallel and BT.656
  • 7.2. Transmitter drivers
    • 7.2.1. Media bus pixel code
    • 7.2.2. Link frequency
    • 7.2.3. .s_stream() callback
  • 7.3. CSI-2 transmitter drivers
    • 7.3.1. Pixel rate
    • 7.3.2. LP-11 and LP-111 states
    • 7.3.3. Stopping the transmitter
• 8. Writing camera sensor drivers
  • 8.1. CSI-2, parallel and BT.656 buses
  • 8.2. Handling clocks
    • 8.2.1. ACPI
    • 8.2.2. Devicetree
  • 8.3. Power management
    • 8.3.1. Control framework
  • 8.4. Rotation, orientation and flipping
  • 8.5. Example drivers
• 9. Media driver-specific documentation
  • 9.1. Video4Linux (V4L) drivers
    • 9.1.1. The bttv driver
      • 9.1.1.1. bttv and sound mini howto
        • 9.1.1.1.1. How sound works in detail
    • 9.1.2. The cx2341x driver
      • 9.1.2.1. Memory at cx2341x chips
        • 9.1.2.1.1. Memory Map
        • 9.1.2.1.2. Registers
        • 9.1.2.1.3. Interrupt Status Register
      • 9.1.2.2. Missing documentation
      • 9.1.2.3. The cx2341x firmware upload
        • 9.1.2.3.1. How to find
        • 9.1.2.3.2. How to load
      • 9.1.2.4. How to call the firmware API
      • 9.1.2.5. OSD firmware API description
        • 9.1.2.5.1. CX2341X_OSD_GET_FRAMEBUFFER
        • 9.1.2.5.2. CX2341X_OSD_GET_PIXEL_FORMAT
        • 9.1.2.5.3. CX2341X_OSD_SET_PIXEL_FORMAT
        • 9.1.2.5.4. CX2341X_OSD_GET_STATE
        • 9.1.2.5.5. CX2341X_OSD_SET_STATE
        • 9.1.2.5.6. CX2341X_OSD_GET_OSD_COORDS
        • 9.1.2.5.7. CX2341X_OSD_SET_OSD_COORDS
        • 9.1.2.5.8. CX2341X_OSD_GET_SCREEN_COORDS
        • 9.1.2.5.9. CX2341X_OSD_SET_SCREEN_COORDS
        • 9.1.2.5.10. CX2341X_OSD_GET_GLOBAL_ALPHA
        • 9.1.2.5.11. CX2341X_OSD_SET_GLOBAL_ALPHA
        • 9.1.2.5.12. CX2341X_OSD_SET_BLEND_COORDS
        • 9.1.2.5.13. CX2341X_OSD_GET_FLICKER_STATE
        • 9.1.2.5.14. CX2341X_OSD_SET_FLICKER_STATE
        • 9.1.2.5.15. CX2341X_OSD_BLT_COPY
        • 9.1.2.5.16. CX2341X_OSD_BLT_FILL
        • 9.1.2.5.17. CX2341X_OSD_BLT_TEXT
        • 9.1.2.5.18. CX2341X_OSD_SET_FRAMEBUFFER_WINDOW
        • 9.1.2.5.19. CX2341X_OSD_SET_CHROMA_KEY
        • 9.1.2.5.20. CX2341X_OSD_GET_ALPHA_CONTENT_INDEX
        • 9.1.2.5.21. CX2341X_OSD_SET_ALPHA_CONTENT_INDEX
      • 9.1.2.6. Encoder firmware API description
        • 9.1.2.6.1. CX2341X_ENC_PING_FW
        • 9.1.2.6.2. CX2341X_ENC_START_CAPTURE
        • 9.1.2.6.3. CX2341X_ENC_STOP_CAPTURE
        • 9.1.2.6.4. CX2341X_ENC_SET_AUDIO_ID
        • 9.1.2.6.5. CX2341X_ENC_SET_VIDEO_ID
        • 9.1.2.6.6. CX2341X_ENC_SET_PCR_ID
        • 9.1.2.6.7. CX2341X_ENC_SET_FRAME_RATE
        • 9.1.2.6.8. CX2341X_ENC_SET_FRAME_SIZE
        • 9.1.2.6.9. CX2341X_ENC_SET_BIT_RATE
        • 9.1.2.6.10. CX2341X_ENC_SET_GOP_PROPERTIES
        • 9.1.2.6.11. CX2341X_ENC_SET_ASPECT_RATIO
        • 9.1.2.6.12. CX2341X_ENC_SET_DNR_FILTER_MODE
        • 9.1.2.6.13. CX2341X_ENC_SET_DNR_FILTER_PROPS
        • 9.1.2.6.14. CX2341X_ENC_SET_CORING_LEVELS
        • 9.1.2.6.15. CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
        • 9.1.2.6.16. CX2341X_ENC_SET_VBI_LINE
        • 9.1.2.6.17. CX2341X_ENC_SET_STREAM_TYPE
        • 9.1.2.6.18. CX2341X_ENC_SET_OUTPUT_PORT
        • 9.1.2.6.19. CX2341X_ENC_SET_AUDIO_PROPERTIES
        • 9.1.2.6.20. CX2341X_ENC_HALT_FW
        • 9.1.2.6.21. CX2341X_ENC_GET_VERSION
        • 9.1.2.6.22. CX2341X_ENC_SET_GOP_CLOSURE
        • 9.1.2.6.23. CX2341X_ENC_GET_SEQ_END
        • 9.1.2.6.24. CX2341X_ENC_SET_PGM_INDEX_INFO
        • 9.1.2.6.25. CX2341X_ENC_SET_VBI_CONFIG
        • 9.1.2.6.26. CX2341X_ENC_SET_DMA_BLOCK_SIZE
        • 9.1.2.6.27. CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
        • 9.1.2.6.28. CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
        • 9.1.2.6.29. CX2341X_ENC_SCHED_DMA_TO_HOST
        • 9.1.2.6.30. CX2341X_ENC_INITIALIZE_INPUT
        • 9.1.2.6.31. CX2341X_ENC_SET_FRAME_DROP_RATE
        • 9.1.2.6.32. CX2341X_ENC_PAUSE_ENCODER
        • 9.1.2.6.33. CX2341X_ENC_REFRESH_INPUT
        • 9.1.2.6.34. CX2341X_ENC_SET_COPYRIGHT
        • 9.1.2.6.35. CX2341X_ENC_SET_EVENT_NOTIFICATION
        • 9.1.2.6.36. CX2341X_ENC_SET_NUM_VSYNC_LINES
        • 9.1.2.6.37. CX2341X_ENC_SET_PLACEHOLDER
        • 9.1.2.6.38. CX2341X_ENC_MUTE_VIDEO
        • 9.1.2.6.39. CX2341X_ENC_MUTE_AUDIO
        • 9.1.2.6.40. CX2341X_ENC_SET_VERT_CROP_LINE
        • 9.1.2.6.41. CX2341X_ENC_MISC
      • 9.1.2.7. Decoder firmware API description
        • 9.1.2.7.1. CX2341X_DEC_PING_FW
        • 9.1.2.7.2. CX2341X_DEC_START_PLAYBACK
        • 9.1.2.7.3. CX2341X_DEC_STOP_PLAYBACK
        • 9.1.2.7.4. CX2341X_DEC_SET_PLAYBACK_SPEED
        • 9.1.2.7.5. CX2341X_DEC_STEP_VIDEO
        • 9.1.2.7.6. CX2341X_DEC_SET_DMA_BLOCK_SIZE
        • 9.1.2.7.7. CX2341X_DEC_GET_XFER_INFO
        • 9.1.2.7.8. CX2341X_DEC_GET_DMA_STATUS
        • 9.1.2.7.9. CX2341X_DEC_SCHED_DMA_FROM_HOST
        • 9.1.2.7.10. CX2341X_DEC_PAUSE_PLAYBACK
        • 9.1.2.7.11. CX2341X_DEC_HALT_FW
        • 9.1.2.7.12. CX2341X_DEC_SET_STANDARD
        • 9.1.2.7.13. CX2341X_DEC_GET_VERSION
        • 9.1.2.7.14. CX2341X_DEC_SET_STREAM_INPUT
        • 9.1.2.7.15. CX2341X_DEC_GET_TIMING_INFO
        • 9.1.2.7.16. CX2341X_DEC_SET_AUDIO_MODE
        • 9.1.2.7.17. CX2341X_DEC_SET_EVENT_NOTIFICATION
        • 9.1.2.7.18. CX2341X_DEC_SET_DISPLAY_BUFFERS
        • 9.1.2.7.19. CX2341X_DEC_EXTRACT_VBI
        • 9.1.2.7.20. CX2341X_DEC_SET_DECODER_SOURCE
        • 9.1.2.7.21. CX2341X_DEC_SET_PREBUFFERING
      • 9.1.2.8. PVR350 Video decoder registers 0x02002800 -> 0x02002B00
      • 9.1.2.9. The cx231xx DMA engine
        • 9.1.2.9.1. Introduction
        • 9.1.2.9.2. Flow
        • 9.1.2.9.3. Mailbox #10
        • 9.1.2.9.4. Scatter-Gather Array
        • 9.1.2.9.5. DMA Transfer Status
    • 9.1.3. The cx88 driver
      • 9.1.3.1. Documentation missing at the cx88 datasheet
      • 9.1.3.2. Hauppauge WinTV cx88 IR information
        • 9.1.3.2.1. Additional info
    • 9.1.4. The Samsung S5P/EXYNOS4 FIMC driver
      • 9.1.4.1. Files partitioning
    • 9.1.5. The pvrusb2 driver
      • 9.1.5.1. Background
      • 9.1.5.2. Building
      • 9.1.5.3. Source file list / functional overview
    • 9.1.6. PXA-Camera Host Driver
      • 9.1.6.1. Constraints
      • 9.1.6.2. Global video workflow
      • 9.1.6.3. DMA usage
    • 9.1.7. The Radiotrack radio driver
      • 9.1.7.1. ACKNOWLEDGMENTS
      • 9.1.7.2. WHY THIS DOCUMENT?
      • 9.1.7.3. PHYSICAL DESCRIPTION
      • 9.1.7.4. CONTROLLING THE CARD WITH IOPORT
      • 9.1.7.5. PROGRAMMING EXAMPLES
    • 9.1.8. The Rockchip Image Signal Processor Driver (rkisp1)
      • 9.1.8.1. Versions and their differences
      • 9.1.8.2. Changes from V10 to V12
      • 9.1.8.3. Changes from V12 to V13
    • 9.1.9. The saa7134 driver
      • 9.1.9.1. Card Variations:
      • 9.1.9.2. LifeView GPIOs
      • 9.1.9.3. Credits
    • 9.1.10. Cropping and Scaling algorithm, used in the sh_mobile_ceu_camera driver
      • 9.1.10.1. Terminology
      • 9.1.10.2. Generic scaling / cropping scheme
      • 9.1.10.3. S_FMT
      • 9.1.10.4. S_CROP
    • 9.1.11. Tuner drivers
      • 9.1.11.1. Simple tuner Programming
      • 9.1.11.2. Tuner Manufacturers
    • 9.1.12. The Virtual Media Controller Driver (vimc)
      • 9.1.12.1. Source code documentation
        • 9.1.12.1.1. vimc-streamer
    • 9.1.13. The Zoran driver
      • 9.1.13.1. Frequently Asked Questions
      • 9.1.13.2. What cards are supported
        • 9.1.13.2.1. Iomega Buz
        • 9.1.13.2.2. AverMedia 6 Eyes AVS6EYES
        • 9.1.13.2.3. Linux Media Labs LML33
        • 9.1.13.2.4. Linux Media Labs LML33R10
        • 9.1.13.2.5. Pinnacle/Miro DC10(new)
        • 9.1.13.2.6. Pinnacle/Miro DC10+
        • 9.1.13.2.7. Pinnacle/Miro DC10(old)
        • 9.1.13.2.8. Pinnacle/Miro DC30
        • 9.1.13.2.9. Pinnacle/Miro DC30+
      • 9.1.13.3. 1.1 What the TV decoder can do an what not
        • 9.1.13.3.1. Philips saa7111 TV decoder
        • 9.1.13.3.2. Philips saa7110a TV decoder
        • 9.1.13.3.3. Philips saa7114 TV decoder
        • 9.1.13.3.4. Brooktree bt819 TV decoder
        • 9.1.13.3.5. Micronas vpx3220a TV decoder
        • 9.1.13.3.6. Samsung ks0127 TV decoder
      • 9.1.13.4. What the TV encoder can do an what not
        • 9.1.13.4.1. Philips saa7185 TV Encoder
        • 9.1.13.4.2. Brooktree bt856 TV Encoder
        • 9.1.13.4.3. Analog Devices adv7170 TV Encoder
        • 9.1.13.4.4. Analog Devices adv7175 TV Encoder
        • 9.1.13.4.5. ITT mse3000 TV encoder
        • 9.1.13.4.6. Conexant bt866 TV encoder
      • 9.1.13.5. How do I get this damn thing to work
      • 9.1.13.6. What mainboard should I use (or why doesn't my card work)
      • 9.1.13.7. Programming interface
      • 9.1.13.8. Applications
      • 9.1.13.9. Concerning buffer sizes, quality, output size etc.
      • 9.1.13.10. It hangs/crashes/fails/whatevers! Help!
      • 9.1.13.11. Maintainers/Contacting
      • 9.1.13.12. Driver's License
    • 9.1.14. MIPI CCS camera sensor driver
      • 9.1.14.1. Pixel Array sub-device
      • 9.1.14.2. Binner
      • 9.1.14.3. Scaler
      • 9.1.14.4. Digital and analogue crop
      • 9.1.14.5. CCS static data
        • 9.1.14.5.1. CCS tools
      • 9.1.14.6. Register definition generator
        • 9.1.14.6.1. Usage
    • 9.1.15. CCS PLL calculator
  • 9.2. Digital TV drivers
    • 9.2.1. Idea behind the dvb-usb-framework
      • 9.2.1.1. Supported devices
      • 9.2.1.2. How to use?
        • 9.2.1.2.1. Firmware
        • 9.2.1.2.2. Compiling
        • 9.2.1.2.3. Loading the drivers
      • 9.2.1.3. Known problems and bugs
        • 9.2.1.3.1. Adding support for devices
        • 9.2.1.3.2. USB1.1 Bandwidth limitation
        • 9.2.1.3.3. Comments
      • 9.2.1.4. 3. Acknowledgements
    • 9.2.2. Frontend drivers
      • 9.2.2.1. Frontend attach headers
    • 9.2.3. vidtv: Virtual Digital TV driver
      • 9.2.3.1. Background
      • 9.2.3.2. Building vidtv
      • 9.2.3.3. Running vidtv
      • 9.2.3.4. Command-line arguments to vidtv
      • 9.2.3.5. vidtv internal structure
      • 9.2.3.6. Testing vidtv with v4l-utils
        • 9.2.3.6.1. Using dvb-fe-tool
        • 9.2.3.6.2. Using dvb-scan
        • 9.2.3.6.3. Using dvb-zap
      • 9.2.3.7. What can still be improved in vidtv
        • 9.2.3.7.1. Add debugfs integration
        • 9.2.3.7.2. Add a way to test video
        • 9.2.3.7.3. Add white noise simulation
      • 9.2.3.8. Functions and structs used within vidtv
    • 9.2.4. Contributors

Copyright © 2009-2020 : LinuxTV Developers

This documentation is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

For more details see the file COPYING in the source distribution of Linux.