From 8e4bff4cab0ddac6060645b0715210484d02ff40 Mon Sep 17 00:00:00 2001
From: Yuval Adam <_@yuv.al>
Date: Wed, 30 Aug 2017 08:25:59 +0000
Subject: Initial file dump from open source release
---
Documentation/DocBook/media/v4l/dev-sliced-vbi.xml | 699 +++++++++++++++++++++
1 file changed, 699 insertions(+)
create mode 100644 Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
(limited to 'Documentation/DocBook/media/v4l/dev-sliced-vbi.xml')
diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
new file mode 100644
index 00000000..548f8ea2
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
@@ -0,0 +1,699 @@
+ Sliced VBI Data Interface
+
+ VBI stands for Vertical Blanking Interval, a gap in the
+sequence of lines of an analog video signal. During VBI no picture
+information is transmitted, allowing some time while the electron beam
+of a cathode ray tube TV returns to the top of the screen.
+
+ Sliced VBI devices use hardware to demodulate data transmitted
+in the VBI. V4L2 drivers shall not do this by
+software, see also the raw VBI
+interface. The data is passed as short packets of fixed size,
+covering one scan line each. The number of packets per video frame is
+variable.
+
+ Sliced VBI capture and output devices are accessed through the
+same character special files as raw VBI devices. When a driver
+supports both interfaces, the default function of a
+/dev/vbi device is raw VBI
+capturing or output, and the sliced VBI function is only available
+after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
+/dev/video device may support the sliced VBI API,
+however the default function here is video capturing or output.
+Different file descriptors must be used to pass raw and sliced VBI
+data simultaneously, if this is supported by the driver.
+
+
+ Querying Capabilities
+
+ Devices supporting the sliced VBI capturing or output API
+set the V4L2_CAP_SLICED_VBI_CAPTURE or
+V4L2_CAP_SLICED_VBI_OUTPUT flag respectively, in
+the capabilities field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
+read/write, streaming or asynchronous I/O
+methods must be supported. Sliced VBI devices may have a tuner
+or modulator.
+
+
+
+ Supplemental Functions
+
+ Sliced VBI devices shall support video
+input or output and tuner or
+modulator ioctls if they have these capabilities, and they may
+support control ioctls. The video standard ioctls provide information
+vital to program a sliced VBI device, therefore must be
+supported.
+
+
+
+ Sliced VBI Format Negotiation
+
+ To find out which data services are supported by the
+hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
+All drivers implementing the sliced VBI interface must support this
+ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
+when the number of VBI lines the hardware can capture or output per
+frame, or the number of services it can identify on a given line are
+limited. For example on PAL line 16 the hardware may be able to look
+for a VPS or Teletext signal, but not both at the same time.
+
+ To determine the currently selected services applications
+set the type field of &v4l2-format; to
+ V4L2_BUF_TYPE_SLICED_VBI_CAPTURE or
+V4L2_BUF_TYPE_SLICED_VBI_OUTPUT, and the &VIDIOC-G-FMT;
+ioctl fills the fmt.sliced member, a
+&v4l2-sliced-vbi-format;.
+
+ Applications can request different parameters by
+initializing or modifying the fmt.sliced
+member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
+v4l2_format structure.
+
+ The sliced VBI API is more complicated than the raw VBI API
+because the hardware must be told which VBI service to expect on each
+scan line. Not all services may be supported by the hardware on all
+lines (this is especially true for VBI output where Teletext is often
+unsupported and other services can only be inserted in one specific
+line). In many cases, however, it is sufficient to just set the
+service_set field to the required services
+and let the driver fill the service_lines
+array according to hardware capabilities. Only if more precise control
+is needed should the programmer set the
+service_lines array explicitly.
+
+ The &VIDIOC-S-FMT; ioctl modifies the parameters
+according to hardware capabilities. When the driver allocates
+resources at this point, it may return an &EBUSY; if the required
+resources are temporarily unavailable. Other resource allocation
+points which may return EBUSY can be the
+&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
+&func-select; call.
+
+
+ struct
+<structname>v4l2_sliced_vbi_format</structname>
+
+
+
+
+
+
+
+
+
+ __u32
+ service_set
+ If
+service_set is non-zero when passed with
+&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
+service_lines array will be filled by the
+driver according to the services specified in this field. For example,
+if service_set is initialized with
+V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625, a
+driver for the cx25840 video decoder sets lines 7-22 of both
+fieldsAccording to ETS 300 706 lines 6-22 of the
+first field and lines 5-22 of the second field may carry Teletext
+data. to V4L2_SLICED_TELETEXT_B
+and line 23 of the first field to
+V4L2_SLICED_WSS_625. If
+service_set is set to zero, then the values
+of service_lines will be used instead.
+On return the driver sets this field to the union of all
+elements of the returned service_lines
+array. It may contain less services than requested, perhaps just one,
+if the hardware cannot handle more services simultaneously. It may be
+empty (zero) if none of the requested services are supported by the
+hardware.
+
+
+ __u16
+ service_lines[2][24]
+ Applications initialize this
+array with sets of data services the driver shall look for or insert
+on the respective scan line. Subject to hardware capabilities drivers
+return the requested set, a subset, which may be just a single
+service, or an empty set. When the hardware cannot handle multiple
+services on the same line the driver shall choose one. No assumptions
+can be made on which service the driver chooses.Data
+services are defined in . Array indices
+map to ITU-R line numbers (see also and ) as follows:
+
+
+
+
+ Element
+ 525 line systems
+ 625 line systems
+
+
+
+
+ service_lines[0][1]
+ 1
+ 1
+
+
+
+
+ service_lines[0][23]
+ 23
+ 23
+
+
+
+
+ service_lines[1][1]
+ 264
+ 314
+
+
+
+
+ service_lines[1][23]
+ 286
+ 336
+
+
+
+
+
+ Drivers must set
+service_lines[0][0] and
+service_lines[1][0] to zero.
+
+
+ __u32
+ io_size
+ Maximum number of bytes passed by
+one &func-read; or &func-write; call, and the buffer size in bytes for
+the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
+the size of &v4l2-sliced-vbi-data; times the number of non-zero
+elements in the returned service_lines
+array (that is the number of lines potentially carrying data).
+
+
+ __u32
+ reserved[2]
+ This array is reserved for future
+extensions. Applications and drivers must set it to zero.
+
+
+
+
+
+
+
+ Sliced VBI services
+
+
+
+
+
+
+
+
+
+ Symbol
+ Value
+ Reference
+ Lines, usually
+ Payload
+
+
+
+
+ V4L2_SLICED_TELETEXT_B
+(Teletext System B)
+ 0x0001
+ ,
+ PAL/SECAM line 7-22, 320-335 (second field 7-22)
+ Last 42 of the 45 byte Teletext packet, that is
+without clock run-in and framing code, lsb first transmitted.
+
+
+ V4L2_SLICED_VPS
+ 0x0400
+
+ PAL line 16
+ Byte number 3 to 15 according to Figure 9 of
+ETS 300 231, lsb first transmitted.
+
+
+ V4L2_SLICED_CAPTION_525
+ 0x1000
+
+ NTSC line 21, 284 (second field 21)
+ Two bytes in transmission order, including parity
+bit, lsb first transmitted.
+
+
+ V4L2_SLICED_WSS_625
+ 0x4000
+ ,
+ PAL/SECAM line 23
+
+Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+
+
+ V4L2_SLICED_VBI_525
+ 0x1000
+ Set of services applicable to 525
+line systems.
+
+
+ V4L2_SLICED_VBI_625
+ 0x4401
+ Set of services applicable to 625
+line systems.
+
+
+
+
+
+ Drivers may return an &EINVAL; when applications attempt to
+read or write data without prior format negotiation, after switching
+the video standard (which may invalidate the negotiated VBI
+parameters) and after switching the video input (which may change the
+video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
+an &EBUSY; when applications attempt to change the format while i/o is
+in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
+and after the first &func-read; or &func-write; call).
+
+
+
+ Reading and writing sliced VBI data
+
+ A single &func-read; or &func-write; call must pass all data
+belonging to one video frame. That is an array of
+v4l2_sliced_vbi_data structures with one or
+more elements and a total size not exceeding
+io_size bytes. Likewise in streaming I/O
+mode one buffer of io_size bytes must
+contain data of one video frame. The id of
+unused v4l2_sliced_vbi_data elements must be
+zero.
+
+
+ struct
+<structname>v4l2_sliced_vbi_data</structname>
+
+ &cs-def;
+
+
+ __u32
+ id
+ A flag from
+identifying the type of data in this packet. Only a single bit must be
+set. When the id of a captured packet is
+zero, the packet is empty and the contents of other fields are
+undefined. Applications shall ignore empty packets. When the
+id of a packet for output is zero the
+contents of the data field are undefined
+and the driver must no longer insert data on the requested
+field and
+line.
+
+
+ __u32
+ field
+ The video field number this data has been captured
+from, or shall be inserted at. 0 for the first
+field, 1 for the second field.
+
+
+ __u32
+ line
+ The field (as opposed to frame) line number this
+data has been captured from, or shall be inserted at. See and for valid
+values. Sliced VBI capture devices can set the line number of all
+packets to 0 if the hardware cannot reliably
+identify scan lines. The field number must always be valid.
+
+
+ __u32
+ reserved
+ This field is reserved for future extensions.
+Applications and drivers must set it to zero.
+
+
+ __u8
+ data[48]
+ The packet payload. See for the contents and number of
+bytes passed for each data type. The contents of padding bytes at the
+end of this array are undefined, drivers and applications shall ignore
+them.
+
+
+
+
+
+ Packets are always passed in ascending line number order,
+without duplicate line numbers. The &func-write; function and the
+&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
+this rule. They must also return an &EINVAL; when applications pass an
+incorrect field or line number, or a combination of
+field, line and
+id which has not been negotiated with the
+&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
+unknown the driver must pass the packets in transmitted order. The
+driver can insert empty packets with id set
+to zero anywhere in the packet array.
+
+ To assure synchronization and to distinguish from frame
+dropping, when a captured frame does not carry any of the requested
+data services drivers must pass one or more empty packets. When an
+application fails to pass VBI data in time for output, the driver
+must output the last VPS and WSS packet again, and disable the output
+of Closed Caption and Teletext data, or output data which is ignored
+by Closed Caption and Teletext decoders.
+
+ A sliced VBI device may support read/write and/or streaming (memory mapping and/or user
+pointer) I/O. The latter bears the possibility of synchronizing
+video and VBI data by using buffer timestamps.
+
+
+
+
+ Sliced VBI Data in MPEG Streams
+
+ If a device can produce an MPEG output stream, it may be
+capable of providing negotiated sliced VBI
+services as data embedded in the MPEG stream. Users or
+applications control this sliced VBI data insertion with the V4L2_CID_MPEG_STREAM_VBI_FMT
+control.
+
+ If the driver does not provide the V4L2_CID_MPEG_STREAM_VBI_FMT
+control, or only allows that control to be set to
+V4L2_MPEG_STREAM_VBI_FMT_NONE, then the device
+cannot embed sliced VBI data in the MPEG stream.
+
+ The
+V4L2_CID_MPEG_STREAM_VBI_FMT control does not implicitly set
+the device driver to capture nor cease capturing sliced VBI data. The
+control only indicates to embed sliced VBI data in the MPEG stream, if
+an application has negotiated sliced VBI service be captured.
+
+ It may also be the case that a device can embed sliced VBI
+data in only certain types of MPEG streams: for example in an MPEG-2
+PS but not an MPEG-2 TS. In this situation, if sliced VBI data
+insertion is requested, the sliced VBI data will be embedded in MPEG
+stream types when supported, and silently omitted from MPEG stream
+types where sliced VBI data insertion is not supported by the device.
+
+
+ The following subsections specify the format of the
+embedded sliced VBI data.
+
+
+ MPEG Stream Embedded, Sliced VBI Data Format: NONE
+ The
+V4L2_MPEG_STREAM_VBI_FMT_NONE embedded sliced VBI
+format shall be interpreted by drivers as a control to cease
+embedding sliced VBI data in MPEG streams. Neither the device nor
+driver shall insert "empty" embedded sliced VBI data packets in the
+MPEG stream when this format is set. No MPEG stream data structures
+are specified for this format.
+
+
+
+ MPEG Stream Embedded, Sliced VBI Data Format: IVTV
+ The
+V4L2_MPEG_STREAM_VBI_FMT_IVTV embedded sliced VBI
+format, when supported, indicates to the driver to embed up to 36
+lines of sliced VBI data per frame in an MPEG-2 Private
+Stream 1 PES packet encapsulated in an MPEG-2
+Program Pack in the MPEG stream.
+
+ Historical context: This format
+specification originates from a custom, embedded, sliced VBI data
+format used by the ivtv driver. This format
+has already been informally specified in the kernel sources in the
+file Documentation/video4linux/cx2341x/README.vbi
+. The maximum size of the payload and other aspects of this format
+are driven by the CX23415 MPEG decoder's capabilities and limitations
+with respect to extracting, decoding, and displaying sliced VBI data
+embedded within an MPEG stream.
+
+ This format's use is not exclusive to
+the ivtv driver nor
+exclusive to CX2341x devices, as the sliced VBI data packet insertion
+into the MPEG stream is implemented in driver software. At least the
+cx18 driver provides sliced VBI data insertion
+into an MPEG-2 PS in this format as well.
+
+ The following definitions specify the payload of the
+MPEG-2 Private Stream 1 PES packets that contain
+sliced VBI data when
+V4L2_MPEG_STREAM_VBI_FMT_IVTV is set.
+(The MPEG-2 Private Stream 1 PES packet header
+and encapsulating MPEG-2 Program Pack header are
+not detailed here. Please refer to the MPEG-2 specifications for
+details on those packet headers.)
+
+ The payload of the MPEG-2 Private Stream 1 PES
+ packets that contain sliced VBI data is specified by
+&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
+length, depending on the actual number of lines of sliced VBI data
+present in a video frame. The payload may be padded at the end with
+unspecified fill bytes to align the end of the payload to a 4-byte
+boundary. The payload shall never exceed 1552 bytes (2 fields with
+18 lines/field with 43 bytes of data/line and a 4 byte magic number).
+
+
+
+ struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
+
+
+ &cs-ustr;
+
+
+ __u8
+ magic[4]
+
+ A "magic" constant from that indicates
+this is a valid sliced VBI data payload and also indicates which
+member of the anonymous union, itv0 or
+ITV0, to use for the payload data.
+
+
+ union
+ (anonymous)
+
+
+
+ struct
+ v4l2_mpeg_vbi_itv0
+
+ itv0
+ The primary form of the sliced VBI data payload
+that contains anywhere from 1 to 35 lines of sliced VBI data.
+Line masks are provided in this form of the payload indicating
+which VBI lines are provided.
+
+
+
+ struct
+ v4l2_mpeg_vbi_ITV0
+
+ ITV0
+ An alternate form of the sliced VBI data payload
+used when 36 lines of sliced VBI data are present. No line masks are
+provided in this form of the payload; all valid line mask bits are
+implcitly set.
+
+
+
+
+
+
+ Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
+ <structfield>magic</structfield> field
+
+ &cs-def;
+
+
+ Defined Symbol
+ Value
+ Description
+
+
+
+
+ V4L2_MPEG_VBI_IVTV_MAGIC0
+
+ "itv0"
+ Indicates the itv0
+member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.
+
+
+ V4L2_MPEG_VBI_IVTV_MAGIC1
+
+ "ITV0"
+ Indicates the ITV0
+member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
+that 36 lines of sliced VBI data are present.
+
+
+
+
+
+
+ struct <structname>v4l2_mpeg_vbi_itv0</structname>
+
+
+ &cs-str;
+
+
+ __le32
+ linemask[2]
+ Bitmasks indicating the VBI service lines
+present. These linemask values are stored
+in little endian byte order in the MPEG stream. Some reference
+linemask bit positions with their
+corresponding VBI line number and video field are given below.
+b0 indicates the least significant bit of a
+linemask value:
+linemask[0] b0: line 6 first field
+linemask[0] b17: line 23 first field
+linemask[0] b18: line 6 second field
+linemask[0] b31: line 19 second field
+linemask[1] b0: line 20 second field
+linemask[1] b3: line 23 second field
+linemask[1] b4-b31: unused and set to 0
+
+
+ struct
+ v4l2_mpeg_vbi_itv0_line
+
+ line[35]
+ This is a variable length array that holds from 1
+to 35 lines of sliced VBI data. The sliced VBI data lines present
+correspond to the bits set in the linemask
+array, starting from b0 of
+linemask[0] up through b31 of
+linemask[0], and from b0
+ of linemask[1] up through b
+3 of linemask[1].
+line[0] corresponds to the first bit
+found set in the linemask array,
+line[1] corresponds to the second bit
+found set in the linemask array, etc.
+If no linemask array bits are set, then
+line[0] may contain one line of
+unspecified data that should be ignored by applications.
+
+
+
+
+
+
+ struct <structname>v4l2_mpeg_vbi_ITV0</structname>
+
+
+ &cs-str;
+
+
+ struct
+ v4l2_mpeg_vbi_itv0_line
+
+ line[36]
+ A fixed length array of 36 lines of sliced VBI
+data. line[0] through line
+[17] correspond to lines 6 through 23 of the
+first field. line[18] through
+line[35] corresponds to lines 6
+through 23 of the second field.
+
+
+
+
+
+
+ struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
+
+
+ &cs-str;
+
+
+ __u8
+ id
+ A line identifier value from
+ that indicates
+the type of sliced VBI data stored on this line.
+
+
+ __u8
+ data[42]
+ The sliced VBI data for the line.
+
+
+
+
+
+
+ Line Identifiers for struct <link
+ linkend="v4l2-mpeg-vbi-itv0-line"><structname>
+v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
+</structfield> field
+
+ &cs-def;
+
+
+ Defined Symbol
+ Value
+ Description
+
+
+
+
+ V4L2_MPEG_VBI_IVTV_TELETEXT_B
+
+ 1
+ Refer to
+Sliced VBI services for a description of the line payload.
+
+
+ V4L2_MPEG_VBI_IVTV_CAPTION_525
+
+ 4
+ Refer to
+Sliced VBI services for a description of the line payload.
+
+
+ V4L2_MPEG_VBI_IVTV_WSS_625
+
+ 5
+ Refer to
+Sliced VBI services for a description of the line payload.
+
+
+ V4L2_MPEG_VBI_IVTV_VPS
+
+ 7
+ Refer to
+Sliced VBI services for a description of the line payload.
+
+
+
+