Part II - Digital TV API

Note

This API is also known as Linux DVB API.

It it was originally written to support the European digital TV standard (DVB), and later extended to support all digital TV standards.

In order to avoid confusion, within this document, it was opted to refer to it, and to associated hardware as Digital TV.

The word DVB is reserved to be used for:

• the Digital TV API version (e. g. DVB API version 3 or DVB API version 5);

• digital TV data types (enums, structs, defines, etc);

• digital TV device nodes (/dev/dvb/...);

• the European DVB standard.

Version 5.10

Table of Contents

• 1. Introduction
  • 1.1. What you need to know
  • 1.2. History
  • 1.3. Overview
  • 1.4. Linux Digital TV Devices
  • 1.5. API include files
• 2. Digital TV Frontend API
  • 2.1. Querying frontend information
  • 2.2. Querying frontend status and statistics
  • 2.3. Property types
    • 2.3.1. Digital TV property parameters
      • 2.3.1.1. DTV_UNDEFINED
      • 2.3.1.2. DTV_TUNE
      • 2.3.1.3. DTV_CLEAR
      • 2.3.1.4. DTV_FREQUENCY
      • 2.3.1.5. DTV_MODULATION
      • 2.3.1.6. DTV_BANDWIDTH_HZ
      • 2.3.1.7. DTV_INVERSION
      • 2.3.1.8. DTV_DISEQC_MASTER
      • 2.3.1.9. DTV_SYMBOL_RATE
      • 2.3.1.10. DTV_INNER_FEC
      • 2.3.1.11. DTV_VOLTAGE
      • 2.3.1.12. DTV_TONE
      • 2.3.1.13. DTV_PILOT
      • 2.3.1.14. DTV_ROLLOFF
      • 2.3.1.15. DTV_DISEQC_SLAVE_REPLY
      • 2.3.1.16. DTV_FE_CAPABILITY_COUNT
      • 2.3.1.17. DTV_FE_CAPABILITY
      • 2.3.1.18. DTV_DELIVERY_SYSTEM
      • 2.3.1.19. DTV_ISDBT_PARTIAL_RECEPTION
      • 2.3.1.20. DTV_ISDBT_SOUND_BROADCASTING
      • 2.3.1.21. DTV_ISDBT_SB_SUBCHANNEL_ID
      • 2.3.1.22. DTV_ISDBT_SB_SEGMENT_IDX
      • 2.3.1.23. DTV_ISDBT_SB_SEGMENT_COUNT
      • 2.3.1.24. DTV-ISDBT-LAYER[A-C] parameters
        • 2.3.1.24.1. DTV_ISDBT_LAYER_ENABLED
        • 2.3.1.24.2. DTV_ISDBT_LAYER[A-C]_FEC
        • 2.3.1.24.3. DTV_ISDBT_LAYER[A-C]_MODULATION
        • 2.3.1.24.4. DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT
        • 2.3.1.24.5. DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING
        • 2.3.1.24.6. DTV_ATSCMH_FIC_VER
        • 2.3.1.24.7. DTV_ATSCMH_PARADE_ID
        • 2.3.1.24.8. DTV_ATSCMH_NOG
        • 2.3.1.24.9. DTV_ATSCMH_TNOG
        • 2.3.1.24.10. DTV_ATSCMH_SGN
        • 2.3.1.24.11. DTV_ATSCMH_PRC
        • 2.3.1.24.12. DTV_ATSCMH_RS_FRAME_MODE
        • 2.3.1.24.13. DTV_ATSCMH_RS_FRAME_ENSEMBLE
        • 2.3.1.24.14. DTV_ATSCMH_RS_CODE_MODE_PRI
        • 2.3.1.24.15. DTV_ATSCMH_RS_CODE_MODE_SEC
        • 2.3.1.24.16. DTV_ATSCMH_SCCC_BLOCK_MODE
        • 2.3.1.24.17. DTV_ATSCMH_SCCC_CODE_MODE_A
        • 2.3.1.24.18. DTV_ATSCMH_SCCC_CODE_MODE_B
        • 2.3.1.24.19. DTV_ATSCMH_SCCC_CODE_MODE_C
        • 2.3.1.24.20. DTV_ATSCMH_SCCC_CODE_MODE_D
      • 2.3.1.25. DTV_API_VERSION
      • 2.3.1.26. DTV_CODE_RATE_HP
      • 2.3.1.27. DTV_CODE_RATE_LP
      • 2.3.1.28. DTV_GUARD_INTERVAL
      • 2.3.1.29. DTV_TRANSMISSION_MODE
      • 2.3.1.30. DTV_HIERARCHY
      • 2.3.1.31. DTV_STREAM_ID
      • 2.3.1.32. DTV_DVBT2_PLP_ID_LEGACY
      • 2.3.1.33. DTV_ENUM_DELSYS
      • 2.3.1.34. DTV_INTERLEAVING
      • 2.3.1.35. DTV_LNA
      • 2.3.1.36. DTV_SCRAMBLING_SEQUENCE_INDEX
    • 2.3.2. Frontend statistics indicators
      • 2.3.2.1. DTV_STAT_SIGNAL_STRENGTH
      • 2.3.2.2. DTV_STAT_CNR
      • 2.3.2.3. DTV_STAT_PRE_ERROR_BIT_COUNT
      • 2.3.2.4. DTV_STAT_PRE_TOTAL_BIT_COUNT
      • 2.3.2.5. DTV_STAT_POST_ERROR_BIT_COUNT
      • 2.3.2.6. DTV_STAT_POST_TOTAL_BIT_COUNT
      • 2.3.2.7. DTV_STAT_ERROR_BLOCK_COUNT
      • 2.3.2.8. DTV-STAT_TOTAL_BLOCK_COUNT
    • 2.3.3. Properties used on terrestrial delivery systems
      • 2.3.3.1. DVB-T delivery system
      • 2.3.3.2. DVB-T2 delivery system
      • 2.3.3.3. ISDB-T delivery system
      • 2.3.3.4. ATSC delivery system
      • 2.3.3.5. ATSC-MH delivery system
      • 2.3.3.6. DTMB delivery system
    • 2.3.4. Properties used on cable delivery systems
      • 2.3.4.1. DVB-C delivery system
      • 2.3.4.2. DVB-C Annex B delivery system
    • 2.3.5. Properties used on satellite delivery systems
      • 2.3.5.1. DVB-S delivery system
      • 2.3.5.2. DVB-S2 delivery system
      • 2.3.5.3. Turbo code delivery system
      • 2.3.5.4. ISDB-S delivery system
    • 2.3.6. Frontend uAPI data types
  • 2.4. Frontend Function Calls
    • 2.4.1. Digital TV frontend open()
      • 2.4.1.1. Name
      • 2.4.1.2. Synopsis
      • 2.4.1.3. Arguments
      • 2.4.1.4. Description
      • 2.4.1.5. Return Value
    • 2.4.2. Digital TV frontend close()
      • 2.4.2.1. Name
      • 2.4.2.2. Synopsis
      • 2.4.2.3. Arguments
      • 2.4.2.4. Description
      • 2.4.2.5. Return Value
    • 2.4.3. ioctl FE_GET_INFO
      • 2.4.3.1. Name
      • 2.4.3.2. Synopsis
      • 2.4.3.3. Arguments
      • 2.4.3.4. Description
      • 2.4.3.5. frontend capabilities
      • 2.4.3.6. Return Value
    • 2.4.4. ioctl FE_READ_STATUS
      • 2.4.4.1. Name
      • 2.4.4.2. Synopsis
      • 2.4.4.3. Arguments
      • 2.4.4.4. Description
      • 2.4.4.5. int fe_status
      • 2.4.4.6. Return Value
    • 2.4.5. ioctl FE_SET_PROPERTY, FE_GET_PROPERTY
      • 2.4.5.1. Name
      • 2.4.5.2. Synopsis
      • 2.4.5.3. Arguments
      • 2.4.5.4. Description
      • 2.4.5.5. Return Value
    • 2.4.6. ioctl FE_DISEQC_RESET_OVERLOAD
      • 2.4.6.1. Name
      • 2.4.6.2. Synopsis
      • 2.4.6.3. Arguments
      • 2.4.6.4. Description
      • 2.4.6.5. Return Value
    • 2.4.7. ioctl FE_DISEQC_SEND_MASTER_CMD
      • 2.4.7.1. Name
      • 2.4.7.2. Synopsis
      • 2.4.7.3. Arguments
      • 2.4.7.4. Description
      • 2.4.7.5. Return Value
    • 2.4.8. ioctl FE_DISEQC_RECV_SLAVE_REPLY
      • 2.4.8.1. Name
      • 2.4.8.2. Synopsis
      • 2.4.8.3. Arguments
      • 2.4.8.4. Description
      • 2.4.8.5. Return Value
    • 2.4.9. ioctl FE_DISEQC_SEND_BURST
      • 2.4.9.1. Name
      • 2.4.9.2. Synopsis
      • 2.4.9.3. Arguments
      • 2.4.9.4. Description
      • 2.4.9.5. Return Value
    • 2.4.10. ioctl FE_SET_TONE
      • 2.4.10.1. Name
      • 2.4.10.2. Synopsis
      • 2.4.10.3. Arguments
      • 2.4.10.4. Description
      • 2.4.10.5. Return Value
    • 2.4.11. ioctl FE_SET_VOLTAGE
      • 2.4.11.1. Name
      • 2.4.11.2. Synopsis
      • 2.4.11.3. Arguments
      • 2.4.11.4. Description
      • 2.4.11.5. Return Value
    • 2.4.12. ioctl FE_ENABLE_HIGH_LNB_VOLTAGE
      • 2.4.12.1. Name
      • 2.4.12.2. Synopsis
      • 2.4.12.3. Arguments
      • 2.4.12.4. Description
      • 2.4.12.5. Return Value
    • 2.4.13. ioctl FE_SET_FRONTEND_TUNE_MODE
      • 2.4.13.1. Name
      • 2.4.13.2. Synopsis
      • 2.4.13.3. Arguments
      • 2.4.13.4. Description
      • 2.4.13.5. Return Value
• 3. Digital TV Demux Device
  • 3.1. Demux Data Types
  • 3.2. Demux Function Calls
    • 3.2.1. Digital TV demux open()
      • 3.2.1.1. Name
      • 3.2.1.2. Synopsis
      • 3.2.1.3. Arguments
      • 3.2.1.4. Description
      • 3.2.1.5. Return Value
    • 3.2.2. Digital TV demux close()
      • 3.2.2.1. Name
      • 3.2.2.2. Synopsis
      • 3.2.2.3. Arguments
      • 3.2.2.4. Description
      • 3.2.2.5. Return Value
    • 3.2.3. Digital TV demux read()
      • 3.2.3.1. Name
      • 3.2.3.2. Synopsis
      • 3.2.3.3. Arguments
      • 3.2.3.4. Description
      • 3.2.3.5. Return Value
    • 3.2.4. Digital TV demux write()
      • 3.2.4.1. Name
      • 3.2.4.2. Synopsis
      • 3.2.4.3. Arguments
      • 3.2.4.4. Description
      • 3.2.4.5. Return Value
    • 3.2.5. Digital TV mmap()
      • 3.2.5.1. Name
      • 3.2.5.2. Synopsis
      • 3.2.5.3. Arguments
      • 3.2.5.4. Description
      • 3.2.5.5. Return Value
    • 3.2.6. DVB munmap()
      • 3.2.6.1. Name
      • 3.2.6.2. Synopsis
      • 3.2.6.3. Arguments
      • 3.2.6.4. Description
      • 3.2.6.5. Return Value
    • 3.2.7. DMX_START
      • 3.2.7.1. Name
      • 3.2.7.2. Synopsis
      • 3.2.7.3. Arguments
      • 3.2.7.4. Description
      • 3.2.7.5. Return Value
    • 3.2.8. DMX_STOP
      • 3.2.8.1. Name
      • 3.2.8.2. Synopsis
      • 3.2.8.3. Arguments
      • 3.2.8.4. Description
      • 3.2.8.5. Return Value
    • 3.2.9. DMX_SET_FILTER
      • 3.2.9.1. Name
      • 3.2.9.2. Synopsis
      • 3.2.9.3. Arguments
      • 3.2.9.4. Description
      • 3.2.9.5. Return Value
    • 3.2.10. DMX_SET_PES_FILTER
      • 3.2.10.1. Name
      • 3.2.10.2. Synopsis
      • 3.2.10.3. Arguments
      • 3.2.10.4. Description
      • 3.2.10.5. Return Value
    • 3.2.11. DMX_SET_BUFFER_SIZE
      • 3.2.11.1. Name
      • 3.2.11.2. Synopsis
      • 3.2.11.3. Arguments
      • 3.2.11.4. Description
      • 3.2.11.5. Return Value
    • 3.2.12. DMX_GET_STC
      • 3.2.12.1. Name
      • 3.2.12.2. Synopsis
      • 3.2.12.3. Arguments
      • 3.2.12.4. Description
      • 3.2.12.5. Return Value
    • 3.2.13. DMX_GET_PES_PIDS
      • 3.2.13.1. Name
      • 3.2.13.2. Synopsis
      • 3.2.13.3. Arguments
      • 3.2.13.4. Description
      • 3.2.13.5. Return Value
    • 3.2.14. DMX_ADD_PID
      • 3.2.14.1. Name
      • 3.2.14.2. Synopsis
      • 3.2.14.3. Arguments
      • 3.2.14.4. Description
      • 3.2.14.5. Return Value
    • 3.2.15. DMX_REMOVE_PID
      • 3.2.15.1. Name
      • 3.2.15.2. Synopsis
      • 3.2.15.3. Arguments
      • 3.2.15.4. Description
      • 3.2.15.5. Return Value
    • 3.2.16. ioctl DMX_REQBUFS
      • 3.2.16.1. Name
      • 3.2.16.2. Synopsis
      • 3.2.16.3. Arguments
      • 3.2.16.4. Description
      • 3.2.16.5. Return Value
    • 3.2.17. ioctl DMX_QUERYBUF
      • 3.2.17.1. Name
      • 3.2.17.2. Synopsis
      • 3.2.17.3. Arguments
      • 3.2.17.4. Description
      • 3.2.17.5. Return Value
    • 3.2.18. ioctl DMX_EXPBUF
      • 3.2.18.1. Name
      • 3.2.18.2. Synopsis
      • 3.2.18.3. Arguments
      • 3.2.18.4. Description
      • 3.2.18.5. Examples
      • 3.2.18.6. Return Value
    • 3.2.19. ioctl DMX_QBUF, DMX_DQBUF
      • 3.2.19.1. Name
      • 3.2.19.2. Synopsis
      • 3.2.19.3. Arguments
      • 3.2.19.4. Description
      • 3.2.19.5. Return Value
• 4. Digital TV CA Device
  • 4.1. CA Data Types
  • 4.2. CA Function Calls
    • 4.2.1. Digital TV CA open()
      • 4.2.1.1. Name
      • 4.2.1.2. Synopsis
      • 4.2.1.3. Arguments
      • 4.2.1.4. Description
      • 4.2.1.5. Return Value
    • 4.2.2. Digital TV CA close()
      • 4.2.2.1. Name
      • 4.2.2.2. Synopsis
      • 4.2.2.3. Arguments
      • 4.2.2.4. Description
      • 4.2.2.5. Return Value
    • 4.2.3. CA_RESET
      • 4.2.3.1. Name
      • 4.2.3.2. Synopsis
      • 4.2.3.3. Arguments
      • 4.2.3.4. Description
      • 4.2.3.5. Return Value
    • 4.2.4. CA_GET_CAP
      • 4.2.4.1. Name
      • 4.2.4.2. Synopsis
      • 4.2.4.3. Arguments
      • 4.2.4.4. Description
      • 4.2.4.5. Return Value
    • 4.2.5. CA_GET_SLOT_INFO
      • 4.2.5.1. Name
      • 4.2.5.2. Synopsis
      • 4.2.5.3. Arguments
      • 4.2.5.4. Description
      • 4.2.5.5. Return Value
    • 4.2.6. CA_GET_DESCR_INFO
      • 4.2.6.1. Name
      • 4.2.6.2. Synopsis
      • 4.2.6.3. Arguments
      • 4.2.6.4. Description
      • 4.2.6.5. Return Value
    • 4.2.7. CA_GET_MSG
      • 4.2.7.1. Name
      • 4.2.7.2. Synopsis
      • 4.2.7.3. Arguments
      • 4.2.7.4. Description
      • 4.2.7.5. Return Value
    • 4.2.8. CA_SEND_MSG
      • 4.2.8.1. Name
      • 4.2.8.2. Synopsis
      • 4.2.8.3. Arguments
      • 4.2.8.4. Description
      • 4.2.8.5. Return Value
    • 4.2.9. CA_SET_DESCR
      • 4.2.9.1. Name
      • 4.2.9.2. Synopsis
      • 4.2.9.3. Arguments
      • 4.2.9.4. Description
      • 4.2.9.5. Return Value
  • 4.3. The High level CI API
    • 4.3.1. Why the need for another CI interface?
• 5. Digital TV Network API
  • 5.1. Digital TV net Function Calls
    • 5.1.1. Net Data Types
    • 5.1.2. ioctl NET_ADD_IF
      • 5.1.2.1. Name
      • 5.1.2.2. Synopsis
      • 5.1.2.3. Arguments
      • 5.1.2.4. Description
      • 5.1.2.5. Return Value
    • 5.1.3. ioctl NET_REMOVE_IF
      • 5.1.3.1. Name
      • 5.1.3.2. Synopsis
      • 5.1.3.3. Arguments
      • 5.1.3.4. Description
      • 5.1.3.5. Return Value
    • 5.1.4. ioctl NET_GET_IF
      • 5.1.4.1. Name
      • 5.1.4.2. Synopsis
      • 5.1.4.3. Arguments
      • 5.1.4.4. Description
      • 5.1.4.5. Return Value
• 6. Digital TV Deprecated APIs
  • 6.1. Digital TV Frontend legacy API (a. k. a. DVBv3)
    • 6.1.1. Frontend Legacy Data Types
      • 6.1.1.1. Frontend type
      • 6.1.1.2. Frontend bandwidth
      • 6.1.1.3. frontend parameters
        • 6.1.1.3.1. QPSK parameters
        • 6.1.1.3.2. QAM parameters
        • 6.1.1.3.3. VSB parameters
        • 6.1.1.3.4. OFDM parameters
      • 6.1.1.4. frontend events
    • 6.1.2. Frontend Legacy Function Calls
      • 6.1.2.1. FE_READ_BER
        • 6.1.2.1.1. Name
        • 6.1.2.1.2. Synopsis
        • 6.1.2.1.3. Arguments
        • 6.1.2.1.4. Description
        • 6.1.2.1.5. Return Value
      • 6.1.2.2. FE_READ_SNR
        • 6.1.2.2.1. Name
        • 6.1.2.2.2. Synopsis
        • 6.1.2.2.3. Arguments
        • 6.1.2.2.4. Description
        • 6.1.2.2.5. Return Value
      • 6.1.2.3. FE_READ_SIGNAL_STRENGTH
        • 6.1.2.3.1. Name
        • 6.1.2.3.2. Synopsis
        • 6.1.2.3.3. Arguments
        • 6.1.2.3.4. Description
        • 6.1.2.3.5. Return Value
      • 6.1.2.4. FE_READ_UNCORRECTED_BLOCKS
        • 6.1.2.4.1. Name
        • 6.1.2.4.2. Synopsis
        • 6.1.2.4.3. Arguments
        • 6.1.2.4.4. Description
        • 6.1.2.4.5. Return Value
      • 6.1.2.5. FE_SET_FRONTEND
        • 6.1.2.5.1. Name
        • 6.1.2.5.2. Synopsis
        • 6.1.2.5.3. Arguments
        • 6.1.2.5.4. Description
        • 6.1.2.5.5. Return Value
      • 6.1.2.6. FE_GET_FRONTEND
        • 6.1.2.6.1. Name
        • 6.1.2.6.2. Synopsis
        • 6.1.2.6.3. Arguments
        • 6.1.2.6.4. Description
        • 6.1.2.6.5. Return Value
      • 6.1.2.7. FE_GET_EVENT
        • 6.1.2.7.1. Name
        • 6.1.2.7.2. Synopsis
        • 6.1.2.7.3. Arguments
        • 6.1.2.7.4. Description
        • 6.1.2.7.5. Return Value
      • 6.1.2.8. FE_DISHNETWORK_SEND_LEGACY_CMD
        • 6.1.2.8.1. Name
        • 6.1.2.8.2. Synopsis
        • 6.1.2.8.3. Arguments
        • 6.1.2.8.4. Description
        • 6.1.2.8.5. Return Value
  • 6.2. Legacy DVB MPEG Decoder APIs
    • 6.2.1. General Notes
    • 6.2.2. Data Formats
    • 6.2.3. Table of Contents
      • 6.2.3.1. DVB Video Device
        • 6.2.3.1.1. Video Data Types
        • 6.2.3.1.2. Video Function Calls
      • 6.2.3.2. DVB Audio Device
        • 6.2.3.2.1. Audio Data Types
        • 6.2.3.2.2. Audio Function Calls
      • 6.2.3.3. DVB OSD Device
        • 6.2.3.3.1. OSD Data Types
        • 6.2.3.3.2. OSD Function Calls
• 7. Examples
• 8. Digital TV uAPI header files
  • 8.1. Digital TV uAPI headers
    • 8.1.1. frontend.h
    • 8.1.2. dmx.h
    • 8.1.3. ca.h
    • 8.1.4. net.h

Revision and Copyright

Authors:

• 10. 11. Metzler, Ralph <rjkm@metzlerbros.de>

• Original author of the Digital TV API documentation.

• 15. 3. Metzler, Marcus <rjkm@metzlerbros.de>

• Original author of the Digital TV API documentation.

• Carvalho Chehab, Mauro <mchehab+samsung@kernel.org>

• Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix.

Copyright © 2002-2003 : Convergence GmbH

Copyright © 2009-2017 : Mauro Carvalho Chehab

Revision History

revision

2.2.0 / 2017-09-01 (mcc)

Most gaps between the uAPI document and the Kernel implementation got fixed for the non-legacy API.

revision

2.1.0 / 2015-05-29 (mcc)

DocBook improvements and cleanups, in order to document the system calls on a more standard way and provide more description about the current Digital TV API.

revision

2.0.4 / 2011-05-06 (mcc)

Add more information about DVBv5 API, better describing the frontend GET/SET props ioctl’s.

revision

2.0.3 / 2010-07-03 (mcc)

Add some frontend capabilities flags, present on kernel, but missing at the specs.

revision

2.0.2 / 2009-10-25 (mcc)

documents FE_SET_FRONTEND_TUNE_MODE and FE_DISHETWORK_SEND_LEGACY_CMD ioctls.

revision

2.0.1 / 2009-09-16 (mcc)

Added ISDB-T test originally written by Patrick Boettcher

revision

2.0.0 / 2009-09-06 (mcc)

Conversion from LaTex to DocBook XML. The contents is the same as the original LaTex version.

revision

1.0.0 / 2003-07-24 (rjkm)

Initial revision on LaTEX.