xref: /linux/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst (revision 8be98d2f2a0a262f8bf8a0bc1fdf522b3c7aab17)
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_ENUMSTD:
5
6*******************************************
7ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD
8*******************************************
9
10Name
11====
12
13VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards
14
15Synopsis
16========
17
18.. c:macro:: VIDIOC_ENUMSTD
19
20``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)``
21
22.. c:macro:: VIDIOC_SUBDEV_ENUMSTD
23
24``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)``
25
26Arguments
27=========
28
29``fd``
30    File descriptor returned by :c:func:`open()`.
31
32``argp``
33    Pointer to struct :c:type:`v4l2_standard`.
34
35Description
36===========
37
38To query the attributes of a video standard, especially a custom (driver
39defined) one, applications initialize the ``index`` field of struct
40:c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD`
41ioctl with a pointer to this structure. Drivers fill the rest of the
42structure or return an ``EINVAL`` error code when the index is out of
43bounds. To enumerate all standards applications shall begin at index
44zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
45enumerate a different set of standards after switching the video input
46or output. [#f1]_
47
48.. c:type:: v4l2_standard
49
50.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
51
52.. flat-table:: struct v4l2_standard
53    :header-rows:  0
54    :stub-columns: 0
55    :widths:       1 1 2
56
57    * - __u32
58      - ``index``
59      - Number of the video standard, set by the application.
60    * - :ref:`v4l2_std_id <v4l2-std-id>`
61      - ``id``
62      - The bits in this field identify the standard as one of the common
63	standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
64	set as custom standards. Multiple bits can be set if the hardware
65	does not distinguish between these standards, however separate
66	indices do not indicate the opposite. The ``id`` must be unique.
67	No other enumerated struct :c:type:`v4l2_standard` structure,
68	for this input or output anyway, can contain the same set of bits.
69    * - __u8
70      - ``name``\ [24]
71      - Name of the standard, a NUL-terminated ASCII string, for example:
72	"PAL-B/G", "NTSC Japan". This information is intended for the
73	user.
74    * - struct :c:type:`v4l2_fract`
75      - ``frameperiod``
76      - The frame period (not field period) is numerator / denominator.
77	For example M/NTSC has a frame period of 1001 / 30000 seconds.
78    * - __u32
79      - ``framelines``
80      - Total lines per frame including blanking, e. g. 625 for B/PAL.
81    * - __u32
82      - ``reserved``\ [4]
83      - Reserved for future extensions. Drivers must set the array to
84	zero.
85
86
87.. c:type:: v4l2_fract
88
89.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
90
91.. flat-table:: struct v4l2_fract
92    :header-rows:  0
93    :stub-columns: 0
94    :widths:       1 1 2
95
96    * - __u32
97      - ``numerator``
98      -
99    * - __u32
100      - ``denominator``
101      -
102
103.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
104
105.. _v4l2-std-id:
106
107.. flat-table:: typedef v4l2_std_id
108    :header-rows:  0
109    :stub-columns: 0
110    :widths:       1 1 2
111
112    * - __u64
113      - ``v4l2_std_id``
114      - This type is a set, each bit representing another video standard
115	as listed below and in :ref:`video-standards`. The 32 most
116	significant bits are reserved for custom (driver defined) video
117	standards.
118
119
120.. code-block:: c
121
122    #define V4L2_STD_PAL_B          ((v4l2_std_id)0x00000001)
123    #define V4L2_STD_PAL_B1         ((v4l2_std_id)0x00000002)
124    #define V4L2_STD_PAL_G          ((v4l2_std_id)0x00000004)
125    #define V4L2_STD_PAL_H          ((v4l2_std_id)0x00000008)
126    #define V4L2_STD_PAL_I          ((v4l2_std_id)0x00000010)
127    #define V4L2_STD_PAL_D          ((v4l2_std_id)0x00000020)
128    #define V4L2_STD_PAL_D1         ((v4l2_std_id)0x00000040)
129    #define V4L2_STD_PAL_K          ((v4l2_std_id)0x00000080)
130
131    #define V4L2_STD_PAL_M          ((v4l2_std_id)0x00000100)
132    #define V4L2_STD_PAL_N          ((v4l2_std_id)0x00000200)
133    #define V4L2_STD_PAL_Nc         ((v4l2_std_id)0x00000400)
134    #define V4L2_STD_PAL_60         ((v4l2_std_id)0x00000800)
135
136``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
137rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
138PAL video recorders can play back NTSC tapes in this mode for display on
139a 50/60 Hz agnostic PAL TV.
140
141.. code-block:: c
142
143    #define V4L2_STD_NTSC_M         ((v4l2_std_id)0x00001000)
144    #define V4L2_STD_NTSC_M_JP      ((v4l2_std_id)0x00002000)
145    #define V4L2_STD_NTSC_443       ((v4l2_std_id)0x00004000)
146
147``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
148rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
149
150.. code-block:: c
151
152    #define V4L2_STD_NTSC_M_KR      ((v4l2_std_id)0x00008000)
153
154    #define V4L2_STD_SECAM_B        ((v4l2_std_id)0x00010000)
155    #define V4L2_STD_SECAM_D        ((v4l2_std_id)0x00020000)
156    #define V4L2_STD_SECAM_G        ((v4l2_std_id)0x00040000)
157    #define V4L2_STD_SECAM_H        ((v4l2_std_id)0x00080000)
158    #define V4L2_STD_SECAM_K        ((v4l2_std_id)0x00100000)
159    #define V4L2_STD_SECAM_K1       ((v4l2_std_id)0x00200000)
160    #define V4L2_STD_SECAM_L        ((v4l2_std_id)0x00400000)
161    #define V4L2_STD_SECAM_LC       ((v4l2_std_id)0x00800000)
162
163    /* ATSC/HDTV */
164    #define V4L2_STD_ATSC_8_VSB     ((v4l2_std_id)0x01000000)
165    #define V4L2_STD_ATSC_16_VSB    ((v4l2_std_id)0x02000000)
166
167``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
168terrestrial digital TV standards. Presently the V4L2 API does not
169support digital TV. See also the Linux DVB API at
170`https://linuxtv.org <https://linuxtv.org>`__.
171
172.. code-block:: c
173
174    #define V4L2_STD_PAL_BG         (V4L2_STD_PAL_B         |
175		     V4L2_STD_PAL_B1        |
176		     V4L2_STD_PAL_G)
177    #define V4L2_STD_B              (V4L2_STD_PAL_B         |
178		     V4L2_STD_PAL_B1        |
179		     V4L2_STD_SECAM_B)
180    #define V4L2_STD_GH             (V4L2_STD_PAL_G         |
181		     V4L2_STD_PAL_H         |
182		     V4L2_STD_SECAM_G       |
183		     V4L2_STD_SECAM_H)
184    #define V4L2_STD_PAL_DK         (V4L2_STD_PAL_D         |
185		     V4L2_STD_PAL_D1        |
186		     V4L2_STD_PAL_K)
187    #define V4L2_STD_PAL            (V4L2_STD_PAL_BG        |
188		     V4L2_STD_PAL_DK        |
189		     V4L2_STD_PAL_H         |
190		     V4L2_STD_PAL_I)
191    #define V4L2_STD_NTSC           (V4L2_STD_NTSC_M        |
192		     V4L2_STD_NTSC_M_JP     |
193		     V4L2_STD_NTSC_M_KR)
194    #define V4L2_STD_MN             (V4L2_STD_PAL_M         |
195		     V4L2_STD_PAL_N         |
196		     V4L2_STD_PAL_Nc        |
197		     V4L2_STD_NTSC)
198    #define V4L2_STD_SECAM_DK       (V4L2_STD_SECAM_D       |
199		     V4L2_STD_SECAM_K       |
200		     V4L2_STD_SECAM_K1)
201    #define V4L2_STD_DK             (V4L2_STD_PAL_DK        |
202		     V4L2_STD_SECAM_DK)
203
204    #define V4L2_STD_SECAM          (V4L2_STD_SECAM_B       |
205		     V4L2_STD_SECAM_G       |
206		     V4L2_STD_SECAM_H       |
207		     V4L2_STD_SECAM_DK      |
208		     V4L2_STD_SECAM_L       |
209		     V4L2_STD_SECAM_LC)
210
211    #define V4L2_STD_525_60         (V4L2_STD_PAL_M         |
212		     V4L2_STD_PAL_60        |
213		     V4L2_STD_NTSC          |
214		     V4L2_STD_NTSC_443)
215    #define V4L2_STD_625_50         (V4L2_STD_PAL           |
216		     V4L2_STD_PAL_N         |
217		     V4L2_STD_PAL_Nc        |
218		     V4L2_STD_SECAM)
219
220    #define V4L2_STD_UNKNOWN        0
221    #define V4L2_STD_ALL            (V4L2_STD_525_60        |
222		     V4L2_STD_625_50)
223
224.. raw:: latex
225
226    \begingroup
227    \tiny
228    \setlength{\tabcolsep}{2pt}
229
230..                            NTSC/M   PAL/M    /N       /B       /D       /H       /I        SECAM/B    /D       /K1     /L
231.. tabularcolumns:: |p{1.43cm}|p{1.38cm}|p{1.59cm}|p{1.7cm}|p{1.7cm}|p{1.17cm}|p{0.64cm}|p{1.71cm}|p{1.6cm}|p{1.07cm}|p{1.07cm}|p{1.07cm}|
232
233.. _video-standards:
234
235.. flat-table:: Video Standards (based on :ref:`itu470`)
236    :header-rows:  1
237    :stub-columns: 0
238
239    * - Characteristics
240      - M/NTSC [#f2]_
241      - M/PAL
242      - N/PAL [#f3]_
243      - B, B1, G/PAL
244      - D, D1, K/PAL
245      - H/PAL
246      - I/PAL
247      - B, G/SECAM
248      - D, K/SECAM
249      - K1/SECAM
250      - L/SECAM
251    * - Frame lines
252      - :cspan:`1` 525
253      - :cspan:`8` 625
254    * - Frame period (s)
255      - :cspan:`1` 1001/30000
256      - :cspan:`8` 1/25
257    * - Chrominance sub-carrier frequency (Hz)
258      - 3579545 ± 10
259      - 3579611.49 ± 10
260      - 4433618.75 ± 5
261
262	(3582056.25 ± 5)
263      - :cspan:`3` 4433618.75 ± 5
264      - 4433618.75 ± 1
265      - :cspan:`2` f\ :sub:`OR` = 4406250 ± 2000,
266
267	f\ :sub:`OB` = 4250000 ± 2000
268    * - Nominal radio-frequency channel bandwidth (MHz)
269      - 6
270      - 6
271      - 6
272      - B: 7; B1, G: 8
273      - 8
274      - 8
275      - 8
276      - 8
277      - 8
278      - 8
279      - 8
280    * - Sound carrier relative to vision carrier (MHz)
281      - 4.5
282      - 4.5
283      - 4.5
284      - 5.5 ± 0.001  [#f4]_  [#f5]_  [#f6]_  [#f7]_
285      - 6.5 ± 0.001
286      - 5.5
287      - 5.9996 ± 0.0005
288      - 5.5 ± 0.001
289      - 6.5 ± 0.001
290      - 6.5
291      - 6.5 [#f8]_
292
293.. raw:: latex
294
295    \endgroup
296
297
298Return Value
299============
300
301On success 0 is returned, on error -1 and the ``errno`` variable is set
302appropriately. The generic error codes are described at the
303:ref:`Generic Error Codes <gen-errors>` chapter.
304
305EINVAL
306    The struct :c:type:`v4l2_standard` ``index`` is out
307    of bounds.
308
309ENODATA
310    Standard video timings are not supported for this input or output.
311
312.. [#f1]
313   The supported standards may overlap and we need an unambiguous set to
314   find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
315
316.. [#f2]
317   Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
318
319.. [#f3]
320   The values in brackets apply to the combination N/PAL a.k.a.
321   N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
322
323.. [#f4]
324   In the Federal Republic of Germany, Austria, Italy, the Netherlands,
325   Slovakia and Switzerland a system of two sound carriers is used, the
326   frequency of the second carrier being 242.1875 kHz above the
327   frequency of the first sound carrier. For stereophonic sound
328   transmissions a similar system is used in Australia.
329
330.. [#f5]
331   New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
332   the vision carrier.
333
334.. [#f6]
335   In Denmark, Finland, New Zealand, Sweden and Spain a system of two
336   sound carriers is used. In Iceland, Norway and Poland the same system
337   is being introduced. The second carrier is 5.85 MHz above the vision
338   carrier and is DQPSK modulated with 728 kbit/s sound and data
339   multiplex. (NICAM system)
340
341.. [#f7]
342   In the United Kingdom, a system of two sound carriers is used. The
343   second sound carrier is 6.552 MHz above the vision carrier and is
344   DQPSK modulated with a 728 kbit/s sound and data multiplex able to
345   carry two sound channels. (NICAM system)
346
347.. [#f8]
348   In France, a digital carrier 5.85 MHz away from the vision carrier
349   may be used in addition to the main sound carrier. It is modulated in
350   differentially encoded QPSK with a 728 kbit/s sound and data
351   multiplexer capable of carrying two sound channels. (NICAM system)
352