7.42. ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER

7.42.1. 名稱

VIDIOC_G_TUNER - VIDIOC_S_TUNER - 獲取或設定調諧器屬性

7.42.2. 概要

VIDIOC_G_TUNER

int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)

VIDIOC_S_TUNER

int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)

7.42.3. 引數

fd

由 open() 返回的檔案描述符。

argp

指向 struct v4l2_tuner 的指標。

7.42.4. 描述

要查詢調諧器的屬性，應用程式初始化 index 欄位並清零 struct v4l2_tuner 的 reserved 陣列，然後呼叫 VIDIOC_G_TUNER ioctl 並傳入指向此結構的指標。 如果索引越界，驅動程式會填充結構的其餘部分或返回 EINVAL 錯誤程式碼。 要列舉所有調諧器，應用程式應從索引零開始，每次遞增一，直到驅動程式返回 EINVAL。

調諧器具有兩個可寫屬性：音訊模式和無線電頻率。 要更改音訊模式，應用程式初始化 index、audmode 和 reserved 欄位，然後呼叫 VIDIOC_S_TUNER ioctl。 這不會更改當前調諧器，當前調諧器由當前的影片輸入確定。 如果請求的模式無效或不受支援，驅動程式可以選擇不同的音訊模式。 由於這是一個只寫 ioctl，它不會返回實際選擇的音訊模式。

SDR 特定調諧器型別為 V4L2_TUNER_SDR 和 V4L2_TUNER_RF。 對於 SDR 裝置，audmode 欄位必須初始化為零。 在這種情況下，“調諧器”一詞是指 SDR 接收器。

要更改無線電頻率，可以使用 VIDIOC_S_FREQUENCY ioctl。

type v4l2_tuner

struct v4l2_tuner

__u32	index	標識調諧器，由應用程式設定。
__u8	name[32]	調諧器的名稱，以 NUL 結尾的 ASCII 字串。 此資訊供使用者使用。
__u32	type	調諧器的型別，請參見 v4l2_tuner_type。
__u32	capability	調諧器功能標誌，請參見 調諧器和調製器功能標誌。 音訊標誌表示解碼音訊子節目的能力。 它們不會更改，例如隨當前影片標準而更改。 當結構引用無線電調諧器時，不能使用 V4L2_TUNER_CAP_LANG1、V4L2_TUNER_CAP_LANG2 和 V4L2_TUNER_CAP_NORM 標誌。 如果支援多個頻段，則 capability 是每個 struct v4l2_frequency_band 的所有 capability 欄位的並集。
__u32	rangelow	最低可調諧頻率，單位為 62.5 kHz，或者如果設定了 capability 標誌 V4L2_TUNER_CAP_LOW，則單位為 62.5 Hz，或者如果設定了 capability 標誌 V4L2_TUNER_CAP_1HZ，則單位為 1 Hz。 如果支援多個頻段，則 rangelow 是所有頻段的最低頻率。
__u32	rangehigh	最高可調諧頻率，單位為 62.5 kHz，或者如果設定了 capability 標誌 V4L2_TUNER_CAP_LOW，則單位為 62.5 Hz，或者如果設定了 capability 標誌 V4L2_TUNER_CAP_1HZ，則單位為 1 Hz。 如果支援多個頻段，則 rangehigh 是所有頻段的最高頻率。
__u32	rxsubchans	某些調諧器或音訊解碼器可以透過分析音訊載波、引導音或其他指示符來確定接收到的音訊子節目。 要傳遞此資訊，驅動程式在此欄位中設定在 調諧器音訊接收標誌 中定義的標誌。 例如
		V4L2_TUNER_SUB_MONO	接收單聲道音訊
		STEREO | SAP	接收立體聲音訊和輔助音訊節目
		MONO | STEREO	接收單聲道或立體聲音訊，硬體無法區分
		LANG1 | LANG2	接收雙語音訊
		MONO | STEREO | LANG1 | LANG2	接收單聲道、立體聲或雙語音訊
		如果在 capability 欄位中清除了 V4L2_TUNER_CAP_STEREO、_LANG1、_LANG2 或 _SAP 標誌，則不能在此處設定相應的 V4L2_TUNER_SUB_ 標誌。 只有當這是當前影片輸入的調諧器時，或者當結構引用無線電調諧器時，此欄位才有效。
__u32	audmode	選擇的音訊模式，有關有效值，請參見 調諧器音訊模式。 音訊模式不影響音訊子節目檢測，並且像 使用者控制元件 一樣，除非請求的模式無效或不受支援，否則它不會自動更改。 有關所選音訊節目與接收到的音訊節目不匹配時可能的結果，請參見 調諧器音訊矩陣。 目前，這是 struct struct v4l2_tuner 應用程式可以更改的唯一欄位。
__u32	signal	已知的訊號強度。 範圍從 0 到 65535。 值越高表示訊號越好。
__s32	afc	自動頻率控制。 當 afc 值為負時，頻率太低，為正時太高。
__u32	reserved[4]	保留供將來擴充套件使用。 驅動程式和應用程式必須將陣列設定為零。

type v4l2_tuner_type

enum v4l2_tuner_type

V4L2_TUNER_RADIO	1	調諧器支援無線電
V4L2_TUNER_ANALOG_TV	2	調諧器支援模擬電視
V4L2_TUNER_SDR	4	調諧器控制軟體數字無線電 (SDR) 的 A/D 和/或 D/A 模組
V4L2_TUNER_RF	5	調諧器控制軟體數字無線電 (SDR) 的 RF 部分

調諧器和調製器功能標誌

V4L2_TUNER_CAP_LOW	0x0001	設定後，調諧頻率以 62.5 Hz 為單位表示，而不是以 62.5 kHz 為單位表示。
V4L2_TUNER_CAP_NORM	0x0002	這是一個多標準調諧器；可以或必須切換影片標準。 （例如，B/G PAL 調諧器通常不被認為是多標準的，因為影片標準是從頻段自動確定的。） 支援的影片標準集可從指向此調諧器的 struct v4l2_input 獲得，請參見 ioctl ioctl VIDIOC_ENUMINPUT 的描述以瞭解詳細資訊。 只有 V4L2_TUNER_ANALOG_TV 調諧器可以具有此功能。
V4L2_TUNER_CAP_HWSEEK_BOUNDED	0x0004	如果設定，則此調諧器支援硬體搜尋功能，該功能在到達頻率範圍的末尾時停止搜尋。
V4L2_TUNER_CAP_HWSEEK_WRAP	0x0008	如果設定，則此調諧器支援硬體搜尋功能，該功能在到達頻率範圍的末尾時會迴繞。
V4L2_TUNER_CAP_STEREO	0x0010	支援立體聲音訊接收。
V4L2_TUNER_CAP_LANG1	0x0040	支援接收雙語音訊節目的主要語言。 雙語音訊是雙聲道系統的一項功能，它在主音訊載波上傳輸主要語言的單聲道，並在第二個載波上傳輸輔助語言的單聲道。 只有 V4L2_TUNER_ANALOG_TV 調諧器可以具有此功能。
V4L2_TUNER_CAP_LANG2	0x0020	支援接收雙語音訊節目的輔助語言。 只有 V4L2_TUNER_ANALOG_TV 調諧器可以具有此功能。
V4L2_TUNER_CAP_SAP	0x0020	支援接收輔助音訊節目。 這是 BTSC 系統的一項功能，該系統伴隨 NTSC 影片標準。 有兩個音訊載波可用於主要語言的單聲道或立體聲傳輸，還有一個獨立的第三個載波可用於單聲道輔助語言。 只有 V4L2_TUNER_ANALOG_TV 調諧器可以具有此功能。 注意 V4L2_TUNER_CAP_LANG2 和 V4L2_TUNER_CAP_SAP 標誌是同義詞。 當調諧器支援 V4L2_STD_NTSC_M 影片標準時，應用 V4L2_TUNER_CAP_SAP。
V4L2_TUNER_CAP_RDS	0x0080	支援 RDS 捕獲。 此功能僅對無線電調諧器有效。
V4L2_TUNER_CAP_RDS_BLOCK_IO	0x0100	RDS 資料作為未解析的 RDS 塊傳遞。
V4L2_TUNER_CAP_RDS_CONTROLS	0x0200	RDS 資料由硬體解析並透過控制元件設定。
V4L2_TUNER_CAP_FREQ_BANDS	0x0400	可以使用 ioctl VIDIOC_ENUM_FREQ_BANDS ioctl 列舉可用的頻段。
V4L2_TUNER_CAP_HWSEEK_PROG_LIM	0x0800	使用硬體搜尋功能時要搜尋的範圍是可程式設計的，有關詳細資訊，請參見 ioctl VIDIOC_S_HW_FREQ_SEEK。
V4L2_TUNER_CAP_1HZ	0x1000	設定後，調諧頻率以 1 Hz 為單位表示，而不是以 62.5 kHz 為單位表示。

調諧器音訊接收標誌

V4L2_TUNER_SUB_MONO	0x0001	調諧器接收單聲道音訊訊號。
V4L2_TUNER_SUB_STEREO	0x0002	調諧器接收立體聲音訊訊號。
V4L2_TUNER_SUB_LANG1	0x0008	調諧器接收雙語音訊節目的主要語言。 噹噹前影片標準為 V4L2_STD_NTSC_M 時，驅動程式必須清除此標誌。
V4L2_TUNER_SUB_LANG2	0x0004	調諧器接收雙語音訊節目的輔助語言（或第二個音訊節目）。
V4L2_TUNER_SUB_SAP	0x0004	調諧器接收輔助音訊節目。 注意 V4L2_TUNER_SUB_LANG2 和 V4L2_TUNER_SUB_SAP 標誌是同義詞。 噹噹前影片標準為 V4L2_STD_NTSC_M 時，應用 V4L2_TUNER_SUB_SAP 標誌。
V4L2_TUNER_SUB_RDS	0x0010	調諧器接收 RDS 頻道。

調諧器音訊模式

V4L2_TUNER_MODE_MONO	0	播放單聲道音訊。 當調諧器接收到立體聲訊號時，這是左聲道和右聲道的下混。 當調諧器接收到雙語或 SAP 訊號時，此模式選擇主要語言。
V4L2_TUNER_MODE_STEREO	1	播放立體聲音訊。 當調諧器接收到雙語音訊時，它可能會在左聲道和右聲道上播放不同的語言，或者主要語言在兩個聲道上播放。 不建議在此模式下播放不同的語言。 新驅動程式應僅在 MODE_LANG1_LANG2 中執行此操作。 當調諧器未接收到立體聲訊號或不支援立體聲接收時，驅動程式應回退到 MODE_MONO。
V4L2_TUNER_MODE_LANG1	3	播放主要語言，單聲道或立體聲。 只有 V4L2_TUNER_ANALOG_TV 調諧器支援此模式。
V4L2_TUNER_MODE_LANG2	2	播放輔助語言，單聲道。 當調諧器未接收到雙語音訊或 SAP，或者不支援其接收時，驅動程式應回退到單聲道或立體聲模式。 只有 V4L2_TUNER_ANALOG_TV 調諧器支援此模式。
V4L2_TUNER_MODE_SAP	2	播放輔助音訊節目。 當調諧器未接收到雙語音訊或 SAP，或者不支援其接收時，驅動程式應回退到單聲道或立體聲模式。 只有 V4L2_TUNER_ANALOG_TV 調諧器支援此模式。 注意 V4L2_TUNER_MODE_LANG2 和 V4L2_TUNER_MODE_SAP 是同義詞。
V4L2_TUNER_MODE_LANG1_LANG2	4	在左聲道播放主要語言，在右聲道播放輔助語言。 當調諧器未接收到雙語音訊或 SAP 時，它應回退到 MODE_LANG1 或 MODE_MONO。 只有 V4L2_TUNER_ANALOG_TV 調諧器支援此模式。

調諧器音訊矩陣

	選擇的 V4L2_TUNER_MODE_
接收到的 V4L2_TUNER_SUB_	MONO	STEREO	LANG1	LANG2 = SAP	LANG1_LANG2[1]
MONO	Mono	Mono/Mono	Mono	Mono	Mono/Mono
MONO | SAP	Mono	Mono/Mono	Mono	SAP	Mono/SAP (首選) 或 Mono/Mono
STEREO	L+R	L/R	Stereo L/R (首選) 或 Mono L+R	Stereo L/R (首選) 或 Mono L+R	L/R (首選) 或 L+R/L+R
STEREO | SAP	L+R	L/R	Stereo L/R (首選) 或 Mono L+R	SAP	左+右/SAP（首選）或 左/右 或 左+右/左+右
LANG1 | LANG2	語言 1	語言1/語言2（已棄用[2]）或 語言1/語言1	語言 1	語言 2	語言1/語言2（首選）或 語言1/語言1

7.42.5. 返回值

成功時返回 0，出錯時返回 -1，並相應地設定 errno 變數。 通用錯誤程式碼在通用錯誤程式碼章節中描述。

EINVAL

結構體 v4l2_tuner index 超出範圍。

[1]

此模式已新增到 Linux 2.6.17 中，可能不受較舊驅動程式的支援。

[2]

MODE_STEREO中兩種語言的回放已被棄用。 未來，驅動程式應僅在此模式下生成主要語言。 應用程式應請求 MODE_LANG1_LANG2 來錄製兩種語言或立體聲訊號。