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 来录制两种语言或立体声信号。