xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

media: docs: move uAPI book to userspace-api/media

Browse Source 
Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee38 ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2020-03-04 10:21:39 +01:00
parent 5dfb8db56b
commit 54f38fcae5
464 changed files with 464 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
Documentation/userspace-api/media/Makefile Normal file
View File

@@ -0,0 +1,69 @@
# SPDX-License-Identifier: GPL-2.0
# Rules to convert a .h file to inline RST documentation
SRC_DIR=$(srctree)/Documentation/userspace-api/media
PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
UAPI = $(srctree)/include/uapi/linux
KAPI = $(srctree)/include/linux
FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
gen_rst = \
echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
silent_gen_rst = ${gen_rst}
$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/cec.h.rst: ${UAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions
@$($(quiet)gen_rst)
# Media build rules
.PHONY: all html epub xml latex
all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
html: all
epub: all
xml: all
latex: $(IMGPDF) all
linkcheck:
clean:
-rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
$(BUILDDIR):
$(Q)mkdir -p $@

19
Documentation/userspace-api/media/audio.h.rst.exceptions Normal file
View File

@@ -0,0 +1,19 @@
# SPDX-License-Identifier: GPL-2.0
# Ignore header name
ignore define _DVBAUDIO_H_
# Undocumented audio caps, as this is a deprecated API anyway
ignore define AUDIO_CAP_DTS
ignore define AUDIO_CAP_LPCM
ignore define AUDIO_CAP_MP1
ignore define AUDIO_CAP_MP2
ignore define AUDIO_CAP_MP3
ignore define AUDIO_CAP_AAC
ignore define AUDIO_CAP_OGG
ignore define AUDIO_CAP_SDDS
ignore define AUDIO_CAP_AC3
# some typedefs should point to struct/enums
replace typedef audio_mixer_t :c:type:`audio_mixer`
replace typedef audio_status_t :c:type:`audio_status`

25
Documentation/userspace-api/media/ca.h.rst.exceptions Normal file
View File

@@ -0,0 +1,25 @@
# SPDX-License-Identifier: GPL-2.0
# Ignore header name
ignore define _DVBCA_H_
# struct ca_slot_info defines
replace define CA_CI :c:type:`ca_slot_info`
replace define CA_CI_LINK :c:type:`ca_slot_info`
replace define CA_CI_PHYS :c:type:`ca_slot_info`
replace define CA_DESCR :c:type:`ca_slot_info`
replace define CA_SC :c:type:`ca_slot_info`
replace define CA_CI_MODULE_PRESENT :c:type:`ca_slot_info`
replace define CA_CI_MODULE_READY :c:type:`ca_slot_info`
# struct ca_descr_info defines
replace define CA_ECD :c:type:`ca_descr_info`
replace define CA_NDS :c:type:`ca_descr_info`
replace define CA_DSS :c:type:`ca_descr_info`
# some typedefs should point to struct/enums
replace typedef ca_slot_info_t :c:type:`ca_slot_info`
replace typedef ca_descr_info_t :c:type:`ca_descr_info`
replace typedef ca_caps_t :c:type:`ca_caps`
replace typedef ca_msg_t :c:type:`ca_msg`
replace typedef ca_descr_t :c:type:`ca_descr`

575
Documentation/userspace-api/media/cec.h.rst.exceptions Normal file
View File

@@ -0,0 +1,575 @@
# SPDX-License-Identifier: GPL-2.0
# Ignore header name
ignore define _CEC_UAPI_H
# define macros to ignore
ignore define CEC_MAX_MSG_SIZE
ignore define CEC_MAX_LOG_ADDRS
ignore define CEC_LOG_ADDR_MASK_TV
ignore define CEC_LOG_ADDR_MASK_RECORD
ignore define CEC_LOG_ADDR_MASK_TUNER
ignore define CEC_LOG_ADDR_MASK_PLAYBACK
ignore define CEC_LOG_ADDR_MASK_AUDIOSYSTEM
ignore define CEC_LOG_ADDR_MASK_BACKUP
ignore define CEC_LOG_ADDR_MASK_SPECIFIC
ignore define CEC_LOG_ADDR_MASK_UNREGISTERED
# Shouldn't them be documented?
ignore define CEC_LOG_ADDR_INVALID
ignore define CEC_PHYS_ADDR_INVALID
ignore define CEC_VENDOR_ID_NONE
ignore define CEC_MODE_INITIATOR_MSK
ignore define CEC_MODE_FOLLOWER_MSK
# Part of CEC 2.0 spec - shouldn't be documented too?
ignore define CEC_LOG_ADDR_TV
ignore define CEC_LOG_ADDR_RECORD_1
ignore define CEC_LOG_ADDR_RECORD_2
ignore define CEC_LOG_ADDR_TUNER_1
ignore define CEC_LOG_ADDR_PLAYBACK_1
ignore define CEC_LOG_ADDR_AUDIOSYSTEM
ignore define CEC_LOG_ADDR_TUNER_2
ignore define CEC_LOG_ADDR_TUNER_3
ignore define CEC_LOG_ADDR_PLAYBACK_2
ignore define CEC_LOG_ADDR_RECORD_3
ignore define CEC_LOG_ADDR_TUNER_4
ignore define CEC_LOG_ADDR_PLAYBACK_3
ignore define CEC_LOG_ADDR_BACKUP_1
ignore define CEC_LOG_ADDR_BACKUP_2
ignore define CEC_LOG_ADDR_SPECIFIC
ignore define CEC_LOG_ADDR_UNREGISTERED
ignore define CEC_LOG_ADDR_BROADCAST
# IMHO, those should also be documented
ignore define CEC_MSG_ACTIVE_SOURCE
ignore define CEC_MSG_IMAGE_VIEW_ON
ignore define CEC_MSG_TEXT_VIEW_ON
ignore define CEC_MSG_INACTIVE_SOURCE
ignore define CEC_MSG_REQUEST_ACTIVE_SOURCE
ignore define CEC_MSG_ROUTING_CHANGE
ignore define CEC_MSG_ROUTING_INFORMATION
ignore define CEC_MSG_SET_STREAM_PATH
ignore define CEC_MSG_STANDBY
ignore define CEC_MSG_RECORD_OFF
ignore define CEC_MSG_RECORD_ON
ignore define CEC_OP_RECORD_SRC_OWN
ignore define CEC_OP_RECORD_SRC_DIGITAL
ignore define CEC_OP_RECORD_SRC_ANALOG
ignore define CEC_OP_RECORD_SRC_EXT_PLUG
ignore define CEC_OP_RECORD_SRC_EXT_PHYS_ADDR
ignore define CEC_OP_SERVICE_ID_METHOD_BY_DIG_ID
ignore define CEC_OP_SERVICE_ID_METHOD_BY_CHANNEL
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_BS
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_CS
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_T
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_CABLE
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_SAT
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_T
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_C
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S2
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_T
ignore define CEC_OP_ANA_BCAST_TYPE_CABLE
ignore define CEC_OP_ANA_BCAST_TYPE_SATELLITE
ignore define CEC_OP_ANA_BCAST_TYPE_TERRESTRIAL
ignore define CEC_OP_BCAST_SYSTEM_PAL_BG
ignore define CEC_OP_BCAST_SYSTEM_SECAM_LQ
ignore define CEC_OP_BCAST_SYSTEM_PAL_M
ignore define CEC_OP_BCAST_SYSTEM_NTSC_M
ignore define CEC_OP_BCAST_SYSTEM_PAL_I
ignore define CEC_OP_BCAST_SYSTEM_SECAM_DK
ignore define CEC_OP_BCAST_SYSTEM_SECAM_BG
ignore define CEC_OP_BCAST_SYSTEM_SECAM_L
ignore define CEC_OP_BCAST_SYSTEM_PAL_DK
ignore define CEC_OP_BCAST_SYSTEM_OTHER
ignore define CEC_OP_CHANNEL_NUMBER_FMT_1_PART
ignore define CEC_OP_CHANNEL_NUMBER_FMT_2_PART
ignore define CEC_MSG_RECORD_STATUS
ignore define CEC_OP_RECORD_STATUS_CUR_SRC
ignore define CEC_OP_RECORD_STATUS_DIG_SERVICE
ignore define CEC_OP_RECORD_STATUS_ANA_SERVICE
ignore define CEC_OP_RECORD_STATUS_EXT_INPUT
ignore define CEC_OP_RECORD_STATUS_NO_DIG_SERVICE
ignore define CEC_OP_RECORD_STATUS_NO_ANA_SERVICE
ignore define CEC_OP_RECORD_STATUS_NO_SERVICE
ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PLUG
ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PHYS_ADDR
ignore define CEC_OP_RECORD_STATUS_UNSUP_CA
ignore define CEC_OP_RECORD_STATUS_NO_CA_ENTITLEMENTS
ignore define CEC_OP_RECORD_STATUS_CANT_COPY_SRC
ignore define CEC_OP_RECORD_STATUS_NO_MORE_COPIES
ignore define CEC_OP_RECORD_STATUS_NO_MEDIA
ignore define CEC_OP_RECORD_STATUS_PLAYING
ignore define CEC_OP_RECORD_STATUS_ALREADY_RECORDING
ignore define CEC_OP_RECORD_STATUS_MEDIA_PROT
ignore define CEC_OP_RECORD_STATUS_NO_SIGNAL
ignore define CEC_OP_RECORD_STATUS_MEDIA_PROBLEM
ignore define CEC_OP_RECORD_STATUS_NO_SPACE
ignore define CEC_OP_RECORD_STATUS_PARENTAL_LOCK
ignore define CEC_OP_RECORD_STATUS_TERMINATED_OK
ignore define CEC_OP_RECORD_STATUS_ALREADY_TERM
ignore define CEC_OP_RECORD_STATUS_OTHER
ignore define CEC_MSG_RECORD_TV_SCREEN
ignore define CEC_MSG_CLEAR_ANALOGUE_TIMER
ignore define CEC_OP_REC_SEQ_SUNDAY
ignore define CEC_OP_REC_SEQ_MONDAY
ignore define CEC_OP_REC_SEQ_TUESDAY
ignore define CEC_OP_REC_SEQ_WEDNESDAY
ignore define CEC_OP_REC_SEQ_THURSDAY
ignore define CEC_OP_REC_SEQ_FRIDAY
ignore define CEC_OP_REC_SEQ_SATERDAY
ignore define CEC_OP_REC_SEQ_ONCE_ONLY
ignore define CEC_MSG_CLEAR_DIGITAL_TIMER
ignore define CEC_MSG_CLEAR_EXT_TIMER
ignore define CEC_OP_EXT_SRC_PLUG
ignore define CEC_OP_EXT_SRC_PHYS_ADDR
ignore define CEC_MSG_SET_ANALOGUE_TIMER
ignore define CEC_MSG_SET_DIGITAL_TIMER
ignore define CEC_MSG_SET_EXT_TIMER
ignore define CEC_MSG_SET_TIMER_PROGRAM_TITLE
ignore define CEC_MSG_TIMER_CLEARED_STATUS
ignore define CEC_OP_TIMER_CLR_STAT_RECORDING
ignore define CEC_OP_TIMER_CLR_STAT_NO_MATCHING
ignore define CEC_OP_TIMER_CLR_STAT_NO_INFO
ignore define CEC_OP_TIMER_CLR_STAT_CLEARED
ignore define CEC_MSG_TIMER_STATUS
ignore define CEC_OP_TIMER_OVERLAP_WARNING_NO_OVERLAP
ignore define CEC_OP_TIMER_OVERLAP_WARNING_OVERLAP
ignore define CEC_OP_MEDIA_INFO_UNPROT_MEDIA
ignore define CEC_OP_MEDIA_INFO_PROT_MEDIA
ignore define CEC_OP_MEDIA_INFO_NO_MEDIA
ignore define CEC_OP_PROG_IND_NOT_PROGRAMMED
ignore define CEC_OP_PROG_IND_PROGRAMMED
ignore define CEC_OP_PROG_INFO_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_NOT_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_MIGHT_NOT_BE_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_NONE_AVAILABLE
ignore define CEC_OP_PROG_ERROR_NO_FREE_TIMER
ignore define CEC_OP_PROG_ERROR_DATE_OUT_OF_RANGE
ignore define CEC_OP_PROG_ERROR_REC_SEQ_ERROR
ignore define CEC_OP_PROG_ERROR_INV_EXT_PLUG
ignore define CEC_OP_PROG_ERROR_INV_EXT_PHYS_ADDR
ignore define CEC_OP_PROG_ERROR_CA_UNSUPP
ignore define CEC_OP_PROG_ERROR_INSUF_CA_ENTITLEMENTS
ignore define CEC_OP_PROG_ERROR_RESOLUTION_UNSUPP
ignore define CEC_OP_PROG_ERROR_PARENTAL_LOCK
ignore define CEC_OP_PROG_ERROR_CLOCK_FAILURE
ignore define CEC_OP_PROG_ERROR_DUPLICATE
ignore define CEC_MSG_CEC_VERSION
ignore define CEC_OP_CEC_VERSION_1_3A
ignore define CEC_OP_CEC_VERSION_1_4
ignore define CEC_OP_CEC_VERSION_2_0
ignore define CEC_MSG_GET_CEC_VERSION
ignore define CEC_MSG_GIVE_PHYSICAL_ADDR
ignore define CEC_MSG_GET_MENU_LANGUAGE
ignore define CEC_MSG_REPORT_PHYSICAL_ADDR
ignore define CEC_OP_PRIM_DEVTYPE_TV
ignore define CEC_OP_PRIM_DEVTYPE_RECORD
ignore define CEC_OP_PRIM_DEVTYPE_TUNER
ignore define CEC_OP_PRIM_DEVTYPE_PLAYBACK
ignore define CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM
ignore define CEC_OP_PRIM_DEVTYPE_SWITCH
ignore define CEC_OP_PRIM_DEVTYPE_PROCESSOR
ignore define CEC_MSG_SET_MENU_LANGUAGE
ignore define CEC_MSG_REPORT_FEATURES
ignore define CEC_OP_ALL_DEVTYPE_TV
ignore define CEC_OP_ALL_DEVTYPE_RECORD
ignore define CEC_OP_ALL_DEVTYPE_TUNER
ignore define CEC_OP_ALL_DEVTYPE_PLAYBACK
ignore define CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM
ignore define CEC_OP_ALL_DEVTYPE_SWITCH
ignore define CEC_OP_FEAT_EXT
ignore define CEC_OP_FEAT_RC_TV_PROFILE_NONE
ignore define CEC_OP_FEAT_RC_TV_PROFILE_1
ignore define CEC_OP_FEAT_RC_TV_PROFILE_2
ignore define CEC_OP_FEAT_RC_TV_PROFILE_3
ignore define CEC_OP_FEAT_RC_TV_PROFILE_4
ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_ROOT_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_SETUP_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_CONTENTS_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_TOP_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_CONTEXT_MENU
ignore define CEC_OP_FEAT_DEV_HAS_RECORD_TV_SCREEN
ignore define CEC_OP_FEAT_DEV_HAS_SET_OSD_STRING
ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL
ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE
ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX
ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX
ignore define CEC_MSG_GIVE_FEATURES
ignore define CEC_MSG_DECK_CONTROL
ignore define CEC_OP_DECK_CTL_MODE_SKIP_FWD
ignore define CEC_OP_DECK_CTL_MODE_SKIP_REV
ignore define CEC_OP_DECK_CTL_MODE_STOP
ignore define CEC_OP_DECK_CTL_MODE_EJECT
ignore define CEC_MSG_DECK_STATUS
ignore define CEC_OP_DECK_INFO_PLAY
ignore define CEC_OP_DECK_INFO_RECORD
ignore define CEC_OP_DECK_INFO_PLAY_REV
ignore define CEC_OP_DECK_INFO_STILL
ignore define CEC_OP_DECK_INFO_SLOW
ignore define CEC_OP_DECK_INFO_SLOW_REV
ignore define CEC_OP_DECK_INFO_FAST_FWD
ignore define CEC_OP_DECK_INFO_FAST_REV
ignore define CEC_OP_DECK_INFO_NO_MEDIA
ignore define CEC_OP_DECK_INFO_STOP
ignore define CEC_OP_DECK_INFO_SKIP_FWD
ignore define CEC_OP_DECK_INFO_SKIP_REV
ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_FWD
ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_REV
ignore define CEC_OP_DECK_INFO_OTHER
ignore define CEC_MSG_GIVE_DECK_STATUS
ignore define CEC_OP_STATUS_REQ_ON
ignore define CEC_OP_STATUS_REQ_OFF
ignore define CEC_OP_STATUS_REQ_ONCE
ignore define CEC_MSG_PLAY
ignore define CEC_OP_PLAY_MODE_PLAY_FWD
ignore define CEC_OP_PLAY_MODE_PLAY_REV
ignore define CEC_OP_PLAY_MODE_PLAY_STILL
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MED
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MED
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MED
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MED
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MAX
ignore define CEC_MSG_GIVE_TUNER_DEVICE_STATUS
ignore define CEC_MSG_SELECT_ANALOGUE_SERVICE
ignore define CEC_MSG_SELECT_DIGITAL_SERVICE
ignore define CEC_MSG_TUNER_DEVICE_STATUS
ignore define CEC_OP_REC_FLAG_USED
ignore define CEC_OP_REC_FLAG_NOT_USED
ignore define CEC_OP_TUNER_DISPLAY_INFO_DIGITAL
ignore define CEC_OP_TUNER_DISPLAY_INFO_NONE
ignore define CEC_OP_TUNER_DISPLAY_INFO_ANALOGUE
ignore define CEC_MSG_TUNER_STEP_DECREMENT
ignore define CEC_MSG_TUNER_STEP_INCREMENT
ignore define CEC_MSG_DEVICE_VENDOR_ID
ignore define CEC_MSG_GIVE_DEVICE_VENDOR_ID
ignore define CEC_MSG_VENDOR_COMMAND
ignore define CEC_MSG_VENDOR_COMMAND_WITH_ID
ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_DOWN
ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_UP
ignore define CEC_MSG_SET_OSD_STRING
ignore define CEC_OP_DISP_CTL_DEFAULT
ignore define CEC_OP_DISP_CTL_UNTIL_CLEARED
ignore define CEC_OP_DISP_CTL_CLEAR
ignore define CEC_MSG_GIVE_OSD_NAME
ignore define CEC_MSG_SET_OSD_NAME
ignore define CEC_MSG_MENU_REQUEST
ignore define CEC_OP_MENU_REQUEST_ACTIVATE
ignore define CEC_OP_MENU_REQUEST_DEACTIVATE
ignore define CEC_OP_MENU_REQUEST_QUERY
ignore define CEC_MSG_MENU_STATUS
ignore define CEC_OP_MENU_STATE_ACTIVATED
ignore define CEC_OP_MENU_STATE_DEACTIVATED
ignore define CEC_MSG_USER_CONTROL_PRESSED
ignore define CEC_OP_UI_CMD_SELECT
ignore define CEC_OP_UI_CMD_UP
ignore define CEC_OP_UI_CMD_DOWN
ignore define CEC_OP_UI_CMD_LEFT
ignore define CEC_OP_UI_CMD_RIGHT
ignore define CEC_OP_UI_CMD_RIGHT_UP
ignore define CEC_OP_UI_CMD_RIGHT_DOWN
ignore define CEC_OP_UI_CMD_LEFT_UP
ignore define CEC_OP_UI_CMD_LEFT_DOWN
ignore define CEC_OP_UI_CMD_DEVICE_ROOT_MENU
ignore define CEC_OP_UI_CMD_DEVICE_SETUP_MENU
ignore define CEC_OP_UI_CMD_CONTENTS_MENU
ignore define CEC_OP_UI_CMD_FAVORITE_MENU
ignore define CEC_OP_UI_CMD_BACK
ignore define CEC_OP_UI_CMD_MEDIA_TOP_MENU
ignore define CEC_OP_UI_CMD_MEDIA_CONTEXT_SENSITIVE_MENU
ignore define CEC_OP_UI_CMD_NUMBER_ENTRY_MODE
ignore define CEC_OP_UI_CMD_NUMBER_11
ignore define CEC_OP_UI_CMD_NUMBER_12
ignore define CEC_OP_UI_CMD_NUMBER_0_OR_NUMBER_10
ignore define CEC_OP_UI_CMD_NUMBER_1
ignore define CEC_OP_UI_CMD_NUMBER_2
ignore define CEC_OP_UI_CMD_NUMBER_3
ignore define CEC_OP_UI_CMD_NUMBER_4
ignore define CEC_OP_UI_CMD_NUMBER_5
ignore define CEC_OP_UI_CMD_NUMBER_6
ignore define CEC_OP_UI_CMD_NUMBER_7
ignore define CEC_OP_UI_CMD_NUMBER_8
ignore define CEC_OP_UI_CMD_NUMBER_9
ignore define CEC_OP_UI_CMD_DOT
ignore define CEC_OP_UI_CMD_ENTER
ignore define CEC_OP_UI_CMD_CLEAR
ignore define CEC_OP_UI_CMD_NEXT_FAVORITE
ignore define CEC_OP_UI_CMD_CHANNEL_UP
ignore define CEC_OP_UI_CMD_CHANNEL_DOWN
ignore define CEC_OP_UI_CMD_PREVIOUS_CHANNEL
ignore define CEC_OP_UI_CMD_SOUND_SELECT
ignore define CEC_OP_UI_CMD_INPUT_SELECT
ignore define CEC_OP_UI_CMD_DISPLAY_INFORMATION
ignore define CEC_OP_UI_CMD_HELP
ignore define CEC_OP_UI_CMD_PAGE_UP
ignore define CEC_OP_UI_CMD_PAGE_DOWN
ignore define CEC_OP_UI_CMD_POWER
ignore define CEC_OP_UI_CMD_VOLUME_UP
ignore define CEC_OP_UI_CMD_VOLUME_DOWN
ignore define CEC_OP_UI_CMD_MUTE
ignore define CEC_OP_UI_CMD_PLAY
ignore define CEC_OP_UI_CMD_STOP
ignore define CEC_OP_UI_CMD_PAUSE
ignore define CEC_OP_UI_CMD_RECORD
ignore define CEC_OP_UI_CMD_REWIND
ignore define CEC_OP_UI_CMD_FAST_FORWARD
ignore define CEC_OP_UI_CMD_EJECT
ignore define CEC_OP_UI_CMD_SKIP_FORWARD
ignore define CEC_OP_UI_CMD_SKIP_BACKWARD
ignore define CEC_OP_UI_CMD_STOP_RECORD
ignore define CEC_OP_UI_CMD_PAUSE_RECORD
ignore define CEC_OP_UI_CMD_ANGLE
ignore define CEC_OP_UI_CMD_SUB_PICTURE
ignore define CEC_OP_UI_CMD_VIDEO_ON_DEMAND
ignore define CEC_OP_UI_CMD_ELECTRONIC_PROGRAM_GUIDE
ignore define CEC_OP_UI_CMD_TIMER_PROGRAMMING
ignore define CEC_OP_UI_CMD_INITIAL_CONFIGURATION
ignore define CEC_OP_UI_CMD_SELECT_BROADCAST_TYPE
ignore define CEC_OP_UI_CMD_SELECT_SOUND_PRESENTATION
ignore define CEC_OP_UI_CMD_AUDIO_DESCRIPTION
ignore define CEC_OP_UI_CMD_INTERNET
ignore define CEC_OP_UI_CMD_3D_MODE
ignore define CEC_OP_UI_CMD_PLAY_FUNCTION
ignore define CEC_OP_UI_CMD_PAUSE_PLAY_FUNCTION
ignore define CEC_OP_UI_CMD_RECORD_FUNCTION
ignore define CEC_OP_UI_CMD_PAUSE_RECORD_FUNCTION
ignore define CEC_OP_UI_CMD_STOP_FUNCTION
ignore define CEC_OP_UI_CMD_MUTE_FUNCTION
ignore define CEC_OP_UI_CMD_RESTORE_VOLUME_FUNCTION
ignore define CEC_OP_UI_CMD_TUNE_FUNCTION
ignore define CEC_OP_UI_CMD_SELECT_MEDIA_FUNCTION
ignore define CEC_OP_UI_CMD_SELECT_AV_INPUT_FUNCTION
ignore define CEC_OP_UI_CMD_SELECT_AUDIO_INPUT_FUNCTION
ignore define CEC_OP_UI_CMD_POWER_TOGGLE_FUNCTION
ignore define CEC_OP_UI_CMD_POWER_OFF_FUNCTION
ignore define CEC_OP_UI_CMD_POWER_ON_FUNCTION
ignore define CEC_OP_UI_CMD_F1_BLUE
ignore define CEC_OP_UI_CMD_F2_RED
ignore define CEC_OP_UI_CMD_F3_GREEN
ignore define CEC_OP_UI_CMD_F4_YELLOW
ignore define CEC_OP_UI_CMD_F5
ignore define CEC_OP_UI_CMD_DATA
ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_ALL
ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_DIG_ANA
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_T
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_CABLE
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_T
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_CABLE
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT2
ignore define CEC_OP_UI_BCAST_TYPE_IP
ignore define CEC_OP_UI_SND_PRES_CTL_DUAL_MONO
ignore define CEC_OP_UI_SND_PRES_CTL_KARAOKE
ignore define CEC_OP_UI_SND_PRES_CTL_DOWNMIX
ignore define CEC_OP_UI_SND_PRES_CTL_REVERB
ignore define CEC_OP_UI_SND_PRES_CTL_EQUALIZER
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_UP
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_NEUTRAL
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_DOWN
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_UP
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_NEUTRAL
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_DOWN
ignore define CEC_MSG_USER_CONTROL_RELEASED
ignore define CEC_MSG_GIVE_DEVICE_POWER_STATUS
ignore define CEC_MSG_REPORT_POWER_STATUS
ignore define CEC_OP_POWER_STATUS_ON
ignore define CEC_OP_POWER_STATUS_STANDBY
ignore define CEC_OP_POWER_STATUS_TO_ON
ignore define CEC_OP_POWER_STATUS_TO_STANDBY
ignore define CEC_MSG_FEATURE_ABORT
ignore define CEC_OP_ABORT_UNRECOGNIZED_OP
ignore define CEC_OP_ABORT_INCORRECT_MODE
ignore define CEC_OP_ABORT_NO_SOURCE
ignore define CEC_OP_ABORT_INVALID_OP
ignore define CEC_OP_ABORT_REFUSED
ignore define CEC_OP_ABORT_UNDETERMINED
ignore define CEC_MSG_ABORT
ignore define CEC_MSG_GIVE_AUDIO_STATUS
ignore define CEC_MSG_GIVE_SYSTEM_AUDIO_MODE_STATUS
ignore define CEC_MSG_REPORT_AUDIO_STATUS
ignore define CEC_OP_AUD_MUTE_STATUS_OFF
ignore define CEC_OP_AUD_MUTE_STATUS_ON
ignore define CEC_MSG_REPORT_SHORT_AUDIO_DESCRIPTOR
ignore define CEC_MSG_REQUEST_SHORT_AUDIO_DESCRIPTOR
ignore define CEC_MSG_SET_SYSTEM_AUDIO_MODE
ignore define CEC_OP_SYS_AUD_STATUS_OFF
ignore define CEC_OP_SYS_AUD_STATUS_ON
ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST
ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS
ignore define CEC_OP_AUD_FMT_ID_CEA861
ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT
ignore define CEC_MSG_SET_AUDIO_RATE
ignore define CEC_OP_AUD_RATE_OFF
ignore define CEC_OP_AUD_RATE_WIDE_STD
ignore define CEC_OP_AUD_RATE_WIDE_FAST
ignore define CEC_OP_AUD_RATE_WIDE_SLOW
ignore define CEC_OP_AUD_RATE_NARROW_STD
ignore define CEC_OP_AUD_RATE_NARROW_FAST
ignore define CEC_OP_AUD_RATE_NARROW_SLOW
ignore define CEC_MSG_INITIATE_ARC
ignore define CEC_MSG_REPORT_ARC_INITIATED
ignore define CEC_MSG_REPORT_ARC_TERMINATED
ignore define CEC_MSG_REQUEST_ARC_INITIATION
ignore define CEC_MSG_REQUEST_ARC_TERMINATION
ignore define CEC_MSG_TERMINATE_ARC
ignore define CEC_MSG_REQUEST_CURRENT_LATENCY
ignore define CEC_MSG_REPORT_CURRENT_LATENCY
ignore define CEC_OP_LOW_LATENCY_MODE_OFF
ignore define CEC_OP_LOW_LATENCY_MODE_ON
ignore define CEC_OP_AUD_OUT_COMPENSATED_NA
ignore define CEC_OP_AUD_OUT_COMPENSATED_DELAY
ignore define CEC_OP_AUD_OUT_COMPENSATED_NO_DELAY
ignore define CEC_OP_AUD_OUT_COMPENSATED_PARTIAL_DELAY
ignore define CEC_MSG_CDC_MESSAGE
ignore define CEC_MSG_CDC_HEC_INQUIRE_STATE
ignore define CEC_MSG_CDC_HEC_REPORT_STATE
ignore define CEC_OP_HEC_FUNC_STATE_NOT_SUPPORTED
ignore define CEC_OP_HEC_FUNC_STATE_INACTIVE
ignore define CEC_OP_HEC_FUNC_STATE_ACTIVE
ignore define CEC_OP_HEC_FUNC_STATE_ACTIVATION_FIELD
ignore define CEC_OP_HOST_FUNC_STATE_NOT_SUPPORTED
ignore define CEC_OP_HOST_FUNC_STATE_INACTIVE
ignore define CEC_OP_HOST_FUNC_STATE_ACTIVE
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_NOT_SUPPORTED
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_INACTIVE
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_ACTIVE
ignore define CEC_OP_CDC_ERROR_CODE_NONE
ignore define CEC_OP_CDC_ERROR_CODE_CAP_UNSUPPORTED
ignore define CEC_OP_CDC_ERROR_CODE_WRONG_STATE
ignore define CEC_OP_CDC_ERROR_CODE_OTHER
ignore define CEC_OP_HEC_SUPPORT_NO
ignore define CEC_OP_HEC_SUPPORT_YES
ignore define CEC_OP_HEC_ACTIVATION_ON
ignore define CEC_OP_HEC_ACTIVATION_OFF
ignore define CEC_MSG_CDC_HEC_SET_STATE_ADJACENT
ignore define CEC_MSG_CDC_HEC_SET_STATE
ignore define CEC_OP_HEC_SET_STATE_DEACTIVATE
ignore define CEC_OP_HEC_SET_STATE_ACTIVATE
ignore define CEC_MSG_CDC_HEC_REQUEST_DEACTIVATION
ignore define CEC_MSG_CDC_HEC_NOTIFY_ALIVE
ignore define CEC_MSG_CDC_HEC_DISCOVER
ignore define CEC_MSG_CDC_HPD_SET_STATE
ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE
ignore define CEC_OP_HPD_STATE_CP_EDID_ENABLE
ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE_ENABLE
ignore define CEC_OP_HPD_STATE_EDID_DISABLE
ignore define CEC_OP_HPD_STATE_EDID_ENABLE
ignore define CEC_OP_HPD_STATE_EDID_DISABLE_ENABLE
ignore define CEC_MSG_CDC_HPD_REPORT_STATE
ignore define CEC_OP_HPD_ERROR_NONE
ignore define CEC_OP_HPD_ERROR_INITIATOR_NOT_CAPABLE
ignore define CEC_OP_HPD_ERROR_INITIATOR_WRONG_STATE
ignore define CEC_OP_HPD_ERROR_OTHER
ignore define CEC_OP_HPD_ERROR_NONE_NO_VIDEO

54
Documentation/userspace-api/media/cec/cec-api.rst Normal file
View File

@@ -0,0 +1,54 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. include:: <isonum.txt>
.. _cec:
#########################################
Part V - Consumer Electronics Control API
#########################################
This part describes the CEC: Consumer Electronics Control
.. only:: html
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
cec-intro
cec-funcs
cec-pin-error-inj
cec-header
**********************
Revision and Copyright
**********************
Authors:
- Verkuil, Hans <hverkuil-cisco@xs4all.nl>
- Initial version.
**Copyright** |copy| 2016 : Hans Verkuil
****************
Revision History
****************
:revision: 1.0.0 / 2016-03-17 (*hv*)
Initial revision

54
Documentation/userspace-api/media/cec/cec-func-close.rst Normal file
View File

@@ -0,0 +1,54 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-func-close:
***********
cec close()
***********
Name
====
cec-close - Close a cec device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: int close( int fd )
:name: cec-close
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
Description
===========
Closes the cec device. Resources associated with the file descriptor are
freed. The device configuration remain unchanged.
Return Value
============
:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
``EBADF``
``fd`` is not a valid open file descriptor.

73
Documentation/userspace-api/media/cec/cec-func-ioctl.rst Normal file
View File

@@ -0,0 +1,73 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-func-ioctl:
***********
cec ioctl()
***********
Name
====
cec-ioctl - Control a cec device
Synopsis
========
.. code-block:: c
#include <sys/ioctl.h>
.. c:function:: int ioctl( int fd, int request, void *argp )
:name: cec-ioctl
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``request``
CEC ioctl request code as defined in the cec.h header file, for
example :ref:`CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`.
``argp``
Pointer to a request-specific structure.
Description
===========
The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The
argument ``fd`` must be an open file descriptor.
The ioctl ``request`` code specifies the cec function to be called. It
has encoded in it whether the argument is an input, output or read/write
parameter, and the size of the argument ``argp`` in bytes.
Macros and structures definitions specifying cec ioctl requests and
their parameters are located in the cec.h header file. All cec ioctl
requests, their respective function and parameters are specified in
:ref:`cec-user-func`.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
Request-specific error codes are listed in the individual requests
descriptions.
When an ioctl that takes an output or read/write parameter fails, the
parameter remains unmodified.

85
Documentation/userspace-api/media/cec/cec-func-open.rst Normal file
View File

@@ -0,0 +1,85 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-func-open:
**********
cec open()
**********
Name
====
cec-open - Open a cec device
Synopsis
========
.. code-block:: c
#include <fcntl.h>
.. c:function:: int open( const char *device_name, int flags )
:name: cec-open
Arguments
=========
``device_name``
Device to be opened.
``flags``
Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the
:ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
:ref:`CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
all return 0.
Other flags have no effect.
Description
===========
To open a cec device applications call :c:func:`open() <cec-open>` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
Return Value
============
:c:func:`open() <cec-open>` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
include:
``EACCES``
The requested access to the file is not allowed.
``EMFILE``
The process already has the maximum number of files open.
``ENFILE``
The system limit on the total number of open files has been reached.
``ENOMEM``
Insufficient kernel memory was available.
``ENXIO``
No device corresponding to this device special file exists.

85
Documentation/userspace-api/media/cec/cec-func-poll.rst Normal file
View File

@@ -0,0 +1,85 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-func-poll:
**********
cec poll()
**********
Name
====
cec-poll - Wait for some event on a file descriptor
Synopsis
========
.. code-block:: c
#include <sys/poll.h>
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
:name: cec-poll
Arguments
=========
``ufds``
List of FD events to be watched
``nfds``
Number of FD events at the \*ufds array
``timeout``
Timeout to wait for events
Description
===========
With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
events.
On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
For more details see the :c:func:`poll() <cec-poll>` manual page.
Return Value
============
On success, :c:func:`poll() <cec-poll>` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
``EBADF``
One or more of the ``ufds`` members specify an invalid file
descriptor.
``EFAULT``
``ufds`` references an inaccessible memory area.
``EINTR``
The call was interrupted by a signal.
``EINVAL``
The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
``getrlimit()`` to obtain this value.

30
Documentation/userspace-api/media/cec/cec-funcs.rst Normal file
View File

@@ -0,0 +1,30 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-user-func:
******************
Function Reference
******************
.. toctree::
:maxdepth: 1
cec-func-open
cec-func-close
cec-func-ioctl
cec-func-poll
cec-ioc-adap-g-caps
cec-ioc-adap-g-log-addrs
cec-ioc-adap-g-phys-addr
cec-ioc-adap-g-conn-info
cec-ioc-dqevent
cec-ioc-g-mode
cec-ioc-receive

17
Documentation/userspace-api/media/cec/cec-header.rst Normal file
View File

@@ -0,0 +1,17 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec_header:
***************
CEC Header File
***************
.. kernel-include:: $BUILDDIR/cec.h.rst

49
Documentation/userspace-api/media/cec/cec-intro.rst Normal file
View File

@@ -0,0 +1,49 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _cec-intro:
Introduction
============
HDMI connectors provide a single pin for use by the Consumer Electronics
Control protocol. This protocol allows different devices connected by an
HDMI cable to communicate. The protocol for CEC version 1.4 is defined
in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return
Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the
extensions added to CEC version 2.0 are defined in chapter 11 of the
HDMI 2.0 (:ref:`hdmi2`) specification.
The bitrate is very slow (effectively no more than 36 bytes per second)
and is based on the ancient AV.link protocol used in old SCART
connectors. The protocol closely resembles a crazy Rube Goldberg
contraption and is an unholy mix of low and high level messages. Some
messages, especially those part of the HEAC protocol layered on top of
CEC, need to be handled by the kernel, others can be handled either by
the kernel or by userspace.
In addition, CEC can be implemented in HDMI receivers, transmitters and
in USB devices that have an HDMI input and an HDMI output and that
control just the CEC pin.
Drivers that support CEC will create a CEC device node (/dev/cecX) to
give userspace access to the CEC adapter. The
:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do.
In order to check the support and test it, it is suggested to download
the `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ package. It
provides three tools to handle CEC:
- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit
and monitor CEC messages.
- cec-compliance: does a CEC compliance test of a remote CEC device to
determine how compliant the CEC implementation is.
- cec-follower: emulates a CEC follower.

150
Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst Normal file
View File

@@ -0,0 +1,150 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_ADAP_G_CAPS:
*********************
ioctl CEC_ADAP_G_CAPS
*********************
Name
====
CEC_ADAP_G_CAPS - Query device capabilities
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
:name: CEC_ADAP_G_CAPS
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Description
===========
All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
device information, applications call the ioctl with a pointer to a
struct :c:type:`cec_caps`. The driver fills the structure and
returns the information to the application. The ioctl never fails.
.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}|
.. c:type:: cec_caps
.. flat-table:: struct cec_caps
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - char
- ``driver[32]``
- The name of the cec adapter driver.
* - char
- ``name[32]``
- The name of this CEC adapter. The combination ``driver`` and
``name`` must be unique.
* - __u32
- ``capabilities``
- The capabilities of the CEC adapter, see
:ref:`cec-capabilities`.
* - __u32
- ``version``
- CEC Framework API version, formatted with the ``KERNEL_VERSION()``
macro.
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. _cec-capabilities:
.. flat-table:: CEC Capabilities Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-CAP-PHYS-ADDR`:
- ``CEC_CAP_PHYS_ADDR``
- 0x00000001
- Userspace has to configure the physical address by calling
:ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`. If
this capability isn't set, then setting the physical address is
handled by the kernel whenever the EDID is set (for an HDMI
receiver) or read (for an HDMI transmitter).
* .. _`CEC-CAP-LOG-ADDRS`:
- ``CEC_CAP_LOG_ADDRS``
- 0x00000002
- Userspace has to configure the logical addresses by calling
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. If
this capability isn't set, then the kernel will have configured
this.
* .. _`CEC-CAP-TRANSMIT`:
- ``CEC_CAP_TRANSMIT``
- 0x00000004
- Userspace can transmit CEC messages by calling
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. This implies that
userspace can be a follower as well, since being able to transmit
messages is a prerequisite of becoming a follower. If this
capability isn't set, then the kernel will handle all CEC
transmits and process all CEC messages it receives.
* .. _`CEC-CAP-PASSTHROUGH`:
- ``CEC_CAP_PASSTHROUGH``
- 0x00000008
- Userspace can use the passthrough mode by calling
:ref:`ioctl CEC_S_MODE <CEC_S_MODE>`.
* .. _`CEC-CAP-RC`:
- ``CEC_CAP_RC``
- 0x00000010
- This adapter supports the remote control protocol.
* .. _`CEC-CAP-MONITOR-ALL`:
- ``CEC_CAP_MONITOR_ALL``
- 0x00000020
- The CEC hardware can monitor all messages, not just directed and
broadcast messages.
* .. _`CEC-CAP-NEEDS-HPD`:
- ``CEC_CAP_NEEDS_HPD``
- 0x00000040
- The CEC hardware is only active if the HDMI Hotplug Detect pin is
high. This makes it impossible to use CEC to wake up displays that
set the HPD pin low when in standby mode, but keep the CEC bus
alive.
* .. _`CEC-CAP-MONITOR-PIN`:
- ``CEC_CAP_MONITOR_PIN``
- 0x00000080
- The CEC hardware can monitor CEC pin changes from low to high voltage
and vice versa. When in pin monitoring mode the application will
receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events.
* .. _`CEC-CAP-CONNECTOR-INFO`:
- ``CEC_CAP_CONNECTOR_INFO``
- 0x00000100
- If this capability is set, then :ref:`CEC_ADAP_G_CONNECTOR_INFO` can
be used.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

105
Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst Normal file
View File

@@ -0,0 +1,105 @@
.. SPDX-License-Identifier: GPL-2.0
..
.. Copyright 2019 Google LLC
..
.. _CEC_ADAP_G_CONNECTOR_INFO:
*******************************
ioctl CEC_ADAP_G_CONNECTOR_INFO
*******************************
Name
====
CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp )
:name: CEC_ADAP_G_CONNECTOR_INFO
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Description
===========
Using this ioctl an application can learn which HDMI connector this CEC
device corresponds to. While calling this ioctl the application should
provide a pointer to a cec_connector_info struct which will be populated
by the kernel with the info provided by the adapter's driver. This ioctl
is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set.
.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
.. c:type:: cec_connector_info
.. flat-table:: struct cec_connector_info
:header-rows: 0
:stub-columns: 0
:widths: 1 1 8
* - __u32
- ``type``
- The type of connector this adapter is associated with.
* - union {
- ``(anonymous)``
* - ``struct cec_drm_connector_info``
- drm
- :ref:`cec-drm-connector-info`
* - }
-
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. _connector-type:
.. flat-table:: Connector types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-CONNECTOR-TYPE-NO-CONNECTOR`:
- ``CEC_CONNECTOR_TYPE_NO_CONNECTOR``
- 0
- No connector is associated with the adapter/the information is not
provided by the driver.
* .. _`CEC-CONNECTOR-TYPE-DRM`:
- ``CEC_CONNECTOR_TYPE_DRM``
- 1
- Indicates that a DRM connector is associated with this adapter.
Information about the connector can be found in
:ref:`cec-drm-connector-info`.
.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
.. c:type:: cec_drm_connector_info
.. _cec-drm-connector-info:
.. flat-table:: struct cec_drm_connector_info
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-DRM-CONNECTOR-TYPE-CARD-NO`:
- __u32
- ``card_no``
- DRM card number: the number from a card's path, e.g. 0 in case of
/dev/card0.
* .. _`CEC-DRM-CONNECTOR-TYPE-CONNECTOR_ID`:
- __u32
- ``connector_id``
- DRM connector ID.

378
Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst Normal file
View File

@@ -0,0 +1,378 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_ADAP_LOG_ADDRS:
.. _CEC_ADAP_G_LOG_ADDRS:
.. _CEC_ADAP_S_LOG_ADDRS:
****************************************************
ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
****************************************************
Name
====
CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
:name: CEC_ADAP_G_LOG_ADDRS
.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
:name: CEC_ADAP_S_LOG_ADDRS
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to struct :c:type:`cec_log_addrs`.
Description
===========
To query the current CEC logical addresses, applications call
:ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
struct :c:type:`cec_log_addrs` where the driver stores the logical addresses.
To set new logical addresses, applications fill in
struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
will be ignored in that case. The adapter will go to the unconfigured state and the
``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default
values (CEC version 2.0, no vendor ID and an empty OSD name).
If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
then this ioctl will block until all requested logical
addresses have been claimed. If the file descriptor is in non-blocking mode then it will
not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
logical addresses are claimed or cleared.
Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
logical address types are already defined will return with error ``EBUSY``.
.. c:type:: cec_log_addrs
.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}|
.. cssclass:: longtable
.. flat-table:: struct cec_log_addrs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u8
- ``log_addr[CEC_MAX_LOG_ADDRS]``
- The actual logical addresses that were claimed. This is set by the
driver. If no logical address could be claimed, then it is set to
``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
``log_addr[0]`` is set to 0xf and all others to
``CEC_LOG_ADDR_INVALID``.
* - __u16
- ``log_addr_mask``
- The bitmask of all logical addresses this adapter has claimed. If
this adapter is Unregistered then ``log_addr_mask`` sets bit 15
and clears all other bits. If this adapter is not configured at
all, then ``log_addr_mask`` is set to 0. Set by the driver.
* - __u8
- ``cec_version``
- The CEC version that this adapter shall use. See
:ref:`cec-versions`. Used to implement the
``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
framework.
* - __u8
- ``num_log_addrs``
- Number of logical addresses to set up. Must be ≤
``available_log_addrs`` as returned by
:ref:`CEC_ADAP_G_CAPS`. All arrays in
this structure are only filled up to index
``available_log_addrs``-1. The remaining array elements will be
ignored. Note that the CEC 2.0 standard allows for a maximum of 2
logical addresses, although some hardware has support for more.
``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
number of logical addresses it could claim, which may be less than
what was requested. If this field is set to 0, then the CEC
adapter shall clear all claimed logical addresses and all other
fields will be ignored.
* - __u32
- ``vendor_id``
- The vendor ID is a 24-bit number that identifies the specific
vendor or entity. Based on this ID vendor specific commands may be
defined. If you do not want a vendor ID then set it to
``CEC_VENDOR_ID_NONE``.
* - __u32
- ``flags``
- Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.
* - char
- ``osd_name[15]``
- The On-Screen Display name as is returned by the
``CEC_MSG_SET_OSD_NAME`` message.
* - __u8
- ``primary_device_type[CEC_MAX_LOG_ADDRS]``
- Primary device type for each logical address. See
:ref:`cec-prim-dev-types` for possible types.
* - __u8
- ``log_addr_type[CEC_MAX_LOG_ADDRS]``
- Logical address types. See :ref:`cec-log-addr-types` for
possible types. The driver will update this with the actual
logical address type that it claimed (e.g. it may have to fallback
to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
* - __u8
- ``all_device_types[CEC_MAX_LOG_ADDRS]``
- CEC 2.0 specific: the bit mask of all device types. See
:ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
this field to 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
* - __u8
- ``features[CEC_MAX_LOG_ADDRS][12]``
- Features for each logical address. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
RC Profile and the Device Features. For CEC 1.4 you can either leave
this field to all 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-log-addrs-flags:
.. flat-table:: Flags for struct cec_log_addrs
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:
- ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``
- 1
- By default if no logical address of the requested type can be claimed, then
it will go back to the unconfigured state. If this flag is set, then it will
fallback to the Unregistered logical address. Note that if the Unregistered
logical address was explicitly requested, then this flag has no effect.
* .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`:
- ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU``
- 2
- By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED``
messages are only passed on to the follower(s), if any. If this flag is set,
then these messages are also passed on to the remote control input subsystem
and will appear as keystrokes. This features needs to be enabled explicitly.
If CEC is used to enter e.g. passwords, then you may not want to enable this
to avoid trivial snooping of the keystrokes.
* .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`:
- ``CEC_LOG_ADDRS_FL_CDC_ONLY``
- 4
- If this flag is set, then the device is CDC-Only. CDC-Only CEC devices
are CEC devices that can only handle CDC messages.
All other messages are ignored.
.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
.. _cec-versions:
.. flat-table:: CEC Versions
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-CEC-VERSION-1-3A`:
- ``CEC_OP_CEC_VERSION_1_3A``
- 4
- CEC version according to the HDMI 1.3a standard.
* .. _`CEC-OP-CEC-VERSION-1-4B`:
- ``CEC_OP_CEC_VERSION_1_4B``
- 5
- CEC version according to the HDMI 1.4b standard.
* .. _`CEC-OP-CEC-VERSION-2-0`:
- ``CEC_OP_CEC_VERSION_2_0``
- 6
- CEC version according to the HDMI 2.0 standard.
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-prim-dev-types:
.. flat-table:: CEC Primary Device Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-PRIM-DEVTYPE-TV`:
- ``CEC_OP_PRIM_DEVTYPE_TV``
- 0
- Use for a TV.
* .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
- ``CEC_OP_PRIM_DEVTYPE_RECORD``
- 1
- Use for a recording device.
* .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
- ``CEC_OP_PRIM_DEVTYPE_TUNER``
- 3
- Use for a device with a tuner.
* .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
- ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
- 4
- Use for a playback device.
* .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
- 5
- Use for an audio system (e.g. an audio/video receiver).
* .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
- ``CEC_OP_PRIM_DEVTYPE_SWITCH``
- 6
- Use for a CEC switch.
* .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
- ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
- 7
- Use for a video processor device.
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-log-addr-types:
.. flat-table:: CEC Logical Address Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-LOG-ADDR-TYPE-TV`:
- ``CEC_LOG_ADDR_TYPE_TV``
- 0
- Use for a TV.
* .. _`CEC-LOG-ADDR-TYPE-RECORD`:
- ``CEC_LOG_ADDR_TYPE_RECORD``
- 1
- Use for a recording device.
* .. _`CEC-LOG-ADDR-TYPE-TUNER`:
- ``CEC_LOG_ADDR_TYPE_TUNER``
- 2
- Use for a tuner device.
* .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
- ``CEC_LOG_ADDR_TYPE_PLAYBACK``
- 3
- Use for a playback device.
* .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
- ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
- 4
- Use for an audio system device.
* .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
- ``CEC_LOG_ADDR_TYPE_SPECIFIC``
- 5
- Use for a second TV or for a video processor device.
* .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
- ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
- 6
- Use this if you just want to remain unregistered. Used for pure
CEC switches or CDC-only devices (CDC: Capability Discovery and
Control).
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _cec-all-dev-types-flags:
.. flat-table:: CEC All Device Types Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-OP-ALL-DEVTYPE-TV`:
- ``CEC_OP_ALL_DEVTYPE_TV``
- 0x80
- This supports the TV type.
* .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
- ``CEC_OP_ALL_DEVTYPE_RECORD``
- 0x40
- This supports the Recording type.
* .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
- ``CEC_OP_ALL_DEVTYPE_TUNER``
- 0x20
- This supports the Tuner type.
* .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
- ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
- 0x10
- This supports the Playback type.
* .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
- 0x08
- This supports the Audio System type.
* .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
- ``CEC_OP_ALL_DEVTYPE_SWITCH``
- 0x04
- This supports the CEC Switch or Video Processing type.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported.
EBUSY
The CEC adapter is currently configuring itself, or it is already configured and
``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or
initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``.
EINVAL
The contents of struct :c:type:`cec_log_addrs` is invalid.

100
Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst Normal file
View File

@@ -0,0 +1,100 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
.. _CEC_ADAP_S_PHYS_ADDR:
****************************************************
ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
****************************************************
Name
====
CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
:name: CEC_ADAP_G_PHYS_ADDR
.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
:name: CEC_ADAP_S_PHYS_ADDR
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to the CEC address.
Description
===========
To query the current physical address applications call
:ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
driver stores the physical address.
To set a new physical address applications store the physical address in
a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
The adapter will go to the unconfigured state.
If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
then this ioctl will block until all
requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
then it will not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
changes.
The physical address is a 16-bit number where each group of 4 bits
represent a digit of the physical address a.b.c.d where the most
significant 4 bits represent 'a'. The CEC root device (usually the TV)
has address 0.0.0.0. Every device that is hooked up to an input of the
TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
is supported. The physical address a device shall use is stored in the
EDID of the sink.
For example, the EDID for each HDMI input of the TV will have a
different physical address of the form a.0.0.0 that the sources will
read out and use as their physical address.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
EBUSY
Another filehandle is in exclusive follower or initiator mode, or the filehandle
is in mode ``CEC_MODE_NO_INITIATOR``.
EINVAL
The physical address is malformed.

257
Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst Normal file
View File

@@ -0,0 +1,257 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_DQEVENT:
*****************
ioctl CEC_DQEVENT
*****************
Name
====
CEC_DQEVENT - Dequeue a CEC event
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
:name: CEC_DQEVENT
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Description
===========
CEC devices can send asynchronous events. These can be retrieved by
calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code.
The internal event queues are per-filehandle and per-event type. If
there is no more room in a queue then the last event is overwritten with
the new one. This means that intermediate results can be thrown away but
that the latest event is always available. This also means that is it
possible to read two successive events that have the same value (e.g.
two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
the same state). In that case the intermediate state changes were lost but
it is guaranteed that the state did change in between the two events.
.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
.. c:type:: cec_event_state_change
.. flat-table:: struct cec_event_state_change
:header-rows: 0
:stub-columns: 0
:widths: 1 1 8
* - __u16
- ``phys_addr``
- The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
valid physical address is set.
* - __u16
- ``log_addr_mask``
- The current set of claimed logical addresses. This is 0 if no logical
addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``.
If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device
has the unregistered logical address. In that case all other bits are 0.
* - __u16
- ``have_conn_info``
- If non-zero, then HDMI connector information is available.
This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that
capability is set and ``have_conn_info`` is zero, then that indicates
that the HDMI connector device is not instantiated, either because
the HDMI driver is still configuring the device or because the HDMI
device was unbound.
.. c:type:: cec_event_lost_msgs
.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
.. flat-table:: struct cec_event_lost_msgs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u32
- ``lost_msgs``
- Set to the number of lost messages since the filehandle was opened
or since the last time this event was dequeued for this
filehandle. The messages lost are the oldest messages. So when a
new message arrives and there is no more room, then the oldest
message is discarded to make room for the new one. The internal
size of the message queue guarantees that all messages received in
the last two seconds will be stored. Since messages should be
replied to within a second according to the CEC specification,
this is more than enough.
.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
.. c:type:: cec_event
.. flat-table:: struct cec_event
:header-rows: 0
:stub-columns: 0
:widths: 1 1 8
* - __u64
- ``ts``
- Timestamp of the event in ns.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock.
To access the same clock from userspace use :c:func:`clock_gettime`.
* - __u32
- ``event``
- The CEC event type, see :ref:`cec-events`.
* - __u32
- ``flags``
- Event flags, see :ref:`cec-event-flags`.
* - union {
- (anonymous)
* - struct cec_event_state_change
- ``state_change``
- The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
event.
* - struct cec_event_lost_msgs
- ``lost_msgs``
- The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
event.
* - }
-
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-events:
.. flat-table:: CEC Events Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-EVENT-STATE-CHANGE`:
- ``CEC_EVENT_STATE_CHANGE``
- 1
- Generated when the CEC Adapter's state changes. When open() is
called an initial event will be generated for that filehandle with
the CEC Adapter's state at that time.
* .. _`CEC-EVENT-LOST-MSGS`:
- ``CEC_EVENT_LOST_MSGS``
- 2
- Generated if one or more CEC messages were lost because the
application didn't dequeue CEC messages fast enough.
* .. _`CEC-EVENT-PIN-CEC-LOW`:
- ``CEC_EVENT_PIN_CEC_LOW``
- 3
- Generated if the CEC pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set.
* .. _`CEC-EVENT-PIN-CEC-HIGH`:
- ``CEC_EVENT_PIN_CEC_HIGH``
- 4
- Generated if the CEC pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set.
* .. _`CEC-EVENT-PIN-HPD-LOW`:
- ``CEC_EVENT_PIN_HPD_LOW``
- 5
- Generated if the HPD pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the HPD pin can be read and
if the HPD is low, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-HPD-HIGH`:
- ``CEC_EVENT_PIN_HPD_HIGH``
- 6
- Generated if the HPD pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the HPD pin can be read and
if the HPD is high, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-5V-LOW`:
- ``CEC_EVENT_PIN_5V_LOW``
- 6
- Generated if the 5V pin goes from a high voltage to a low voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the 5V pin can be read and
if the 5V is low, then an initial event will be generated for that
filehandle.
* .. _`CEC-EVENT-PIN-5V-HIGH`:
- ``CEC_EVENT_PIN_5V_HIGH``
- 7
- Generated if the 5V pin goes from a low voltage to a high voltage.
Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
capability set. When open() is called, the 5V pin can be read and
if the 5V is high, then an initial event will be generated for that
filehandle.
.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
.. _cec-event-flags:
.. flat-table:: CEC Event Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
* .. _`CEC-EVENT-FL-INITIAL-STATE`:
- ``CEC_EVENT_FL_INITIAL_STATE``
- 1
- Set for the initial events that are generated when the device is
opened. See the table above for which events do this. This allows
applications to learn the initial state of the CEC adapter at
open() time.
* .. _`CEC-EVENT-FL-DROPPED-EVENTS`:
- ``CEC_EVENT_FL_DROPPED_EVENTS``
- 2
- Set if one or more events of the given event type have been dropped.
This is an indication that the application cannot keep up.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following
error codes:
EAGAIN
This is returned when the filehandle is in non-blocking mode and there
are no pending events.
ERESTARTSYS
An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for
events to arrive.

301
Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst Normal file
View File

@@ -0,0 +1,301 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_MODE:
.. _CEC_G_MODE:
.. _CEC_S_MODE:
********************************
ioctls CEC_G_MODE and CEC_S_MODE
********************************
CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
:name: CEC_G_MODE
.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
:name: CEC_S_MODE
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to CEC mode.
Description
===========
By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
applications from stepping on each others toes it must be possible to
obtain exclusive access to the CEC adapter. This ioctl sets the
filehandle to initiator and/or follower mode which can be exclusive
depending on the chosen mode. The initiator is the filehandle that is
used to initiate messages, i.e. it commands other CEC devices. The
follower is the filehandle that receives messages sent to the CEC
adapter and processes them. The same filehandle can be both initiator
and follower, or this role can be taken by two different filehandles.
When a CEC message is received, then the CEC framework will decide how
it will be processed. If the message is a reply to an earlier
transmitted message, then the reply is sent back to the filehandle that
is waiting for it. In addition the CEC framework will process it.
If the message is not a reply, then the CEC framework will process it
first. If there is no follower, then the message is just discarded and a
feature abort is sent back to the initiator if the framework couldn't
process it. If there is a follower, then the message is passed on to the
follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
the new message. The framework expects the follower to make the right
decisions.
The CEC framework will process core messages unless requested otherwise
by the follower. The follower can enable the passthrough mode. In that
case, the CEC framework will pass on most core messages without
processing them and the follower will have to implement those messages.
There are some messages that the core will always process, regardless of
the passthrough mode. See :ref:`cec-core-processing` for details.
If there is no initiator, then any CEC filehandle can use
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
initiator then only that initiator can call
:ref:`CEC_TRANSMIT`. The follower can of course
always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
Available initiator modes are:
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-mode-initiator_e:
.. flat-table:: Initiator Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-MODE-NO-INITIATOR`:
- ``CEC_MODE_NO_INITIATOR``
- 0x0
- This is not an initiator, i.e. it cannot transmit CEC messages or
make any other changes to the CEC adapter.
* .. _`CEC-MODE-INITIATOR`:
- ``CEC_MODE_INITIATOR``
- 0x1
- This is an initiator (the default when the device is opened) and
it can transmit CEC messages and make changes to the CEC adapter,
unless there is an exclusive initiator.
* .. _`CEC-MODE-EXCL-INITIATOR`:
- ``CEC_MODE_EXCL_INITIATOR``
- 0x2
- This is an exclusive initiator and this file descriptor is the
only one that can transmit CEC messages and make changes to the
CEC adapter. If someone else is already the exclusive initiator
then an attempt to become one will return the ``EBUSY`` error code
error.
Available follower modes are:
.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
.. _cec-mode-follower_e:
.. cssclass:: longtable
.. flat-table:: Follower Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-MODE-NO-FOLLOWER`:
- ``CEC_MODE_NO_FOLLOWER``
- 0x00
- This is not a follower (the default when the device is opened).
* .. _`CEC-MODE-FOLLOWER`:
- ``CEC_MODE_FOLLOWER``
- 0x10
- This is a follower and it will receive CEC messages unless there
is an exclusive follower. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-EXCL-FOLLOWER`:
- ``CEC_MODE_EXCL_FOLLOWER``
- 0x20
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. If someone else is already
the exclusive follower then an attempt to become one will return
the ``EBUSY`` error code. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
- ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
- 0x30
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. In addition it will put the
CEC device into passthrough mode, allowing the exclusive follower
to handle most core messages instead of relying on the CEC
framework for that. If someone else is already the exclusive
follower then an attempt to become one will return the ``EBUSY`` error
code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
the ``EINVAL`` error code is returned in that case.
* .. _`CEC-MODE-MONITOR-PIN`:
- ``CEC_MODE_MONITOR_PIN``
- 0xd0
- Put the file descriptor into pin monitoring mode. Can only be used in
combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
otherwise the ``EINVAL`` error code will be returned.
This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
capability is set, otherwise the ``EINVAL`` error code is returned.
While in pin monitoring mode this file descriptor can receive the
``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
low-level CEC pin transitions. This is very useful for debugging.
This mode is only allowed if the process has the ``CAP_NET_ADMIN``
capability. If that is not set, then the ``EPERM`` error code is returned.
* .. _`CEC-MODE-MONITOR`:
- ``CEC_MODE_MONITOR``
- 0xe0
- Put the file descriptor into monitor mode. Can only be used in
combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
otherwise the ``EINVAL`` error code will be returned.
In monitor mode all messages this CEC
device transmits and all messages it receives (both broadcast
messages and directed messages for one its logical addresses) will
be reported. This is very useful for debugging. This is only
allowed if the process has the ``CAP_NET_ADMIN`` capability. If
that is not set, then the ``EPERM`` error code is returned.
* .. _`CEC-MODE-MONITOR-ALL`:
- ``CEC_MODE_MONITOR_ALL``
- 0xf0
- Put the file descriptor into 'monitor all' mode. Can only be used
in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
this CEC device transmits and all messages it receives, including
directed messages for other CEC devices will be reported. This is
very useful for debugging, but not all devices support this. This
mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
otherwise the ``EINVAL`` error code is returned. This is only allowed if
the process has the ``CAP_NET_ADMIN`` capability. If that is not
set, then the ``EPERM`` error code is returned.
Core message processing details:
.. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
.. _cec-core-processing:
.. flat-table:: Core Message Processing
:header-rows: 0
:stub-columns: 0
:widths: 1 8
* .. _`CEC-MSG-GET-CEC-VERSION`:
- ``CEC_MSG_GET_CEC_VERSION``
- The core will return the CEC version that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
- ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
- The core will return the vendor ID that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-ABORT`:
- ``CEC_MSG_ABORT``
- The core will return a Feature Abort message with reason
'Feature Refused' as per the specification, except when in
passthrough mode. In passthrough mode the core does nothing
and this message has to be handled by a follower instead.
* .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
- ``CEC_MSG_GIVE_PHYSICAL_ADDR``
- The core will report the current physical address, except when
in passthrough mode. In passthrough mode the core does nothing
and this message has to be handled by a follower instead.
* .. _`CEC-MSG-GIVE-OSD-NAME`:
- ``CEC_MSG_GIVE_OSD_NAME``
- The core will report the current OSD name that was set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing and this message has to be handled by a follower
instead.
* .. _`CEC-MSG-GIVE-FEATURES`:
- ``CEC_MSG_GIVE_FEATURES``
- The core will do nothing if the CEC version is older than 2.0,
otherwise it will report the current features that were set with
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
except when in passthrough mode. In passthrough mode the core
does nothing (for any CEC version) and this message has to be handled
by a follower instead.
* .. _`CEC-MSG-USER-CONTROL-PRESSED`:
- ``CEC_MSG_USER_CONTROL_PRESSED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
:ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
is set, then generate a remote control key
press. This message is always passed on to the follower(s).
* .. _`CEC-MSG-USER-CONTROL-RELEASED`:
- ``CEC_MSG_USER_CONTROL_RELEASED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
:ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
is set, then generate a remote control key
release. This message is always passed on to the follower(s).
* .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
- ``CEC_MSG_REPORT_PHYSICAL_ADDR``
- The CEC framework will make note of the reported physical address
and then just pass the message on to the follower(s).
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
error codes:
EINVAL
The requested mode is invalid.
EPERM
Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN``
capability.
EBUSY
Someone else is already an exclusive follower or initiator.

391
Documentation/userspace-api/media/cec/cec-ioc-receive.rst Normal file
View File

@@ -0,0 +1,391 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CEC_TRANSMIT:
.. _CEC_RECEIVE:
***********************************
ioctls CEC_RECEIVE and CEC_TRANSMIT
***********************************
Name
====
CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
Synopsis
========
.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
:name: CEC_RECEIVE
.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
:name: CEC_TRANSMIT
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <cec-open>`.
``argp``
Pointer to struct cec_msg.
Description
===========
To receive a CEC message the application has to fill in the
``timeout`` field of struct :c:type:`cec_msg` and pass it to
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If the file descriptor is in non-blocking mode and there are no received
messages pending, then it will return -1 and set errno to the ``EAGAIN``
error code. If the file descriptor is in blocking mode and ``timeout``
is non-zero and no message arrived within ``timeout`` milliseconds, then
it will return -1 and set errno to the ``ETIMEDOUT`` error code.
A received message can be:
1. a message received from another CEC device (the ``sequence`` field will
be 0).
2. the result of an earlier non-blocking transmit (the ``sequence`` field will
be non-zero).
To send a CEC message the application has to fill in the struct
:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
queue, then it will return -1 and set errno to the ``EBUSY`` error code.
The transmit queue has enough room for 18 messages (about 1 second worth
of 2-byte messages). Note that the CEC kernel framework will also reply
to core messages (see :ref:`cec-core-processing`), so it is not a good
idea to fully fill up the transmit queue.
If the file descriptor is in non-blocking mode then the transmit will
return 0 and the result of the transmit will be available via
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
(including waiting for a reply, if requested).
The ``sequence`` field is filled in for every transmit and this can be
checked against the received messages to find the corresponding transmit
result.
Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
address is invalid (due to e.g. a disconnect) will return ``ENONET``.
However, the CEC specification allows sending messages from 'Unregistered' to
'TV' when the physical address is invalid since some TVs pull the hotplug detect
pin of the HDMI connector low when they go into standby, or when switching to
another input.
When the hotplug detect pin goes low the EDID disappears, and thus the
physical address, but the cable is still connected and CEC still works.
In order to detect/wake up the device it is allowed to send poll and 'Image/Text
View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
.. c:type:: cec_msg
.. cssclass:: longtable
.. flat-table:: struct cec_msg
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
* - __u64
- ``tx_ts``
- Timestamp in ns of when the last byte of the message was transmitted.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime`.
* - __u64
- ``rx_ts``
- Timestamp in ns of when the last byte of the message was received.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime`.
* - __u32
- ``len``
- The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
by the application. The driver will fill this in for
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
filled in by the driver with the length of the reply message if ``reply`` was set.
* - __u32
- ``timeout``
- The timeout in milliseconds. This is the time the device will wait
for a message to be received before timing out. If it is set to 0,
then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
then it will be replaced by 1000 if the ``reply`` is non-zero or
ignored if ``reply`` is 0.
* - __u32
- ``sequence``
- A non-zero sequence number is automatically assigned by the CEC framework
for all transmitted messages. It is used by the CEC framework when it queues
the transmit result (when transmit was called in non-blocking mode). This
allows the application to associate the received message with the original
transmit.
* - __u32
- ``flags``
- Flags. See :ref:`cec-msg-flags` for a list of available flags.
* - __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this message was received, not transmitted.
* - __u8
- ``msg[16]``
- The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
the payload of the reply message if ``timeout`` was set.
* - __u8
- ``reply``
- Wait until this message is replied. If ``reply`` is 0 and the
``timeout`` is 0, then don't wait for a reply but return after
transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
The case where ``reply`` is 0 (this is the opcode for the Feature Abort
message) and ``timeout`` is non-zero is specifically allowed to make it
possible to send a message and wait up to ``timeout`` milliseconds for a
Feature Abort reply. In this case ``rx_status`` will either be set
to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
:ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
are processed differently: either value will match both possible replies.
The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
message that has two possible replies other than Feature Abort. The
``reply`` field will be updated with the actual reply so that it is
synchronized with the contents of the received message.
* - __u8
- ``rx_status``
- The status bits of the received message. See
:ref:`cec-rx-status` for the possible status values. It is 0 if
this message was transmitted, not received, unless this is the
reply to a transmitted message. In that case both ``rx_status``
and ``tx_status`` are set.
* - __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this message was received, not transmitted.
* - __u8
- ``tx_arb_lost_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
* - __u8
- ``tx_nack_cnt``
- A counter of the number of transmit attempts that resulted in the
Not Acknowledged error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
* - __u8
- ``tx_low_drive_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
* - __u8
- ``tx_error_cnt``
- A counter of the number of transmit errors other than Arbitration
Lost or Not Acknowledged. This is only set if the hardware
supports this, otherwise it is always 0. This counter is only
valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
.. _cec-msg-flags:
.. flat-table:: Flags for struct cec_msg
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
* .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
- ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
- 1
- If a CEC transmit expects a reply, then by default that reply is only sent to
the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
flag is set, then the reply is also sent to all followers, if any. If the
filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
follower, then that filehandle will receive the reply twice: once as the
result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
* .. _`CEC-MSG-FL-RAW`:
- ``CEC_MSG_FL_RAW``
- 2
- Normally CEC messages are validated before transmitting them. If this
flag is set when :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is called,
then no validation takes place and the message is transmitted as-is.
This is useful when debugging CEC issues.
This flag is only allowed if the process has the ``CAP_SYS_RAWIO``
capability. If that is not set, then the ``EPERM`` error code is
returned.
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-tx-status:
.. flat-table:: CEC Transmit Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-TX-STATUS-OK`:
- ``CEC_TX_STATUS_OK``
- 0x01
- The message was transmitted successfully. This is mutually
exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
Other bits can still be set if earlier attempts met with failure before
the transmit was eventually successful.
* .. _`CEC-TX-STATUS-ARB-LOST`:
- ``CEC_TX_STATUS_ARB_LOST``
- 0x02
- CEC line arbitration was lost, i.e. another transmit started at the
same time with a higher priority. Optional status, not all hardware
can detect this error condition.
* .. _`CEC-TX-STATUS-NACK`:
- ``CEC_TX_STATUS_NACK``
- 0x04
- Message was not acknowledged. Note that some hardware cannot tell apart
a 'Not Acknowledged' status from other error conditions, i.e. the result
of a transmit is just OK or FAIL. In that case this status will be
returned when the transmit failed.
* .. _`CEC-TX-STATUS-LOW-DRIVE`:
- ``CEC_TX_STATUS_LOW_DRIVE``
- 0x08
- Low drive was detected on the CEC bus. This indicates that a
follower detected an error on the bus and requests a
retransmission. Optional status, not all hardware can detect this
error condition.
* .. _`CEC-TX-STATUS-ERROR`:
- ``CEC_TX_STATUS_ERROR``
- 0x10
- Some error occurred. This is used for any errors that do not fit
``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because
the hardware could not tell which error occurred, or because the hardware
tested for other conditions besides those two. Optional status.
* .. _`CEC-TX-STATUS-MAX-RETRIES`:
- ``CEC_TX_STATUS_MAX_RETRIES``
- 0x20
- The transmit failed after one or more retries. This status bit is
mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
Other bits can still be set to explain which failures were seen.
* .. _`CEC-TX-STATUS-ABORTED`:
- ``CEC_TX_STATUS_ABORTED``
- 0x40
- The transmit was aborted due to an HDMI disconnect, or the adapter
was unconfigured, or a transmit was interrupted, or the driver
returned an error when attempting to start a transmit.
* .. _`CEC-TX-STATUS-TIMEOUT`:
- ``CEC_TX_STATUS_TIMEOUT``
- 0x80
- The transmit timed out. This should not normally happen and this
indicates a driver problem.
.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
.. _cec-rx-status:
.. flat-table:: CEC Receive Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
* .. _`CEC-RX-STATUS-OK`:
- ``CEC_RX_STATUS_OK``
- 0x01
- The message was received successfully.
* .. _`CEC-RX-STATUS-TIMEOUT`:
- ``CEC_RX_STATUS_TIMEOUT``
- 0x02
- The reply to an earlier transmitted message timed out.
* .. _`CEC-RX-STATUS-FEATURE-ABORT`:
- ``CEC_RX_STATUS_FEATURE_ABORT``
- 0x04
- The message was received successfully but the reply was
``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
was the reply to an earlier transmitted message.
* .. _`CEC-RX-STATUS-ABORTED`:
- ``CEC_RX_STATUS_ABORTED``
- 0x08
- The wait for a reply to an earlier transmitted message was aborted
because the HDMI cable was disconnected, the adapter was unconfigured
or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a
reply was interrupted.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
error codes:
EAGAIN
No messages are in the receive queue, and the filehandle is in non-blocking mode.
ETIMEDOUT
The ``timeout`` was reached while waiting for a message.
ERESTARTSYS
The wait for a message was interrupted (e.g. by Ctrl-C).
The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
error codes:
ENOTTY
The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
EPERM
The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that
did not have the ``CAP_SYS_RAWIO`` capability.
ENONET
The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
was called, but the physical address is invalid so no logical address was claimed.
An exception is made in this case for transmits from initiator 0xf ('Unregistered')
to destination 0 ('TV'). In that case the transmit will proceed as usual.
EBUSY
Another filehandle is in exclusive follower or initiator mode, or the filehandle
is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
queue is full.
EINVAL
The contents of struct :c:type:`cec_msg` is invalid.
ERESTARTSYS
The wait for a successful transmit was interrupted (e.g. by Ctrl-C).

334
Documentation/userspace-api/media/cec/cec-pin-error-inj.rst Normal file
View File

@@ -0,0 +1,334 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
CEC Pin Framework Error Injection
=================================
The CEC Pin Framework is a core CEC framework for CEC hardware that only
has low-level support for the CEC bus. Most hardware today will have
high-level CEC support where the hardware deals with driving the CEC bus,
but some older devices aren't that fancy. However, this framework also
allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and
you have now made a CEC adapter.
What makes doing this so interesting is that since we have full control
over the bus it is easy to support error injection. This is ideal to
test how well CEC adapters can handle error conditions.
Currently only the cec-gpio driver (when the CEC line is directly
connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver
support this framework.
If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available
through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is
now an ``error-inj`` file.
.. note::
The error injection commands are not a stable ABI and may change in the
future.
With ``cat error-inj`` you can see both the possible commands and the current
error injection status::
$ cat /sys/kernel/debug/cec/cec0/error-inj
# Clear error injections:
# clear clear all rx and tx error injections
# rx-clear clear all rx error injections
# tx-clear clear all tx error injections
# <op> clear clear all rx and tx error injections for <op>
# <op> rx-clear clear all rx error injections for <op>
# <op> tx-clear clear all tx error injections for <op>
#
# RX error injection:
# <op>[,<mode>] rx-nack NACK the message instead of sending an ACK
# <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position
# <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message
# <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message
# <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost
#
# TX error injection settings:
# tx-ignore-nack-until-eom ignore early NACKs until EOM
# tx-custom-low-usecs <usecs> define the 'low' time for the custom pulse
# tx-custom-high-usecs <usecs> define the 'high' time for the custom pulse
# tx-custom-pulse transmit the custom pulse once the bus is idle
#
# TX error injection:
# <op>[,<mode>] tx-no-eom don't set the EOM bit
# <op>[,<mode>] tx-early-eom set the EOM bit one byte too soon
# <op>[,<mode>] tx-add-bytes <num> append <num> (1-255) spurious bytes to the message
# <op>[,<mode>] tx-remove-byte drop the last byte from the message
# <op>[,<mode>] tx-short-bit <bit> make this bit shorter than allowed
# <op>[,<mode>] tx-long-bit <bit> make this bit longer than allowed
# <op>[,<mode>] tx-custom-bit <bit> send the custom pulse instead of this bit
# <op>[,<mode>] tx-short-start send a start pulse that's too short
# <op>[,<mode>] tx-long-start send a start pulse that's too long
# <op>[,<mode>] tx-custom-start send the custom pulse instead of the start pulse
# <op>[,<mode>] tx-last-bit <bit> stop sending after this bit
# <op>[,<mode>] tx-low-drive <bit> force a low-drive condition at this bit position
#
# <op> CEC message opcode (0-255) or 'any'
# <mode> 'once' (default), 'always', 'toggle' or 'off'
# <bit> CEC message bit (0-159)
# 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK
# <poll> CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f)
# <usecs> microseconds (0-10000000, default 1000)
clear
You can write error injection commands to ``error-inj`` using
``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj``
output contains the current error commands. You can save the output to a file
and use it as an input to ``error-inj`` later.
Basic Syntax
------------
Leading spaces/tabs are ignored. If the next character is a ``#`` or the end
of the line was reached, then the whole line is ignored. Otherwise a command
is expected.
The error injection commands fall in two main groups: those relating to
receiving CEC messages and those relating to transmitting CEC messages. In
addition, there are commands to clear existing error injection commands and
to create custom pulses on the CEC bus.
Most error injection commands can be executed for specific CEC opcodes or for
all opcodes (``any``). Each command also has a 'mode' which can be ``off``
(can be used to turn off an existing error injection command), ``once``
(the default) which will trigger the error injection only once for the next
received or transmitted message, ``always`` to always trigger the error
injection and ``toggle`` to toggle the error injection on or off for every
transmit or receive.
So '``any rx-nack``' will NACK the next received CEC message,
'``any,always rx-nack``' will NACK all received CEC messages and
'``0x82,toggle rx-nack``' will only NACK if an Active Source message was
received and do that only for every other received message.
After an error was injected with mode ``once`` the error injection command
is cleared automatically, so ``once`` is a one-time deal.
All combinations of ``<op>`` and error injection commands can co-exist. So
this is fine::
0x9e tx-add-bytes 1
0x9e tx-early-eom
0x9f tx-add-bytes 2
any rx-nack
All four error injection commands will be active simultaneously.
However, if the same ``<op>`` and command combination is specified,
but with different arguments::
0x9e tx-add-bytes 1
0x9e tx-add-bytes 2
Then the second will overwrite the first.
Clear Error Injections
----------------------
``clear``
Clear all error injections.
``rx-clear``
Clear all receive error injections
``tx-clear``
Clear all transmit error injections
``<op> clear``
Clear all error injections for the given opcode.
``<op> rx-clear``
Clear all receive error injections for the given opcode.
``<op> tx-clear``
Clear all transmit error injections for the given opcode.
Receive Messages
----------------
``<op>[,<mode>] rx-nack``
NACK broadcast messages and messages directed to this CEC adapter.
Every byte of the message will be NACKed in case the transmitter
keeps transmitting after the first byte was NACKed.
``<op>[,<mode>] rx-low-drive <bit>``
Force a Low Drive condition at this bit position. If <op> specifies
a specific CEC opcode then the bit position must be at least 18,
otherwise the opcode hasn't been received yet. This tests if the
transmitter can handle the Low Drive condition correctly and reports
the error correctly. Note that a Low Drive in the first 4 bits can also
be interpreted as an Arbitration Lost condition by the transmitter.
This is implementation dependent.
``<op>[,<mode>] rx-add-byte``
Add a spurious 0x55 byte to the received CEC message, provided
the message was 15 bytes long or less. This is useful to test
the high-level protocol since spurious bytes should be ignored.
``<op>[,<mode>] rx-remove-byte``
Remove the last byte from the received CEC message, provided it
was at least 2 bytes long. This is useful to test the high-level
protocol since messages that are too short should be ignored.
``<op>[,<mode>] rx-arb-lost <poll>``
Generate a POLL message to trigger an Arbitration Lost condition.
This command is only allowed for ``<op>`` values of ``next`` or ``all``.
As soon as a start bit has been received the CEC adapter will switch
to transmit mode and it will transmit a POLL message. By default this is
0x0f, but it can also be specified explicitly via the ``<poll>`` argument.
This command can be used to test the Arbitration Lost condition in
the remote CEC transmitter. Arbitration happens when two CEC adapters
start sending a message at the same time. In that case the initiator
with the most leading zeroes wins and the other transmitter has to
stop transmitting ('Arbitration Lost'). This is very hard to test,
except by using this error injection command.
This does not work if the remote CEC transmitter has logical address
0 ('TV') since that will always win.
Transmit Messages
-----------------
``tx-ignore-nack-until-eom``
This setting changes the behavior of transmitting CEC messages. Normally
as soon as the receiver NACKs a byte the transmit will stop, but the
specification also allows that the full message is transmitted and only
at the end will the transmitter look at the ACK bit. This is not
recommended behavior since there is no point in keeping the CEC bus busy
for longer than is strictly needed. Especially given how slow the bus is.
This setting can be used to test how well a receiver deals with
transmitters that ignore NACKs until the very end of the message.
``<op>[,<mode>] tx-no-eom``
Don't set the EOM bit. Normally the last byte of the message has the EOM
(End-Of-Message) bit set. With this command the transmit will just stop
without ever sending an EOM. This can be used to test how a receiver
handles this case. Normally receivers have a time-out after which
they will go back to the Idle state.
``<op>[,<mode>] tx-early-eom``
Set the EOM bit one byte too soon. This obviously only works for messages
of two bytes or more. The EOM bit will be set for the second-to-last byte
and not for the final byte. The receiver should ignore the last byte in
this case. Since the resulting message is likely to be too short for this
same reason the whole message is typically ignored. The receiver should be
in Idle state after the last byte was transmitted.
``<op>[,<mode>] tx-add-bytes <num>``
Append ``<num>`` (1-255) spurious bytes to the message. The extra bytes
have the value of the byte position in the message. So if you transmit a
two byte message (e.g. a Get CEC Version message) and add 2 bytes, then
the full message received by the remote CEC adapter is
``0x40 0x9f 0x02 0x03``.
This command can be used to test buffer overflows in the receiver. E.g.
what does it do when it receives more than the maximum message size of 16
bytes.
``<op>[,<mode>] tx-remove-byte``
Drop the last byte from the message, provided the message is at least
two bytes long. The receiver should ignore messages that are too short.
``<op>[,<mode>] tx-short-bit <bit>``
Make this bit period shorter than allowed. The bit position cannot be
an Ack bit. If <op> specifies a specific CEC opcode then the bit position
must be at least 18, otherwise the opcode hasn't been received yet.
Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
With this command the period of this bit is 1.8 milliseconds, this is
done by reducing the time the CEC bus is high. This bit period is less
than is allowed and the receiver should respond with a Low Drive
condition.
This command is ignored for 0 bits in bit positions 0 to 3. This is
because the receiver also looks for an Arbitration Lost condition in
those first four bits and it is undefined what will happen if it
sees a too-short 0 bit.
``<op>[,<mode>] tx-long-bit <bit>``
Make this bit period longer than is valid. The bit position cannot be
an Ack bit. If <op> specifies a specific CEC opcode then the bit position
must be at least 18, otherwise the opcode hasn't been received yet.
Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
With this command the period of this bit is 2.9 milliseconds, this is
done by increasing the time the CEC bus is high.
Even though this bit period is longer than is valid it is undefined what
a receiver will do. It might just accept it, or it might time out and
return to Idle state. Unfortunately the CEC specification is silent about
this.
This command is ignored for 0 bits in bit positions 0 to 3. This is
because the receiver also looks for an Arbitration Lost condition in
those first four bits and it is undefined what will happen if it
sees a too-long 0 bit.
``<op>[,<mode>] tx-short-start``
Make this start bit period shorter than allowed. Normally the period of
a start bit is between 4.3 and 4.7 milliseconds. With this command the
period of the start bit is 4.1 milliseconds, this is done by reducing
the time the CEC bus is high. This start bit period is less than is
allowed and the receiver should return to Idle state when this is detected.
``<op>[,<mode>] tx-long-start``
Make this start bit period longer than is valid. Normally the period of
a start bit is between 4.3 and 4.7 milliseconds. With this command the
period of the start bit is 5 milliseconds, this is done by increasing
the time the CEC bus is high. This start bit period is more than is
valid and the receiver should return to Idle state when this is detected.
Even though this start bit period is longer than is valid it is undefined
what a receiver will do. It might just accept it, or it might time out and
return to Idle state. Unfortunately the CEC specification is silent about
this.
``<op>[,<mode>] tx-last-bit <bit>``
Just stop transmitting after this bit. If <op> specifies a specific CEC
opcode then the bit position must be at least 18, otherwise the opcode
hasn't been received yet. This command can be used to test how the receiver
reacts when a message just suddenly stops. It should time out and go back
to Idle state.
``<op>[,<mode>] tx-low-drive <bit>``
Force a Low Drive condition at this bit position. If <op> specifies a
specific CEC opcode then the bit position must be at least 18, otherwise
the opcode hasn't been received yet. This can be used to test how the
receiver handles Low Drive conditions. Note that if this happens at bit
positions 0-3 the receiver can interpret this as an Arbitration Lost
condition. This is implementation dependent.
Custom Pulses
-------------
``tx-custom-low-usecs <usecs>``
This defines the duration in microseconds that the custom pulse pulls
the CEC line low. The default is 1000 microseconds.
``tx-custom-high-usecs <usecs>``
This defines the duration in microseconds that the custom pulse keeps the
CEC line high (unless another CEC adapter pulls it low in that time).
The default is 1000 microseconds. The total period of the custom pulse is
``tx-custom-low-usecs + tx-custom-high-usecs``.
``<op>[,<mode>] tx-custom-bit <bit>``
Send the custom bit instead of a regular data bit. The bit position cannot
be an Ack bit. If <op> specifies a specific CEC opcode then the bit
position must be at least 18, otherwise the opcode hasn't been received yet.
``<op>[,<mode>] tx-custom-start``
Send the custom bit instead of a regular start bit.
``tx-custom-pulse``
Transmit a single custom pulse as soon as the CEC bus is idle.

111
Documentation/userspace-api/media/conf_nitpick.py Normal file
View File

@@ -0,0 +1,111 @@
# -*- coding: utf-8; mode: python -*-
# SPDX-License-Identifier: GPL-2.0
project = 'Linux Media Subsystem Documentation'
# It is possible to run Sphinx in nickpick mode with:
nitpicky = True
# within nit-picking build, do not refer to any intersphinx object
intersphinx_mapping = {}
# In nickpick mode, it will complain about lots of missing references that
#
# 1) are just typedefs like: bool, __u32, etc;
# 2) It will complain for things like: enum, NULL;
# 3) It will complain for symbols that should be on different
# books (but currently aren't ported to ReST)
#
# The list below has a list of such symbols to be ignored in nitpick mode
#
nitpick_ignore = [
("c:func", "clock_gettime"),
("c:func", "close"),
("c:func", "container_of"),
("c:func", "copy_from_user"),
("c:func", "copy_to_user"),
("c:func", "determine_valid_ioctls"),
("c:func", "ERR_PTR"),
("c:func", "i2c_new_device"),
("c:func", "ioctl"),
("c:func", "IS_ERR"),
("c:func", "KERNEL_VERSION"),
("c:func", "mmap"),
("c:func", "open"),
("c:func", "pci_name"),
("c:func", "poll"),
("c:func", "PTR_ERR"),
("c:func", "read"),
("c:func", "release"),
("c:func", "set"),
("c:func", "struct fd_set"),
("c:func", "struct pollfd"),
("c:func", "usb_make_path"),
("c:func", "wait_finish"),
("c:func", "wait_prepare"),
("c:func", "write"),
("c:type", "atomic_t"),
("c:type", "bool"),
("c:type", "boolean"),
("c:type", "buf_queue"),
("c:type", "device"),
("c:type", "device_driver"),
("c:type", "device_node"),
("c:type", "enum"),
("c:type", "fd"),
("c:type", "fd_set"),
("c:type", "file"),
("c:type", "i2c_adapter"),
("c:type", "i2c_board_info"),
("c:type", "i2c_client"),
("c:type", "int16_t"),
("c:type", "ktime_t"),
("c:type", "led_classdev_flash"),
("c:type", "list_head"),
("c:type", "lock_class_key"),
("c:type", "module"),
("c:type", "mutex"),
("c:type", "NULL"),
("c:type", "off_t"),
("c:type", "pci_dev"),
("c:type", "pdvbdev"),
("c:type", "poll_table"),
("c:type", "platform_device"),
("c:type", "pollfd"),
("c:type", "poll_table_struct"),
("c:type", "s32"),
("c:type", "s64"),
("c:type", "sd"),
("c:type", "size_t"),
("c:type", "spi_board_info"),
("c:type", "spi_device"),
("c:type", "spi_master"),
("c:type", "ssize_t"),
("c:type", "fb_fix_screeninfo"),
("c:type", "pollfd"),
("c:type", "timeval"),
("c:type", "video_capability"),
("c:type", "timeval"),
("c:type", "__u16"),
("c:type", "u16"),
("c:type", "__u32"),
("c:type", "u32"),
("c:type", "__u64"),
("c:type", "u64"),
("c:type", "u8"),
("c:type", "uint16_t"),
("c:type", "uint32_t"),
("c:type", "union"),
("c:type", "__user"),
("c:type", "usb_device"),
("c:type", "usb_interface"),
("c:type", "v4l2_std_id"),
("c:type", "video_system_t"),
("c:type", "vm_area_struct"),
# Opaque structures
("c:type", "v4l2_m2m_dev"),
]

66
Documentation/userspace-api/media/dmx.h.rst.exceptions Normal file
View File

@@ -0,0 +1,66 @@
# SPDX-License-Identifier: GPL-2.0
# Ignore header name
ignore define _UAPI_DVBDMX_H_
# Ignore limit constants
ignore define DMX_FILTER_SIZE
# dmx_pes_type_t enum symbols
replace enum dmx_ts_pes :c:type:`dmx_pes_type`
replace symbol DMX_PES_AUDIO0 :c:type:`dmx_pes_type`
replace symbol DMX_PES_VIDEO0 :c:type:`dmx_pes_type`
replace symbol DMX_PES_TELETEXT0 :c:type:`dmx_pes_type`
replace symbol DMX_PES_SUBTITLE0 :c:type:`dmx_pes_type`
replace symbol DMX_PES_PCR0 :c:type:`dmx_pes_type`
replace symbol DMX_PES_AUDIO1 :c:type:`dmx_pes_type`
replace symbol DMX_PES_VIDEO1 :c:type:`dmx_pes_type`
replace symbol DMX_PES_TELETEXT1 :c:type:`dmx_pes_type`
replace symbol DMX_PES_SUBTITLE1 :c:type:`dmx_pes_type`
replace symbol DMX_PES_PCR1 :c:type:`dmx_pes_type`
replace symbol DMX_PES_AUDIO2 :c:type:`dmx_pes_type`
replace symbol DMX_PES_VIDEO2 :c:type:`dmx_pes_type`
replace symbol DMX_PES_TELETEXT2 :c:type:`dmx_pes_type`
replace symbol DMX_PES_SUBTITLE2 :c:type:`dmx_pes_type`
replace symbol DMX_PES_PCR2 :c:type:`dmx_pes_type`
replace symbol DMX_PES_AUDIO3 :c:type:`dmx_pes_type`
replace symbol DMX_PES_VIDEO3 :c:type:`dmx_pes_type`
replace symbol DMX_PES_TELETEXT3 :c:type:`dmx_pes_type`
replace symbol DMX_PES_SUBTITLE3 :c:type:`dmx_pes_type`
replace symbol DMX_PES_PCR3 :c:type:`dmx_pes_type`
replace symbol DMX_PES_OTHER :c:type:`dmx_pes_type`
# Ignore obsolete symbols
ignore define DMX_PES_AUDIO
ignore define DMX_PES_VIDEO
ignore define DMX_PES_TELETEXT
ignore define DMX_PES_SUBTITLE
ignore define DMX_PES_PCR
# dmx_input_t symbols
replace enum dmx_input :c:type:`dmx_input`
replace symbol DMX_IN_FRONTEND :c:type:`dmx_input`
replace symbol DMX_IN_DVR :c:type:`dmx_input`
# Flags for struct dmx_sct_filter_params
replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params`
replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params`
replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params`
# some typedefs should point to struct/enums
replace typedef dmx_filter_t :c:type:`dmx_filter`
replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
replace typedef dmx_input_t :c:type:`dmx_input`
replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags`
replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags`
replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags`
replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags`
replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags`
replace symbol DMX_OUT_DECODER :c:type:`dmx_output`
replace symbol DMX_OUT_TAP :c:type:`dmx_output`
replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output`
replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output`
replace ioctl DMX_DQBUF dmx_qbuf

66
Documentation/userspace-api/media/dvb/audio-bilingual-channel-select.rst Normal file
View File

@@ -0,0 +1,66 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_BILINGUAL_CHANNEL_SELECT:
==============================
AUDIO_BILINGUAL_CHANNEL_SELECT
==============================
Name
----
AUDIO_BILINGUAL_CHANNEL_SELECT
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select)
:name: AUDIO_BILINGUAL_CHANNEL_SELECT
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- audio_channel_select_t ch
- Select the output format of the audio (mono left/right, stereo).
Description
-----------
This ioctl is obsolete. Do not use in new drivers. It has been replaced
by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
for MPEG decoders controlled through V4L2.
This ioctl call asks the Audio Device to select the requested channel
for bilingual streams if possible.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

66
Documentation/userspace-api/media/dvb/audio-channel-select.rst Normal file
View File

@@ -0,0 +1,66 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_CHANNEL_SELECT:
====================
AUDIO_CHANNEL_SELECT
====================
Name
----
AUDIO_CHANNEL_SELECT
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select)
:name: AUDIO_CHANNEL_SELECT
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- audio_channel_select_t ch
- Select the output format of the audio (mono left/right, stereo).
Description
-----------
This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
This ioctl call asks the Audio Device to select the requested channel if
possible.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

55
Documentation/userspace-api/media/dvb/audio-clear-buffer.rst Normal file
View File

@@ -0,0 +1,55 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_CLEAR_BUFFER:
==================
AUDIO_CLEAR_BUFFER
==================
Name
----
AUDIO_CLEAR_BUFFER
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER)
:name: AUDIO_CLEAR_BUFFER
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This ioctl call asks the Audio Device to clear all software and hardware
buffers of the audio decoder device.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

56
Documentation/userspace-api/media/dvb/audio-continue.rst Normal file
View File

@@ -0,0 +1,56 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_CONTINUE:
==============
AUDIO_CONTINUE
==============
Name
----
AUDIO_CONTINUE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_CONTINUE)
:name: AUDIO_CONTINUE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This ioctl restarts the decoding and playing process previously paused
with AUDIO_PAUSE command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

63
Documentation/userspace-api/media/dvb/audio-fclose.rst Normal file
View File

@@ -0,0 +1,63 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _audio_fclose:
========================
Digital TV audio close()
========================
Name
----
Digital TV audio close()
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int close(int fd)
:name: dvb-audio-close
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This system call closes a previously opened audio device.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EBADF``
- fd is not a valid open file descriptor.

115
Documentation/userspace-api/media/dvb/audio-fopen.rst Normal file
View File

@@ -0,0 +1,115 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _audio_fopen:
=======================
Digital TV audio open()
=======================
Name
----
Digital TV audio open()
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int open(const char *deviceName, int flags)
:name: dvb-audio-open
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- const char \*deviceName
- Name of specific audio device.
- .. row 2
- int flags
- A bit-wise OR of the following flags:
- .. row 3
-
- O_RDONLY read-only access
- .. row 4
-
- O_RDWR read/write access
- .. row 5
-
- O_NONBLOCK open in non-blocking mode
- .. row 6
-
- (blocking mode is the default)
Description
-----------
This system call opens a named audio device (e.g.
/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
succeeded, the device will be ready for use. The significance of
blocking or non-blocking mode is described in the documentation for
functions where there is a difference. It does not affect the semantics
of the open() call itself. A device opened in blocking mode can later be
put into non-blocking mode (and vice versa) using the F_SETFL command
of the fcntl system call. This is a standard system call, documented in
the Linux manual page for fcntl. Only one user can open the Audio Device
in O_RDWR mode. All other attempts to open the device in this mode will
fail, and an error code will be returned. If the Audio Device is opened
in O_RDONLY mode, the only ioctl call that can be used is
AUDIO_GET_STATUS. All other call will return with an error code.
Return Value
------------
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``ENODEV``
- Device driver not loaded/available.
- .. row 2
- ``EBUSY``
- Device or resource busy.
- .. row 3
- ``EINVAL``
- Invalid argument.

91
Documentation/userspace-api/media/dvb/audio-fwrite.rst Normal file
View File

@@ -0,0 +1,91 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _audio_fwrite:
=========================
Digital TV audio write()
=========================
Name
----
Digital TV audio write()
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: size_t write(int fd, const void *buf, size_t count)
:name: dvb-audio-write
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- void \*buf
- Pointer to the buffer containing the PES data.
- .. row 3
- size_t count
- Size of buf.
Description
-----------
This system call can only be used if AUDIO_SOURCE_MEMORY is selected
in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
PES format. If O_NONBLOCK is not specified the function will block
until buffer space is available. The amount of data to be transferred is
implied by count.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EPERM``
- Mode AUDIO_SOURCE_MEMORY not selected.
- .. row 2
- ``ENOMEM``
- Attempted to write more data than the internal buffer can hold.
- .. row 3
- ``EBADF``
- fd is not a valid open file descriptor.

63
Documentation/userspace-api/media/dvb/audio-get-capabilities.rst Normal file
View File

@@ -0,0 +1,63 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_GET_CAPABILITIES:
======================
AUDIO_GET_CAPABILITIES
======================
Name
----
AUDIO_GET_CAPABILITIES
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap)
:name: AUDIO_GET_CAPABILITIES
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- unsigned int \*cap
- Returns a bit array of supported sound formats.
Description
-----------
This ioctl call asks the Audio Device to tell us about the decoding
capabilities of the audio hardware.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

63
Documentation/userspace-api/media/dvb/audio-get-status.rst Normal file
View File

@@ -0,0 +1,63 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_GET_STATUS:
================
AUDIO_GET_STATUS
================
Name
----
AUDIO_GET_STATUS
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status)
:name: AUDIO_GET_STATUS
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- struct audio_status \*status
- Returns the current state of Audio Device.
Description
-----------
This ioctl call asks the Audio Device to return the current state of the
Audio Device.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

57
Documentation/userspace-api/media/dvb/audio-pause.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_PAUSE:
===========
AUDIO_PAUSE
===========
Name
----
AUDIO_PAUSE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_PAUSE)
:name: AUDIO_PAUSE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This ioctl call suspends the audio stream being played. Decoding and
playing are paused. It is then possible to restart again decoding and
playing process of the audio stream using AUDIO_CONTINUE command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

56
Documentation/userspace-api/media/dvb/audio-play.rst Normal file
View File

@@ -0,0 +1,56 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_PLAY:
==========
AUDIO_PLAY
==========
Name
----
AUDIO_PLAY
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_PLAY)
:name: AUDIO_PLAY
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This ioctl call asks the Audio Device to start playing an audio stream
from the selected source.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

65
Documentation/userspace-api/media/dvb/audio-select-source.rst Normal file
View File

@@ -0,0 +1,65 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SELECT_SOURCE:
===================
AUDIO_SELECT_SOURCE
===================
Name
----
AUDIO_SELECT_SOURCE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source)
:name: AUDIO_SELECT_SOURCE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- audio_stream_source_t source
- Indicates the source that shall be used for the Audio stream.
Description
-----------
This ioctl call informs the audio device which source shall be used for
the input data. The possible sources are demux or memory. If
AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
through the write command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

67
Documentation/userspace-api/media/dvb/audio-set-av-sync.rst Normal file
View File

@@ -0,0 +1,67 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_AV_SYNC:
=================
AUDIO_SET_AV_SYNC
=================
Name
----
AUDIO_SET_AV_SYNC
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state)
:name: AUDIO_SET_AV_SYNC
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- boolean state
- Tells the Digital TV subsystem if A/V synchronization shall be ON or OFF.
TRUE: AV-sync ON
FALSE: AV-sync OFF
Description
-----------
This ioctl call asks the Audio Device to turn ON or OFF A/V
synchronization.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

70
Documentation/userspace-api/media/dvb/audio-set-bypass-mode.rst Normal file
View File

@@ -0,0 +1,70 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_BYPASS_MODE:
=====================
AUDIO_SET_BYPASS_MODE
=====================
Name
----
AUDIO_SET_BYPASS_MODE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode)
:name: AUDIO_SET_BYPASS_MODE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- boolean mode
- Enables or disables the decoding of the current Audio stream in
the Digital TV subsystem.
TRUE: Bypass is disabled
FALSE: Bypass is enabled
Description
-----------
This ioctl call asks the Audio Device to bypass the Audio decoder and
forward the stream without decoding. This mode shall be used if streams
that can’t be handled by the Digital TV system shall be decoded. Dolby
DigitalTM streams are automatically forwarded by the Digital TV subsystem if
the hardware can handle it.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

67
Documentation/userspace-api/media/dvb/audio-set-id.rst Normal file
View File

@@ -0,0 +1,67 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_ID:
============
AUDIO_SET_ID
============
Name
----
AUDIO_SET_ID
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id)
:name: AUDIO_SET_ID
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- int id
- audio sub-stream id
Description
-----------
This ioctl selects which sub-stream is to be decoded if a program or
system stream is sent to the video device. If no audio stream type is
set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
other stream types. If the stream type is set the id just specifies the
substream id of the audio stream and only the first 5 bits are
recognized.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

61
Documentation/userspace-api/media/dvb/audio-set-mixer.rst Normal file
View File

@@ -0,0 +1,61 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_MIXER:
===============
AUDIO_SET_MIXER
===============
Name
----
AUDIO_SET_MIXER
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix)
:name: AUDIO_SET_MIXER
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- audio_mixer_t \*mix
- mixer settings.
Description
-----------
This ioctl lets you adjust the mixer settings of the audio decoder.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

71
Documentation/userspace-api/media/dvb/audio-set-mute.rst Normal file
View File

@@ -0,0 +1,71 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_MUTE:
==============
AUDIO_SET_MUTE
==============
Name
----
AUDIO_SET_MUTE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state)
:name: AUDIO_SET_MUTE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- boolean state
- Indicates if audio device shall mute or not.
TRUE: Audio Mute
FALSE: Audio Un-mute
Description
-----------
This ioctl is for Digital TV devices only. To control a V4L2 decoder use the
V4L2 :ref:`VIDIOC_DECODER_CMD` with the
``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
This ioctl call asks the audio device to mute the stream that is
currently being played.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

77
Documentation/userspace-api/media/dvb/audio-set-streamtype.rst Normal file
View File

@@ -0,0 +1,77 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_SET_STREAMTYPE:
====================
AUDIO_SET_STREAMTYPE
====================
Name
----
AUDIO_SET_STREAMTYPE
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type)
:name: AUDIO_SET_STREAMTYPE
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
-
- int fd
- File descriptor returned by a previous call to open().
-
- int type
- stream type
Description
-----------
This ioctl tells the driver which kind of audio stream to expect. This
is useful if the stream offers several audio sub-streams like LPCM and
AC3.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- type is not a valid or supported stream type.

56
Documentation/userspace-api/media/dvb/audio-stop.rst Normal file
View File

@@ -0,0 +1,56 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _AUDIO_STOP:
==========
AUDIO_STOP
==========
Name
----
AUDIO_STOP
.. attention:: This ioctl is deprecated
Synopsis
--------
.. c:function:: int ioctl(int fd, AUDIO_STOP)
:name: AUDIO_STOP
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This ioctl call asks the Audio Device to stop playing the current
stream.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

34
Documentation/userspace-api/media/dvb/audio.rst Normal file
View File

@@ -0,0 +1,34 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dvb_audio:
#######################
Digital TV Audio Device
#######################
The Digital TV audio device controls the MPEG2 audio decoder of the Digital
TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
types and and ioctl definitions can be accessed by including
``linux/dvb/audio.h`` in your application.
Please note that some Digital TV cards don’t have their own MPEG decoder, which
results in the omission of the audio and video device.
These ioctls were also used by V4L2 to control MPEG decoders implemented
in V4L2. The use of these ioctls for that purpose has been made obsolete
and proper V4L2 ioctls or controls have been created to replace that
functionality.
.. toctree::
:maxdepth: 1
audio_data_types
audio_function_calls

123
Documentation/userspace-api/media/dvb/audio_data_types.rst Normal file
View File

@@ -0,0 +1,123 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _audio_data_types:
****************
Audio Data Types
****************
This section describes the structures, data types and defines used when
talking to the audio device.
.. c:type:: audio_stream_source
The audio stream source is set through the AUDIO_SELECT_SOURCE call
and can take the following values, depending on whether we are replaying
from an internal (demux) or external (user write) source.
.. code-block:: c
typedef enum {
AUDIO_SOURCE_DEMUX,
AUDIO_SOURCE_MEMORY
} audio_stream_source_t;
AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
frontend or the DVR device) as the source of the video stream. If
AUDIO_SOURCE_MEMORY is selected the stream comes from the application
through the ``write()`` system call.
.. c:type:: audio_play_state
The following values can be returned by the AUDIO_GET_STATUS call
representing the state of audio playback.
.. code-block:: c
typedef enum {
AUDIO_STOPPED,
AUDIO_PLAYING,
AUDIO_PAUSED
} audio_play_state_t;
.. c:type:: audio_channel_select
The audio channel selected via AUDIO_CHANNEL_SELECT is determined by
the following values.
.. code-block:: c
typedef enum {
AUDIO_STEREO,
AUDIO_MONO_LEFT,
AUDIO_MONO_RIGHT,
AUDIO_MONO,
AUDIO_STEREO_SWAPPED
} audio_channel_select_t;
.. c:type:: audio_status
The AUDIO_GET_STATUS call returns the following structure informing
about various states of the playback operation.
.. code-block:: c
typedef struct audio_status {
boolean AV_sync_state;
boolean mute_state;
audio_play_state_t play_state;
audio_stream_source_t stream_source;
audio_channel_select_t channel_select;
boolean bypass_mode;
audio_mixer_t mixer_state;
} audio_status_t;
.. c:type:: audio_mixer
The following structure is used by the AUDIO_SET_MIXER call to set the
audio volume.
.. code-block:: c
typedef struct audio_mixer {
unsigned int volume_left;
unsigned int volume_right;
} audio_mixer_t;
.. _audio_encodings:
audio encodings
===============
A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the
following bits set according to the hardwares capabilities.
.. code-block:: c
#define AUDIO_CAP_DTS 1
#define AUDIO_CAP_LPCM 2
#define AUDIO_CAP_MP1 4
#define AUDIO_CAP_MP2 8
#define AUDIO_CAP_MP3 16
#define AUDIO_CAP_AAC 32
#define AUDIO_CAP_OGG 64
#define AUDIO_CAP_SDDS 128
#define AUDIO_CAP_AC3 256

37
Documentation/userspace-api/media/dvb/audio_function_calls.rst Normal file
View File

@@ -0,0 +1,37 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _audio_function_calls:
********************
Audio Function Calls
********************
.. toctree::
:maxdepth: 1
audio-fopen
audio-fclose
audio-fwrite
audio-stop
audio-play
audio-pause
audio-continue
audio-select-source
audio-set-mute
audio-set-av-sync
audio-set-bypass-mode
audio-channel-select
audio-bilingual-channel-select
audio-get-status
audio-get-capabilities
audio-clear-buffer
audio-set-id
audio-set-mixer
audio-set-streamtype

50
Documentation/userspace-api/media/dvb/ca-fclose.rst Normal file
View File

@@ -0,0 +1,50 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _ca_fclose:
=====================
Digital TV CA close()
=====================
Name
----
Digital TV CA close()
Synopsis
--------
.. c:function:: int close(int fd)
:name: dvb-ca-close
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
Description
-----------
This system call closes a previously opened CA device.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

84
Documentation/userspace-api/media/dvb/ca-fopen.rst Normal file
View File

@@ -0,0 +1,84 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _ca_fopen:
====================
Digital TV CA open()
====================
Name
----
Digital TV CA open()
Synopsis
--------
.. c:function:: int open(const char *name, int flags)
:name: dvb-ca-open
Arguments
---------
``name``
Name of specific Digital TV CA device.
``flags``
A bit-wise OR of the following flags:
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``O_RDONLY``
- read-only access
- - ``O_RDWR``
- read/write access
- - ``O_NONBLOCK``
- open in non-blocking mode
(blocking mode is the default)
Description
-----------
This system call opens a named ca device (e.g. ``/dev/dvb/adapter?/ca?``)
for subsequent use.
When an ``open()`` call has succeeded, the device will be ready for use. The
significance of blocking or non-blocking mode is described in the
documentation for functions where there is a difference. It does not
affect the semantics of the ``open()`` call itself. A device opened in
blocking mode can later be put into non-blocking mode (and vice versa)
using the ``F_SETFL`` command of the ``fcntl`` system call. This is a
standard system call, documented in the Linux manual page for fcntl.
Only one user can open the CA Device in ``O_RDWR`` mode. All other
attempts to open the device in this mode will fail, and an error code
will be returned.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

53
Documentation/userspace-api/media/dvb/ca-get-cap.rst Normal file
View File

@@ -0,0 +1,53 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_GET_CAP:
==========
CA_GET_CAP
==========
Name
----
CA_GET_CAP
Synopsis
--------
.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)
:name: CA_GET_CAP
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
``caps``
Pointer to struct :c:type:`ca_caps`.
Description
-----------
Queries the Kernel for information about the available CA and descrambler
slots, and their types.
Return Value
------------
On success 0 is returned and :c:type:`ca_caps` is filled.
On error, -1 is returned and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

49
Documentation/userspace-api/media/dvb/ca-get-descr-info.rst Normal file
View File

@@ -0,0 +1,49 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_GET_DESCR_INFO:
=================
CA_GET_DESCR_INFO
=================
Name
----
CA_GET_DESCR_INFO
Synopsis
--------
.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)
:name: CA_GET_DESCR_INFO
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
``desc``
Pointer to struct :c:type:`ca_descr_info`.
Description
-----------
Returns information about all descrambler slots.
Return Value
------------
On success 0 is returned, and :c:type:`ca_descr_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

59
Documentation/userspace-api/media/dvb/ca-get-msg.rst Normal file
View File

@@ -0,0 +1,59 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_GET_MSG:
==========
CA_GET_MSG
==========
Name
----
CA_GET_MSG
Synopsis
--------
.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)
:name: CA_GET_MSG
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
``msg``
Pointer to struct :c:type:`ca_msg`.
Description
-----------
Receives a message via a CI CA module.
.. note::
Please notice that, on most drivers, this is done by reading from
the /dev/adapter?/ca? device node.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

64
Documentation/userspace-api/media/dvb/ca-get-slot-info.rst Normal file
View File

@@ -0,0 +1,64 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_GET_SLOT_INFO:
================
CA_GET_SLOT_INFO
================
Name
----
CA_GET_SLOT_INFO
Synopsis
--------
.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)
:name: CA_GET_SLOT_INFO
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
``info``
Pointer to struct :c:type:`ca_slot_info`.
Description
-----------
Returns information about a CA slot identified by
:c:type:`ca_slot_info`.slot_num.
Return Value
------------
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``ENODEV``
- the slot is not available.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

51
Documentation/userspace-api/media/dvb/ca-reset.rst Normal file
View File

@@ -0,0 +1,51 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_RESET:
========
CA_RESET
========
Name
----
CA_RESET
Synopsis
--------
.. c:function:: int ioctl(fd, CA_RESET)
:name: CA_RESET
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
Description
-----------
Puts the Conditional Access hardware on its initial state. It should
be called before start using the CA hardware.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

58
Documentation/userspace-api/media/dvb/ca-send-msg.rst Normal file
View File

@@ -0,0 +1,58 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_SEND_MSG:
===========
CA_SEND_MSG
===========
Name
----
CA_SEND_MSG
Synopsis
--------
.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)
:name: CA_SEND_MSG
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
``msg``
Pointer to struct :c:type:`ca_msg`.
Description
-----------
Sends a message via a CI CA module.
.. note::
Please notice that, on most drivers, this is done by writing
to the /dev/adapter?/ca? device node.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

53
Documentation/userspace-api/media/dvb/ca-set-descr.rst Normal file
View File

@@ -0,0 +1,53 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _CA_SET_DESCR:
============
CA_SET_DESCR
============
Name
----
CA_SET_DESCR
Synopsis
--------
.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)
:name: CA_SET_DESCR
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
``msg``
Pointer to struct :c:type:`ca_descr`.
Description
-----------
CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
keys (referred as control words).
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

32
Documentation/userspace-api/media/dvb/ca.rst Normal file
View File

@@ -0,0 +1,32 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dvb_ca:
####################
Digital TV CA Device
####################
The Digital TV CA device controls the conditional access hardware. It
can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl
definitions can be accessed by including ``linux/dvb/ca.h`` in your
application.
.. note::
There are three ioctls at this API that aren't documented:
:ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`.
Documentation for them are welcome.
.. toctree::
:maxdepth: 1
ca_data_types
ca_function_calls
ca_high_level

16
Documentation/userspace-api/media/dvb/ca_data_types.rst Normal file
View File

@@ -0,0 +1,16 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _ca_data_types:
*************
CA Data Types
*************
.. kernel-doc:: include/uapi/linux/dvb/ca.h

27
Documentation/userspace-api/media/dvb/ca_function_calls.rst Normal file
View File

@@ -0,0 +1,27 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _ca_function_calls:
*****************
CA Function Calls
*****************
.. toctree::
:maxdepth: 1
ca-fopen
ca-fclose
ca-reset
ca-get-cap
ca-get-slot-info
ca-get-descr-info
ca-get-msg
ca-send-msg
ca-set-descr

157
Documentation/userspace-api/media/dvb/ca_high_level.rst Normal file
View File

@@ -0,0 +1,157 @@
.. SPDX-License-Identifier: GPL-2.0
The High level CI API
=====================
.. note::
This documentation is outdated.
This document describes the high level CI API as in accordance to the
Linux DVB API.
With the High Level CI approach any new card with almost any random
architecture can be implemented with this style, the definitions
inside the switch statement can be easily adapted for any card, thereby
eliminating the need for any additional ioctls.
The disadvantage is that the driver/hardware has to manage the rest. For
the application programmer it would be as simple as sending/receiving an
array to/from the CI ioctls as defined in the Linux DVB API. No changes
have been made in the API to accommodate this feature.
Why the need for another CI interface?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is one of the most commonly asked question. Well a nice question.
Strictly speaking this is not a new interface.
The CI interface is defined in the DVB API in ca.h as:
.. code-block:: c
typedef struct ca_slot_info {
int num; /* slot number */
int type; /* CA interface this slot supports */
#define CA_CI 1 /* CI high level interface */
#define CA_CI_LINK 2 /* CI link layer level interface */
#define CA_CI_PHYS 4 /* CI physical layer level interface */
#define CA_DESCR 8 /* built-in descrambler */
#define CA_SC 128 /* simple smart card interface */
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2
} ca_slot_info_t;
This CI interface follows the CI high level interface, which is not
implemented by most applications. Hence this area is revisited.
This CI interface is quite different in the case that it tries to
accommodate all other CI based devices, that fall into the other categories.
This means that this CI interface handles the EN50221 style tags in the
Application layer only and no session management is taken care of by the
application. The driver/hardware will take care of all that.
This interface is purely an EN50221 interface exchanging APDU's. This
means that no session management, link layer or a transport layer do
exist in this case in the application to driver communication. It is
as simple as that. The driver/hardware has to take care of that.
With this High Level CI interface, the interface can be defined with the
regular ioctls.
All these ioctls are also valid for the High level CI interface
#define CA_RESET _IO('o', 128)
#define CA_GET_CAP _IOR('o', 129, ca_caps_t)
#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
#define CA_GET_MSG _IOR('o', 132, ca_msg_t)
#define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
#define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
On querying the device, the device yields information thus:
.. code-block:: none
CA_GET_SLOT_INFO
----------------------------
Command = [info]
APP: Number=[1]
APP: Type=[1]
APP: flags=[1]
APP: CI High level interface
APP: CA/CI Module Present
CA_GET_CAP
----------------------------
Command = [caps]
APP: Slots=[1]
APP: Type=[1]
APP: Descrambler keys=[16]
APP: Type=[1]
CA_SEND_MSG
----------------------------
Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
Found CA descriptor @ program level
(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
ca_message length is 25 (0x19) bytes
EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00]
Not all ioctl's are implemented in the driver from the API, the other
features of the hardware that cannot be implemented by the API are achieved
using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
used to exchange the data to maintain compatibility with other hardware.
.. code-block:: c
/* a message to/from a CI-CAM */
typedef struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
} ca_msg_t;
The flow of data can be described thus,
.. code-block:: none
App (User)
-----
parse
|
|
v
en50221 APDU (package)
--------------------------------------
| | | High Level CI driver
| | |
| v |
| en50221 APDU (unpackage) |
| | |
| | |
| v |
| sanity checks |
| | |
| | |
| v |
| do (H/W dep) |
--------------------------------------
| Hardware
|
v
The High Level CI interface uses the EN50221 DVB standard, following a
standard ensures futureproofness.

30
Documentation/userspace-api/media/dvb/demux.rst Normal file
View File

@@ -0,0 +1,30 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dvb_demux:
#######################
Digital TV Demux Device
#######################
The Digital TV demux device controls the MPEG-TS filters for the
digital TV. If the driver and hardware supports, those filters are
implemented at the hardware. Otherwise, the Kernel provides a software
emulation.
It can be accessed through ``/dev/adapter?/demux?``. Data types and and
ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in
your application.
.. toctree::
:maxdepth: 1
dmx_types
dmx_fcalls

56
Documentation/userspace-api/media/dvb/dmx-add-pid.rst Normal file
View File

@@ -0,0 +1,56 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_ADD_PID:
===========
DMX_ADD_PID
===========
Name
----
DMX_ADD_PID
Synopsis
--------
.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid)
:name: DMX_ADD_PID
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``pid``
PID number to be filtered.
Description
-----------
This ioctl call allows to add multiple PIDs to a transport stream filter
previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to
:c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

97
Documentation/userspace-api/media/dvb/dmx-expbuf.rst Normal file
View File

@@ -0,0 +1,97 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_EXPBUF:
****************
ioctl DMX_EXPBUF
****************
Name
====
DMX_EXPBUF - Export a buffer as a DMABUF file descriptor.
.. warning:: this API is still experimental
Synopsis
========
.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp )
:name: DMX_EXPBUF
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <dmx_fopen>`.
``argp``
Pointer to struct :c:type:`dmx_exportbuffer`.
Description
===========
This ioctl is an extension to the memory mapping I/O method.
It can be used to export a buffer as a DMABUF file at any time after
buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl.
To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`.
Applications must set the ``index`` field. Valid index numbers
range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS`
(struct :c:type:`dmx_requestbuffers` ``count``) minus one.
Additional flags may be posted in the ``flags`` field. Refer to a manual
for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
and O_RDWR are supported.
All other fields must be set to zero. In the
case of multi-planar API, every plane is exported separately using
multiple :ref:`DMX_EXPBUF` calls.
After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a
driver, on success. This is a DMABUF file descriptor. The application may
pass it to other DMABUF-aware devices. It is recommended to close a DMABUF
file when it is no longer used to allow the associated memory to be reclaimed.
Examples
========
.. code-block:: c
int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd)
{
struct dmx_exportbuffer expbuf;
memset(&expbuf, 0, sizeof(expbuf));
expbuf.type = bt;
expbuf.index = index;
if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) {
perror("DMX_EXPBUF");
return -1;
}
*dmafd = expbuf.fd;
return 0;
}
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EINVAL
A queue is not in MMAP mode or DMABUF exporting is not supported or
``flags`` or ``index`` fields are invalid.

52
Documentation/userspace-api/media/dvb/dmx-fclose.rst Normal file
View File

@@ -0,0 +1,52 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_fclose:
========================
Digital TV demux close()
========================
Name
----
Digital TV demux close()
Synopsis
--------
.. c:function:: int close(int fd)
:name: dvb-dmx-close
Arguments
---------
``fd``
File descriptor returned by a previous call to
:c:func:`open() <dvb-dmx-open>`.
Description
-----------
This system call deactivates and deallocates a filter that was
previously allocated via the :c:func:`open() <dvb-dmx-open>` call.
Return Value
------------
On success 0 is returned.
On error, -1 is returned and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

98
Documentation/userspace-api/media/dvb/dmx-fopen.rst Normal file
View File

@@ -0,0 +1,98 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_fopen:
=======================
Digital TV demux open()
=======================
Name
----
Digital TV demux open()
Synopsis
--------
.. c:function:: int open(const char *deviceName, int flags)
:name: dvb-dmx-open
Arguments
---------
``name``
Name of specific Digital TV demux device.
``flags``
A bit-wise OR of the following flags:
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
-
- ``O_RDONLY``
- read-only access
-
- ``O_RDWR``
- read/write access
-
- ``O_NONBLOCK``
- open in non-blocking mode
(blocking mode is the default)
Description
-----------
This system call, used with a device name of ``/dev/dvb/adapter?/demux?``,
allocates a new filter and returns a handle which can be used for
subsequent control of that filter. This call has to be made for each
filter to be used, i.e. every returned file descriptor is a reference to
a single filter. ``/dev/dvb/adapter?/dvr?`` is a logical device to be used
for retrieving Transport Streams for digital video recording. When
reading from this device a transport stream containing the packets from
all PES filters set in the corresponding demux device
(``/dev/dvb/adapter?/demux?``) having the output set to ``DMX_OUT_TS_TAP``.
A recorded Transport Stream is replayed by writing to this device.
The significance of blocking or non-blocking mode is described in the
documentation for functions where there is a difference. It does not
affect the semantics of the ``open()`` call itself. A device opened
in blocking mode can later be put into non-blocking mode (and vice versa)
using the ``F_SETFL`` command of the fcntl system call.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EMFILE``
- “Too many open files”, i.e. no more filters available.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

87
Documentation/userspace-api/media/dvb/dmx-fread.rst Normal file
View File

@@ -0,0 +1,87 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_fread:
=======================
Digital TV demux read()
=======================
Name
----
Digital TV demux read()
Synopsis
--------
.. c:function:: size_t read(int fd, void *buf, size_t count)
:name: dvb-dmx-read
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
``buf``
Buffer to be filled
``count``
Max number of bytes to read
Description
-----------
This system call returns filtered data, which might be section or Packetized
Elementary Stream (PES) data. The filtered data is transferred from
the driver’s internal circular buffer to ``buf``. The maximum amount of data
to be transferred is implied by count.
.. note::
if a section filter created with
:c:type:`DMX_CHECK_CRC <dmx_sct_filter_params>` flag set,
data that fails on CRC check will be silently ignored.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EWOULDBLOCK``
- No data to return and ``O_NONBLOCK`` was specified.
- - ``EOVERFLOW``
- The filtered data was not read from the buffer in due time,
resulting in non-read data being lost. The buffer is flushed.
- - ``ETIMEDOUT``
- The section was not loaded within the stated timeout period.
See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout.
- - ``EFAULT``
- The driver failed to write to the callers buffer due to an
invalid \*buf pointer.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

79
Documentation/userspace-api/media/dvb/dmx-fwrite.rst Normal file
View File

@@ -0,0 +1,79 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_fwrite:
========================
Digital TV demux write()
========================
Name
----
Digital TV demux write()
Synopsis
--------
.. c:function:: ssize_t write(int fd, const void *buf, size_t count)
:name: dvb-dmx-write
Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
``buf``
Buffer with data to be written
``count``
Number of bytes at the buffer
Description
-----------
This system call is only provided by the logical device
``/dev/dvb/adapter?/dvr?``, associated with the physical demux device that
provides the actual DVR functionality. It is used for replay of a
digitally recorded Transport Stream. Matching filters have to be defined
in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``.
The amount of data to be transferred is implied by count.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EWOULDBLOCK``
- No data was written. This might happen if ``O_NONBLOCK`` was
specified and there is no more buffer space available (if
``O_NONBLOCK`` is not specified the function will block until buffer
space is available).
- - ``EBUSY``
- This error code indicates that there are conflicting requests. The
corresponding demux device is setup to receive data from the
front- end. Make sure that these filters are stopped and that the
filters with input set to ``DMX_IN_DVR`` are started.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

71
Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst Normal file
View File

@@ -0,0 +1,71 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_GET_PES_PIDS:
================
DMX_GET_PES_PIDS
================
Name
----
DMX_GET_PES_PIDS
Synopsis
--------
.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])
:name: DMX_GET_PES_PIDS
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``pids``
Array used to store 5 Program IDs.
Description
-----------
This ioctl allows to query a DVB device to return the first PID used
by audio, video, textext, subtitle and PCR programs on a given service.
They're stored as:
======================= ======== =======================================
PID element position content
======================= ======== =======================================
pids[DMX_PES_AUDIO] 0 first audio PID
pids[DMX_PES_VIDEO] 1 first video PID
pids[DMX_PES_TELETEXT] 2 first teletext PID
pids[DMX_PES_SUBTITLE] 3 first subtitle PID
pids[DMX_PES_PCR] 4 first Program Clock Reference PID
======================= ======== =======================================
.. note::
A value equal to 0xffff means that the PID was not filled by the
Kernel.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

73
Documentation/userspace-api/media/dvb/dmx-get-stc.rst Normal file
View File

@@ -0,0 +1,73 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_GET_STC:
===========
DMX_GET_STC
===========
Name
----
DMX_GET_STC
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc)
:name: DMX_GET_STC
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``stc``
Pointer to :c:type:`dmx_stc` where the stc data is to be stored.
Description
-----------
This ioctl call returns the current value of the system time counter
(which is driven by a PES filter of type :c:type:`DMX_PES_PCR <dmx_ts_pes>`).
Some hardware supports more than one STC, so you must specify which one by
setting the :c:type:`num <dmx_stc>` field of stc before the ioctl (range 0...n).
The result is returned in form of a ratio with a 64 bit numerator
and a 32 bit denominator, so the real 90kHz STC value is
``stc->stc / stc->base``.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
- ``EINVAL``
- Invalid stc number.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

125
Documentation/userspace-api/media/dvb/dmx-mmap.rst Normal file
View File

@@ -0,0 +1,125 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx-mmap:
*****************
Digital TV mmap()
*****************
Name
====
dmx-mmap - Map device memory into application address space
.. warning:: this API is still experimental
Synopsis
========
.. code-block:: c
#include <unistd.h>
#include <sys/mman.h>
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
:name: dmx-mmap
Arguments
=========
``start``
Map the buffer to this address in the application's address space.
When the ``MAP_FIXED`` flag is specified, ``start`` must be a
multiple of the pagesize and mmap will fail when the specified
address cannot be used. Use of this option is discouraged;
applications should just specify a ``NULL`` pointer here.
``length``
Length of the memory area to map. This must be a multiple of the
DVB packet length (188, on most drivers).
``prot``
The ``prot`` argument describes the desired memory protection.
Regardless of the device type and the direction of data exchange it
should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
and write access to image buffers. Drivers should support at least
this combination of flags.
``flags``
The ``flags`` parameter specifies the type of the mapped object,
mapping options and whether modifications made to the mapped copy of
the page are private to the process or are to be shared with other
references.
``MAP_FIXED`` requests that the driver selects no other address than
the one specified. If the specified address cannot be used,
:ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified,
``start`` must be a multiple of the pagesize. Use of this option is
discouraged.
One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
``MAP_SHARED`` allows applications to share the mapped memory with
other (e. g. child-) processes.
.. note::
The Linux Digital TV applications should not set the
``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
flags.
``fd``
File descriptor returned by :ref:`open() <dmx_fopen>`.
``offset``
Offset of the buffer in device memory, as returned by
:ref:`DMX_QUERYBUF` ioctl.
Description
===========
The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at
``offset`` in the memory of the device specified by ``fd`` into the
application address space, preferably at address ``start``. This latter
address is a hint only, and is usually specified as 0.
Suitable length and offset parameters are queried with the
:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the
:ref:`DMX_REQBUFS` ioctl before they can be queried.
To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used.
Return Value
============
On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
appropriately. Possible error codes are:
EBADF
``fd`` is not a valid file descriptor.
EACCES
``fd`` is not open for reading and writing.
EINVAL
The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
they are too large, or not aligned on a ``PAGESIZE`` boundary.)
The ``flags`` or ``prot`` value is not supported.
No buffers have been allocated with the
:ref:`DMX_REQBUFS` ioctl.
ENOMEM
Not enough physical or virtual memory was available to complete the
request.

63
Documentation/userspace-api/media/dvb/dmx-munmap.rst Normal file
View File

@@ -0,0 +1,63 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx-munmap:
************
DVB munmap()
************
Name
====
dmx-munmap - Unmap device memory
.. warning:: This API is still experimental.
Synopsis
========
.. code-block:: c
#include <unistd.h>
#include <sys/mman.h>
.. c:function:: int munmap( void *start, size_t length )
:name: dmx-munmap
Arguments
=========
``start``
Address of the mapped buffer as returned by the
:ref:`mmap() <dmx-mmap>` function.
``length``
Length of the mapped buffer. This must be the same value as given to
:ref:`mmap() <dmx-mmap>`.
Description
===========
Unmaps a previously with the :ref:`mmap() <dmx-mmap>` function mapped
buffer and frees it, if possible.
Return Value
============
On success :ref:`munmap() <dmx-munmap>` returns 0, on failure -1 and the
``errno`` variable is set appropriately:
EINVAL
The ``start`` or ``length`` is incorrect, or no buffers have been
mapped yet.

93
Documentation/userspace-api/media/dvb/dmx-qbuf.rst Normal file
View File

@@ -0,0 +1,93 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_QBUF:
*************************
ioctl DMX_QBUF, DMX_DQBUF
*************************
Name
====
DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
.. warning:: this API is still experimental
Synopsis
========
.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp )
:name: DMX_QBUF
.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp )
:name: DMX_DQBUF
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <dmx_fopen>`.
``argp``
Pointer to struct :c:type:`dmx_buffer`.
Description
===========
Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
(capturing) or filled (output) buffer in the driver's incoming queue.
The semantics depend on the selected I/O method.
To enqueue a buffer applications set the ``index`` field. Valid index
numbers range from zero to the number of buffers allocated with
:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
one. The contents of the struct :c:type:`dmx_buffer` returned
by a :ref:`DMX_QUERYBUF` ioctl will do as well.
When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
memory pages of the buffer in physical memory, so they cannot be swapped
out to disk. Buffers remain locked until dequeued, until the
the device is closed.
Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled
(capturing) buffer from the driver's outgoing queue.
They just set the ``index`` field with the buffer ID to be queued.
When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`,
the driver fills the remaining fields or returns an error code.
By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
queue. When the ``O_NONBLOCK`` flag was given to the
:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
immediately with an ``EAGAIN`` error code when no buffer is available.
The struct :c:type:`dmx_buffer` structure is specified in
:ref:`buffer`.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EAGAIN
Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
buffer was in the outgoing queue.
EINVAL
The ``index`` is out of bounds, or no buffers have been allocated yet.
EIO
``DMX_DQBUF`` failed due to an internal error. Can also indicate
temporary problems like signal loss or CRC errors.

72
Documentation/userspace-api/media/dvb/dmx-querybuf.rst Normal file
View File

@@ -0,0 +1,72 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_QUERYBUF:
******************
ioctl DMX_QUERYBUF
******************
Name
====
DMX_QUERYBUF - Query the status of a buffer
.. warning:: this API is still experimental
Synopsis
========
.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp )
:name: DMX_QUERYBUF
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <dmx_fopen>`.
``argp``
Pointer to struct :c:type:`dvb_buffer`.
Description
===========
This ioctl is part of the mmap streaming I/O method. It can
be used to query the status of a buffer at any time after buffers have
been allocated with the :ref:`DMX_REQBUFS` ioctl.
Applications set the ``index`` field. Valid index numbers range from zero
to the number of buffers allocated with :ref:`DMX_REQBUFS`
(struct :c:type:`dvb_requestbuffers` ``count``) minus one.
After calling :ref:`DMX_QUERYBUF` with a pointer to this structure,
drivers return an error code or fill the rest of the structure.
On success, the ``offset`` will contain the offset of the buffer from the
start of the device memory, the ``length`` field its size, and the
``bytesused`` the number of bytes occupied by data in the buffer (payload).
Return Value
============
On success 0 is returned, the ``offset`` will contain the offset of the
buffer from the start of the device memory, the ``length`` field its size,
and the ``bytesused`` the number of bytes occupied by data in the buffer
(payload).
On error it returns -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EINVAL
The ``index`` is out of bounds.

57
Documentation/userspace-api/media/dvb/dmx-remove-pid.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_REMOVE_PID:
==============
DMX_REMOVE_PID
==============
Name
----
DMX_REMOVE_PID
Synopsis
--------
.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)
:name: DMX_REMOVE_PID
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``pid``
PID of the PES filter to be removed.
Description
-----------
This ioctl call allows to remove a PID when multiple PIDs are set on a
transport stream filter, e. g. a filter previously set up with output
equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`, created via either
:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

83
Documentation/userspace-api/media/dvb/dmx-reqbufs.rst Normal file
View File

@@ -0,0 +1,83 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_REQBUFS:
*****************
ioctl DMX_REQBUFS
*****************
Name
====
DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O
.. warning:: this API is still experimental
Synopsis
========
.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp )
:name: DMX_REQBUFS
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <dmx_fopen>`.
``argp``
Pointer to struct :c:type:`dmx_requestbuffers`.
Description
===========
This ioctl is used to initiate a memory mapped or DMABUF based demux I/O.
Memory mapped buffers are located in device memory and must be allocated
with this ioctl before they can be mapped into the application's address
space. User buffers are allocated by applications themselves, and this
ioctl is merely used to switch the driver into user pointer I/O mode and
to setup some internal structures. Similarly, DMABUF buffers are
allocated by applications through a device driver, and this ioctl only
configures the driver into DMABUF I/O mode without performing any direct
allocation.
To allocate device buffers applications initialize all fields of the
struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field
to the desired number of buffers, and ``size`` to the size of each
buffer.
When the ioctl is called with a pointer to this structure, the driver will
attempt to allocate the requested number of buffers and it stores the actual
number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger
number is also possible when the driver requires more buffers to
function correctly. The actual allocated buffer size can is returned
at ``size``, and can be smaller than what's requested.
When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP``
error code.
Applications can call :ref:`DMX_REQBUFS` again to change the number of
buffers, however this cannot succeed when any buffers are still mapped.
A ``count`` value of zero frees all buffers, after aborting or finishing
any DMA in progress.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EOPNOTSUPP
The the requested I/O method is not supported.

57
Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_SET_BUFFER_SIZE:
===================
DMX_SET_BUFFER_SIZE
===================
Name
----
DMX_SET_BUFFER_SIZE
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size)
:name: DMX_SET_BUFFER_SIZE
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``size``
Unsigned long size
Description
-----------
This ioctl call is used to set the size of the circular buffer used for
filtered data. The default size is two maximum sized sections, i.e. if
this function is not called a buffer size of ``2 * 4096`` bytes will be
used.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

64
Documentation/userspace-api/media/dvb/dmx-set-filter.rst Normal file
View File

@@ -0,0 +1,64 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_SET_FILTER:
==============
DMX_SET_FILTER
==============
Name
----
DMX_SET_FILTER
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)
:name: DMX_SET_FILTER
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``params``
Pointer to structure containing filter parameters.
Description
-----------
This ioctl call sets up a filter according to the filter and mask
parameters provided. A timeout may be defined stating number of seconds
to wait for a section to be loaded. A value of 0 means that no timeout
should be applied. Finally there is a flag field where it is possible to
state whether a section should be CRC-checked, whether the filter should
be a ”one-shot” filter, i.e. if the filtering operation should be
stopped after the first section is received, and whether the filtering
operation should be started immediately (without waiting for a
:ref:`DMX_START` ioctl call). If a filter was previously set-up, this
filter will be canceled, and the receive buffer will be flushed.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

76
Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst Normal file
View File

@@ -0,0 +1,76 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_SET_PES_FILTER:
==================
DMX_SET_PES_FILTER
==================
Name
----
DMX_SET_PES_FILTER
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)
:name: DMX_SET_PES_FILTER
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``params``
Pointer to structure containing filter parameters.
Description
-----------
This ioctl call sets up a PES filter according to the parameters
provided. By a PES filter is meant a filter that is based just on the
packet identifier (PID), i.e. no PES header or payload filtering
capability is supported.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
- ``EBUSY``
- This error code indicates that there are conflicting requests.
There are active filters filtering data from another input source.
Make sure that these filters are stopped before starting this
filter.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

75
Documentation/userspace-api/media/dvb/dmx-start.rst Normal file
View File

@@ -0,0 +1,75 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_START:
=========
DMX_START
=========
Name
----
DMX_START
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_START)
:name: DMX_START
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
Description
-----------
This ioctl call is used to start the actual filtering operation defined
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- Invalid argument, i.e. no filtering parameters provided via the
:ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls.
- .. row 2
- ``EBUSY``
- This error code indicates that there are conflicting requests.
There are active filters filtering data from another input source.
Make sure that these filters are stopped before starting this
filter.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

52
Documentation/userspace-api/media/dvb/dmx-stop.rst Normal file
View File

@@ -0,0 +1,52 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _DMX_STOP:
========
DMX_STOP
========
Name
----
DMX_STOP
Synopsis
--------
.. c:function:: int ioctl( int fd, DMX_STOP)
:name: DMX_STOP
Arguments
---------
``fd``
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
Description
-----------
This ioctl call is used to stop the actual filtering operation defined
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and
started via the :ref:`DMX_START` command.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

37
Documentation/userspace-api/media/dvb/dmx_fcalls.rst Normal file
View File

@@ -0,0 +1,37 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_fcalls:
********************
Demux Function Calls
********************
.. toctree::
:maxdepth: 1
dmx-fopen
dmx-fclose
dmx-fread
dmx-fwrite
dmx-mmap
dmx-munmap
dmx-start
dmx-stop
dmx-set-filter
dmx-set-pes-filter
dmx-set-buffer-size
dmx-get-stc
dmx-get-pes-pids
dmx-add-pid
dmx-remove-pid
dmx-reqbufs
dmx-querybuf
dmx-expbuf
dmx-qbuf

16
Documentation/userspace-api/media/dvb/dmx_types.rst Normal file
View File

@@ -0,0 +1,16 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dmx_types:
****************
Demux Data Types
****************
.. kernel-doc:: include/uapi/linux/dvb/dmx.h

32
Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst Normal file
View File

@@ -0,0 +1,32 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dvb-fe-read-status:
***************************************
Querying frontend status and statistics
***************************************
Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the
frontend will run a kernel thread that will periodically check for the
tuner lock status and provide statistics about the quality of the
signal.
The information about the frontend tuner locking status can be queried
using :ref:`FE_READ_STATUS`.
Signal statistics are provided via
:ref:`FE_GET_PROPERTY`.
.. note::
Most statistics require the demodulator to be fully locked
(e. g. with :c:type:`FE_HAS_LOCK <fe_status>` bit set). See
:ref:`Frontend statistics indicators <frontend-stat-properties>` for
more details.

22
Documentation/userspace-api/media/dvb/dvb-frontend-event.rst Normal file
View File

@@ -0,0 +1,22 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. c:type:: dvb_frontend_event
***************
frontend events
***************
.. code-block:: c
struct dvb_frontend_event {
fe_status_t status;
struct dvb_frontend_parameters parameters;
};

126
Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst Normal file
View File

@@ -0,0 +1,126 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. c:type:: dvb_frontend_parameters
*******************
frontend parameters
*******************
The kind of parameters passed to the frontend device for tuning depend
on the kind of hardware you are using.
The struct ``dvb_frontend_parameters`` uses a union with specific
per-system parameters. However, as newer delivery systems required more
data, the structure size weren't enough to fit, and just extending its
size would break the existing applications. So, those parameters were
replaced by the usage of
:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
ioctl's. The new API is flexible enough to add new parameters to
existing delivery systems, and to add newer delivery systems.
So, newer applications should use
:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
instead, in order to be able to support the newer System Delivery like
DVB-S2, DVB-T2, DVB-C2, ISDB, etc.
All kinds of parameters are combined as a union in the
``dvb_frontend_parameters`` structure:
.. code-block:: c
struct dvb_frontend_parameters {
uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */
/* intermediate frequency in kHz for QPSK */
fe_spectral_inversion_t inversion;
union {
struct dvb_qpsk_parameters qpsk;
struct dvb_qam_parameters qam;
struct dvb_ofdm_parameters ofdm;
struct dvb_vsb_parameters vsb;
} u;
};
In the case of QPSK frontends the ``frequency`` field specifies the
intermediate frequency, i.e. the offset which is effectively added to
the local oscillator frequency (LOF) of the LNB. The intermediate
frequency has to be specified in units of kHz. For QAM and OFDM
frontends the ``frequency`` specifies the absolute frequency and is
given in Hz.
.. c:type:: dvb_qpsk_parameters
QPSK parameters
===============
For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters``
structure:
.. code-block:: c
struct dvb_qpsk_parameters {
uint32_t symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
};
.. c:type:: dvb_qam_parameters
QAM parameters
==============
for cable QAM frontend you use the ``dvb_qam_parameters`` structure:
.. code-block:: c
struct dvb_qam_parameters {
uint32_t symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
fe_modulation_t modulation; /* modulation type (see above) */
};
.. c:type:: dvb_vsb_parameters
VSB parameters
==============
ATSC frontends are supported by the ``dvb_vsb_parameters`` structure:
.. code-block:: c
struct dvb_vsb_parameters {
fe_modulation_t modulation; /* modulation type (see above) */
};
.. c:type:: dvb_ofdm_parameters
OFDM parameters
===============
DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure:
.. code-block:: c
struct dvb_ofdm_parameters {
fe_bandwidth_t bandwidth;
fe_code_rate_t code_rate_HP; /* high priority stream code rate */
fe_code_rate_t code_rate_LP; /* low priority stream code rate */
fe_modulation_t constellation; /* modulation type (see above) */
fe_transmit_mode_t transmission_mode;
fe_guard_interval_t guard_interval;
fe_hierarchy_t hierarchy_information;
};

126
Documentation/userspace-api/media/dvb/dvbapi.rst Normal file
View File

@@ -0,0 +1,126 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. include:: <isonum.txt>
.. _dvbapi:
########################
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**
.. only:: html
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
intro
frontend
demux
ca
net
legacy_dvb_apis
examples
headers
**********************
Revision and Copyright
**********************
Authors:
- J. K. Metzler, Ralph <rjkm@metzlerbros.de>
- Original author of the Digital TV API documentation.
- O. C. 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** |copy| 2002-2003 : Convergence GmbH
**Copyright** |copy| 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.

133
Documentation/userspace-api/media/dvb/dvbproperty.rst Normal file
View File

@@ -0,0 +1,133 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _frontend-properties:
**************
Property types
**************
Tuning into a Digital TV physical channel and starting decoding it
requires changing a set of parameters, in order to control the tuner,
the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
antenna subsystem via Satellite Equipment Control - SEC (on satellite
systems). The actual parameters are specific to each particular digital
TV standards, and may change as the digital TV specs evolves.
In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a
union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and
ATSC delivery systems grouped there. The problem is that, as the second
generation standards appeared, the size of such union was not big
enough to group the structs that would be required for those new
standards. Also, extending it would break userspace.
So, the legacy union/struct based approach was deprecated, in favor
of a properties set approach. On such approach,
:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
to setup the frontend and read its status.
The actual action is determined by a set of dtv_property cmd/data pairs.
With one single ioctl, is possible to get/set up to 64 properties.
This section describes the new and recommended way to set the frontend,
with supports all digital TV delivery systems.
.. note::
1. On Linux DVB API version 3, setting a frontend was done via
struct :c:type:`dvb_frontend_parameters`.
2. Don't use DVB API version 3 calls on hardware with supports
newer standards. Such API provides no support or a very limited
support to new standards and/or new hardware.
3. Nowadays, most frontends support multiple delivery systems.
Only with DVB API version 5 calls it is possible to switch between
the multiple delivery systems supported by a frontend.
4. DVB API version 5 is also called *S2API*, as the first
new standard added to it was DVB-S2.
**Example**: in order to set the hardware to tune into a DVB-C channel
at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217
Mbauds, those properties should be sent to
:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A
:ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
:ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
:ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
:ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
:ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
:ref:`DTV_TUNE <DTV-TUNE>`
The code that would that would do the above is show in
:ref:`dtv-prop-example`.
.. code-block:: c
:caption: Example: Setting digital TV frontend properties
:name: dtv-prop-example
#include <stdio.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/dvb/frontend.h>
static struct dtv_property props[] = {
{ .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
{ .cmd = DTV_FREQUENCY, .u.data = 651000000 },
{ .cmd = DTV_MODULATION, .u.data = QAM_256 },
{ .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
{ .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
{ .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
{ .cmd = DTV_TUNE }
};
static struct dtv_properties dtv_prop = {
.num = 6, .props = props
};
int main(void)
{
int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
if (!fd) {
perror ("open");
return -1;
}
if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
perror("ioctl");
return -1;
}
printf("Frontend set\\n");
return 0;
}
.. attention:: While it is possible to directly call the Kernel code like the
above example, it is strongly recommended to use
`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
provides abstraction to work with the supported digital TV standards and
provides methods for usual operations like program scanning and to
read/write channel descriptor files.
.. toctree::
:maxdepth: 1
fe_property_parameters
frontend-stat-properties
frontend-property-terrestrial-systems
frontend-property-cable-systems
frontend-property-satellite-systems
frontend-header

43
Documentation/userspace-api/media/dvb/dvbstb.svg Normal file
View File

@@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is dual-licensed: you can use it either under the terms
of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this
dual licensing only applies to this file, and not this project as a
whole.
a) This file 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 version 2 of
the License.
This file 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.
Or, alternatively,
b) Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation, with no Invariant Sections, no Front-Cover Texts
and no Back-Cover Texts. A copy of the license is included at
Documentation/userspace-api/media/fdl-appendix.rst.
TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
-->
<svg id="svg2" width="15.847cm" height="8.4187cm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 23770.123 12628.122" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><defs id="defs142"><marker id="Arrow1Lend" overflow="visible" orient="auto"><path id="path954" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker><marker id="marker1243" overflow="visible" orient="auto"><path id="path1241" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker></defs><metadata id="metadata519"><rdf:RDF><cc:Work
rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><rect id="rect197" class="BoundingBox" x="5355.1" y="13.122" width="18403" height="9603" fill="none"/><path id="path199" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="#fff"/><path id="path201" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="none" stroke="#000"/><rect id="rect206" class="BoundingBox" x="13.122" y="4013.1" width="4544" height="2403" fill="none"/><path id="path208" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path210" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text212" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition"
x="1281.1219" y="5435.1221"><tspan id="tspan218" fill="#000000">Antena</tspan></tspan></tspan></text>
<rect id="rect223" class="BoundingBox" x="6213.1" y="1813.1" width="4544" height="2403" fill="none"/><path id="path225" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path227" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text229" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan231" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan233" class="TextPosition" x="7217.1221" y="3235.1221"><tspan id="tspan235" fill="#000000">Frontend</tspan></tspan></tspan></text>
<rect id="rect240" class="BoundingBox" x="12113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path242" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path244" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text246" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan248" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan250" class="TextPosition" x="13944.122" y="3235.1221"><tspan id="tspan252" fill="#000000">CA</tspan></tspan></tspan></text>
<rect id="rect257" class="BoundingBox" x="18113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path259" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path261" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text263" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan265" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan267" class="TextPosition" x="19384.123" y="3235.1221"><tspan id="tspan269" fill="#000000">Demux</tspan></tspan></tspan></text>
<rect id="rect274" class="BoundingBox" x="6113.1" y="5813.1" width="4544" height="2403" fill="none"/><path id="path276" d="m8385.1 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path278" d="m8385.1 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text280" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan282" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan284" class="TextPosition" x="7733.1221" y="7235.1221"><tspan id="tspan286" fill="#000000">SEC</tspan></tspan></tspan></text>
<rect id="rect291" class="BoundingBox" x="12213" y="5813.1" width="4544" height="2403" fill="none"/><path id="path293" d="m14485 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path295" d="m14485 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text297" class="TextShape" x="-2443.8779" y="-4903.3779"><tspan id="tspan299" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan301" class="TextPosition" x="13676.122" y="6917.6221"><tspan id="tspan303" fill="#000000">Audio</tspan></tspan></tspan></text>
<rect id="rect308" class="BoundingBox" x="18113" y="5813.1" width="4544" height="2403" fill="none"/><path id="path310" d="m20385 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path312" d="m20385 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text314" class="TextShape" x="-2443.8779" y="-4903.3779"><tspan id="tspan316" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan318" class="TextPosition" x="19583.123" y="6917.6221"><tspan id="tspan320" fill="#000000">Video</tspan></tspan></tspan></text>
<rect id="rect325" class="BoundingBox" x="15213" y="10213" width="4544" height="2403" fill="none"/><path id="path327" d="m17485 12614h-2271v-2400h4541v2400z" fill="#fff"/><path id="path329" d="m17485 12614h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text331" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan333" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan335" class="TextPosition" x="17076.123" y="11635.122"><tspan id="tspan337" fill="#000000">TV</tspan></tspan></tspan></text>
<rect id="rect342" class="BoundingBox" x="4555.1" y="3014.1" width="1661" height="2202" fill="none"/><path id="path344" d="m4556.1 5214.1 1400-1857" fill="none" stroke="#000"/><path id="path346" d="m6215.1 3014.1-391 269 240 181z"/><rect id="rect351" class="BoundingBox" x="4555.1" y="5213.1" width="1561" height="1802" fill="none"/><path id="path353" d="m4556.1 5214.1 1277 1475" fill="none" stroke="#000"/><path id="path355" d="m6115.1 7014.1-181-438-227 196z"/><rect id="rect360" class="BoundingBox" x="10755" y="2864.1" width="1361" height="301" fill="none"/><path id="path362" d="m10756 3014.1h929" fill="none" stroke="#000"/><path id="path364" d="m12115 3014.1-450-150v300z"/><rect id="rect369" class="BoundingBox" x="16655" y="2864.1" width="1461" height="301" fill="none"/><path id="path371" d="m16656 3014.1h1029" fill="none" stroke="#000"/><path id="path373" d="m18115
3014.1-450-150v300z"/><rect id="rect378" class="BoundingBox" x="20235" y="4213.1" width="301" height="1602" fill="none"/><rect id="rect387" class="BoundingBox" x="17485" y="8213.1" width="2902" height="2002" fill="none"/><path id="path389" d="m20385 8214.1-2546 1756" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><path id="path391" d="m17485 10214 456-132-171-247z"/><rect id="rect396" class="BoundingBox" x="14484" y="8213.1" width="3002" height="2002" fill="none"/><path id="path398" d="m14485 8214.1 2642 1761" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><path id="path400" d="m17485 10214-291-374-167 249z"/><rect id="rect405" class="BoundingBox" x="14485" y="4213.1" width="5902" height="1629" fill="none"/><path id="path949" d="m20387 4213.1v1629" fill="none" marker-end="url(#Arrow1Lend)"
stroke="#000" stroke-dasharray="26.45879596, 52.91759192999999328" stroke-linejoin="miter" stroke-width="26.459"/><path id="path1233" d="m20385 4214.1-3628 1599" fill="none" marker-end="url(#marker1243)" stroke="#000" stroke-dasharray="26.45879596, 52.91759193" stroke-linejoin="miter" stroke-width="26.459"/><text id="text297-3" class="TextShape" x="-2911.9202" y="-4257.2061" font-size="12px" stroke-width="1"><tspan id="tspan299-6" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400" stroke-width="1"><tspan id="tspan301-7" class="TextPosition" x="13208.079" y="7563.793" stroke-width="1"><tspan id="tspan303-5" fill="#000000" stroke-width="1">Decoder</tspan></tspan></tspan></text>
<text id="text297-3-3" class="TextShape" x="2950.9287" y="-4259.5928" font-size="12px" stroke-width="1"><tspan id="tspan299-6-5" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400" stroke-width="1"><tspan id="tspan301-7-6" class="TextPosition" x="19070.928" y="7561.4053" stroke-width="1"><tspan id="tspan303-5-2" fill="#000000" stroke-width="1">Decoder</tspan></tspan></tspan></text>
</svg>

23
Documentation/userspace-api/media/dvb/examples.rst Normal file
View File

@@ -0,0 +1,23 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _dvb_examples:
********
Examples
********
In the past, we used to have a set of examples here. However, those
examples got out of date and doesn't even compile nowadays.
Also, nowadays, the best is to use the libdvbv5 DVB API nowadays,
with is fully documented.
Please refer to the `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__
for updated/recommended examples.

81
Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst Normal file
View File

@@ -0,0 +1,81 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
******************
Frontend bandwidth
******************
.. c:type:: fe_bandwidth
.. flat-table:: enum fe_bandwidth
:header-rows: 1
:stub-columns: 0
- .. row 1
- ID
- Description
- .. row 2
- .. _BANDWIDTH-AUTO:
``BANDWIDTH_AUTO``
- Autodetect bandwidth (if supported)
- .. row 3
- .. _BANDWIDTH-1-712-MHZ:
``BANDWIDTH_1_712_MHZ``
- 1.712 MHz
- .. row 4
- .. _BANDWIDTH-5-MHZ:
``BANDWIDTH_5_MHZ``
- 5 MHz
- .. row 5
- .. _BANDWIDTH-6-MHZ:
``BANDWIDTH_6_MHZ``
- 6 MHz
- .. row 6
- .. _BANDWIDTH-7-MHZ:
``BANDWIDTH_7_MHZ``
- 7 MHz
- .. row 7
- .. _BANDWIDTH-8-MHZ:
``BANDWIDTH_8_MHZ``
- 8 MHz
- .. row 8
- .. _BANDWIDTH-10-MHZ:
``BANDWIDTH_10_MHZ``
- 10 MHz

55
Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst Normal file
View File

@@ -0,0 +1,55 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_DISEQC_RECV_SLAVE_REPLY:
********************************
ioctl FE_DISEQC_RECV_SLAVE_REPLY
********************************
Name
====
FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command
Synopsis
========
.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp )
:name: FE_DISEQC_RECV_SLAVE_REPLY
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
pointer to struct :c:type:`dvb_diseqc_slave_reply`.
Description
===========
Receives reply from a DiSEqC 2.0 command.
The received message is stored at the buffer pointed by ``argp``.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

53
Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst Normal file
View File

@@ -0,0 +1,53 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_DISEQC_RESET_OVERLOAD:
******************************
ioctl FE_DISEQC_RESET_OVERLOAD
******************************
Name
====
FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL )
:name: FE_DISEQC_RESET_OVERLOAD
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
Description
===========
If the bus has been automatically powered off due to power overload,
this ioctl call restores the power to the bus. The call requires
read/write access to the device. This call has no effect if the device
is manually powered off. Not all Digital TV adapters support this ioctl.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

59
Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst Normal file
View File

@@ -0,0 +1,59 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_DISEQC_SEND_BURST:
**************************
ioctl FE_DISEQC_SEND_BURST
**************************
Name
====
FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone )
:name: FE_DISEQC_SEND_BURST
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``tone``
An integer enumered value described at :c:type:`fe_sec_mini_cmd`.
Description
===========
This ioctl is used to set the generation of a 22kHz tone burst for mini
DiSEqC satellite selection for 2x1 switches. This call requires
read/write permissions.
It provides support for what's specified at
`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

56
Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst Normal file
View File

@@ -0,0 +1,56 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_DISEQC_SEND_MASTER_CMD:
*******************************
ioctl FE_DISEQC_SEND_MASTER_CMD
*******************************
Name
====
FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command
Synopsis
========
.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp )
:name: FE_DISEQC_SEND_MASTER_CMD
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
pointer to struct
:c:type:`dvb_diseqc_master_cmd`
Description
===========
Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd`
to the antenna subsystem.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

62
Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst Normal file
View File

@@ -0,0 +1,62 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_DISHNETWORK_SEND_LEGACY_CMD:
******************************
FE_DISHNETWORK_SEND_LEGACY_CMD
******************************
Name
====
FE_DISHNETWORK_SEND_LEGACY_CMD
Synopsis
========
.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)
:name: FE_DISHNETWORK_SEND_LEGACY_CMD
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``cmd``
Sends the specified raw cmd to the dish via DISEqC.
Description
===========
.. warning::
This is a very obscure legacy command, used only at stv0299
driver. Should not be used on newer drivers.
It provides a non-standard method for selecting Diseqc voltage on the
frontend, for Dish Network legacy switches.
As support for this ioctl were added in 2004, this means that such
dishes were already legacy in 2004.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

61
Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst Normal file
View File

@@ -0,0 +1,61 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_ENABLE_HIGH_LNB_VOLTAGE:
********************************
ioctl FE_ENABLE_HIGH_LNB_VOLTAGE
********************************
Name
====
FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high )
:name: FE_ENABLE_HIGH_LNB_VOLTAGE
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``high``
Valid flags:
- 0 - normal 13V and 18V.
- >0 - enables slightly higher voltages instead of 13/18V, in order
to compensate for long antenna cables.
Description
===========
Select output DC level between normal LNBf voltages or higher LNBf
voltages between 0 (normal) or a value grater than 0 for higher
voltages.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

78
Documentation/userspace-api/media/dvb/fe-get-event.rst Normal file
View File

@@ -0,0 +1,78 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_GET_EVENT:
************
FE_GET_EVENT
************
Name
====
FE_GET_EVENT
.. attention:: This ioctl is deprecated.
Synopsis
========
.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)
:name: FE_GET_EVENT
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``ev``
Points to the location where the event, if any, is to be stored.
Description
===========
This ioctl call returns a frontend event if available. If an event is
not available, the behavior depends on whether the device is in blocking
or non-blocking mode. In the latter case, the call fails immediately
with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until
an event becomes available.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EWOULDBLOCK``
- There is no event pending, and the device is in non-blocking mode.
- .. row 2
- ``EOVERFLOW``
- Overflow in event queue - one or more events were lost.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

69
Documentation/userspace-api/media/dvb/fe-get-frontend.rst Normal file
View File

@@ -0,0 +1,69 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_GET_FRONTEND:
***************
FE_GET_FRONTEND
***************
Name
====
FE_GET_FRONTEND
.. attention:: This ioctl is deprecated.
Synopsis
========
.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)
:name: FE_GET_FRONTEND
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``p``
Points to parameters for tuning operation.
Description
===========
This ioctl call queries the currently effective frontend parameters. For
this command, read-only access to the device is sufficient.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- Maximum supported symbol rate reached.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

70
Documentation/userspace-api/media/dvb/fe-get-info.rst Normal file
View File

@@ -0,0 +1,70 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_GET_INFO:
*****************
ioctl FE_GET_INFO
*****************
Name
====
FE_GET_INFO - Query Digital TV frontend capabilities and returns information
about the - front-end. This call only requires read-only access to the device.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp )
:name: FE_GET_INFO
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
pointer to struct struct
:c:type:`dvb_frontend_info`
Description
===========
All Digital TV frontend devices support the :ref:`FE_GET_INFO` ioctl. It is
used to identify kernel devices compatible with this specification and to
obtain information about driver and hardware capabilities. The ioctl
takes a pointer to dvb_frontend_info which is filled by the driver.
When the driver is not compatible with this specification the ioctl
returns an error.
frontend capabilities
=====================
Capabilities describe what a frontend can do. Some capabilities are
supported only on some specific frontend types.
The frontend capabilities are described at :c:type:`fe_caps`.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

83
Documentation/userspace-api/media/dvb/fe-get-property.rst Normal file
View File

@@ -0,0 +1,83 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_GET_PROPERTY:
**************************************
ioctl FE_SET_PROPERTY, FE_GET_PROPERTY
**************************************
Name
====
FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp )
:name: FE_GET_PROPERTY
.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp )
:name: FE_SET_PROPERTY
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
Pointer to struct :c:type:`dtv_properties`.
Description
===========
All Digital TV frontend devices support the ``FE_SET_PROPERTY`` and
``FE_GET_PROPERTY`` ioctls. The supported properties and statistics
depends on the delivery system and on the device:
- ``FE_SET_PROPERTY:``
- This ioctl is used to set one or more frontend properties.
- This is the basic command to request the frontend to tune into
some frequency and to start decoding the digital TV signal.
- This call requires read/write access to the device.
.. note::
At return, the values aren't updated to reflect the actual
parameters used. If the actual parameters are needed, an explicit
call to ``FE_GET_PROPERTY`` is needed.
- ``FE_GET_PROPERTY:``
- This ioctl is used to get properties and statistics from the
frontend.
- No properties are changed, and statistics aren't reset.
- This call only requires read-only access to the device.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

57
Documentation/userspace-api/media/dvb/fe-read-ber.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_READ_BER:
***********
FE_READ_BER
***********
Name
====
FE_READ_BER
.. attention:: This ioctl is deprecated.
Synopsis
========
.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber)
:name: FE_READ_BER
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``ber``
The bit error rate is stored into \*ber.
Description
===========
This ioctl call returns the bit error rate for the signal currently
received/demodulated by the front-end. For this command, read-only
access to the device is sufficient.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

57
Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_READ_SIGNAL_STRENGTH:
***********************
FE_READ_SIGNAL_STRENGTH
***********************
Name
====
FE_READ_SIGNAL_STRENGTH
.. attention:: This ioctl is deprecated.
Synopsis
========
.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)
:name: FE_READ_SIGNAL_STRENGTH
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``strength``
The signal strength value is stored into \*strength.
Description
===========
This ioctl call returns the signal strength value for the signal
currently received by the front-end. For this command, read-only access
to the device is sufficient.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

57
Documentation/userspace-api/media/dvb/fe-read-snr.rst Normal file
View File

@@ -0,0 +1,57 @@
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/userspace-api/media/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
.. _FE_READ_SNR:
***********
FE_READ_SNR
***********
Name
====
FE_READ_SNR
.. attention:: This ioctl is deprecated.
Synopsis
========
.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr)
:name: FE_READ_SNR
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <dvb-fe-open>`.
``snr``
The signal-to-noise ratio is stored into \*snr.
Description
===========
This ioctl call returns the signal-to-noise ratio for the signal
currently received by the front-end. For this command, read-only access
to the device is sufficient.
Return Value
============
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

Some files were not shown because too many files have changed in this diff Show More