vidioc-g-tuner.xml 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535
  1. <refentry id="vidioc-g-tuner">
  2. <refmeta>
  3. <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle>
  4. &manvol;
  5. </refmeta>
  6. <refnamediv>
  7. <refname>VIDIOC_G_TUNER</refname>
  8. <refname>VIDIOC_S_TUNER</refname>
  9. <refpurpose>Get or set tuner attributes</refpurpose>
  10. </refnamediv>
  11. <refsynopsisdiv>
  12. <funcsynopsis>
  13. <funcprototype>
  14. <funcdef>int <function>ioctl</function></funcdef>
  15. <paramdef>int <parameter>fd</parameter></paramdef>
  16. <paramdef>int <parameter>request</parameter></paramdef>
  17. <paramdef>struct v4l2_tuner
  18. *<parameter>argp</parameter></paramdef>
  19. </funcprototype>
  20. </funcsynopsis>
  21. <funcsynopsis>
  22. <funcprototype>
  23. <funcdef>int <function>ioctl</function></funcdef>
  24. <paramdef>int <parameter>fd</parameter></paramdef>
  25. <paramdef>int <parameter>request</parameter></paramdef>
  26. <paramdef>const struct v4l2_tuner
  27. *<parameter>argp</parameter></paramdef>
  28. </funcprototype>
  29. </funcsynopsis>
  30. </refsynopsisdiv>
  31. <refsect1>
  32. <title>Arguments</title>
  33. <variablelist>
  34. <varlistentry>
  35. <term><parameter>fd</parameter></term>
  36. <listitem>
  37. <para>&fd;</para>
  38. </listitem>
  39. </varlistentry>
  40. <varlistentry>
  41. <term><parameter>request</parameter></term>
  42. <listitem>
  43. <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para>
  44. </listitem>
  45. </varlistentry>
  46. <varlistentry>
  47. <term><parameter>argp</parameter></term>
  48. <listitem>
  49. <para></para>
  50. </listitem>
  51. </varlistentry>
  52. </variablelist>
  53. </refsect1>
  54. <refsect1>
  55. <title>Description</title>
  56. <para>To query the attributes of a tuner applications initialize the
  57. <structfield>index</structfield> field and zero out the
  58. <structfield>reserved</structfield> array of a &v4l2-tuner; and call the
  59. <constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this
  60. structure. Drivers fill the rest of the structure or return an
  61. &EINVAL; when the index is out of bounds. To enumerate all tuners
  62. applications shall begin at index zero, incrementing by one until the
  63. driver returns <errorcode>EINVAL</errorcode>.</para>
  64. <para>Tuners have two writable properties, the audio mode and
  65. the radio frequency. To change the audio mode, applications initialize
  66. the <structfield>index</structfield>,
  67. <structfield>audmode</structfield> and
  68. <structfield>reserved</structfield> fields and call the
  69. <constant>VIDIOC_S_TUNER</constant> ioctl. This will
  70. <emphasis>not</emphasis> change the current tuner, which is determined
  71. by the current video input. Drivers may choose a different audio mode
  72. if the requested mode is invalid or unsupported. Since this is a
  73. <!-- FIXME -->write-only ioctl, it does not return the actually
  74. selected audio mode.</para>
  75. <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
  76. is available.</para>
  77. <table pgwide="1" frame="none" id="v4l2-tuner">
  78. <title>struct <structname>v4l2_tuner</structname></title>
  79. <tgroup cols="3">
  80. <colspec colname="c1" colwidth="1*" />
  81. <colspec colname="c2" colwidth="1*" />
  82. <colspec colname="c3" colwidth="1*" />
  83. <colspec colname="c4" colwidth="1*" />
  84. <spanspec spanname="hspan" namest="c3" nameend="c4" />
  85. <tbody valign="top">
  86. <row>
  87. <entry>__u32</entry>
  88. <entry><structfield>index</structfield></entry>
  89. <entry spanname="hspan">Identifies the tuner, set by the
  90. application.</entry>
  91. </row>
  92. <row>
  93. <entry>__u8</entry>
  94. <entry><structfield>name</structfield>[32]</entry>
  95. <entry spanname="hspan"><para>Name of the tuner, a
  96. NUL-terminated ASCII string. This information is intended for the
  97. user.<!-- FIXME Video inputs already have a name, the purpose of this
  98. field is not quite clear.--></para></entry>
  99. </row>
  100. <row>
  101. <entry>&v4l2-tuner-type;</entry>
  102. <entry><structfield>type</structfield></entry>
  103. <entry spanname="hspan">Type of the tuner, see <xref
  104. linkend="v4l2-tuner-type" />.</entry>
  105. </row>
  106. <row>
  107. <entry>__u32</entry>
  108. <entry><structfield>capability</structfield></entry>
  109. <entry spanname="hspan"><para>Tuner capability flags, see
  110. <xref linkend="tuner-capability" />. Audio flags indicate the ability
  111. to decode audio subprograms. They will <emphasis>not</emphasis>
  112. change, for example with the current video standard.</para><para>When
  113. the structure refers to a radio tuner only the
  114. <constant>V4L2_TUNER_CAP_LOW</constant>,
  115. <constant>V4L2_TUNER_CAP_STEREO</constant> and
  116. <constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry>
  117. </row>
  118. <row>
  119. <entry>__u32</entry>
  120. <entry><structfield>rangelow</structfield></entry>
  121. <entry spanname="hspan">The lowest tunable frequency in
  122. units of 62.5 kHz, or if the <structfield>capability</structfield>
  123. flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
  124. Hz.</entry>
  125. </row>
  126. <row>
  127. <entry>__u32</entry>
  128. <entry><structfield>rangehigh</structfield></entry>
  129. <entry spanname="hspan">The highest tunable frequency in
  130. units of 62.5 kHz, or if the <structfield>capability</structfield>
  131. flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
  132. Hz.</entry>
  133. </row>
  134. <row>
  135. <entry>__u32</entry>
  136. <entry><structfield>rxsubchans</structfield></entry>
  137. <entry spanname="hspan"><para>Some tuners or audio
  138. decoders can determine the received audio subprograms by analyzing
  139. audio carriers, pilot tones or other indicators. To pass this
  140. information drivers set flags defined in <xref
  141. linkend="tuner-rxsubchans" /> in this field. For
  142. example:</para></entry>
  143. </row>
  144. <row>
  145. <entry></entry>
  146. <entry></entry>
  147. <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
  148. <entry>receiving mono audio</entry>
  149. </row>
  150. <row>
  151. <entry></entry>
  152. <entry></entry>
  153. <entry><constant>STEREO | SAP</constant></entry>
  154. <entry>receiving stereo audio and a secondary audio
  155. program</entry>
  156. </row>
  157. <row>
  158. <entry></entry>
  159. <entry></entry>
  160. <entry><constant>MONO | STEREO</constant></entry>
  161. <entry>receiving mono or stereo audio, the hardware cannot
  162. distinguish</entry>
  163. </row>
  164. <row>
  165. <entry></entry>
  166. <entry></entry>
  167. <entry><constant>LANG1 | LANG2</constant></entry>
  168. <entry>receiving bilingual audio</entry>
  169. </row>
  170. <row>
  171. <entry></entry>
  172. <entry></entry>
  173. <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry>
  174. <entry>receiving mono, stereo or bilingual
  175. audio</entry>
  176. </row>
  177. <row>
  178. <entry></entry>
  179. <entry></entry>
  180. <entry spanname="hspan"><para>When the
  181. <constant>V4L2_TUNER_CAP_STEREO</constant>,
  182. <constant>_LANG1</constant>, <constant>_LANG2</constant> or
  183. <constant>_SAP</constant> flag is cleared in the
  184. <structfield>capability</structfield> field, the corresponding
  185. <constant>V4L2_TUNER_SUB_</constant> flag must not be set
  186. here.</para><para>This field is valid only if this is the tuner of the
  187. current video input, or when the structure refers to a radio
  188. tuner.</para></entry>
  189. </row>
  190. <row>
  191. <entry>__u32</entry>
  192. <entry><structfield>audmode</structfield></entry>
  193. <entry spanname="hspan"><para>The selected audio mode, see
  194. <xref linkend="tuner-audmode" /> for valid values. The audio mode does
  195. not affect audio subprogram detection, and like a <link
  196. linkend="control">control</link> it does not automatically change
  197. unless the requested mode is invalid or unsupported. See <xref
  198. linkend="tuner-matrix" /> for possible results when
  199. the selected and received audio programs do not
  200. match.</para><para>Currently this is the only field of struct
  201. <structname>v4l2_tuner</structname> applications can
  202. change.</para></entry>
  203. </row>
  204. <row>
  205. <entry>__u32</entry>
  206. <entry><structfield>signal</structfield></entry>
  207. <entry spanname="hspan">The signal strength if known, ranging
  208. from 0 to 65535. Higher values indicate a better signal.</entry>
  209. </row>
  210. <row>
  211. <entry>__s32</entry>
  212. <entry><structfield>afc</structfield></entry>
  213. <entry spanname="hspan">Automatic frequency control: When the
  214. <structfield>afc</structfield> value is negative, the frequency is too
  215. low, when positive too high.<!-- FIXME need example what to do when it never
  216. settles at zero, &ie; range is what? --></entry>
  217. </row>
  218. <row>
  219. <entry>__u32</entry>
  220. <entry><structfield>reserved</structfield>[4]</entry>
  221. <entry spanname="hspan">Reserved for future extensions. Drivers and
  222. applications must set the array to zero.</entry>
  223. </row>
  224. </tbody>
  225. </tgroup>
  226. </table>
  227. <table pgwide="1" frame="none" id="v4l2-tuner-type">
  228. <title>enum v4l2_tuner_type</title>
  229. <tgroup cols="3">
  230. &cs-def;
  231. <tbody valign="top">
  232. <row>
  233. <entry><constant>V4L2_TUNER_RADIO</constant></entry>
  234. <entry>1</entry>
  235. <entry></entry>
  236. </row>
  237. <row>
  238. <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry>
  239. <entry>2</entry>
  240. <entry></entry>
  241. </row>
  242. </tbody>
  243. </tgroup>
  244. </table>
  245. <table pgwide="1" frame="none" id="tuner-capability">
  246. <title>Tuner and Modulator Capability Flags</title>
  247. <tgroup cols="3">
  248. &cs-def;
  249. <tbody valign="top">
  250. <row>
  251. <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
  252. <entry>0x0001</entry>
  253. <entry>When set, tuning frequencies are expressed in units of
  254. 62.5&nbsp;Hz, otherwise in units of 62.5&nbsp;kHz.</entry>
  255. </row>
  256. <row>
  257. <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
  258. <entry>0x0002</entry>
  259. <entry>This is a multi-standard tuner; the video standard
  260. can or must be switched. (B/G PAL tuners for example are typically not
  261. considered multi-standard because the video standard is automatically
  262. determined from the frequency band.) The set of supported video
  263. standards is available from the &v4l2-input; pointing to this tuner,
  264. see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only
  265. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
  266. </row>
  267. <row>
  268. <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry>
  269. <entry>0x0010</entry>
  270. <entry>Stereo audio reception is supported.</entry>
  271. </row>
  272. <row>
  273. <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry>
  274. <entry>0x0040</entry>
  275. <entry>Reception of the primary language of a bilingual
  276. audio program is supported. Bilingual audio is a feature of
  277. two-channel systems, transmitting the primary language monaural on the
  278. main audio carrier and a secondary language monaural on a second
  279. carrier. Only
  280. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
  281. </row>
  282. <row>
  283. <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry>
  284. <entry>0x0020</entry>
  285. <entry>Reception of the secondary language of a bilingual
  286. audio program is supported. Only
  287. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
  288. </row>
  289. <row>
  290. <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry>
  291. <entry>0x0020</entry>
  292. <entry><para>Reception of a secondary audio program is
  293. supported. This is a feature of the BTSC system which accompanies the
  294. NTSC video standard. Two audio carriers are available for mono or
  295. stereo transmissions of a primary language, and an independent third
  296. carrier for a monaural secondary language. Only
  297. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the
  298. <constant>V4L2_TUNER_CAP_LANG2</constant> and
  299. <constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms.
  300. <constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner
  301. supports the <constant>V4L2_STD_NTSC_M</constant> video
  302. standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
  303. </row>
  304. <row>
  305. <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
  306. <entry>0x0080</entry>
  307. <entry>RDS capture is supported. This capability is only valid for
  308. radio tuners.</entry>
  309. </row>
  310. </tbody>
  311. </tgroup>
  312. </table>
  313. <table pgwide="1" frame="none" id="tuner-rxsubchans">
  314. <title>Tuner Audio Reception Flags</title>
  315. <tgroup cols="3">
  316. &cs-def;
  317. <tbody valign="top">
  318. <row>
  319. <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
  320. <entry>0x0001</entry>
  321. <entry>The tuner receives a mono audio signal.</entry>
  322. </row>
  323. <row>
  324. <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
  325. <entry>0x0002</entry>
  326. <entry>The tuner receives a stereo audio signal.</entry>
  327. </row>
  328. <row>
  329. <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
  330. <entry>0x0008</entry>
  331. <entry>The tuner receives the primary language of a
  332. bilingual audio signal. Drivers must clear this flag when the current
  333. video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
  334. </row>
  335. <row>
  336. <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
  337. <entry>0x0004</entry>
  338. <entry>The tuner receives the secondary language of a
  339. bilingual audio signal (or a second audio program).</entry>
  340. </row>
  341. <row>
  342. <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
  343. <entry>0x0004</entry>
  344. <entry>The tuner receives a Second Audio Program. Note the
  345. <constant>V4L2_TUNER_SUB_LANG2</constant> and
  346. <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
  347. <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
  348. current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
  349. </row>
  350. <row>
  351. <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
  352. <entry>0x0010</entry>
  353. <entry>The tuner receives an RDS channel.</entry>
  354. </row>
  355. </tbody>
  356. </tgroup>
  357. </table>
  358. <table pgwide="1" frame="none" id="tuner-audmode">
  359. <title>Tuner Audio Modes</title>
  360. <tgroup cols="3">
  361. &cs-def;
  362. <tbody valign="top">
  363. <row>
  364. <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
  365. <entry>0</entry>
  366. <entry>Play mono audio. When the tuner receives a stereo
  367. signal this a down-mix of the left and right channel. When the tuner
  368. receives a bilingual or SAP signal this mode selects the primary
  369. language.</entry>
  370. </row>
  371. <row>
  372. <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
  373. <entry>1</entry>
  374. <entry><para>Play stereo audio. When the tuner receives
  375. bilingual audio it may play different languages on the left and right
  376. channel or the primary language is played on both channels.</para><para>Playing
  377. different languages in this mode is
  378. deprecated. New drivers should do this only in
  379. <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
  380. receives no stereo signal or does not support stereo reception the
  381. driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
  382. </row>
  383. <row>
  384. <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
  385. <entry>3</entry>
  386. <entry>Play the primary language, mono or stereo. Only
  387. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
  388. mode.</entry>
  389. </row>
  390. <row>
  391. <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
  392. <entry>2</entry>
  393. <entry>Play the secondary language, mono. When the tuner
  394. receives no bilingual audio or SAP, or their reception is not
  395. supported the driver shall fall back to mono or stereo mode. Only
  396. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
  397. mode.</entry>
  398. </row>
  399. <row>
  400. <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
  401. <entry>2</entry>
  402. <entry>Play the Second Audio Program. When the tuner
  403. receives no bilingual audio or SAP, or their reception is not
  404. supported the driver shall fall back to mono or stereo mode. Only
  405. <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
  406. Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
  407. <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
  408. </row>
  409. <row>
  410. <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
  411. <entry>4</entry>
  412. <entry>Play the primary language on the left channel, the
  413. secondary language on the right channel. When the tuner receives no
  414. bilingual audio or SAP, it shall fall back to
  415. <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
  416. Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
  417. mode.</entry>
  418. </row>
  419. </tbody>
  420. </tgroup>
  421. </table>
  422. <table pgwide="1" frame="all" id="tuner-matrix">
  423. <title>Tuner Audio Matrix</title>
  424. <tgroup cols="6" align="center">
  425. <colspec align="left" />
  426. <colspec colname="c2" colwidth="1*" />
  427. <colspec colwidth="1*" />
  428. <colspec colwidth="1*" />
  429. <colspec colnum="6" colname="c6" colwidth="1*" />
  430. <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
  431. <thead>
  432. <row>
  433. <entry></entry>
  434. <entry spanname="hspan">Selected
  435. <constant>V4L2_TUNER_MODE_</constant></entry>
  436. </row>
  437. <row>
  438. <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
  439. <entry><constant>MONO</constant></entry>
  440. <entry><constant>STEREO</constant></entry>
  441. <entry><constant>LANG1</constant></entry>
  442. <entry><constant>LANG2 = SAP</constant></entry>
  443. <entry><constant>LANG1_LANG2</constant><footnote><para>This
  444. mode has been added in Linux 2.6.17 and may not be supported by older
  445. drivers.</para></footnote></entry>
  446. </row>
  447. </thead>
  448. <tbody valign="top">
  449. <row>
  450. <entry><constant>MONO</constant></entry>
  451. <entry>Mono</entry>
  452. <entry>Mono/Mono</entry>
  453. <entry>Mono</entry>
  454. <entry>Mono</entry>
  455. <entry>Mono/Mono</entry>
  456. </row>
  457. <row>
  458. <entry><constant>MONO | SAP</constant></entry>
  459. <entry>Mono</entry>
  460. <entry>Mono/Mono</entry>
  461. <entry>Mono</entry>
  462. <entry>SAP</entry>
  463. <entry>Mono/SAP (preferred) or Mono/Mono</entry>
  464. </row>
  465. <row>
  466. <entry><constant>STEREO</constant></entry>
  467. <entry>L+R</entry>
  468. <entry>L/R</entry>
  469. <entry>Stereo L/R (preferred) or Mono L+R</entry>
  470. <entry>Stereo L/R (preferred) or Mono L+R</entry>
  471. <entry>L/R (preferred) or L+R/L+R</entry>
  472. </row>
  473. <row>
  474. <entry><constant>STEREO | SAP</constant></entry>
  475. <entry>L+R</entry>
  476. <entry>L/R</entry>
  477. <entry>Stereo L/R (preferred) or Mono L+R</entry>
  478. <entry>SAP</entry>
  479. <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
  480. </row>
  481. <row>
  482. <entry><constant>LANG1 | LANG2</constant></entry>
  483. <entry>Language&nbsp;1</entry>
  484. <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
  485. both languages in <constant>MODE_STEREO</constant> is deprecated. In
  486. the future drivers should produce only the primary language in this
  487. mode. Applications should request
  488. <constant>MODE_LANG1_LANG2</constant> to record both languages or a
  489. stereo signal.</para></footnote>) or
  490. Lang1/Lang1</entry>
  491. <entry>Language&nbsp;1</entry>
  492. <entry>Language&nbsp;2</entry>
  493. <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
  494. </row>
  495. </tbody>
  496. </tgroup>
  497. </table>
  498. </refsect1>
  499. <refsect1>
  500. &return-value;
  501. <variablelist>
  502. <varlistentry>
  503. <term><errorcode>EINVAL</errorcode></term>
  504. <listitem>
  505. <para>The &v4l2-tuner; <structfield>index</structfield> is
  506. out of bounds.</para>
  507. </listitem>
  508. </varlistentry>
  509. </variablelist>
  510. </refsect1>
  511. </refentry>
  512. <!--
  513. Local Variables:
  514. mode: sgml
  515. sgml-parent-document: "v4l2.sgml"
  516. indent-tabs-mode: nil
  517. End:
  518. -->