diff options
Diffstat (limited to 'Documentation')
250 files changed, 44768 insertions, 1255 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index d05737aaa84b..06b982affe76 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX | |||
| @@ -82,6 +82,8 @@ block/ | |||
| 82 | - info on the Block I/O (BIO) layer. | 82 | - info on the Block I/O (BIO) layer. |
| 83 | blockdev/ | 83 | blockdev/ |
| 84 | - info on block devices & drivers | 84 | - info on block devices & drivers |
| 85 | btmrvl.txt | ||
| 86 | - info on Marvell Bluetooth driver usage. | ||
| 85 | cachetlb.txt | 87 | cachetlb.txt |
| 86 | - describes the cache/TLB flushing interfaces Linux uses. | 88 | - describes the cache/TLB flushing interfaces Linux uses. |
| 87 | cdrom/ | 89 | cdrom/ |
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index cbbd3e069945..5f3bedaf8e35 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block | |||
| @@ -94,28 +94,37 @@ What: /sys/block/<disk>/queue/physical_block_size | |||
| 94 | Date: May 2009 | 94 | Date: May 2009 |
| 95 | Contact: Martin K. Petersen <martin.petersen@oracle.com> | 95 | Contact: Martin K. Petersen <martin.petersen@oracle.com> |
| 96 | Description: | 96 | Description: |
| 97 | This is the smallest unit the storage device can write | 97 | This is the smallest unit a physical storage device can |
| 98 | without resorting to read-modify-write operation. It is | 98 | write atomically. It is usually the same as the logical |
| 99 | usually the same as the logical block size but may be | 99 | block size but may be bigger. One example is SATA |
| 100 | bigger. One example is SATA drives with 4KB sectors | 100 | drives with 4KB sectors that expose a 512-byte logical |
| 101 | that expose a 512-byte logical block size to the | 101 | block size to the operating system. For stacked block |
| 102 | operating system. | 102 | devices the physical_block_size variable contains the |
| 103 | maximum physical_block_size of the component devices. | ||
| 103 | 104 | ||
| 104 | What: /sys/block/<disk>/queue/minimum_io_size | 105 | What: /sys/block/<disk>/queue/minimum_io_size |
| 105 | Date: April 2009 | 106 | Date: April 2009 |
| 106 | Contact: Martin K. Petersen <martin.petersen@oracle.com> | 107 | Contact: Martin K. Petersen <martin.petersen@oracle.com> |
| 107 | Description: | 108 | Description: |
| 108 | Storage devices may report a preferred minimum I/O size, | 109 | Storage devices may report a granularity or preferred |
| 109 | which is the smallest request the device can perform | 110 | minimum I/O size which is the smallest request the |
| 110 | without incurring a read-modify-write penalty. For disk | 111 | device can perform without incurring a performance |
| 111 | drives this is often the physical block size. For RAID | 112 | penalty. For disk drives this is often the physical |
| 112 | arrays it is often the stripe chunk size. | 113 | block size. For RAID arrays it is often the stripe |
| 114 | chunk size. A properly aligned multiple of | ||
| 115 | minimum_io_size is the preferred request size for | ||
| 116 | workloads where a high number of I/O operations is | ||
| 117 | desired. | ||
| 113 | 118 | ||
| 114 | What: /sys/block/<disk>/queue/optimal_io_size | 119 | What: /sys/block/<disk>/queue/optimal_io_size |
| 115 | Date: April 2009 | 120 | Date: April 2009 |
| 116 | Contact: Martin K. Petersen <martin.petersen@oracle.com> | 121 | Contact: Martin K. Petersen <martin.petersen@oracle.com> |
| 117 | Description: | 122 | Description: |
| 118 | Storage devices may report an optimal I/O size, which is | 123 | Storage devices may report an optimal I/O size, which is |
| 119 | the device's preferred unit of receiving I/O. This is | 124 | the device's preferred unit for sustained I/O. This is |
| 120 | rarely reported for disk drives. For RAID devices it is | 125 | rarely reported for disk drives. For RAID arrays it is |
| 121 | usually the stripe width or the internal block size. | 126 | usually the stripe width or the internal track size. A |
| 127 | properly aligned multiple of optimal_io_size is the | ||
| 128 | preferred request size for workloads where sustained | ||
| 129 | throughput is desired. If no optimal I/O size is | ||
| 130 | reported this file contains 0. | ||
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 6bf68053e4b8..25be3250f7d6 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci | |||
| @@ -84,6 +84,16 @@ Description: | |||
| 84 | from this part of the device tree. | 84 | from this part of the device tree. |
| 85 | Depends on CONFIG_HOTPLUG. | 85 | Depends on CONFIG_HOTPLUG. |
| 86 | 86 | ||
| 87 | What: /sys/bus/pci/devices/.../reset | ||
| 88 | Date: July 2009 | ||
| 89 | Contact: Michael S. Tsirkin <mst@redhat.com> | ||
| 90 | Description: | ||
| 91 | Some devices allow an individual function to be reset | ||
| 92 | without affecting other functions in the same device. | ||
| 93 | For devices that have this support, a file named reset | ||
| 94 | will be present in sysfs. Writing 1 to this file | ||
| 95 | will perform reset. | ||
| 96 | |||
| 87 | What: /sys/bus/pci/devices/.../vpd | 97 | What: /sys/bus/pci/devices/.../vpd |
| 88 | Date: February 2008 | 98 | Date: February 2008 |
| 89 | Contact: Ben Hutchings <bhutchings@solarflare.com> | 99 | Contact: Ben Hutchings <bhutchings@solarflare.com> |
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 9632444f6c62..ab8300f67182 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile | |||
| @@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ | |||
| 14 | genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ | 14 | genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ |
| 15 | mac80211.xml debugobjects.xml sh.xml regulator.xml \ | 15 | mac80211.xml debugobjects.xml sh.xml regulator.xml \ |
| 16 | alsa-driver-api.xml writing-an-alsa-driver.xml \ | 16 | alsa-driver-api.xml writing-an-alsa-driver.xml \ |
| 17 | tracepoint.xml | 17 | tracepoint.xml media.xml |
| 18 | 18 | ||
| 19 | ### | 19 | ### |
| 20 | # The build process is as follows (targets): | 20 | # The build process is as follows (targets): |
| @@ -32,7 +32,7 @@ PS_METHOD = $(prefer-db2x) | |||
| 32 | 32 | ||
| 33 | ### | 33 | ### |
| 34 | # The targets that may be used. | 34 | # The targets that may be used. |
| 35 | PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs | 35 | PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs media |
| 36 | 36 | ||
| 37 | BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) | 37 | BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) |
| 38 | xmldocs: $(BOOKS) | 38 | xmldocs: $(BOOKS) |
| @@ -45,12 +45,16 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) | |||
| 45 | pdfdocs: $(PDF) | 45 | pdfdocs: $(PDF) |
| 46 | 46 | ||
| 47 | HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) | 47 | HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) |
| 48 | htmldocs: $(HTML) | 48 | htmldocs: media $(HTML) |
| 49 | $(call build_main_index) | 49 | $(call build_main_index) |
| 50 | 50 | ||
| 51 | MAN := $(patsubst %.xml, %.9, $(BOOKS)) | 51 | MAN := $(patsubst %.xml, %.9, $(BOOKS)) |
| 52 | mandocs: $(MAN) | 52 | mandocs: $(MAN) |
| 53 | 53 | ||
| 54 | media: | ||
| 55 | mkdir -p $(srctree)/Documentation/DocBook/media/ | ||
| 56 | cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(srctree)/Documentation/DocBook/media/ | ||
| 57 | |||
| 54 | installmandocs: mandocs | 58 | installmandocs: mandocs |
| 55 | mkdir -p /usr/local/man/man9/ | 59 | mkdir -p /usr/local/man/man9/ |
| 56 | install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ | 60 | install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ |
diff --git a/Documentation/DocBook/dvb/.gitignore b/Documentation/DocBook/dvb/.gitignore new file mode 100644 index 000000000000..d7ec32eafac9 --- /dev/null +++ b/Documentation/DocBook/dvb/.gitignore | |||
| @@ -0,0 +1 @@ | |||
| !*.xml | |||
diff --git a/Documentation/DocBook/dvb/audio.xml b/Documentation/DocBook/dvb/audio.xml new file mode 100644 index 000000000000..eeb96b8a0864 --- /dev/null +++ b/Documentation/DocBook/dvb/audio.xml | |||
| @@ -0,0 +1,1473 @@ | |||
| 1 | <title>DVB Audio Device</title> | ||
| 2 | <para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It | ||
| 3 | can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and | ||
| 4 | ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your | ||
| 5 | application. | ||
| 6 | </para> | ||
| 7 | <para>Please note that some DVB cards don’t have their own MPEG decoder, which results in | ||
| 8 | the omission of the audio and video device. | ||
| 9 | </para> | ||
| 10 | |||
| 11 | <section id="audio_data_types"> | ||
| 12 | <title>Audio Data Types</title> | ||
| 13 | <para>This section describes the structures, data types and defines used when talking to the | ||
| 14 | audio device. | ||
| 15 | </para> | ||
| 16 | |||
| 17 | <section id="audio_stream_source_t"> | ||
| 18 | <title>audio_stream_source_t</title> | ||
| 19 | <para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take | ||
| 20 | the following values, depending on whether we are replaying from an internal (demux) or | ||
| 21 | external (user write) source. | ||
| 22 | </para> | ||
| 23 | <programlisting> | ||
| 24 | typedef enum { | ||
| 25 | AUDIO_SOURCE_DEMUX, | ||
| 26 | AUDIO_SOURCE_MEMORY | ||
| 27 | } audio_stream_source_t; | ||
| 28 | </programlisting> | ||
| 29 | <para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the | ||
| 30 | DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY | ||
| 31 | is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system | ||
| 32 | call. | ||
| 33 | </para> | ||
| 34 | |||
| 35 | </section> | ||
| 36 | <section id="audio_play_state_t"> | ||
| 37 | <title>audio_play_state_t</title> | ||
| 38 | <para>The following values can be returned by the AUDIO_GET_STATUS call representing the | ||
| 39 | state of audio playback. | ||
| 40 | </para> | ||
| 41 | <programlisting> | ||
| 42 | typedef enum { | ||
| 43 | AUDIO_STOPPED, | ||
| 44 | AUDIO_PLAYING, | ||
| 45 | AUDIO_PAUSED | ||
| 46 | } audio_play_state_t; | ||
| 47 | </programlisting> | ||
| 48 | |||
| 49 | </section> | ||
| 50 | <section id="audio_channel_select_t"> | ||
| 51 | <title>audio_channel_select_t</title> | ||
| 52 | <para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the | ||
| 53 | following values. | ||
| 54 | </para> | ||
| 55 | <programlisting> | ||
| 56 | typedef enum { | ||
| 57 | AUDIO_STEREO, | ||
| 58 | AUDIO_MONO_LEFT, | ||
| 59 | AUDIO_MONO_RIGHT, | ||
| 60 | } audio_channel_select_t; | ||
| 61 | </programlisting> | ||
| 62 | |||
| 63 | </section> | ||
| 64 | <section id="struct_audio_status"> | ||
| 65 | <title>struct audio_status</title> | ||
| 66 | <para>The AUDIO_GET_STATUS call returns the following structure informing about various | ||
| 67 | states of the playback operation. | ||
| 68 | </para> | ||
| 69 | <programlisting> | ||
| 70 | typedef struct audio_status { | ||
| 71 | boolean AV_sync_state; | ||
| 72 | boolean mute_state; | ||
| 73 | audio_play_state_t play_state; | ||
| 74 | audio_stream_source_t stream_source; | ||
| 75 | audio_channel_select_t channel_select; | ||
| 76 | boolean bypass_mode; | ||
| 77 | } audio_status_t; | ||
| 78 | </programlisting> | ||
| 79 | |||
| 80 | </section> | ||
| 81 | <section id="struct_audio_mixer"> | ||
| 82 | <title>struct audio_mixer</title> | ||
| 83 | <para>The following structure is used by the AUDIO_SET_MIXER call to set the audio | ||
| 84 | volume. | ||
| 85 | </para> | ||
| 86 | <programlisting> | ||
| 87 | typedef struct audio_mixer { | ||
| 88 | unsigned int volume_left; | ||
| 89 | unsigned int volume_right; | ||
| 90 | } audio_mixer_t; | ||
| 91 | </programlisting> | ||
| 92 | |||
| 93 | </section> | ||
| 94 | <section id="audio_encodings"> | ||
| 95 | <title>audio encodings</title> | ||
| 96 | <para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following | ||
| 97 | bits set according to the hardwares capabilities. | ||
| 98 | </para> | ||
| 99 | <programlisting> | ||
| 100 | #define AUDIO_CAP_DTS 1 | ||
| 101 | #define AUDIO_CAP_LPCM 2 | ||
| 102 | #define AUDIO_CAP_MP1 4 | ||
| 103 | #define AUDIO_CAP_MP2 8 | ||
| 104 | #define AUDIO_CAP_MP3 16 | ||
| 105 | #define AUDIO_CAP_AAC 32 | ||
| 106 | #define AUDIO_CAP_OGG 64 | ||
| 107 | #define AUDIO_CAP_SDDS 128 | ||
| 108 | #define AUDIO_CAP_AC3 256 | ||
| 109 | </programlisting> | ||
| 110 | |||
| 111 | </section> | ||
| 112 | <section id="struct_audio_karaoke"> | ||
| 113 | <title>struct audio_karaoke</title> | ||
| 114 | <para>The ioctl AUDIO_SET_KARAOKE uses the following format: | ||
| 115 | </para> | ||
| 116 | <programlisting> | ||
| 117 | typedef | ||
| 118 | struct audio_karaoke{ | ||
| 119 | int vocal1; | ||
| 120 | int vocal2; | ||
| 121 | int melody; | ||
| 122 | } audio_karaoke_t; | ||
| 123 | </programlisting> | ||
| 124 | <para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, | ||
| 125 | Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the | ||
| 126 | right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left | ||
| 127 | and right. | ||
| 128 | </para> | ||
| 129 | |||
| 130 | </section> | ||
| 131 | <section id="audio_attributes"> | ||
| 132 | <title>audio attributes</title> | ||
| 133 | <para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: | ||
| 134 | </para> | ||
| 135 | <programlisting> | ||
| 136 | typedef uint16_t audio_attributes_t; | ||
| 137 | /⋆ bits: descr. ⋆/ | ||
| 138 | /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ | ||
| 139 | /⋆ 12 multichannel extension ⋆/ | ||
| 140 | /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ | ||
| 141 | /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ | ||
| 142 | /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ | ||
| 143 | /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ | ||
| 144 | /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ | ||
| 145 | </programlisting> | ||
| 146 | </section></section> | ||
| 147 | <section id="audio_function_calls"> | ||
| 148 | <title>Audio Function Calls</title> | ||
| 149 | |||
| 150 | |||
| 151 | <section id="audio_fopen"> | ||
| 152 | <title>open()</title> | ||
| 153 | <para>DESCRIPTION | ||
| 154 | </para> | ||
| 155 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 156 | align="char"> | ||
| 157 | <para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) | ||
| 158 | for subsequent use. When an open() call has succeeded, the device will be ready | ||
| 159 | for use. The significance of blocking or non-blocking mode is described in the | ||
| 160 | documentation for functions where there is a difference. It does not affect the | ||
| 161 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 162 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 163 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 164 | manual page for fcntl. Only one user can open the Audio Device in O_RDWR | ||
| 165 | mode. All other attempts to open the device in this mode will fail, and an error | ||
| 166 | code will be returned. If the Audio Device is opened in O_RDONLY mode, the | ||
| 167 | only ioctl call that can be used is AUDIO_GET_STATUS. All other call will | ||
| 168 | return with an error code.</para> | ||
| 169 | </entry> | ||
| 170 | </row></tbody></tgroup></informaltable> | ||
| 171 | <para>SYNOPSIS | ||
| 172 | </para> | ||
| 173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 174 | align="char"> | ||
| 175 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 176 | </entry> | ||
| 177 | </row></tbody></tgroup></informaltable> | ||
| 178 | <para>PARAMETERS | ||
| 179 | </para> | ||
| 180 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 181 | align="char"> | ||
| 182 | <para>const char | ||
| 183 | *deviceName</para> | ||
| 184 | </entry><entry | ||
| 185 | align="char"> | ||
| 186 | <para>Name of specific audio device.</para> | ||
| 187 | </entry> | ||
| 188 | </row><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>int flags</para> | ||
| 191 | </entry><entry | ||
| 192 | align="char"> | ||
| 193 | <para>A bit-wise OR of the following flags:</para> | ||
| 194 | </entry> | ||
| 195 | </row><row><entry | ||
| 196 | align="char"> | ||
| 197 | </entry><entry | ||
| 198 | align="char"> | ||
| 199 | <para>O_RDONLY read-only access</para> | ||
| 200 | </entry> | ||
| 201 | </row><row><entry | ||
| 202 | align="char"> | ||
| 203 | </entry><entry | ||
| 204 | align="char"> | ||
| 205 | <para>O_RDWR read/write access</para> | ||
| 206 | </entry> | ||
| 207 | </row><row><entry | ||
| 208 | align="char"> | ||
| 209 | </entry><entry | ||
| 210 | align="char"> | ||
| 211 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 212 | </entry> | ||
| 213 | </row><row><entry | ||
| 214 | align="char"> | ||
| 215 | </entry><entry | ||
| 216 | align="char"> | ||
| 217 | <para>(blocking mode is the default)</para> | ||
| 218 | </entry> | ||
| 219 | </row></tbody></tgroup></informaltable> | ||
| 220 | <para>ERRORS | ||
| 221 | </para> | ||
| 222 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 223 | align="char"> | ||
| 224 | <para>ENODEV</para> | ||
| 225 | </entry><entry | ||
| 226 | align="char"> | ||
| 227 | <para>Device driver not loaded/available.</para> | ||
| 228 | </entry> | ||
| 229 | </row><row><entry | ||
| 230 | align="char"> | ||
| 231 | <para>EINTERNAL</para> | ||
| 232 | </entry><entry | ||
| 233 | align="char"> | ||
| 234 | <para>Internal error.</para> | ||
| 235 | </entry> | ||
| 236 | </row><row><entry | ||
| 237 | align="char"> | ||
| 238 | <para>EBUSY</para> | ||
| 239 | </entry><entry | ||
| 240 | align="char"> | ||
| 241 | <para>Device or resource busy.</para> | ||
| 242 | </entry> | ||
| 243 | </row><row><entry | ||
| 244 | align="char"> | ||
| 245 | <para>EINVAL</para> | ||
| 246 | </entry><entry | ||
| 247 | align="char"> | ||
| 248 | <para>Invalid argument.</para> | ||
| 249 | </entry> | ||
| 250 | </row></tbody></tgroup></informaltable> | ||
| 251 | |||
| 252 | </section> | ||
| 253 | <section id="audio_fclose"> | ||
| 254 | <title>close()</title> | ||
| 255 | <para>DESCRIPTION | ||
| 256 | </para> | ||
| 257 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 258 | align="char"> | ||
| 259 | <para>This system call closes a previously opened audio device.</para> | ||
| 260 | </entry> | ||
| 261 | </row></tbody></tgroup></informaltable> | ||
| 262 | <para>SYNOPSIS | ||
| 263 | </para> | ||
| 264 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 265 | align="char"> | ||
| 266 | <para>int close(int fd);</para> | ||
| 267 | </entry> | ||
| 268 | </row></tbody></tgroup></informaltable> | ||
| 269 | <para>PARAMETERS | ||
| 270 | </para> | ||
| 271 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 272 | align="char"> | ||
| 273 | <para>int fd</para> | ||
| 274 | </entry><entry | ||
| 275 | align="char"> | ||
| 276 | <para>File descriptor returned by a previous call to open().</para> | ||
| 277 | </entry> | ||
| 278 | </row></tbody></tgroup></informaltable> | ||
| 279 | <para>ERRORS | ||
| 280 | </para> | ||
| 281 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 282 | align="char"> | ||
| 283 | <para>EBADF</para> | ||
| 284 | </entry><entry | ||
| 285 | align="char"> | ||
| 286 | <para>fd is not a valid open file descriptor.</para> | ||
| 287 | </entry> | ||
| 288 | </row></tbody></tgroup></informaltable> | ||
| 289 | |||
| 290 | </section> | ||
| 291 | <section id="audio_fwrite"> | ||
| 292 | <title>write()</title> | ||
| 293 | <para>DESCRIPTION | ||
| 294 | </para> | ||
| 295 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 296 | align="char"> | ||
| 297 | <para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected | ||
| 298 | in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in | ||
| 299 | PES format. If O_NONBLOCK is not specified the function will block until | ||
| 300 | buffer space is available. The amount of data to be transferred is implied by | ||
| 301 | count.</para> | ||
| 302 | </entry> | ||
| 303 | </row></tbody></tgroup></informaltable> | ||
| 304 | <para>SYNOPSIS | ||
| 305 | </para> | ||
| 306 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 307 | align="char"> | ||
| 308 | <para>size_t write(int fd, const void ⋆buf, size_t count);</para> | ||
| 309 | </entry> | ||
| 310 | </row></tbody></tgroup></informaltable> | ||
| 311 | <para>PARAMETERS | ||
| 312 | </para> | ||
| 313 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 314 | align="char"> | ||
| 315 | <para>int fd</para> | ||
| 316 | </entry><entry | ||
| 317 | align="char"> | ||
| 318 | <para>File descriptor returned by a previous call to open().</para> | ||
| 319 | </entry> | ||
| 320 | </row><row><entry | ||
| 321 | align="char"> | ||
| 322 | <para>void *buf</para> | ||
| 323 | </entry><entry | ||
| 324 | align="char"> | ||
| 325 | <para>Pointer to the buffer containing the PES data.</para> | ||
| 326 | </entry> | ||
| 327 | </row><row><entry | ||
| 328 | align="char"> | ||
| 329 | <para>size_t count</para> | ||
| 330 | </entry><entry | ||
| 331 | align="char"> | ||
| 332 | <para>Size of buf.</para> | ||
| 333 | </entry> | ||
| 334 | </row></tbody></tgroup></informaltable> | ||
| 335 | <para>ERRORS | ||
| 336 | </para> | ||
| 337 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 338 | align="char"> | ||
| 339 | <para>EPERM</para> | ||
| 340 | </entry><entry | ||
| 341 | align="char"> | ||
| 342 | <para>Mode AUDIO_SOURCE_MEMORY not selected.</para> | ||
| 343 | </entry> | ||
| 344 | </row><row><entry | ||
| 345 | align="char"> | ||
| 346 | <para>ENOMEM</para> | ||
| 347 | </entry><entry | ||
| 348 | align="char"> | ||
| 349 | <para>Attempted to write more data than the internal buffer can | ||
| 350 | hold.</para> | ||
| 351 | </entry> | ||
| 352 | </row><row><entry | ||
| 353 | align="char"> | ||
| 354 | <para>EBADF</para> | ||
| 355 | </entry><entry | ||
| 356 | align="char"> | ||
| 357 | <para>fd is not a valid open file descriptor.</para> | ||
| 358 | </entry> | ||
| 359 | </row></tbody></tgroup></informaltable> | ||
| 360 | |||
| 361 | </section><section | ||
| 362 | role="subsection"><title>AUDIO_STOP</title> | ||
| 363 | <para>DESCRIPTION | ||
| 364 | </para> | ||
| 365 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 366 | align="char"> | ||
| 367 | <para>This ioctl call asks the Audio Device to stop playing the current stream.</para> | ||
| 368 | </entry> | ||
| 369 | </row></tbody></tgroup></informaltable> | ||
| 370 | <para>SYNOPSIS | ||
| 371 | </para> | ||
| 372 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 373 | align="char"> | ||
| 374 | <para>int ioctl(int fd, int request = AUDIO_STOP);</para> | ||
| 375 | </entry> | ||
| 376 | </row></tbody></tgroup></informaltable> | ||
| 377 | <para>PARAMETERS | ||
| 378 | </para> | ||
| 379 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 380 | align="char"> | ||
| 381 | <para>int fd</para> | ||
| 382 | </entry><entry | ||
| 383 | align="char"> | ||
| 384 | <para>File descriptor returned by a previous call to open().</para> | ||
| 385 | </entry> | ||
| 386 | </row><row><entry | ||
| 387 | align="char"> | ||
| 388 | <para>int request</para> | ||
| 389 | </entry><entry | ||
| 390 | align="char"> | ||
| 391 | <para>Equals AUDIO_STOP for this command.</para> | ||
| 392 | </entry> | ||
| 393 | </row></tbody></tgroup></informaltable> | ||
| 394 | <para>ERRORS | ||
| 395 | </para> | ||
| 396 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 397 | align="char"> | ||
| 398 | <para>EBADF</para> | ||
| 399 | </entry><entry | ||
| 400 | align="char"> | ||
| 401 | <para>fd is not a valid open file descriptor</para> | ||
| 402 | </entry> | ||
| 403 | </row><row><entry | ||
| 404 | align="char"> | ||
| 405 | <para>EINTERNAL</para> | ||
| 406 | </entry><entry | ||
| 407 | align="char"> | ||
| 408 | <para>Internal error.</para> | ||
| 409 | </entry> | ||
| 410 | </row></tbody></tgroup></informaltable> | ||
| 411 | |||
| 412 | </section><section | ||
| 413 | role="subsection"><title>AUDIO_PLAY</title> | ||
| 414 | <para>DESCRIPTION | ||
| 415 | </para> | ||
| 416 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 417 | align="char"> | ||
| 418 | <para>This ioctl call asks the Audio Device to start playing an audio stream from the | ||
| 419 | selected source.</para> | ||
| 420 | </entry> | ||
| 421 | </row></tbody></tgroup></informaltable> | ||
| 422 | <para>SYNOPSIS | ||
| 423 | </para> | ||
| 424 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 425 | align="char"> | ||
| 426 | <para>int ioctl(int fd, int request = AUDIO_PLAY);</para> | ||
| 427 | </entry> | ||
| 428 | </row></tbody></tgroup></informaltable> | ||
| 429 | <para>PARAMETERS | ||
| 430 | </para> | ||
| 431 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 432 | align="char"> | ||
| 433 | <para>int fd</para> | ||
| 434 | </entry><entry | ||
| 435 | align="char"> | ||
| 436 | <para>File descriptor returned by a previous call to open().</para> | ||
| 437 | </entry> | ||
| 438 | </row><row><entry | ||
| 439 | align="char"> | ||
| 440 | <para>int request</para> | ||
| 441 | </entry><entry | ||
| 442 | align="char"> | ||
| 443 | <para>Equals AUDIO_PLAY for this command.</para> | ||
| 444 | </entry> | ||
| 445 | </row></tbody></tgroup></informaltable> | ||
| 446 | <para>ERRORS | ||
| 447 | </para> | ||
| 448 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 449 | align="char"> | ||
| 450 | <para>EBADF</para> | ||
| 451 | </entry><entry | ||
| 452 | align="char"> | ||
| 453 | <para>fd is not a valid open file descriptor</para> | ||
| 454 | </entry> | ||
| 455 | </row><row><entry | ||
| 456 | align="char"> | ||
| 457 | <para>EINTERNAL</para> | ||
| 458 | </entry><entry | ||
| 459 | align="char"> | ||
| 460 | <para>Internal error.</para> | ||
| 461 | </entry> | ||
| 462 | </row></tbody></tgroup></informaltable> | ||
| 463 | |||
| 464 | </section><section | ||
| 465 | role="subsection"><title>AUDIO_PAUSE</title> | ||
| 466 | <para>DESCRIPTION | ||
| 467 | </para> | ||
| 468 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 469 | align="char"> | ||
| 470 | <para>This ioctl call suspends the audio stream being played. Decoding and playing | ||
| 471 | are paused. It is then possible to restart again decoding and playing process of | ||
| 472 | the audio stream using AUDIO_CONTINUE command.</para> | ||
| 473 | </entry> | ||
| 474 | </row><row><entry | ||
| 475 | align="char"> | ||
| 476 | <para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call | ||
| 477 | AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume) | ||
| 478 | any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is | ||
| 479 | performed.</para> | ||
| 480 | </entry> | ||
| 481 | </row></tbody></tgroup></informaltable> | ||
| 482 | <para>SYNOPSIS | ||
| 483 | </para> | ||
| 484 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 485 | align="char"> | ||
| 486 | <para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> | ||
| 487 | </entry> | ||
| 488 | </row></tbody></tgroup></informaltable> | ||
| 489 | <para>PARAMETERS | ||
| 490 | </para> | ||
| 491 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 492 | align="char"> | ||
| 493 | <para>int fd</para> | ||
| 494 | </entry><entry | ||
| 495 | align="char"> | ||
| 496 | <para>File descriptor returned by a previous call to open().</para> | ||
| 497 | </entry> | ||
| 498 | </row><row><entry | ||
| 499 | align="char"> | ||
| 500 | <para>int request</para> | ||
| 501 | </entry><entry | ||
| 502 | align="char"> | ||
| 503 | <para>Equals AUDIO_PAUSE for this command.</para> | ||
| 504 | </entry> | ||
| 505 | </row></tbody></tgroup></informaltable> | ||
| 506 | <para>ERRORS | ||
| 507 | </para> | ||
| 508 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 509 | align="char"> | ||
| 510 | <para>EBADF</para> | ||
| 511 | </entry><entry | ||
| 512 | align="char"> | ||
| 513 | <para>fd is not a valid open file descriptor.</para> | ||
| 514 | </entry> | ||
| 515 | </row><row><entry | ||
| 516 | align="char"> | ||
| 517 | <para>EINTERNAL</para> | ||
| 518 | </entry><entry | ||
| 519 | align="char"> | ||
| 520 | <para>Internal error.</para> | ||
| 521 | </entry> | ||
| 522 | </row></tbody></tgroup></informaltable> | ||
| 523 | |||
| 524 | </section><section | ||
| 525 | role="subsection"><title>AUDIO_SELECT_SOURCE</title> | ||
| 526 | <para>DESCRIPTION | ||
| 527 | </para> | ||
| 528 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 529 | align="char"> | ||
| 530 | <para>This ioctl call informs the audio device which source shall be used | ||
| 531 | for the input data. The possible sources are demux or memory. If | ||
| 532 | AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device | ||
| 533 | through the write command.</para> | ||
| 534 | </entry> | ||
| 535 | </row></tbody></tgroup></informaltable> | ||
| 536 | <para>SYNOPSIS | ||
| 537 | </para> | ||
| 538 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 539 | align="char"> | ||
| 540 | <para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, | ||
| 541 | audio_stream_source_t source);</para> | ||
| 542 | </entry> | ||
| 543 | </row></tbody></tgroup></informaltable> | ||
| 544 | <para>PARAMETERS | ||
| 545 | </para> | ||
| 546 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 547 | align="char"> | ||
| 548 | <para>int fd</para> | ||
| 549 | </entry><entry | ||
| 550 | align="char"> | ||
| 551 | <para>File descriptor returned by a previous call to open().</para> | ||
| 552 | </entry> | ||
| 553 | </row><row><entry | ||
| 554 | align="char"> | ||
| 555 | <para>int request</para> | ||
| 556 | </entry><entry | ||
| 557 | align="char"> | ||
| 558 | <para>Equals AUDIO_SELECT_SOURCE for this command.</para> | ||
| 559 | </entry> | ||
| 560 | </row><row><entry | ||
| 561 | align="char"> | ||
| 562 | <para>audio_stream_source_t | ||
| 563 | source</para> | ||
| 564 | </entry><entry | ||
| 565 | align="char"> | ||
| 566 | <para>Indicates the source that shall be used for the Audio | ||
| 567 | stream.</para> | ||
| 568 | </entry> | ||
| 569 | </row></tbody></tgroup></informaltable> | ||
| 570 | <para>ERRORS | ||
| 571 | </para> | ||
| 572 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 573 | align="char"> | ||
| 574 | <para>EBADF</para> | ||
| 575 | </entry><entry | ||
| 576 | align="char"> | ||
| 577 | <para>fd is not a valid open file descriptor.</para> | ||
| 578 | </entry> | ||
| 579 | </row><row><entry | ||
| 580 | align="char"> | ||
| 581 | <para>EINTERNAL</para> | ||
| 582 | </entry><entry | ||
| 583 | align="char"> | ||
| 584 | <para>Internal error.</para> | ||
| 585 | </entry> | ||
| 586 | </row><row><entry | ||
| 587 | align="char"> | ||
| 588 | <para>EINVAL</para> | ||
| 589 | </entry><entry | ||
| 590 | align="char"> | ||
| 591 | <para>Illegal input parameter.</para> | ||
| 592 | </entry> | ||
| 593 | </row></tbody></tgroup></informaltable> | ||
| 594 | |||
| 595 | </section><section | ||
| 596 | role="subsection"><title>AUDIO_SET_MUTE</title> | ||
| 597 | <para>DESCRIPTION | ||
| 598 | </para> | ||
| 599 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 600 | align="char"> | ||
| 601 | <para>This ioctl call asks the audio device to mute the stream that is currently being | ||
| 602 | played.</para> | ||
| 603 | </entry> | ||
| 604 | </row></tbody></tgroup></informaltable> | ||
| 605 | <para>SYNOPSIS | ||
| 606 | </para> | ||
| 607 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 608 | align="char"> | ||
| 609 | <para>int ioctl(int fd, int request = AUDIO_SET_MUTE, | ||
| 610 | boolean state);</para> | ||
| 611 | </entry> | ||
| 612 | </row></tbody></tgroup></informaltable> | ||
| 613 | <para>PARAMETERS | ||
| 614 | </para> | ||
| 615 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 616 | align="char"> | ||
| 617 | <para>int fd</para> | ||
| 618 | </entry><entry | ||
| 619 | align="char"> | ||
| 620 | <para>File descriptor returned by a previous call to open().</para> | ||
| 621 | </entry> | ||
| 622 | </row><row><entry | ||
| 623 | align="char"> | ||
| 624 | <para>int request</para> | ||
| 625 | </entry><entry | ||
| 626 | align="char"> | ||
| 627 | <para>Equals AUDIO_SET_MUTE for this command.</para> | ||
| 628 | </entry> | ||
| 629 | </row><row><entry | ||
| 630 | align="char"> | ||
| 631 | <para>boolean state</para> | ||
| 632 | </entry><entry | ||
| 633 | align="char"> | ||
| 634 | <para>Indicates if audio device shall mute or not.</para> | ||
| 635 | </entry> | ||
| 636 | </row><row><entry | ||
| 637 | align="char"> | ||
| 638 | </entry><entry | ||
| 639 | align="char"> | ||
| 640 | <para>TRUE Audio Mute</para> | ||
| 641 | </entry> | ||
| 642 | </row><row><entry | ||
| 643 | align="char"> | ||
| 644 | </entry><entry | ||
| 645 | align="char"> | ||
| 646 | <para>FALSE Audio Un-mute</para> | ||
| 647 | </entry> | ||
| 648 | </row></tbody></tgroup></informaltable> | ||
| 649 | <para>ERRORS | ||
| 650 | </para> | ||
| 651 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 652 | align="char"> | ||
| 653 | <para>EBADF</para> | ||
| 654 | </entry><entry | ||
| 655 | align="char"> | ||
| 656 | <para>fd is not a valid open file descriptor.</para> | ||
| 657 | </entry> | ||
| 658 | </row><row><entry | ||
| 659 | align="char"> | ||
| 660 | <para>EINTERNAL</para> | ||
| 661 | </entry><entry | ||
| 662 | align="char"> | ||
| 663 | <para>Internal error.</para> | ||
| 664 | </entry> | ||
| 665 | </row><row><entry | ||
| 666 | align="char"> | ||
| 667 | <para>EINVAL</para> | ||
| 668 | </entry><entry | ||
| 669 | align="char"> | ||
| 670 | <para>Illegal input parameter.</para> | ||
| 671 | </entry> | ||
| 672 | </row></tbody></tgroup></informaltable> | ||
| 673 | |||
| 674 | </section><section | ||
| 675 | role="subsection"><title>AUDIO_SET_AV_SYNC</title> | ||
| 676 | <para>DESCRIPTION | ||
| 677 | </para> | ||
| 678 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 679 | align="char"> | ||
| 680 | <para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> | ||
| 681 | </entry> | ||
| 682 | </row></tbody></tgroup></informaltable> | ||
| 683 | <para>SYNOPSIS | ||
| 684 | </para> | ||
| 685 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 686 | align="char"> | ||
| 687 | <para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, | ||
| 688 | boolean state);</para> | ||
| 689 | </entry> | ||
| 690 | </row></tbody></tgroup></informaltable> | ||
| 691 | <para>PARAMETERS | ||
| 692 | </para> | ||
| 693 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 694 | align="char"> | ||
| 695 | <para>int fd</para> | ||
| 696 | </entry><entry | ||
| 697 | align="char"> | ||
| 698 | <para>File descriptor returned by a previous call to open().</para> | ||
| 699 | </entry> | ||
| 700 | </row><row><entry | ||
| 701 | align="char"> | ||
| 702 | <para>int request</para> | ||
| 703 | </entry><entry | ||
| 704 | align="char"> | ||
| 705 | <para>Equals AUDIO_AV_SYNC for this command.</para> | ||
| 706 | </entry> | ||
| 707 | </row><row><entry | ||
| 708 | align="char"> | ||
| 709 | <para>boolean state</para> | ||
| 710 | </entry><entry | ||
| 711 | align="char"> | ||
| 712 | <para>Tells the DVB subsystem if A/V synchronization shall be | ||
| 713 | ON or OFF.</para> | ||
| 714 | </entry> | ||
| 715 | </row><row><entry | ||
| 716 | align="char"> | ||
| 717 | </entry><entry | ||
| 718 | align="char"> | ||
| 719 | <para>TRUE AV-sync ON</para> | ||
| 720 | </entry> | ||
| 721 | </row><row><entry | ||
| 722 | align="char"> | ||
| 723 | </entry><entry | ||
| 724 | align="char"> | ||
| 725 | <para>FALSE AV-sync OFF</para> | ||
| 726 | </entry> | ||
| 727 | </row></tbody></tgroup></informaltable> | ||
| 728 | <para>ERRORS | ||
| 729 | </para> | ||
| 730 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 731 | align="char"> | ||
| 732 | <para>EBADF</para> | ||
| 733 | </entry><entry | ||
| 734 | align="char"> | ||
| 735 | <para>fd is not a valid open file descriptor.</para> | ||
| 736 | </entry> | ||
| 737 | </row><row><entry | ||
| 738 | align="char"> | ||
| 739 | <para>EINTERNAL</para> | ||
| 740 | </entry><entry | ||
| 741 | align="char"> | ||
| 742 | <para>Internal error.</para> | ||
| 743 | </entry> | ||
| 744 | </row><row><entry | ||
| 745 | align="char"> | ||
| 746 | <para>EINVAL</para> | ||
| 747 | </entry><entry | ||
| 748 | align="char"> | ||
| 749 | <para>Illegal input parameter.</para> | ||
| 750 | </entry> | ||
| 751 | </row></tbody></tgroup></informaltable> | ||
| 752 | |||
| 753 | </section><section | ||
| 754 | role="subsection"><title>AUDIO_SET_BYPASS_MODE</title> | ||
| 755 | <para>DESCRIPTION | ||
| 756 | </para> | ||
| 757 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 758 | align="char"> | ||
| 759 | <para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward | ||
| 760 | the stream without decoding. This mode shall be used if streams that can’t be | ||
| 761 | handled by the DVB system shall be decoded. Dolby DigitalTM streams are | ||
| 762 | automatically forwarded by the DVB subsystem if the hardware can handle it.</para> | ||
| 763 | </entry> | ||
| 764 | </row></tbody></tgroup></informaltable> | ||
| 765 | <para>SYNOPSIS | ||
| 766 | </para> | ||
| 767 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 768 | align="char"> | ||
| 769 | <para>int ioctl(int fd, int request = | ||
| 770 | AUDIO_SET_BYPASS_MODE, boolean mode);</para> | ||
| 771 | </entry> | ||
| 772 | </row></tbody></tgroup></informaltable> | ||
| 773 | <para>PARAMETERS | ||
| 774 | </para> | ||
| 775 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 776 | align="char"> | ||
| 777 | <para>int fd</para> | ||
| 778 | </entry><entry | ||
| 779 | align="char"> | ||
| 780 | <para>File descriptor returned by a previous call to open().</para> | ||
| 781 | </entry> | ||
| 782 | </row><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>int request</para> | ||
| 785 | </entry><entry | ||
| 786 | align="char"> | ||
| 787 | <para>Equals AUDIO_SET_BYPASS_MODE for this | ||
| 788 | command.</para> | ||
| 789 | </entry> | ||
| 790 | </row><row><entry | ||
| 791 | align="char"> | ||
| 792 | <para>boolean mode</para> | ||
| 793 | </entry><entry | ||
| 794 | align="char"> | ||
| 795 | <para>Enables or disables the decoding of the current Audio | ||
| 796 | stream in the DVB subsystem.</para> | ||
| 797 | </entry> | ||
| 798 | </row><row><entry | ||
| 799 | align="char"> | ||
| 800 | </entry><entry | ||
| 801 | align="char"> | ||
| 802 | <para>TRUE Bypass is disabled</para> | ||
| 803 | </entry> | ||
| 804 | </row><row><entry | ||
| 805 | align="char"> | ||
| 806 | </entry><entry | ||
| 807 | align="char"> | ||
| 808 | <para>FALSE Bypass is enabled</para> | ||
| 809 | </entry> | ||
| 810 | </row></tbody></tgroup></informaltable> | ||
| 811 | <para>ERRORS | ||
| 812 | </para> | ||
| 813 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 814 | align="char"> | ||
| 815 | <para>EBADF</para> | ||
| 816 | </entry><entry | ||
| 817 | align="char"> | ||
| 818 | <para>fd is not a valid open file descriptor.</para> | ||
| 819 | </entry> | ||
| 820 | </row><row><entry | ||
| 821 | align="char"> | ||
| 822 | <para>EINTERNAL</para> | ||
| 823 | </entry><entry | ||
| 824 | align="char"> | ||
| 825 | <para>Internal error.</para> | ||
| 826 | </entry> | ||
| 827 | </row><row><entry | ||
| 828 | align="char"> | ||
| 829 | <para>EINVAL</para> | ||
| 830 | </entry><entry | ||
| 831 | align="char"> | ||
| 832 | <para>Illegal input parameter.</para> | ||
| 833 | </entry> | ||
| 834 | </row></tbody></tgroup></informaltable> | ||
| 835 | |||
| 836 | </section><section | ||
| 837 | role="subsection"><title>AUDIO_CHANNEL_SELECT</title> | ||
| 838 | <para>DESCRIPTION | ||
| 839 | </para> | ||
| 840 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> | ||
| 843 | </entry> | ||
| 844 | </row></tbody></tgroup></informaltable> | ||
| 845 | <para>SYNOPSIS | ||
| 846 | </para> | ||
| 847 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 848 | align="char"> | ||
| 849 | <para>int ioctl(int fd, int request = | ||
| 850 | AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> | ||
| 851 | </entry> | ||
| 852 | </row></tbody></tgroup></informaltable> | ||
| 853 | <para>PARAMETERS | ||
| 854 | </para> | ||
| 855 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 856 | align="char"> | ||
| 857 | <para>int fd</para> | ||
| 858 | </entry><entry | ||
| 859 | align="char"> | ||
| 860 | <para>File descriptor returned by a previous call to open().</para> | ||
| 861 | </entry> | ||
| 862 | </row><row><entry | ||
| 863 | align="char"> | ||
| 864 | <para>int request</para> | ||
| 865 | </entry><entry | ||
| 866 | align="char"> | ||
| 867 | <para>Equals AUDIO_CHANNEL_SELECT for this | ||
| 868 | command.</para> | ||
| 869 | </entry> | ||
| 870 | </row><row><entry | ||
| 871 | align="char"> | ||
| 872 | <para>audio_channel_select_t | ||
| 873 | ch</para> | ||
| 874 | </entry><entry | ||
| 875 | align="char"> | ||
| 876 | <para>Select the output format of the audio (mono left/right, | ||
| 877 | stereo).</para> | ||
| 878 | </entry> | ||
| 879 | </row></tbody></tgroup></informaltable> | ||
| 880 | <para>ERRORS | ||
| 881 | </para> | ||
| 882 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 883 | align="char"> | ||
| 884 | <para>EBADF</para> | ||
| 885 | </entry><entry | ||
| 886 | align="char"> | ||
| 887 | <para>fd is not a valid open file descriptor.</para> | ||
| 888 | </entry> | ||
| 889 | </row><row><entry | ||
| 890 | align="char"> | ||
| 891 | <para>EINTERNAL</para> | ||
| 892 | </entry><entry | ||
| 893 | align="char"> | ||
| 894 | <para>Internal error.</para> | ||
| 895 | </entry> | ||
| 896 | </row><row><entry | ||
| 897 | align="char"> | ||
| 898 | <para>EINVAL</para> | ||
| 899 | </entry><entry | ||
| 900 | align="char"> | ||
| 901 | <para>Illegal input parameter ch.</para> | ||
| 902 | </entry> | ||
| 903 | </row></tbody></tgroup></informaltable> | ||
| 904 | |||
| 905 | </section><section | ||
| 906 | role="subsection"><title>AUDIO_GET_STATUS</title> | ||
| 907 | <para>DESCRIPTION | ||
| 908 | </para> | ||
| 909 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 910 | align="char"> | ||
| 911 | <para>This ioctl call asks the Audio Device to return the current state of the Audio | ||
| 912 | Device.</para> | ||
| 913 | </entry> | ||
| 914 | </row></tbody></tgroup></informaltable> | ||
| 915 | <para>SYNOPSIS | ||
| 916 | </para> | ||
| 917 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 918 | align="char"> | ||
| 919 | <para>int ioctl(int fd, int request = AUDIO_GET_STATUS, | ||
| 920 | struct audio_status ⋆status);</para> | ||
| 921 | </entry> | ||
| 922 | </row></tbody></tgroup></informaltable> | ||
| 923 | <para>PARAMETERS | ||
| 924 | </para> | ||
| 925 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 926 | align="char"> | ||
| 927 | <para>int fd</para> | ||
| 928 | </entry><entry | ||
| 929 | align="char"> | ||
| 930 | <para>File descriptor returned by a previous call to open().</para> | ||
| 931 | </entry> | ||
| 932 | </row><row><entry | ||
| 933 | align="char"> | ||
| 934 | <para>int request</para> | ||
| 935 | </entry><entry | ||
| 936 | align="char"> | ||
| 937 | <para>Equals AUDIO_GET_STATUS for this command.</para> | ||
| 938 | </entry> | ||
| 939 | </row><row><entry | ||
| 940 | align="char"> | ||
| 941 | <para>struct audio_status | ||
| 942 | *status</para> | ||
| 943 | </entry><entry | ||
| 944 | align="char"> | ||
| 945 | <para>Returns the current state of Audio Device.</para> | ||
| 946 | </entry> | ||
| 947 | </row></tbody></tgroup></informaltable> | ||
| 948 | <para>ERRORS | ||
| 949 | </para> | ||
| 950 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 951 | align="char"> | ||
| 952 | <para>EBADF</para> | ||
| 953 | </entry><entry | ||
| 954 | align="char"> | ||
| 955 | <para>fd is not a valid open file descriptor.</para> | ||
| 956 | </entry> | ||
| 957 | </row><row><entry | ||
| 958 | align="char"> | ||
| 959 | <para>EINTERNAL</para> | ||
| 960 | </entry><entry | ||
| 961 | align="char"> | ||
| 962 | <para>Internal error.</para> | ||
| 963 | </entry> | ||
| 964 | </row><row><entry | ||
| 965 | align="char"> | ||
| 966 | <para>EFAULT</para> | ||
| 967 | </entry><entry | ||
| 968 | align="char"> | ||
| 969 | <para>status points to invalid address.</para> | ||
| 970 | </entry> | ||
| 971 | </row></tbody></tgroup></informaltable> | ||
| 972 | |||
| 973 | </section><section | ||
| 974 | role="subsection"><title>AUDIO_GET_CAPABILITIES</title> | ||
| 975 | <para>DESCRIPTION | ||
| 976 | </para> | ||
| 977 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 978 | align="char"> | ||
| 979 | <para>This ioctl call asks the Audio Device to tell us about the decoding capabilities | ||
| 980 | of the audio hardware.</para> | ||
| 981 | </entry> | ||
| 982 | </row></tbody></tgroup></informaltable> | ||
| 983 | <para>SYNOPSIS | ||
| 984 | </para> | ||
| 985 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 986 | align="char"> | ||
| 987 | <para>int ioctl(int fd, int request = | ||
| 988 | AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> | ||
| 989 | </entry> | ||
| 990 | </row></tbody></tgroup></informaltable> | ||
| 991 | <para>PARAMETERS | ||
| 992 | </para> | ||
| 993 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 994 | align="char"> | ||
| 995 | <para>int fd</para> | ||
| 996 | </entry><entry | ||
| 997 | align="char"> | ||
| 998 | <para>File descriptor returned by a previous call to open().</para> | ||
| 999 | </entry> | ||
| 1000 | </row><row><entry | ||
| 1001 | align="char"> | ||
| 1002 | <para>int request</para> | ||
| 1003 | </entry><entry | ||
| 1004 | align="char"> | ||
| 1005 | <para>Equals AUDIO_GET_CAPABILITIES for this | ||
| 1006 | command.</para> | ||
| 1007 | </entry> | ||
| 1008 | </row><row><entry | ||
| 1009 | align="char"> | ||
| 1010 | <para>unsigned int *cap</para> | ||
| 1011 | </entry><entry | ||
| 1012 | align="char"> | ||
| 1013 | <para>Returns a bit array of supported sound formats.</para> | ||
| 1014 | </entry> | ||
| 1015 | </row></tbody></tgroup></informaltable> | ||
| 1016 | <para>ERRORS | ||
| 1017 | </para> | ||
| 1018 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1019 | align="char"> | ||
| 1020 | <para>EBADF</para> | ||
| 1021 | </entry><entry | ||
| 1022 | align="char"> | ||
| 1023 | <para>fd is not a valid open file descriptor.</para> | ||
| 1024 | </entry> | ||
| 1025 | </row><row><entry | ||
| 1026 | align="char"> | ||
| 1027 | <para>EINTERNAL</para> | ||
| 1028 | </entry><entry | ||
| 1029 | align="char"> | ||
| 1030 | <para>Internal error.</para> | ||
| 1031 | </entry> | ||
| 1032 | </row><row><entry | ||
| 1033 | align="char"> | ||
| 1034 | <para>EFAULT</para> | ||
| 1035 | </entry><entry | ||
| 1036 | align="char"> | ||
| 1037 | <para>cap points to an invalid address.</para> | ||
| 1038 | </entry> | ||
| 1039 | </row></tbody></tgroup></informaltable> | ||
| 1040 | |||
| 1041 | </section><section | ||
| 1042 | role="subsection"><title>AUDIO_CLEAR_BUFFER</title> | ||
| 1043 | <para>DESCRIPTION | ||
| 1044 | </para> | ||
| 1045 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1046 | align="char"> | ||
| 1047 | <para>This ioctl call asks the Audio Device to clear all software and hardware buffers | ||
| 1048 | of the audio decoder device.</para> | ||
| 1049 | </entry> | ||
| 1050 | </row></tbody></tgroup></informaltable> | ||
| 1051 | <para>SYNOPSIS | ||
| 1052 | </para> | ||
| 1053 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1054 | align="char"> | ||
| 1055 | <para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> | ||
| 1056 | </entry> | ||
| 1057 | </row></tbody></tgroup></informaltable> | ||
| 1058 | <para>PARAMETERS | ||
| 1059 | </para> | ||
| 1060 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1061 | align="char"> | ||
| 1062 | <para>int fd</para> | ||
| 1063 | </entry><entry | ||
| 1064 | align="char"> | ||
| 1065 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1066 | </entry> | ||
| 1067 | </row><row><entry | ||
| 1068 | align="char"> | ||
| 1069 | <para>int request</para> | ||
| 1070 | </entry><entry | ||
| 1071 | align="char"> | ||
| 1072 | <para>Equals AUDIO_CLEAR_BUFFER for this command.</para> | ||
| 1073 | </entry> | ||
| 1074 | </row></tbody></tgroup></informaltable> | ||
| 1075 | <para>ERRORS | ||
| 1076 | </para> | ||
| 1077 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1078 | align="char"> | ||
| 1079 | <para>EBADF</para> | ||
| 1080 | </entry><entry | ||
| 1081 | align="char"> | ||
| 1082 | <para>fd is not a valid open file descriptor.</para> | ||
| 1083 | </entry> | ||
| 1084 | </row><row><entry | ||
| 1085 | align="char"> | ||
| 1086 | <para>EINTERNAL</para> | ||
| 1087 | </entry><entry | ||
| 1088 | align="char"> | ||
| 1089 | <para>Internal error.</para> | ||
| 1090 | </entry> | ||
| 1091 | </row></tbody></tgroup></informaltable> | ||
| 1092 | |||
| 1093 | </section><section | ||
| 1094 | role="subsection"><title>AUDIO_SET_ID</title> | ||
| 1095 | <para>DESCRIPTION | ||
| 1096 | </para> | ||
| 1097 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1098 | align="char"> | ||
| 1099 | <para>This ioctl selects which sub-stream is to be decoded if a program or system | ||
| 1100 | stream is sent to the video device. If no audio stream type is set the id has to be | ||
| 1101 | in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] | ||
| 1102 | for LPCM. More specifications may follow for other stream types. If the stream | ||
| 1103 | type is set the id just specifies the substream id of the audio stream and only | ||
| 1104 | the first 5 bits are recognized.</para> | ||
| 1105 | </entry> | ||
| 1106 | </row></tbody></tgroup></informaltable> | ||
| 1107 | <para>SYNOPSIS | ||
| 1108 | </para> | ||
| 1109 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1110 | align="char"> | ||
| 1111 | <para>int ioctl(int fd, int request = AUDIO_SET_ID, int | ||
| 1112 | id);</para> | ||
| 1113 | </entry> | ||
| 1114 | </row></tbody></tgroup></informaltable> | ||
| 1115 | <para>PARAMETERS | ||
| 1116 | </para> | ||
| 1117 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1118 | align="char"> | ||
| 1119 | <para>int fd</para> | ||
| 1120 | </entry><entry | ||
| 1121 | align="char"> | ||
| 1122 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1123 | </entry> | ||
| 1124 | </row><row><entry | ||
| 1125 | align="char"> | ||
| 1126 | <para>int request</para> | ||
| 1127 | </entry><entry | ||
| 1128 | align="char"> | ||
| 1129 | <para>Equals AUDIO_SET_ID for this command.</para> | ||
| 1130 | </entry> | ||
| 1131 | </row><row><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para>int id</para> | ||
| 1134 | </entry><entry | ||
| 1135 | align="char"> | ||
| 1136 | <para>audio sub-stream id</para> | ||
| 1137 | </entry> | ||
| 1138 | </row></tbody></tgroup></informaltable> | ||
| 1139 | <para>ERRORS | ||
| 1140 | </para> | ||
| 1141 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1142 | align="char"> | ||
| 1143 | <para>EBADF</para> | ||
| 1144 | </entry><entry | ||
| 1145 | align="char"> | ||
| 1146 | <para>fd is not a valid open file descriptor.</para> | ||
| 1147 | </entry> | ||
| 1148 | </row><row><entry | ||
| 1149 | align="char"> | ||
| 1150 | <para>EINTERNAL</para> | ||
| 1151 | </entry><entry | ||
| 1152 | align="char"> | ||
| 1153 | <para>Internal error.</para> | ||
| 1154 | </entry> | ||
| 1155 | </row><row><entry | ||
| 1156 | align="char"> | ||
| 1157 | <para>EINVAL</para> | ||
| 1158 | </entry><entry | ||
| 1159 | align="char"> | ||
| 1160 | <para>Invalid sub-stream id.</para> | ||
| 1161 | </entry> | ||
| 1162 | </row></tbody></tgroup></informaltable> | ||
| 1163 | |||
| 1164 | </section><section | ||
| 1165 | role="subsection"><title>AUDIO_SET_MIXER</title> | ||
| 1166 | <para>DESCRIPTION | ||
| 1167 | </para> | ||
| 1168 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1169 | align="char"> | ||
| 1170 | <para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> | ||
| 1171 | </entry> | ||
| 1172 | </row></tbody></tgroup></informaltable> | ||
| 1173 | <para>SYNOPSIS | ||
| 1174 | </para> | ||
| 1175 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1176 | align="char"> | ||
| 1177 | <para>int ioctl(int fd, int request = AUDIO_SET_MIXER, | ||
| 1178 | audio_mixer_t ⋆mix);</para> | ||
| 1179 | </entry> | ||
| 1180 | </row></tbody></tgroup></informaltable> | ||
| 1181 | <para>PARAMETERS | ||
| 1182 | </para> | ||
| 1183 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1184 | align="char"> | ||
| 1185 | <para>int fd</para> | ||
| 1186 | </entry><entry | ||
| 1187 | align="char"> | ||
| 1188 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1189 | </entry> | ||
| 1190 | </row><row><entry | ||
| 1191 | align="char"> | ||
| 1192 | <para>int request</para> | ||
| 1193 | </entry><entry | ||
| 1194 | align="char"> | ||
| 1195 | <para>Equals AUDIO_SET_ID for this command.</para> | ||
| 1196 | </entry> | ||
| 1197 | </row><row><entry | ||
| 1198 | align="char"> | ||
| 1199 | <para>audio_mixer_t *mix</para> | ||
| 1200 | </entry><entry | ||
| 1201 | align="char"> | ||
| 1202 | <para>mixer settings.</para> | ||
| 1203 | </entry> | ||
| 1204 | </row></tbody></tgroup></informaltable> | ||
| 1205 | <para>ERRORS | ||
| 1206 | </para> | ||
| 1207 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>EBADF</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>fd is not a valid open file descriptor.</para> | ||
| 1213 | </entry> | ||
| 1214 | </row><row><entry | ||
| 1215 | align="char"> | ||
| 1216 | <para>EINTERNAL</para> | ||
| 1217 | </entry><entry | ||
| 1218 | align="char"> | ||
| 1219 | <para>Internal error.</para> | ||
| 1220 | </entry> | ||
| 1221 | </row><row><entry | ||
| 1222 | align="char"> | ||
| 1223 | <para>EFAULT</para> | ||
| 1224 | </entry><entry | ||
| 1225 | align="char"> | ||
| 1226 | <para>mix points to an invalid address.</para> | ||
| 1227 | </entry> | ||
| 1228 | </row></tbody></tgroup></informaltable> | ||
| 1229 | |||
| 1230 | </section><section | ||
| 1231 | role="subsection"><title>AUDIO_SET_STREAMTYPE</title> | ||
| 1232 | <para>DESCRIPTION | ||
| 1233 | </para> | ||
| 1234 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1235 | align="char"> | ||
| 1236 | <para>This ioctl tells the driver which kind of audio stream to expect. This is useful | ||
| 1237 | if the stream offers several audio sub-streams like LPCM and AC3.</para> | ||
| 1238 | </entry> | ||
| 1239 | </row></tbody></tgroup></informaltable> | ||
| 1240 | <para>SYNOPSIS | ||
| 1241 | </para> | ||
| 1242 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1243 | align="char"> | ||
| 1244 | <para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, | ||
| 1245 | int type);</para> | ||
| 1246 | </entry> | ||
| 1247 | </row></tbody></tgroup></informaltable> | ||
| 1248 | <para>PARAMETERS | ||
| 1249 | </para> | ||
| 1250 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1251 | align="char"> | ||
| 1252 | <para>int fd</para> | ||
| 1253 | </entry><entry | ||
| 1254 | align="char"> | ||
| 1255 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1256 | </entry> | ||
| 1257 | </row><row><entry | ||
| 1258 | align="char"> | ||
| 1259 | <para>int request</para> | ||
| 1260 | </entry><entry | ||
| 1261 | align="char"> | ||
| 1262 | <para>Equals AUDIO_SET_STREAMTYPE for this | ||
| 1263 | command.</para> | ||
| 1264 | </entry> | ||
| 1265 | </row><row><entry | ||
| 1266 | align="char"> | ||
| 1267 | <para>int type</para> | ||
| 1268 | </entry><entry | ||
| 1269 | align="char"> | ||
| 1270 | <para>stream type</para> | ||
| 1271 | </entry> | ||
| 1272 | </row></tbody></tgroup></informaltable> | ||
| 1273 | <para>ERRORS | ||
| 1274 | </para> | ||
| 1275 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1276 | align="char"> | ||
| 1277 | <para>EBADF</para> | ||
| 1278 | </entry><entry | ||
| 1279 | align="char"> | ||
| 1280 | <para>fd is not a valid open file descriptor</para> | ||
| 1281 | </entry> | ||
| 1282 | </row><row><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>EINVAL</para> | ||
| 1285 | </entry><entry | ||
| 1286 | align="char"> | ||
| 1287 | <para>type is not a valid or supported stream type.</para> | ||
| 1288 | </entry> | ||
| 1289 | </row></tbody></tgroup></informaltable> | ||
| 1290 | |||
| 1291 | </section><section | ||
| 1292 | role="subsection"><title>AUDIO_SET_EXT_ID</title> | ||
| 1293 | <para>DESCRIPTION | ||
| 1294 | </para> | ||
| 1295 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1296 | align="char"> | ||
| 1297 | <para>This ioctl can be used to set the extension id for MPEG streams in DVD | ||
| 1298 | playback. Only the first 3 bits are recognized.</para> | ||
| 1299 | </entry> | ||
| 1300 | </row></tbody></tgroup></informaltable> | ||
| 1301 | <para>SYNOPSIS | ||
| 1302 | </para> | ||
| 1303 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1304 | align="char"> | ||
| 1305 | <para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int | ||
| 1306 | id);</para> | ||
| 1307 | </entry> | ||
| 1308 | </row></tbody></tgroup></informaltable> | ||
| 1309 | <para>PARAMETERS | ||
| 1310 | </para> | ||
| 1311 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1312 | align="char"> | ||
| 1313 | <para>int fd</para> | ||
| 1314 | </entry><entry | ||
| 1315 | align="char"> | ||
| 1316 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1317 | </entry> | ||
| 1318 | </row><row><entry | ||
| 1319 | align="char"> | ||
| 1320 | <para>int request</para> | ||
| 1321 | </entry><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>Equals AUDIO_SET_EXT_ID for this command.</para> | ||
| 1324 | </entry> | ||
| 1325 | </row><row><entry | ||
| 1326 | align="char"> | ||
| 1327 | <para>int id</para> | ||
| 1328 | </entry><entry | ||
| 1329 | align="char"> | ||
| 1330 | <para>audio sub_stream_id</para> | ||
| 1331 | </entry> | ||
| 1332 | </row></tbody></tgroup></informaltable> | ||
| 1333 | <para>ERRORS | ||
| 1334 | </para> | ||
| 1335 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1336 | align="char"> | ||
| 1337 | <para>EBADF</para> | ||
| 1338 | </entry><entry | ||
| 1339 | align="char"> | ||
| 1340 | <para>fd is not a valid open file descriptor</para> | ||
| 1341 | </entry> | ||
| 1342 | </row><row><entry | ||
| 1343 | align="char"> | ||
| 1344 | <para>EINVAL</para> | ||
| 1345 | </entry><entry | ||
| 1346 | align="char"> | ||
| 1347 | <para>id is not a valid id.</para> | ||
| 1348 | </entry> | ||
| 1349 | </row></tbody></tgroup></informaltable> | ||
| 1350 | |||
| 1351 | </section><section | ||
| 1352 | role="subsection"><title>AUDIO_SET_ATTRIBUTES</title> | ||
| 1353 | <para>DESCRIPTION | ||
| 1354 | </para> | ||
| 1355 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1356 | align="char"> | ||
| 1357 | <para>This ioctl is intended for DVD playback and allows you to set certain | ||
| 1358 | information about the audio stream.</para> | ||
| 1359 | </entry> | ||
| 1360 | </row></tbody></tgroup></informaltable> | ||
| 1361 | <para>SYNOPSIS | ||
| 1362 | </para> | ||
| 1363 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1364 | align="char"> | ||
| 1365 | <para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, | ||
| 1366 | audio_attributes_t attr );</para> | ||
| 1367 | </entry> | ||
| 1368 | </row></tbody></tgroup></informaltable> | ||
| 1369 | <para>PARAMETERS | ||
| 1370 | </para> | ||
| 1371 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1372 | align="char"> | ||
| 1373 | <para>int fd</para> | ||
| 1374 | </entry><entry | ||
| 1375 | align="char"> | ||
| 1376 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1377 | </entry> | ||
| 1378 | </row><row><entry | ||
| 1379 | align="char"> | ||
| 1380 | <para>int request</para> | ||
| 1381 | </entry><entry | ||
| 1382 | align="char"> | ||
| 1383 | <para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> | ||
| 1384 | </entry> | ||
| 1385 | </row><row><entry | ||
| 1386 | align="char"> | ||
| 1387 | <para>audio_attributes_t | ||
| 1388 | attr</para> | ||
| 1389 | </entry><entry | ||
| 1390 | align="char"> | ||
| 1391 | <para>audio attributes according to section ??</para> | ||
| 1392 | </entry> | ||
| 1393 | </row></tbody></tgroup></informaltable> | ||
| 1394 | <para>ERRORS | ||
| 1395 | </para> | ||
| 1396 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1397 | align="char"> | ||
| 1398 | <para>EBADF</para> | ||
| 1399 | </entry><entry | ||
| 1400 | align="char"> | ||
| 1401 | <para>fd is not a valid open file descriptor</para> | ||
| 1402 | </entry> | ||
| 1403 | </row><row><entry | ||
| 1404 | align="char"> | ||
| 1405 | <para>EINVAL</para> | ||
| 1406 | </entry><entry | ||
| 1407 | align="char"> | ||
| 1408 | <para>attr is not a valid or supported attribute setting.</para> | ||
| 1409 | </entry> | ||
| 1410 | </row></tbody></tgroup></informaltable> | ||
| 1411 | |||
| 1412 | </section><section | ||
| 1413 | role="subsection"><title>AUDIO_SET_KARAOKE</title> | ||
| 1414 | <para>DESCRIPTION | ||
| 1415 | </para> | ||
| 1416 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1417 | align="char"> | ||
| 1418 | <para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> | ||
| 1419 | </entry> | ||
| 1420 | </row></tbody></tgroup></informaltable> | ||
| 1421 | <para>SYNOPSIS | ||
| 1422 | </para> | ||
| 1423 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1424 | align="char"> | ||
| 1425 | <para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, | ||
| 1426 | audio_karaoke_t ⋆karaoke);</para> | ||
| 1427 | </entry> | ||
| 1428 | </row></tbody></tgroup></informaltable> | ||
| 1429 | <para>PARAMETERS | ||
| 1430 | </para> | ||
| 1431 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1432 | align="char"> | ||
| 1433 | <para>int fd</para> | ||
| 1434 | </entry><entry | ||
| 1435 | align="char"> | ||
| 1436 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1437 | </entry> | ||
| 1438 | </row><row><entry | ||
| 1439 | align="char"> | ||
| 1440 | <para>int request</para> | ||
| 1441 | </entry><entry | ||
| 1442 | align="char"> | ||
| 1443 | <para>Equals AUDIO_SET_STREAMTYPE for this | ||
| 1444 | command.</para> | ||
| 1445 | </entry> | ||
| 1446 | </row><row><entry | ||
| 1447 | align="char"> | ||
| 1448 | <para>audio_karaoke_t | ||
| 1449 | *karaoke</para> | ||
| 1450 | </entry><entry | ||
| 1451 | align="char"> | ||
| 1452 | <para>karaoke settings according to section ??.</para> | ||
| 1453 | </entry> | ||
| 1454 | </row></tbody></tgroup></informaltable> | ||
| 1455 | <para>ERRORS | ||
| 1456 | </para> | ||
| 1457 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1458 | align="char"> | ||
| 1459 | <para>EBADF</para> | ||
| 1460 | </entry><entry | ||
| 1461 | align="char"> | ||
| 1462 | <para>fd is not a valid open file descriptor</para> | ||
| 1463 | </entry> | ||
| 1464 | </row><row><entry | ||
| 1465 | align="char"> | ||
| 1466 | <para>EINVAL</para> | ||
| 1467 | </entry><entry | ||
| 1468 | align="char"> | ||
| 1469 | <para>karaoke is not a valid or supported karaoke setting.</para> | ||
| 1470 | </entry> | ||
| 1471 | </row></tbody></tgroup></informaltable> | ||
| 1472 | </section> | ||
| 1473 | </section> | ||
diff --git a/Documentation/DocBook/dvb/ca.xml b/Documentation/DocBook/dvb/ca.xml new file mode 100644 index 000000000000..b1f1d2fad654 --- /dev/null +++ b/Documentation/DocBook/dvb/ca.xml | |||
| @@ -0,0 +1,221 @@ | |||
| 1 | <title>DVB CA Device</title> | ||
| 2 | <para>The DVB CA device controls the conditional access hardware. It can be accessed through | ||
| 3 | <emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by | ||
| 4 | including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application. | ||
| 5 | </para> | ||
| 6 | |||
| 7 | <section id="ca_data_types"> | ||
| 8 | <title>CA Data Types</title> | ||
| 9 | |||
| 10 | |||
| 11 | <section id="ca_slot_info_t"> | ||
| 12 | <title>ca_slot_info_t</title> | ||
| 13 | <programlisting> | ||
| 14 | /⋆ slot interface types and info ⋆/ | ||
| 15 | |||
| 16 | typedef struct ca_slot_info_s { | ||
| 17 | int num; /⋆ slot number ⋆/ | ||
| 18 | |||
| 19 | int type; /⋆ CA interface this slot supports ⋆/ | ||
| 20 | #define CA_CI 1 /⋆ CI high level interface ⋆/ | ||
| 21 | #define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ | ||
| 22 | #define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ | ||
| 23 | #define CA_SC 128 /⋆ simple smart card interface ⋆/ | ||
| 24 | |||
| 25 | unsigned int flags; | ||
| 26 | #define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ | ||
| 27 | #define CA_CI_MODULE_READY 2 | ||
| 28 | } ca_slot_info_t; | ||
| 29 | </programlisting> | ||
| 30 | |||
| 31 | </section> | ||
| 32 | <section id="ca_descr_info_t"> | ||
| 33 | <title>ca_descr_info_t</title> | ||
| 34 | <programlisting> | ||
| 35 | typedef struct ca_descr_info_s { | ||
| 36 | unsigned int num; /⋆ number of available descramblers (keys) ⋆/ | ||
| 37 | unsigned int type; /⋆ type of supported scrambling system ⋆/ | ||
| 38 | #define CA_ECD 1 | ||
| 39 | #define CA_NDS 2 | ||
| 40 | #define CA_DSS 4 | ||
| 41 | } ca_descr_info_t; | ||
| 42 | </programlisting> | ||
| 43 | |||
| 44 | </section> | ||
| 45 | <section id="ca_cap_t"> | ||
| 46 | <title>ca_cap_t</title> | ||
| 47 | <programlisting> | ||
| 48 | typedef struct ca_cap_s { | ||
| 49 | unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ | ||
| 50 | unsigned int slot_type; /⋆ OR of all supported types ⋆/ | ||
| 51 | unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ | ||
| 52 | unsigned int descr_type;/⋆ OR of all supported types ⋆/ | ||
| 53 | } ca_cap_t; | ||
| 54 | </programlisting> | ||
| 55 | |||
| 56 | </section> | ||
| 57 | <section id="ca_msg_t"> | ||
| 58 | <title>ca_msg_t</title> | ||
| 59 | <programlisting> | ||
| 60 | /⋆ a message to/from a CI-CAM ⋆/ | ||
| 61 | typedef struct ca_msg_s { | ||
| 62 | unsigned int index; | ||
| 63 | unsigned int type; | ||
| 64 | unsigned int length; | ||
| 65 | unsigned char msg[256]; | ||
| 66 | } ca_msg_t; | ||
| 67 | </programlisting> | ||
| 68 | |||
| 69 | </section> | ||
| 70 | <section id="ca_descr_t"> | ||
| 71 | <title>ca_descr_t</title> | ||
| 72 | <programlisting> | ||
| 73 | typedef struct ca_descr_s { | ||
| 74 | unsigned int index; | ||
| 75 | unsigned int parity; | ||
| 76 | unsigned char cw[8]; | ||
| 77 | } ca_descr_t; | ||
| 78 | </programlisting> | ||
| 79 | </section></section> | ||
| 80 | <section id="ca_function_calls"> | ||
| 81 | <title>CA Function Calls</title> | ||
| 82 | |||
| 83 | |||
| 84 | <section id="ca_fopen"> | ||
| 85 | <title>open()</title> | ||
| 86 | <para>DESCRIPTION | ||
| 87 | </para> | ||
| 88 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 89 | align="char"> | ||
| 90 | <para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para> | ||
| 91 | <para>When an open() call has succeeded, the device will be ready for use. | ||
| 92 | The significance of blocking or non-blocking mode is described in the | ||
| 93 | documentation for functions where there is a difference. It does not affect the | ||
| 94 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 95 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 96 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 97 | manual page for fcntl. Only one user can open the CA Device in O_RDWR | ||
| 98 | mode. All other attempts to open the device in this mode will fail, and an error | ||
| 99 | code will be returned.</para> | ||
| 100 | </entry> | ||
| 101 | </row></tbody></tgroup></informaltable> | ||
| 102 | <para>SYNOPSIS | ||
| 103 | </para> | ||
| 104 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 105 | align="char"> | ||
| 106 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 107 | </entry> | ||
| 108 | </row></tbody></tgroup></informaltable> | ||
| 109 | <para>PARAMETERS | ||
| 110 | </para> | ||
| 111 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 112 | align="char"> | ||
| 113 | <para>const char | ||
| 114 | *deviceName</para> | ||
| 115 | </entry><entry | ||
| 116 | align="char"> | ||
| 117 | <para>Name of specific video device.</para> | ||
| 118 | </entry> | ||
| 119 | </row><row><entry | ||
| 120 | align="char"> | ||
| 121 | <para>int flags</para> | ||
| 122 | </entry><entry | ||
| 123 | align="char"> | ||
| 124 | <para>A bit-wise OR of the following flags:</para> | ||
| 125 | </entry> | ||
| 126 | </row><row><entry | ||
| 127 | align="char"> | ||
| 128 | </entry><entry | ||
| 129 | align="char"> | ||
| 130 | <para>O_RDONLY read-only access</para> | ||
| 131 | </entry> | ||
| 132 | </row><row><entry | ||
| 133 | align="char"> | ||
| 134 | </entry><entry | ||
| 135 | align="char"> | ||
| 136 | <para>O_RDWR read/write access</para> | ||
| 137 | </entry> | ||
| 138 | </row><row><entry | ||
| 139 | align="char"> | ||
| 140 | </entry><entry | ||
| 141 | align="char"> | ||
| 142 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 143 | </entry> | ||
| 144 | </row><row><entry | ||
| 145 | align="char"> | ||
| 146 | </entry><entry | ||
| 147 | align="char"> | ||
| 148 | <para>(blocking mode is the default)</para> | ||
| 149 | </entry> | ||
| 150 | </row></tbody></tgroup></informaltable> | ||
| 151 | <para>ERRORS | ||
| 152 | </para> | ||
| 153 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 154 | align="char"> | ||
| 155 | <para>ENODEV</para> | ||
| 156 | </entry><entry | ||
| 157 | align="char"> | ||
| 158 | <para>Device driver not loaded/available.</para> | ||
| 159 | </entry> | ||
| 160 | </row><row><entry | ||
| 161 | align="char"> | ||
| 162 | <para>EINTERNAL</para> | ||
| 163 | </entry><entry | ||
| 164 | align="char"> | ||
| 165 | <para>Internal error.</para> | ||
| 166 | </entry> | ||
| 167 | </row><row><entry | ||
| 168 | align="char"> | ||
| 169 | <para>EBUSY</para> | ||
| 170 | </entry><entry | ||
| 171 | align="char"> | ||
| 172 | <para>Device or resource busy.</para> | ||
| 173 | </entry> | ||
| 174 | </row><row><entry | ||
| 175 | align="char"> | ||
| 176 | <para>EINVAL</para> | ||
| 177 | </entry><entry | ||
| 178 | align="char"> | ||
| 179 | <para>Invalid argument.</para> | ||
| 180 | </entry> | ||
| 181 | </row></tbody></tgroup></informaltable> | ||
| 182 | |||
| 183 | </section> | ||
| 184 | <section id="ca_fclose"> | ||
| 185 | <title>close()</title> | ||
| 186 | <para>DESCRIPTION | ||
| 187 | </para> | ||
| 188 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>This system call closes a previously opened audio device.</para> | ||
| 191 | </entry> | ||
| 192 | </row></tbody></tgroup></informaltable> | ||
| 193 | <para>SYNOPSIS | ||
| 194 | </para> | ||
| 195 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 196 | align="char"> | ||
| 197 | <para>int close(int fd);</para> | ||
| 198 | </entry> | ||
| 199 | </row></tbody></tgroup></informaltable> | ||
| 200 | <para>PARAMETERS | ||
| 201 | </para> | ||
| 202 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 203 | align="char"> | ||
| 204 | <para>int fd</para> | ||
| 205 | </entry><entry | ||
| 206 | align="char"> | ||
| 207 | <para>File descriptor returned by a previous call to open().</para> | ||
| 208 | </entry> | ||
| 209 | </row></tbody></tgroup></informaltable> | ||
| 210 | <para>ERRORS | ||
| 211 | </para> | ||
| 212 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 213 | align="char"> | ||
| 214 | <para>EBADF</para> | ||
| 215 | </entry><entry | ||
| 216 | align="char"> | ||
| 217 | <para>fd is not a valid open file descriptor.</para> | ||
| 218 | </entry> | ||
| 219 | </row></tbody></tgroup></informaltable> | ||
| 220 | </section> | ||
| 221 | </section> | ||
diff --git a/Documentation/DocBook/dvb/demux.xml b/Documentation/DocBook/dvb/demux.xml new file mode 100644 index 000000000000..1b8c4e9835b9 --- /dev/null +++ b/Documentation/DocBook/dvb/demux.xml | |||
| @@ -0,0 +1,973 @@ | |||
| 1 | <title>DVB Demux Device</title> | ||
| 2 | |||
| 3 | <para>The DVB demux device controls the filters of the DVB hardware/software. It can be | ||
| 4 | accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be | ||
| 5 | accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application. | ||
| 6 | </para> | ||
| 7 | <section id="dmx_types"> | ||
| 8 | <title>Demux Data Types</title> | ||
| 9 | |||
| 10 | <section id="dmx_output_t"> | ||
| 11 | <title>dmx_output_t</title> | ||
| 12 | <programlisting> | ||
| 13 | typedef enum | ||
| 14 | { | ||
| 15 | DMX_OUT_DECODER, | ||
| 16 | DMX_OUT_TAP, | ||
| 17 | DMX_OUT_TS_TAP | ||
| 18 | } dmx_output_t; | ||
| 19 | </programlisting> | ||
| 20 | <para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is | ||
| 21 | called. | ||
| 22 | </para> | ||
| 23 | <para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>, | ||
| 24 | which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was | ||
| 25 | specified. | ||
| 26 | </para> | ||
| 27 | </section> | ||
| 28 | |||
| 29 | <section id="dmx_input_t"> | ||
| 30 | <title>dmx_input_t</title> | ||
| 31 | <programlisting> | ||
| 32 | typedef enum | ||
| 33 | { | ||
| 34 | DMX_IN_FRONTEND, | ||
| 35 | DMX_IN_DVR | ||
| 36 | } dmx_input_t; | ||
| 37 | </programlisting> | ||
| 38 | </section> | ||
| 39 | |||
| 40 | <section id="dmx_pes_type_t"> | ||
| 41 | <title>dmx_pes_type_t</title> | ||
| 42 | <programlisting> | ||
| 43 | typedef enum | ||
| 44 | { | ||
| 45 | DMX_PES_AUDIO, | ||
| 46 | DMX_PES_VIDEO, | ||
| 47 | DMX_PES_TELETEXT, | ||
| 48 | DMX_PES_SUBTITLE, | ||
| 49 | DMX_PES_PCR, | ||
| 50 | DMX_PES_OTHER | ||
| 51 | } dmx_pes_type_t; | ||
| 52 | </programlisting> | ||
| 53 | </section> | ||
| 54 | |||
| 55 | <section id="dmx_event_t"> | ||
| 56 | <title>dmx_event_t</title> | ||
| 57 | <programlisting> | ||
| 58 | typedef enum | ||
| 59 | { | ||
| 60 | DMX_SCRAMBLING_EV, | ||
| 61 | DMX_FRONTEND_EV | ||
| 62 | } dmx_event_t; | ||
| 63 | </programlisting> | ||
| 64 | </section> | ||
| 65 | |||
| 66 | <section id="dmx_scrambling_status_t"> | ||
| 67 | <title>dmx_scrambling_status_t</title> | ||
| 68 | <programlisting> | ||
| 69 | typedef enum | ||
| 70 | { | ||
| 71 | DMX_SCRAMBLING_OFF, | ||
| 72 | DMX_SCRAMBLING_ON | ||
| 73 | } dmx_scrambling_status_t; | ||
| 74 | </programlisting> | ||
| 75 | </section> | ||
| 76 | |||
| 77 | <section id="dmx_filter"> | ||
| 78 | <title>struct dmx_filter</title> | ||
| 79 | <programlisting> | ||
| 80 | typedef struct dmx_filter | ||
| 81 | { | ||
| 82 | uint8_t filter[DMX_FILTER_SIZE]; | ||
| 83 | uint8_t mask[DMX_FILTER_SIZE]; | ||
| 84 | } dmx_filter_t; | ||
| 85 | </programlisting> | ||
| 86 | </section> | ||
| 87 | |||
| 88 | <section id="dmx_sct_filter_params"> | ||
| 89 | <title>struct dmx_sct_filter_params</title> | ||
| 90 | <programlisting> | ||
| 91 | struct dmx_sct_filter_params | ||
| 92 | { | ||
| 93 | uint16_t pid; | ||
| 94 | dmx_filter_t filter; | ||
| 95 | uint32_t timeout; | ||
| 96 | uint32_t flags; | ||
| 97 | #define DMX_CHECK_CRC 1 | ||
| 98 | #define DMX_ONESHOT 2 | ||
| 99 | #define DMX_IMMEDIATE_START 4 | ||
| 100 | }; | ||
| 101 | </programlisting> | ||
| 102 | </section> | ||
| 103 | |||
| 104 | <section id="dmx_pes_filter_params"> | ||
| 105 | <title>struct dmx_pes_filter_params</title> | ||
| 106 | <programlisting> | ||
| 107 | struct dmx_pes_filter_params | ||
| 108 | { | ||
| 109 | uint16_t pid; | ||
| 110 | dmx_input_t input; | ||
| 111 | dmx_output_t output; | ||
| 112 | dmx_pes_type_t pes_type; | ||
| 113 | uint32_t flags; | ||
| 114 | }; | ||
| 115 | </programlisting> | ||
| 116 | </section> | ||
| 117 | |||
| 118 | <section id="dmx_event"> | ||
| 119 | <title>struct dmx_event</title> | ||
| 120 | <programlisting> | ||
| 121 | struct dmx_event | ||
| 122 | { | ||
| 123 | dmx_event_t event; | ||
| 124 | time_t timeStamp; | ||
| 125 | union | ||
| 126 | { | ||
| 127 | dmx_scrambling_status_t scrambling; | ||
| 128 | } u; | ||
| 129 | }; | ||
| 130 | </programlisting> | ||
| 131 | </section> | ||
| 132 | |||
| 133 | <section id="dmx_stc"> | ||
| 134 | <title>struct dmx_stc</title> | ||
| 135 | <programlisting> | ||
| 136 | struct dmx_stc { | ||
| 137 | unsigned int num; /⋆ input : which STC? 0..N ⋆/ | ||
| 138 | unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ | ||
| 139 | uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ | ||
| 140 | }; | ||
| 141 | </programlisting> | ||
| 142 | </section> | ||
| 143 | |||
| 144 | </section> | ||
| 145 | |||
| 146 | <section id="dmx_fcalls"> | ||
| 147 | <title>Demux Function Calls</title> | ||
| 148 | |||
| 149 | <section id="dmx_fopen"> | ||
| 150 | <title>open()</title> | ||
| 151 | <para>DESCRIPTION | ||
| 152 | </para> | ||
| 153 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 154 | align="char"> | ||
| 155 | <para>This system call, used with a device name of /dev/dvb/adapter0/demux0, | ||
| 156 | allocates a new filter and returns a handle which can be used for subsequent | ||
| 157 | control of that filter. This call has to be made for each filter to be used, i.e. every | ||
| 158 | returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0 | ||
| 159 | is a logical device to be used for retrieving Transport Streams for digital | ||
| 160 | video recording. When reading from this device a transport stream containing | ||
| 161 | the packets from all PES filters set in the corresponding demux device | ||
| 162 | (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A | ||
| 163 | recorded Transport Stream is replayed by writing to this device. </para> | ||
| 164 | <para>The significance of blocking or non-blocking mode is described in the | ||
| 165 | documentation for functions where there is a difference. It does not affect the | ||
| 166 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 167 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 168 | of the fcntl system call.</para> | ||
| 169 | </entry> | ||
| 170 | </row></tbody></tgroup></informaltable> | ||
| 171 | <para>SYNOPSIS | ||
| 172 | </para> | ||
| 173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 174 | align="char"> | ||
| 175 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 176 | </entry> | ||
| 177 | </row></tbody></tgroup></informaltable> | ||
| 178 | <para>PARAMETERS | ||
| 179 | </para> | ||
| 180 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 181 | align="char"> | ||
| 182 | <para>const char | ||
| 183 | *deviceName</para> | ||
| 184 | </entry><entry | ||
| 185 | align="char"> | ||
| 186 | <para>Name of demux device.</para> | ||
| 187 | </entry> | ||
| 188 | </row><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>int flags</para> | ||
| 191 | </entry><entry | ||
| 192 | align="char"> | ||
| 193 | <para>A bit-wise OR of the following flags:</para> | ||
| 194 | </entry> | ||
| 195 | </row><row><entry | ||
| 196 | align="char"> | ||
| 197 | </entry><entry | ||
| 198 | align="char"> | ||
| 199 | <para>O_RDWR read/write access</para> | ||
| 200 | </entry> | ||
| 201 | </row><row><entry | ||
| 202 | align="char"> | ||
| 203 | </entry><entry | ||
| 204 | align="char"> | ||
| 205 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 206 | </entry> | ||
| 207 | </row><row><entry | ||
| 208 | align="char"> | ||
| 209 | </entry><entry | ||
| 210 | align="char"> | ||
| 211 | <para>(blocking mode is the default)</para> | ||
| 212 | </entry> | ||
| 213 | </row></tbody></tgroup></informaltable> | ||
| 214 | <para>ERRORS | ||
| 215 | </para> | ||
| 216 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 217 | align="char"> | ||
| 218 | <para>ENODEV</para> | ||
| 219 | </entry><entry | ||
| 220 | align="char"> | ||
| 221 | <para>Device driver not loaded/available.</para> | ||
| 222 | </entry> | ||
| 223 | </row><row><entry | ||
| 224 | align="char"> | ||
| 225 | <para>EINVAL</para> | ||
| 226 | </entry><entry | ||
| 227 | align="char"> | ||
| 228 | <para>Invalid argument.</para> | ||
| 229 | </entry> | ||
| 230 | </row><row><entry | ||
| 231 | align="char"> | ||
| 232 | <para>EMFILE</para> | ||
| 233 | </entry><entry | ||
| 234 | align="char"> | ||
| 235 | <para>“Too many open files”, i.e. no more filters available.</para> | ||
| 236 | </entry> | ||
| 237 | </row><row><entry | ||
| 238 | align="char"> | ||
| 239 | <para>ENOMEM</para> | ||
| 240 | </entry><entry | ||
| 241 | align="char"> | ||
| 242 | <para>The driver failed to allocate enough memory.</para> | ||
| 243 | </entry> | ||
| 244 | </row></tbody></tgroup></informaltable> | ||
| 245 | </section> | ||
| 246 | |||
| 247 | <section id="dmx_fclose"> | ||
| 248 | <title>close()</title> | ||
| 249 | <para>DESCRIPTION | ||
| 250 | </para> | ||
| 251 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 252 | align="char"> | ||
| 253 | <para>This system call deactivates and deallocates a filter that was previously | ||
| 254 | allocated via the open() call.</para> | ||
| 255 | </entry> | ||
| 256 | </row></tbody></tgroup></informaltable> | ||
| 257 | <para>SYNOPSIS | ||
| 258 | </para> | ||
| 259 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 260 | align="char"> | ||
| 261 | <para>int close(int fd);</para> | ||
| 262 | </entry> | ||
| 263 | </row></tbody></tgroup></informaltable> | ||
| 264 | <para>PARAMETERS | ||
| 265 | </para> | ||
| 266 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 267 | align="char"> | ||
| 268 | <para>int fd</para> | ||
| 269 | </entry><entry | ||
| 270 | align="char"> | ||
| 271 | <para>File descriptor returned by a previous call to open().</para> | ||
| 272 | </entry> | ||
| 273 | </row></tbody></tgroup></informaltable> | ||
| 274 | <para>ERRORS | ||
| 275 | </para> | ||
| 276 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 277 | align="char"> | ||
| 278 | <para>EBADF</para> | ||
| 279 | </entry><entry | ||
| 280 | align="char"> | ||
| 281 | <para>fd is not a valid open file descriptor.</para> | ||
| 282 | </entry> | ||
| 283 | </row></tbody></tgroup></informaltable> | ||
| 284 | </section> | ||
| 285 | |||
| 286 | <section id="dmx_fread"> | ||
| 287 | <title>read()</title> | ||
| 288 | <para>DESCRIPTION | ||
| 289 | </para> | ||
| 290 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 291 | align="char"> | ||
| 292 | <para>This system call returns filtered data, which might be section or PES data. The | ||
| 293 | filtered data is transferred from the driver’s internal circular buffer to buf. The | ||
| 294 | maximum amount of data to be transferred is implied by count.</para> | ||
| 295 | </entry> | ||
| 296 | </row><row><entry | ||
| 297 | align="char"> | ||
| 298 | <para>When returning section data the driver always tries to return a complete single | ||
| 299 | section (even though buf would provide buffer space for more data). If the size | ||
| 300 | of the buffer is smaller than the section as much as possible will be returned, | ||
| 301 | and the remaining data will be provided in subsequent calls.</para> | ||
| 302 | </entry> | ||
| 303 | </row><row><entry | ||
| 304 | align="char"> | ||
| 305 | <para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum | ||
| 306 | sized sections) by default. The size of this buffer may be changed by using the | ||
| 307 | DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if | ||
| 308 | the read operations are not performed fast enough, this may result in a buffer | ||
| 309 | overflow error. In this case EOVERFLOW will be returned, and the circular | ||
| 310 | buffer will be emptied. This call is blocking if there is no data to return, i.e. the | ||
| 311 | process will be put to sleep waiting for data, unless the O_NONBLOCK flag | ||
| 312 | is specified.</para> | ||
| 313 | </entry> | ||
| 314 | </row><row><entry | ||
| 315 | align="char"> | ||
| 316 | <para>Note that in order to be able to read, the filtering process has to be started | ||
| 317 | by defining either a section or a PES filter by means of the ioctl functions, | ||
| 318 | and then starting the filtering process via the DMX_START ioctl function | ||
| 319 | or by setting the DMX_IMMEDIATE_START flag. If the reading is done | ||
| 320 | from a logical DVR demux device, the data will constitute a Transport Stream | ||
| 321 | including the packets from all PES filters in the corresponding demux device | ||
| 322 | /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> | ||
| 323 | </entry> | ||
| 324 | </row></tbody></tgroup></informaltable> | ||
| 325 | <para>SYNOPSIS | ||
| 326 | </para> | ||
| 327 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 328 | align="char"> | ||
| 329 | <para>size_t read(int fd, void ⋆buf, size_t count);</para> | ||
| 330 | </entry> | ||
| 331 | </row></tbody></tgroup></informaltable> | ||
| 332 | <para>PARAMETERS | ||
| 333 | </para> | ||
| 334 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 335 | align="char"> | ||
| 336 | <para>int fd</para> | ||
| 337 | </entry><entry | ||
| 338 | align="char"> | ||
| 339 | <para>File descriptor returned by a previous call to open().</para> | ||
| 340 | </entry> | ||
| 341 | </row><row><entry | ||
| 342 | align="char"> | ||
| 343 | <para>void *buf</para> | ||
| 344 | </entry><entry | ||
| 345 | align="char"> | ||
| 346 | <para>Pointer to the buffer to be used for returned filtered data.</para> | ||
| 347 | </entry> | ||
| 348 | </row><row><entry | ||
| 349 | align="char"> | ||
| 350 | <para>size_t count</para> | ||
| 351 | </entry><entry | ||
| 352 | align="char"> | ||
| 353 | <para>Size of buf.</para> | ||
| 354 | </entry> | ||
| 355 | </row></tbody></tgroup></informaltable> | ||
| 356 | <para>ERRORS | ||
| 357 | </para> | ||
| 358 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 359 | align="char"> | ||
| 360 | <para>EWOULDBLOCK</para> | ||
| 361 | </entry><entry | ||
| 362 | align="char"> | ||
| 363 | <para>No data to return and O_NONBLOCK was specified.</para> | ||
| 364 | </entry> | ||
| 365 | </row><row><entry | ||
| 366 | align="char"> | ||
| 367 | <para>EBADF</para> | ||
| 368 | </entry><entry | ||
| 369 | align="char"> | ||
| 370 | <para>fd is not a valid open file descriptor.</para> | ||
| 371 | </entry> | ||
| 372 | </row><row><entry | ||
| 373 | align="char"> | ||
| 374 | <para>ECRC</para> | ||
| 375 | </entry><entry | ||
| 376 | align="char"> | ||
| 377 | <para>Last section had a CRC error - no data returned. The | ||
| 378 | buffer is flushed.</para> | ||
| 379 | </entry> | ||
| 380 | </row><row><entry | ||
| 381 | align="char"> | ||
| 382 | <para>EOVERFLOW</para> | ||
| 383 | </entry><entry | ||
| 384 | align="char"> | ||
| 385 | </entry> | ||
| 386 | </row><row><entry | ||
| 387 | align="char"> | ||
| 388 | </entry><entry | ||
| 389 | align="char"> | ||
| 390 | <para>The filtered data was not read from the buffer in due | ||
| 391 | time, resulting in non-read data being lost. The buffer is | ||
| 392 | flushed.</para> | ||
| 393 | </entry> | ||
| 394 | </row><row><entry | ||
| 395 | align="char"> | ||
| 396 | <para>ETIMEDOUT</para> | ||
| 397 | </entry><entry | ||
| 398 | align="char"> | ||
| 399 | <para>The section was not loaded within the stated timeout | ||
| 400 | period. See ioctl DMX_SET_FILTER for how to set a | ||
| 401 | timeout.</para> | ||
| 402 | </entry> | ||
| 403 | </row><row><entry | ||
| 404 | align="char"> | ||
| 405 | <para>EFAULT</para> | ||
| 406 | </entry><entry | ||
| 407 | align="char"> | ||
| 408 | <para>The driver failed to write to the callers buffer due to an | ||
| 409 | invalid *buf pointer.</para> | ||
| 410 | </entry> | ||
| 411 | </row></tbody></tgroup></informaltable> | ||
| 412 | </section> | ||
| 413 | |||
| 414 | <section id="dmx_fwrite"> | ||
| 415 | <title>write()</title> | ||
| 416 | <para>DESCRIPTION | ||
| 417 | </para> | ||
| 418 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 419 | align="char"> | ||
| 420 | <para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, | ||
| 421 | associated with the physical demux device that provides the actual DVR | ||
| 422 | functionality. It is used for replay of a digitally recorded Transport Stream. | ||
| 423 | Matching filters have to be defined in the corresponding physical demux | ||
| 424 | device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is | ||
| 425 | implied by count.</para> | ||
| 426 | </entry> | ||
| 427 | </row></tbody></tgroup></informaltable> | ||
| 428 | <para>SYNOPSIS | ||
| 429 | </para> | ||
| 430 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 431 | align="char"> | ||
| 432 | <para>ssize_t write(int fd, const void ⋆buf, size_t | ||
| 433 | count);</para> | ||
| 434 | </entry> | ||
| 435 | </row></tbody></tgroup></informaltable> | ||
| 436 | <para>PARAMETERS | ||
| 437 | </para> | ||
| 438 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 439 | align="char"> | ||
| 440 | <para>int fd</para> | ||
| 441 | </entry><entry | ||
| 442 | align="char"> | ||
| 443 | <para>File descriptor returned by a previous call to open().</para> | ||
| 444 | </entry> | ||
| 445 | </row><row><entry | ||
| 446 | align="char"> | ||
| 447 | <para>void *buf</para> | ||
| 448 | </entry><entry | ||
| 449 | align="char"> | ||
| 450 | <para>Pointer to the buffer containing the Transport Stream.</para> | ||
| 451 | </entry> | ||
| 452 | </row><row><entry | ||
| 453 | align="char"> | ||
| 454 | <para>size_t count</para> | ||
| 455 | </entry><entry | ||
| 456 | align="char"> | ||
| 457 | <para>Size of buf.</para> | ||
| 458 | </entry> | ||
| 459 | </row></tbody></tgroup></informaltable> | ||
| 460 | <para>ERRORS | ||
| 461 | </para> | ||
| 462 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 463 | align="char"> | ||
| 464 | <para>EWOULDBLOCK</para> | ||
| 465 | </entry><entry | ||
| 466 | align="char"> | ||
| 467 | <para>No data was written. This | ||
| 468 | might happen if O_NONBLOCK was specified and there | ||
| 469 | is no more buffer space available (if O_NONBLOCK is | ||
| 470 | not specified the function will block until buffer space is | ||
| 471 | available).</para> | ||
| 472 | </entry> | ||
| 473 | </row><row><entry | ||
| 474 | align="char"> | ||
| 475 | <para>EBUSY</para> | ||
| 476 | </entry><entry | ||
| 477 | align="char"> | ||
| 478 | <para>This error code indicates that there are conflicting | ||
| 479 | requests. The corresponding demux device is setup to | ||
| 480 | receive data from the front- end. Make sure that these | ||
| 481 | filters are stopped and that the filters with input set to | ||
| 482 | DMX_IN_DVR are started.</para> | ||
| 483 | </entry> | ||
| 484 | </row><row><entry | ||
| 485 | align="char"> | ||
| 486 | <para>EBADF</para> | ||
| 487 | </entry><entry | ||
| 488 | align="char"> | ||
| 489 | <para>fd is not a valid open file descriptor.</para> | ||
| 490 | </entry> | ||
| 491 | </row></tbody></tgroup></informaltable> | ||
| 492 | </section> | ||
| 493 | |||
| 494 | <section id="dmx_start"> | ||
| 495 | <title>DMX_START</title> | ||
| 496 | <para>DESCRIPTION | ||
| 497 | </para> | ||
| 498 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 499 | align="char"> | ||
| 500 | <para>This ioctl call is used to start the actual filtering operation defined via the ioctl | ||
| 501 | calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> | ||
| 502 | </entry> | ||
| 503 | </row></tbody></tgroup></informaltable> | ||
| 504 | <para>SYNOPSIS | ||
| 505 | </para> | ||
| 506 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 507 | align="char"> | ||
| 508 | <para>int ioctl( int fd, int request = DMX_START);</para> | ||
| 509 | </entry> | ||
| 510 | </row></tbody></tgroup></informaltable> | ||
| 511 | <para>PARAMETERS | ||
| 512 | </para> | ||
| 513 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 514 | align="char"> | ||
| 515 | <para>int fd</para> | ||
| 516 | </entry><entry | ||
| 517 | align="char"> | ||
| 518 | <para>File descriptor returned by a previous call to open().</para> | ||
| 519 | </entry> | ||
| 520 | </row><row><entry | ||
| 521 | align="char"> | ||
| 522 | <para>int request</para> | ||
| 523 | </entry><entry | ||
| 524 | align="char"> | ||
| 525 | <para>Equals DMX_START for this command.</para> | ||
| 526 | </entry> | ||
| 527 | </row></tbody></tgroup></informaltable> | ||
| 528 | <para>ERRORS | ||
| 529 | </para> | ||
| 530 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 531 | align="char"> | ||
| 532 | <para>EBADF</para> | ||
| 533 | </entry><entry | ||
| 534 | align="char"> | ||
| 535 | <para>fd is not a valid file descriptor.</para> | ||
| 536 | </entry> | ||
| 537 | </row><row><entry | ||
| 538 | align="char"> | ||
| 539 | <para>EINVAL</para> | ||
| 540 | </entry><entry | ||
| 541 | align="char"> | ||
| 542 | <para>Invalid argument, i.e. no filtering parameters provided via | ||
| 543 | the DMX_SET_FILTER or DMX_SET_PES_FILTER | ||
| 544 | functions.</para> | ||
| 545 | </entry> | ||
| 546 | </row><row><entry | ||
| 547 | align="char"> | ||
| 548 | <para>EBUSY</para> | ||
| 549 | </entry><entry | ||
| 550 | align="char"> | ||
| 551 | <para>This error code indicates that there are conflicting | ||
| 552 | requests. There are active filters filtering data from | ||
| 553 | another input source. Make sure that these filters are | ||
| 554 | stopped before starting this filter.</para> | ||
| 555 | </entry> | ||
| 556 | </row></tbody></tgroup></informaltable> | ||
| 557 | </section> | ||
| 558 | |||
| 559 | <section id="dmx_stop"> | ||
| 560 | <title>DMX_STOP</title> | ||
| 561 | <para>DESCRIPTION | ||
| 562 | </para> | ||
| 563 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 564 | align="char"> | ||
| 565 | <para>This ioctl call is used to stop the actual filtering operation defined via the | ||
| 566 | ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via | ||
| 567 | the DMX_START command.</para> | ||
| 568 | </entry> | ||
| 569 | </row></tbody></tgroup></informaltable> | ||
| 570 | <para>SYNOPSIS | ||
| 571 | </para> | ||
| 572 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 573 | align="char"> | ||
| 574 | <para>int ioctl( int fd, int request = DMX_STOP);</para> | ||
| 575 | </entry> | ||
| 576 | </row></tbody></tgroup></informaltable> | ||
| 577 | <para>PARAMETERS | ||
| 578 | </para> | ||
| 579 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 580 | align="char"> | ||
| 581 | <para>int fd</para> | ||
| 582 | </entry><entry | ||
| 583 | align="char"> | ||
| 584 | <para>File descriptor returned by a previous call to open().</para> | ||
| 585 | </entry> | ||
| 586 | </row><row><entry | ||
| 587 | align="char"> | ||
| 588 | <para>int request</para> | ||
| 589 | </entry><entry | ||
| 590 | align="char"> | ||
| 591 | <para>Equals DMX_STOP for this command.</para> | ||
| 592 | </entry> | ||
| 593 | </row></tbody></tgroup></informaltable> | ||
| 594 | <para>ERRORS | ||
| 595 | </para> | ||
| 596 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 597 | align="char"> | ||
| 598 | <para>EBADF</para> | ||
| 599 | </entry><entry | ||
| 600 | align="char"> | ||
| 601 | <para>fd is not a valid file descriptor.</para> | ||
| 602 | </entry> | ||
| 603 | </row></tbody></tgroup></informaltable> | ||
| 604 | </section> | ||
| 605 | |||
| 606 | <section id="dmx_set_filter"> | ||
| 607 | <title>DMX_SET_FILTER</title> | ||
| 608 | <para>DESCRIPTION | ||
| 609 | </para> | ||
| 610 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 611 | align="char"> | ||
| 612 | <para>This ioctl call sets up a filter according to the filter and mask parameters | ||
| 613 | provided. A timeout may be defined stating number of seconds to wait for a | ||
| 614 | section to be loaded. A value of 0 means that no timeout should be applied. | ||
| 615 | Finally there is a flag field where it is possible to state whether a section should | ||
| 616 | be CRC-checked, whether the filter should be a ”one-shot” filter, i.e. if the | ||
| 617 | filtering operation should be stopped after the first section is received, and | ||
| 618 | whether the filtering operation should be started immediately (without waiting | ||
| 619 | for a DMX_START ioctl call). If a filter was previously set-up, this filter will | ||
| 620 | be canceled, and the receive buffer will be flushed.</para> | ||
| 621 | </entry> | ||
| 622 | </row></tbody></tgroup></informaltable> | ||
| 623 | <para>SYNOPSIS | ||
| 624 | </para> | ||
| 625 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 626 | align="char"> | ||
| 627 | <para>int ioctl( int fd, int request = DMX_SET_FILTER, | ||
| 628 | struct dmx_sct_filter_params ⋆params);</para> | ||
| 629 | </entry> | ||
| 630 | </row></tbody></tgroup></informaltable> | ||
| 631 | <para>PARAMETERS | ||
| 632 | </para> | ||
| 633 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 634 | align="char"> | ||
| 635 | <para>int fd</para> | ||
| 636 | </entry><entry | ||
| 637 | align="char"> | ||
| 638 | <para>File descriptor returned by a previous call to open().</para> | ||
| 639 | </entry> | ||
| 640 | </row><row><entry | ||
| 641 | align="char"> | ||
| 642 | <para>int request</para> | ||
| 643 | </entry><entry | ||
| 644 | align="char"> | ||
| 645 | <para>Equals DMX_SET_FILTER for this command.</para> | ||
| 646 | </entry> | ||
| 647 | </row><row><entry | ||
| 648 | align="char"> | ||
| 649 | <para>struct | ||
| 650 | dmx_sct_filter_params | ||
| 651 | *params</para> | ||
| 652 | </entry><entry | ||
| 653 | align="char"> | ||
| 654 | <para>Pointer to structure containing filter parameters.</para> | ||
| 655 | </entry> | ||
| 656 | </row></tbody></tgroup></informaltable> | ||
| 657 | <para>ERRORS | ||
| 658 | </para> | ||
| 659 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 660 | align="char"> | ||
| 661 | <para>EBADF</para> | ||
| 662 | </entry><entry | ||
| 663 | align="char"> | ||
| 664 | <para>fd is not a valid file descriptor.</para> | ||
| 665 | </entry> | ||
| 666 | </row><row><entry | ||
| 667 | align="char"> | ||
| 668 | <para>EINVAL</para> | ||
| 669 | </entry><entry | ||
| 670 | align="char"> | ||
| 671 | <para>Invalid argument.</para> | ||
| 672 | </entry> | ||
| 673 | </row></tbody></tgroup></informaltable> | ||
| 674 | </section> | ||
| 675 | |||
| 676 | <section id="dmx_set_pes_filter"> | ||
| 677 | <title>DMX_SET_PES_FILTER</title> | ||
| 678 | <para>DESCRIPTION | ||
| 679 | </para> | ||
| 680 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 681 | align="char"> | ||
| 682 | <para>This ioctl call sets up a PES filter according to the parameters provided. By a | ||
| 683 | PES filter is meant a filter that is based just on the packet identifier (PID), i.e. | ||
| 684 | no PES header or payload filtering capability is supported.</para> | ||
| 685 | </entry> | ||
| 686 | </row><row><entry | ||
| 687 | align="char"> | ||
| 688 | <para>The transport stream destination for the filtered output may be set. Also the | ||
| 689 | PES type may be stated in order to be able to e.g. direct a video stream directly | ||
| 690 | to the video decoder. Finally there is a flag field where it is possible to state | ||
| 691 | whether the filtering operation should be started immediately (without waiting | ||
| 692 | for a DMX_START ioctl call). If a filter was previously set-up, this filter will | ||
| 693 | be cancelled, and the receive buffer will be flushed.</para> | ||
| 694 | </entry> | ||
| 695 | </row></tbody></tgroup></informaltable> | ||
| 696 | <para>SYNOPSIS | ||
| 697 | </para> | ||
| 698 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 699 | align="char"> | ||
| 700 | <para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, | ||
| 701 | struct dmx_pes_filter_params ⋆params);</para> | ||
| 702 | </entry> | ||
| 703 | </row></tbody></tgroup></informaltable> | ||
| 704 | <para>PARAMETERS | ||
| 705 | </para> | ||
| 706 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 707 | align="char"> | ||
| 708 | <para>int fd</para> | ||
| 709 | </entry><entry | ||
| 710 | align="char"> | ||
| 711 | <para>File descriptor returned by a previous call to open().</para> | ||
| 712 | </entry> | ||
| 713 | </row><row><entry | ||
| 714 | align="char"> | ||
| 715 | <para>int request</para> | ||
| 716 | </entry><entry | ||
| 717 | align="char"> | ||
| 718 | <para>Equals DMX_SET_PES_FILTER for this command.</para> | ||
| 719 | </entry> | ||
| 720 | </row><row><entry | ||
| 721 | align="char"> | ||
| 722 | <para>struct | ||
| 723 | dmx_pes_filter_params | ||
| 724 | *params</para> | ||
| 725 | </entry><entry | ||
| 726 | align="char"> | ||
| 727 | <para>Pointer to structure containing filter parameters.</para> | ||
| 728 | </entry> | ||
| 729 | </row></tbody></tgroup></informaltable> | ||
| 730 | <para>ERRORS | ||
| 731 | </para> | ||
| 732 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>EBADF</para> | ||
| 735 | </entry><entry | ||
| 736 | align="char"> | ||
| 737 | <para>fd is not a valid file descriptor.</para> | ||
| 738 | </entry> | ||
| 739 | </row><row><entry | ||
| 740 | align="char"> | ||
| 741 | <para>EINVAL</para> | ||
| 742 | </entry><entry | ||
| 743 | align="char"> | ||
| 744 | <para>Invalid argument.</para> | ||
| 745 | </entry> | ||
| 746 | </row><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>EBUSY</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>This error code indicates that there are conflicting | ||
| 752 | requests. There are active filters filtering data from | ||
| 753 | another input source. Make sure that these filters are | ||
| 754 | stopped before starting this filter.</para> | ||
| 755 | </entry> | ||
| 756 | </row></tbody></tgroup></informaltable> | ||
| 757 | </section> | ||
| 758 | |||
| 759 | <section id="dms_set_buffer_size"> | ||
| 760 | <title>DMX_SET_BUFFER_SIZE</title> | ||
| 761 | <para>DESCRIPTION | ||
| 762 | </para> | ||
| 763 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 764 | align="char"> | ||
| 765 | <para>This ioctl call is used to set the size of the circular buffer used for filtered data. | ||
| 766 | The default size is two maximum sized sections, i.e. if this function is not called | ||
| 767 | a buffer size of 2 * 4096 bytes will be used.</para> | ||
| 768 | </entry> | ||
| 769 | </row></tbody></tgroup></informaltable> | ||
| 770 | <para>SYNOPSIS | ||
| 771 | </para> | ||
| 772 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 773 | align="char"> | ||
| 774 | <para>int ioctl( int fd, int request = | ||
| 775 | DMX_SET_BUFFER_SIZE, unsigned long size);</para> | ||
| 776 | </entry> | ||
| 777 | </row></tbody></tgroup></informaltable> | ||
| 778 | <para>PARAMETERS | ||
| 779 | </para> | ||
| 780 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 781 | align="char"> | ||
| 782 | <para>int fd</para> | ||
| 783 | </entry><entry | ||
| 784 | align="char"> | ||
| 785 | <para>File descriptor returned by a previous call to open().</para> | ||
| 786 | </entry> | ||
| 787 | </row><row><entry | ||
| 788 | align="char"> | ||
| 789 | <para>int request</para> | ||
| 790 | </entry><entry | ||
| 791 | align="char"> | ||
| 792 | <para>Equals DMX_SET_BUFFER_SIZE for this command.</para> | ||
| 793 | </entry> | ||
| 794 | </row><row><entry | ||
| 795 | align="char"> | ||
| 796 | <para>unsigned long size</para> | ||
| 797 | </entry><entry | ||
| 798 | align="char"> | ||
| 799 | <para>Size of circular buffer.</para> | ||
| 800 | </entry> | ||
| 801 | </row></tbody></tgroup></informaltable> | ||
| 802 | <para>ERRORS | ||
| 803 | </para> | ||
| 804 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 805 | align="char"> | ||
| 806 | <para>EBADF</para> | ||
| 807 | </entry><entry | ||
| 808 | align="char"> | ||
| 809 | <para>fd is not a valid file descriptor.</para> | ||
| 810 | </entry> | ||
| 811 | </row><row><entry | ||
| 812 | align="char"> | ||
| 813 | <para>ENOMEM</para> | ||
| 814 | </entry><entry | ||
| 815 | align="char"> | ||
| 816 | <para>The driver was not able to allocate a buffer of the | ||
| 817 | requested size.</para> | ||
| 818 | </entry> | ||
| 819 | </row></tbody></tgroup></informaltable> | ||
| 820 | </section> | ||
| 821 | |||
| 822 | <section id="dmx_get_event"> | ||
| 823 | <title>DMX_GET_EVENT</title> | ||
| 824 | <para>DESCRIPTION | ||
| 825 | </para> | ||
| 826 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 827 | align="char"> | ||
| 828 | <para>This ioctl call returns an event if available. If an event is not available, | ||
| 829 | the behavior depends on whether the device is in blocking or non-blocking | ||
| 830 | mode. In the latter case, the call fails immediately with errno set to | ||
| 831 | EWOULDBLOCK. In the former case, the call blocks until an event becomes | ||
| 832 | available.</para> | ||
| 833 | </entry> | ||
| 834 | </row><row><entry | ||
| 835 | align="char"> | ||
| 836 | <para>The standard Linux poll() and/or select() system calls can be used with the | ||
| 837 | device file descriptor to watch for new events. For select(), the file descriptor | ||
| 838 | should be included in the exceptfds argument, and for poll(), POLLPRI should | ||
| 839 | be specified as the wake-up condition. Only the latest event for each filter is | ||
| 840 | saved.</para> | ||
| 841 | </entry> | ||
| 842 | </row></tbody></tgroup></informaltable> | ||
| 843 | <para>SYNOPSIS | ||
| 844 | </para> | ||
| 845 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 846 | align="char"> | ||
| 847 | <para>int ioctl( int fd, int request = DMX_GET_EVENT, | ||
| 848 | struct dmx_event ⋆ev);</para> | ||
| 849 | </entry> | ||
| 850 | </row></tbody></tgroup></informaltable> | ||
| 851 | <para>PARAMETERS | ||
| 852 | </para> | ||
| 853 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 854 | align="char"> | ||
| 855 | <para>int fd</para> | ||
| 856 | </entry><entry | ||
| 857 | align="char"> | ||
| 858 | <para>File descriptor returned by a previous call to open().</para> | ||
| 859 | </entry> | ||
| 860 | </row><row><entry | ||
| 861 | align="char"> | ||
| 862 | <para>int request</para> | ||
| 863 | </entry><entry | ||
| 864 | align="char"> | ||
| 865 | <para>Equals DMX_GET_EVENT for this command.</para> | ||
| 866 | </entry> | ||
| 867 | </row><row><entry | ||
| 868 | align="char"> | ||
| 869 | <para>struct dmx_event *ev</para> | ||
| 870 | </entry><entry | ||
| 871 | align="char"> | ||
| 872 | <para>Pointer to the location where the event is to be stored.</para> | ||
| 873 | </entry> | ||
| 874 | </row></tbody></tgroup></informaltable> | ||
| 875 | <para>ERRORS | ||
| 876 | </para> | ||
| 877 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 878 | align="char"> | ||
| 879 | <para>EBADF</para> | ||
| 880 | </entry><entry | ||
| 881 | align="char"> | ||
| 882 | <para>fd is not a valid file descriptor.</para> | ||
| 883 | </entry> | ||
| 884 | </row><row><entry | ||
| 885 | align="char"> | ||
| 886 | <para>EFAULT</para> | ||
| 887 | </entry><entry | ||
| 888 | align="char"> | ||
| 889 | <para>ev points to an invalid address.</para> | ||
| 890 | </entry> | ||
| 891 | </row><row><entry | ||
| 892 | align="char"> | ||
| 893 | <para>EWOULDBLOCK</para> | ||
| 894 | </entry><entry | ||
| 895 | align="char"> | ||
| 896 | <para>There is no event pending, and the device is in | ||
| 897 | non-blocking mode.</para> | ||
| 898 | </entry> | ||
| 899 | </row></tbody></tgroup></informaltable> | ||
| 900 | </section> | ||
| 901 | |||
| 902 | <section id="dmx_get_stc"> | ||
| 903 | <title>DMX_GET_STC</title> | ||
| 904 | <para>DESCRIPTION | ||
| 905 | </para> | ||
| 906 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 907 | align="char"> | ||
| 908 | <para>This ioctl call returns the current value of the system time counter (which is driven | ||
| 909 | by a PES filter of type DMX_PES_PCR). Some hardware supports more than one | ||
| 910 | STC, so you must specify which one by setting the num field of stc before the ioctl | ||
| 911 | (range 0...n). The result is returned in form of a ratio with a 64 bit numerator | ||
| 912 | and a 32 bit denominator, so the real 90kHz STC value is stc->stc / | ||
| 913 | stc->base | ||
| 914 | .</para> | ||
| 915 | </entry> | ||
| 916 | </row></tbody></tgroup></informaltable> | ||
| 917 | <para>SYNOPSIS | ||
| 918 | </para> | ||
| 919 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 920 | align="char"> | ||
| 921 | <para>int ioctl( int fd, int request = DMX_GET_STC, struct | ||
| 922 | dmx_stc ⋆stc);</para> | ||
| 923 | </entry> | ||
| 924 | </row></tbody></tgroup></informaltable> | ||
| 925 | <para>PARAMETERS | ||
| 926 | </para> | ||
| 927 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 928 | align="char"> | ||
| 929 | <para>int fd</para> | ||
| 930 | </entry><entry | ||
| 931 | align="char"> | ||
| 932 | <para>File descriptor returned by a previous call to open().</para> | ||
| 933 | </entry> | ||
| 934 | </row><row><entry | ||
| 935 | align="char"> | ||
| 936 | <para>int request</para> | ||
| 937 | </entry><entry | ||
| 938 | align="char"> | ||
| 939 | <para>Equals DMX_GET_STC for this command.</para> | ||
| 940 | </entry> | ||
| 941 | </row><row><entry | ||
| 942 | align="char"> | ||
| 943 | <para>struct dmx_stc *stc</para> | ||
| 944 | </entry><entry | ||
| 945 | align="char"> | ||
| 946 | <para>Pointer to the location where the stc is to be stored.</para> | ||
| 947 | </entry> | ||
| 948 | </row></tbody></tgroup></informaltable> | ||
| 949 | <para>ERRORS | ||
| 950 | </para> | ||
| 951 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 952 | align="char"> | ||
| 953 | <para>EBADF</para> | ||
| 954 | </entry><entry | ||
| 955 | align="char"> | ||
| 956 | <para>fd is not a valid file descriptor.</para> | ||
| 957 | </entry> | ||
| 958 | </row><row><entry | ||
| 959 | align="char"> | ||
| 960 | <para>EFAULT</para> | ||
| 961 | </entry><entry | ||
| 962 | align="char"> | ||
| 963 | <para>stc points to an invalid address.</para> | ||
| 964 | </entry> | ||
| 965 | </row><row><entry | ||
| 966 | align="char"> | ||
| 967 | <para>EINVAL</para> | ||
| 968 | </entry><entry | ||
| 969 | align="char"> | ||
| 970 | <para>Invalid stc number.</para> | ||
| 971 | </entry> | ||
| 972 | </row></tbody></tgroup></informaltable> | ||
| 973 | </section></section> | ||
diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml new file mode 100644 index 000000000000..4fc5b23470a3 --- /dev/null +++ b/Documentation/DocBook/dvb/dvbapi.xml | |||
| @@ -0,0 +1,87 @@ | |||
| 1 | <partinfo> | ||
| 2 | <authorgroup> | ||
| 3 | <author> | ||
| 4 | <firstname>Ralph</firstname> | ||
| 5 | <surname>Metzler</surname> | ||
| 6 | <othername role="mi">J. K.</othername> | ||
| 7 | <affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> | ||
| 8 | </author> | ||
| 9 | <author> | ||
| 10 | <firstname>Marcus</firstname> | ||
| 11 | <surname>Metzler</surname> | ||
| 12 | <othername role="mi">O. C.</othername> | ||
| 13 | <affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> | ||
| 14 | </author> | ||
| 15 | <author> | ||
| 16 | <firstname>Mauro</firstname> | ||
| 17 | <surname>Chehab</surname> | ||
| 18 | <othername role="mi">Carvalho</othername> | ||
| 19 | <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> | ||
| 20 | <contrib>Ported document to Docbook XML.</contrib> | ||
| 21 | </author> | ||
| 22 | </authorgroup> | ||
| 23 | <copyright> | ||
| 24 | <year>2002</year> | ||
| 25 | <year>2003</year> | ||
| 26 | <year>2009</year> | ||
| 27 | <holder>Convergence GmbH</holder> | ||
| 28 | </copyright> | ||
| 29 | |||
| 30 | <revhistory> | ||
| 31 | <!-- Put document revisions here, newest first. --> | ||
| 32 | <revision> | ||
| 33 | <revnumber>2.0.1</revnumber> | ||
| 34 | <date>2009-09-16</date> | ||
| 35 | <authorinitials>mcc</authorinitials> | ||
| 36 | <revremark> | ||
| 37 | Added ISDB-T test originally written by Patrick Boettcher | ||
| 38 | </revremark> | ||
| 39 | </revision> | ||
| 40 | <revision> | ||
| 41 | <revnumber>2.0.0</revnumber> | ||
| 42 | <date>2009-09-06</date> | ||
| 43 | <authorinitials>mcc</authorinitials> | ||
| 44 | <revremark>Conversion from LaTex to DocBook XML. The | ||
| 45 | contents is the same as the original LaTex version.</revremark> | ||
| 46 | </revision> | ||
| 47 | <revision> | ||
| 48 | <revnumber>1.0.0</revnumber> | ||
| 49 | <date>2003-07-24</date> | ||
| 50 | <authorinitials>rjkm</authorinitials> | ||
| 51 | <revremark>Initial revision on LaTEX.</revremark> | ||
| 52 | </revision> | ||
| 53 | </revhistory> | ||
| 54 | </partinfo> | ||
| 55 | |||
| 56 | |||
| 57 | <title>LINUX DVB API</title> | ||
| 58 | <subtitle>Version 3</subtitle> | ||
| 59 | <!-- ADD THE CHAPTERS HERE --> | ||
| 60 | <chapter id="dvb_introdution"> | ||
| 61 | &sub-intro; | ||
| 62 | </chapter> | ||
| 63 | <chapter id="dvb_frontend"> | ||
| 64 | &sub-frontend; | ||
| 65 | </chapter> | ||
| 66 | <chapter id="dvb_demux"> | ||
| 67 | &sub-demux; | ||
| 68 | </chapter> | ||
| 69 | <chapter id="dvb_video"> | ||
| 70 | &sub-video; | ||
| 71 | </chapter> | ||
| 72 | <chapter id="dvb_audio"> | ||
| 73 | &sub-audio; | ||
| 74 | </chapter> | ||
| 75 | <chapter id="dvb_ca"> | ||
| 76 | &sub-ca; | ||
| 77 | </chapter> | ||
| 78 | <chapter id="dvb_net"> | ||
| 79 | &sub-net; | ||
| 80 | </chapter> | ||
| 81 | <chapter id="dvb_kdapi"> | ||
| 82 | &sub-kdapi; | ||
| 83 | </chapter> | ||
| 84 | <chapter id="dvb_examples"> | ||
| 85 | &sub-examples; | ||
| 86 | </chapter> | ||
| 87 | <!-- END OF CHAPTERS --> | ||
diff --git a/Documentation/DocBook/dvb/dvbstb.pdf b/Documentation/DocBook/dvb/dvbstb.pdf new file mode 100644 index 000000000000..0fa75d90c3eb --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/dvb/dvbstb.png b/Documentation/DocBook/dvb/dvbstb.png new file mode 100644 index 000000000000..9b8f372e7afd --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.png | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/dvb/examples.xml b/Documentation/DocBook/dvb/examples.xml new file mode 100644 index 000000000000..f037e568eb6e --- /dev/null +++ b/Documentation/DocBook/dvb/examples.xml | |||
| @@ -0,0 +1,365 @@ | |||
| 1 | <title>Examples</title> | ||
| 2 | <para>In this section we would like to present some examples for using the DVB API. | ||
| 3 | </para> | ||
| 4 | <para>Maintainer note: This section is out of date. Please refer to the sample programs packaged | ||
| 5 | with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />. | ||
| 6 | </para> | ||
| 7 | |||
| 8 | <section id="tuning"> | ||
| 9 | <title>Tuning</title> | ||
| 10 | <para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as | ||
| 11 | the demux devices. The example is given for QPSK tuners, but can easily be adjusted for | ||
| 12 | QAM. | ||
| 13 | </para> | ||
| 14 | <programlisting> | ||
| 15 | #include <sys/ioctl.h> | ||
| 16 | #include <stdio.h> | ||
| 17 | #include <stdint.h> | ||
| 18 | #include <sys/types.h> | ||
| 19 | #include <sys/stat.h> | ||
| 20 | #include <fcntl.h> | ||
| 21 | #include <time.h> | ||
| 22 | #include <unistd.h> | ||
| 23 | |||
| 24 | #include <linux/dvb/dmx.h> | ||
| 25 | #include <linux/dvb/frontend.h> | ||
| 26 | #include <linux/dvb/sec.h> | ||
| 27 | #include <sys/poll.h> | ||
| 28 | |||
| 29 | #define DMX "/dev/dvb/adapter0/demux1" | ||
| 30 | #define FRONT "/dev/dvb/adapter0/frontend1" | ||
| 31 | #define SEC "/dev/dvb/adapter0/sec1" | ||
| 32 | |||
| 33 | /⋆ routine for checking if we have a signal and other status information⋆/ | ||
| 34 | int FEReadStatus(int fd, fe_status_t ⋆stat) | ||
| 35 | { | ||
| 36 | int ans; | ||
| 37 | |||
| 38 | if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ | ||
| 39 | perror("FE READ STATUS: "); | ||
| 40 | return -1; | ||
| 41 | } | ||
| 42 | |||
| 43 | if (⋆stat & FE_HAS_POWER) | ||
| 44 | printf("FE HAS POWER\n"); | ||
| 45 | |||
| 46 | if (⋆stat & FE_HAS_SIGNAL) | ||
| 47 | printf("FE HAS SIGNAL\n"); | ||
| 48 | |||
| 49 | if (⋆stat & FE_SPECTRUM_INV) | ||
| 50 | printf("SPEKTRUM INV\n"); | ||
| 51 | |||
| 52 | return 0; | ||
| 53 | } | ||
| 54 | |||
| 55 | |||
| 56 | /⋆ tune qpsk ⋆/ | ||
| 57 | /⋆ freq: frequency of transponder ⋆/ | ||
| 58 | /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ | ||
| 59 | /⋆ diseqc: DiSEqC address of the used LNB ⋆/ | ||
| 60 | /⋆ pol: Polarisation ⋆/ | ||
| 61 | /⋆ srate: Symbol Rate ⋆/ | ||
| 62 | /⋆ fec. FEC ⋆/ | ||
| 63 | /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ | ||
| 64 | /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ | ||
| 65 | /⋆ lnb_slof: switch frequency of LNB ⋆/ | ||
| 66 | |||
| 67 | int set_qpsk_channel(int freq, int vpid, int apid, int tpid, | ||
| 68 | int diseqc, int pol, int srate, int fec, int lnb_lof1, | ||
| 69 | int lnb_lof2, int lnb_slof) | ||
| 70 | { | ||
| 71 | struct secCommand scmd; | ||
| 72 | struct secCmdSequence scmds; | ||
| 73 | struct dmx_pes_filter_params pesFilterParams; | ||
| 74 | FrontendParameters frp; | ||
| 75 | struct pollfd pfd[1]; | ||
| 76 | FrontendEvent event; | ||
| 77 | int demux1, demux2, demux3, front; | ||
| 78 | |||
| 79 | frequency = (uint32_t) freq; | ||
| 80 | symbolrate = (uint32_t) srate; | ||
| 81 | |||
| 82 | if((front = open(FRONT,O_RDWR)) < 0){ | ||
| 83 | perror("FRONTEND DEVICE: "); | ||
| 84 | return -1; | ||
| 85 | } | ||
| 86 | |||
| 87 | if((sec = open(SEC,O_RDWR)) < 0){ | ||
| 88 | perror("SEC DEVICE: "); | ||
| 89 | return -1; | ||
| 90 | } | ||
| 91 | |||
| 92 | if (demux1 < 0){ | ||
| 93 | if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 94 | < 0){ | ||
| 95 | perror("DEMUX DEVICE: "); | ||
| 96 | return -1; | ||
| 97 | } | ||
| 98 | } | ||
| 99 | |||
| 100 | if (demux2 < 0){ | ||
| 101 | if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 102 | < 0){ | ||
| 103 | perror("DEMUX DEVICE: "); | ||
| 104 | return -1; | ||
| 105 | } | ||
| 106 | } | ||
| 107 | |||
| 108 | if (demux3 < 0){ | ||
| 109 | if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 110 | < 0){ | ||
| 111 | perror("DEMUX DEVICE: "); | ||
| 112 | return -1; | ||
| 113 | } | ||
| 114 | } | ||
| 115 | |||
| 116 | if (freq < lnb_slof) { | ||
| 117 | frp.Frequency = (freq - lnb_lof1); | ||
| 118 | scmds.continuousTone = SEC_TONE_OFF; | ||
| 119 | } else { | ||
| 120 | frp.Frequency = (freq - lnb_lof2); | ||
| 121 | scmds.continuousTone = SEC_TONE_ON; | ||
| 122 | } | ||
| 123 | frp.Inversion = INVERSION_AUTO; | ||
| 124 | if (pol) scmds.voltage = SEC_VOLTAGE_18; | ||
| 125 | else scmds.voltage = SEC_VOLTAGE_13; | ||
| 126 | |||
| 127 | scmd.type=0; | ||
| 128 | scmd.u.diseqc.addr=0x10; | ||
| 129 | scmd.u.diseqc.cmd=0x38; | ||
| 130 | scmd.u.diseqc.numParams=1; | ||
| 131 | scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | | ||
| 132 | (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | | ||
| 133 | (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); | ||
| 134 | |||
| 135 | scmds.miniCommand=SEC_MINI_NONE; | ||
| 136 | scmds.numCommands=1; | ||
| 137 | scmds.commands=&scmd; | ||
| 138 | if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ | ||
| 139 | perror("SEC SEND: "); | ||
| 140 | return -1; | ||
| 141 | } | ||
| 142 | |||
| 143 | if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ | ||
| 144 | perror("SEC SEND: "); | ||
| 145 | return -1; | ||
| 146 | } | ||
| 147 | |||
| 148 | frp.u.qpsk.SymbolRate = srate; | ||
| 149 | frp.u.qpsk.FEC_inner = fec; | ||
| 150 | |||
| 151 | if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ | ||
| 152 | perror("QPSK TUNE: "); | ||
| 153 | return -1; | ||
| 154 | } | ||
| 155 | |||
| 156 | pfd[0].fd = front; | ||
| 157 | pfd[0].events = POLLIN; | ||
| 158 | |||
| 159 | if (poll(pfd,1,3000)){ | ||
| 160 | if (pfd[0].revents & POLLIN){ | ||
| 161 | printf("Getting QPSK event\n"); | ||
| 162 | if ( ioctl(front, FE_GET_EVENT, &event) | ||
| 163 | |||
| 164 | == -EOVERFLOW){ | ||
| 165 | perror("qpsk get event"); | ||
| 166 | return -1; | ||
| 167 | } | ||
| 168 | printf("Received "); | ||
| 169 | switch(event.type){ | ||
| 170 | case FE_UNEXPECTED_EV: | ||
| 171 | printf("unexpected event\n"); | ||
| 172 | return -1; | ||
| 173 | case FE_FAILURE_EV: | ||
| 174 | printf("failure event\n"); | ||
| 175 | return -1; | ||
| 176 | |||
| 177 | case FE_COMPLETION_EV: | ||
| 178 | printf("completion event\n"); | ||
| 179 | } | ||
| 180 | } | ||
| 181 | } | ||
| 182 | |||
| 183 | |||
| 184 | pesFilterParams.pid = vpid; | ||
| 185 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 186 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 187 | pesFilterParams.pes_type = DMX_PES_VIDEO; | ||
| 188 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 189 | if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 190 | perror("set_vpid"); | ||
| 191 | return -1; | ||
| 192 | } | ||
| 193 | |||
| 194 | pesFilterParams.pid = apid; | ||
| 195 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 196 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 197 | pesFilterParams.pes_type = DMX_PES_AUDIO; | ||
| 198 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 199 | if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 200 | perror("set_apid"); | ||
| 201 | return -1; | ||
| 202 | } | ||
| 203 | |||
| 204 | pesFilterParams.pid = tpid; | ||
| 205 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 206 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 207 | pesFilterParams.pes_type = DMX_PES_TELETEXT; | ||
| 208 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 209 | if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 210 | perror("set_tpid"); | ||
| 211 | return -1; | ||
| 212 | } | ||
| 213 | |||
| 214 | return has_signal(fds); | ||
| 215 | } | ||
| 216 | |||
| 217 | </programlisting> | ||
| 218 | <para>The program assumes that you are using a universal LNB and a standard DiSEqC | ||
| 219 | switch with up to 4 addresses. Of course, you could build in some more checking if | ||
| 220 | tuning was successful and maybe try to repeat the tuning process. Depending on the | ||
| 221 | external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be | ||
| 222 | necessary. | ||
| 223 | </para> | ||
| 224 | </section> | ||
| 225 | |||
| 226 | <section id="the_dvr_device"> | ||
| 227 | <title>The DVR device</title> | ||
| 228 | <para>The following program code shows how to use the DVR device for recording. | ||
| 229 | </para> | ||
| 230 | <programlisting> | ||
| 231 | #include <sys/ioctl.h> | ||
| 232 | #include <stdio.h> | ||
| 233 | #include <stdint.h> | ||
| 234 | #include <sys/types.h> | ||
| 235 | #include <sys/stat.h> | ||
| 236 | #include <fcntl.h> | ||
| 237 | #include <time.h> | ||
| 238 | #include <unistd.h> | ||
| 239 | |||
| 240 | #include <linux/dvb/dmx.h> | ||
| 241 | #include <linux/dvb/video.h> | ||
| 242 | #include <sys/poll.h> | ||
| 243 | #define DVR "/dev/dvb/adapter0/dvr1" | ||
| 244 | #define AUDIO "/dev/dvb/adapter0/audio1" | ||
| 245 | #define VIDEO "/dev/dvb/adapter0/video1" | ||
| 246 | |||
| 247 | #define BUFFY (188⋆20) | ||
| 248 | #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ | ||
| 249 | |||
| 250 | |||
| 251 | /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ | ||
| 252 | |||
| 253 | /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ | ||
| 254 | /⋆ vpid, apid: PIDs of video and audio channels ⋆/ | ||
| 255 | |||
| 256 | int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) | ||
| 257 | { | ||
| 258 | struct dmx_pes_filter_params pesFilterParams; | ||
| 259 | |||
| 260 | if (demux1 < 0){ | ||
| 261 | if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 262 | < 0){ | ||
| 263 | perror("DEMUX DEVICE: "); | ||
| 264 | return -1; | ||
| 265 | } | ||
| 266 | } | ||
| 267 | |||
| 268 | if (demux2 < 0){ | ||
| 269 | if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 270 | < 0){ | ||
| 271 | perror("DEMUX DEVICE: "); | ||
| 272 | return -1; | ||
| 273 | } | ||
| 274 | } | ||
| 275 | |||
| 276 | pesFilterParams.pid = vpid; | ||
| 277 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 278 | pesFilterParams.output = DMX_OUT_TS_TAP; | ||
| 279 | pesFilterParams.pes_type = DMX_PES_VIDEO; | ||
| 280 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 281 | if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 282 | perror("DEMUX DEVICE"); | ||
| 283 | return -1; | ||
| 284 | } | ||
| 285 | pesFilterParams.pid = apid; | ||
| 286 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 287 | pesFilterParams.output = DMX_OUT_TS_TAP; | ||
| 288 | pesFilterParams.pes_type = DMX_PES_AUDIO; | ||
| 289 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 290 | if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 291 | perror("DEMUX DEVICE"); | ||
| 292 | return -1; | ||
| 293 | } | ||
| 294 | return 0; | ||
| 295 | } | ||
| 296 | |||
| 297 | /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ | ||
| 298 | |||
| 299 | /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ | ||
| 300 | /⋆ vpid, apid: PIDs of video and audio channels ⋆/ | ||
| 301 | int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) | ||
| 302 | { | ||
| 303 | int i; | ||
| 304 | int len; | ||
| 305 | int written; | ||
| 306 | uint8_t buf[BUFFY]; | ||
| 307 | uint64_t length; | ||
| 308 | struct pollfd pfd[1]; | ||
| 309 | int dvr, dvr_out; | ||
| 310 | |||
| 311 | /⋆ open dvr device ⋆/ | ||
| 312 | if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ | ||
| 313 | perror("DVR DEVICE"); | ||
| 314 | return -1; | ||
| 315 | } | ||
| 316 | |||
| 317 | /⋆ switch video and audio demuxes to dvr ⋆/ | ||
| 318 | printf ("Switching dvr on\n"); | ||
| 319 | i = switch_to_record(demux1, demux2, vpid, apid); | ||
| 320 | printf("finished: "); | ||
| 321 | |||
| 322 | printf("Recording %2.0f MB of test file in TS format\n", | ||
| 323 | MAX_LENGTH/(1024.0⋆1024.0)); | ||
| 324 | length = 0; | ||
| 325 | |||
| 326 | /⋆ open output file ⋆/ | ||
| 327 | if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT | ||
| 328 | |O_TRUNC, S_IRUSR|S_IWUSR | ||
| 329 | |S_IRGRP|S_IWGRP|S_IROTH| | ||
| 330 | S_IWOTH)) < 0){ | ||
| 331 | perror("Can't open file for dvr test"); | ||
| 332 | return -1; | ||
| 333 | } | ||
| 334 | |||
| 335 | pfd[0].fd = dvr; | ||
| 336 | pfd[0].events = POLLIN; | ||
| 337 | |||
| 338 | /⋆ poll for dvr data and write to file ⋆/ | ||
| 339 | while (length < MAX_LENGTH ) { | ||
| 340 | if (poll(pfd,1,1)){ | ||
| 341 | if (pfd[0].revents & POLLIN){ | ||
| 342 | len = read(dvr, buf, BUFFY); | ||
| 343 | if (len < 0){ | ||
| 344 | perror("recording"); | ||
| 345 | return -1; | ||
| 346 | } | ||
| 347 | if (len > 0){ | ||
| 348 | written = 0; | ||
| 349 | while (written < len) | ||
| 350 | written += | ||
| 351 | write (dvr_out, | ||
| 352 | buf, len); | ||
| 353 | length += len; | ||
| 354 | printf("written %2.0f MB\r", | ||
| 355 | length/1024./1024.); | ||
| 356 | } | ||
| 357 | } | ||
| 358 | } | ||
| 359 | } | ||
| 360 | return 0; | ||
| 361 | } | ||
| 362 | |||
| 363 | </programlisting> | ||
| 364 | |||
| 365 | </section> | ||
diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml new file mode 100644 index 000000000000..9d89a7b94fd5 --- /dev/null +++ b/Documentation/DocBook/dvb/frontend.xml | |||
| @@ -0,0 +1,1766 @@ | |||
| 1 | <title>DVB Frontend API</title> | ||
| 2 | |||
| 3 | <para>The DVB frontend device controls the tuner and DVB demodulator | ||
| 4 | hardware. It can be accessed through <emphasis | ||
| 5 | role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and | ||
| 6 | ioctl definitions can be accessed by including <emphasis | ||
| 7 | role="tt">linux/dvb/frontend.h</emphasis> in your application.</para> | ||
| 8 | |||
| 9 | <para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C | ||
| 10 | (cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) | ||
| 11 | is not yet handled by this API but a future extension is possible. For | ||
| 12 | DVB-S the frontend device also supports satellite equipment control | ||
| 13 | (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) | ||
| 14 | specification is available from | ||
| 15 | <ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para> | ||
| 16 | |||
| 17 | <para>Note that the DVB API may also be used for MPEG decoder-only PCI | ||
| 18 | cards, in which case there exists no frontend device.</para> | ||
| 19 | |||
| 20 | <section id="frontend_types"> | ||
| 21 | <title>Frontend Data Types</title> | ||
| 22 | |||
| 23 | <section id="frontend_type"> | ||
| 24 | <title>frontend type</title> | ||
| 25 | |||
| 26 | <para>For historical reasons frontend types are named after the type of modulation used in | ||
| 27 | transmission.</para> | ||
| 28 | <programlisting> | ||
| 29 | typedef enum fe_type { | ||
| 30 | FE_QPSK, /⋆ DVB-S ⋆/ | ||
| 31 | FE_QAM, /⋆ DVB-C ⋆/ | ||
| 32 | FE_OFDM /⋆ DVB-T ⋆/ | ||
| 33 | } fe_type_t; | ||
| 34 | </programlisting> | ||
| 35 | |||
| 36 | </section> | ||
| 37 | |||
| 38 | <section id="frontend_caps"> | ||
| 39 | <title>frontend capabilities</title> | ||
| 40 | |||
| 41 | <para>Capabilities describe what a frontend can do. Some capabilities can only be supported for | ||
| 42 | a specific frontend type.</para> | ||
| 43 | <programlisting> | ||
| 44 | typedef enum fe_caps { | ||
| 45 | FE_IS_STUPID = 0, | ||
| 46 | FE_CAN_INVERSION_AUTO = 0x1, | ||
| 47 | FE_CAN_FEC_1_2 = 0x2, | ||
| 48 | FE_CAN_FEC_2_3 = 0x4, | ||
| 49 | FE_CAN_FEC_3_4 = 0x8, | ||
| 50 | FE_CAN_FEC_4_5 = 0x10, | ||
| 51 | FE_CAN_FEC_5_6 = 0x20, | ||
| 52 | FE_CAN_FEC_6_7 = 0x40, | ||
| 53 | FE_CAN_FEC_7_8 = 0x80, | ||
| 54 | FE_CAN_FEC_8_9 = 0x100, | ||
| 55 | FE_CAN_FEC_AUTO = 0x200, | ||
| 56 | FE_CAN_QPSK = 0x400, | ||
| 57 | FE_CAN_QAM_16 = 0x800, | ||
| 58 | FE_CAN_QAM_32 = 0x1000, | ||
| 59 | FE_CAN_QAM_64 = 0x2000, | ||
| 60 | FE_CAN_QAM_128 = 0x4000, | ||
| 61 | FE_CAN_QAM_256 = 0x8000, | ||
| 62 | FE_CAN_QAM_AUTO = 0x10000, | ||
| 63 | FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, | ||
| 64 | FE_CAN_BANDWIDTH_AUTO = 0x40000, | ||
| 65 | FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, | ||
| 66 | FE_CAN_HIERARCHY_AUTO = 0x100000, | ||
| 67 | FE_CAN_MUTE_TS = 0x80000000, | ||
| 68 | FE_CAN_CLEAN_SETUP = 0x40000000 | ||
| 69 | } fe_caps_t; | ||
| 70 | </programlisting> | ||
| 71 | </section> | ||
| 72 | |||
| 73 | <section id="frontend_info"> | ||
| 74 | <title>frontend information</title> | ||
| 75 | |||
| 76 | <para>Information about the frontend ca be queried with FE_GET_INFO.</para> | ||
| 77 | |||
| 78 | <programlisting> | ||
| 79 | struct dvb_frontend_info { | ||
| 80 | char name[128]; | ||
| 81 | fe_type_t type; | ||
| 82 | uint32_t frequency_min; | ||
| 83 | uint32_t frequency_max; | ||
| 84 | uint32_t frequency_stepsize; | ||
| 85 | uint32_t frequency_tolerance; | ||
| 86 | uint32_t symbol_rate_min; | ||
| 87 | uint32_t symbol_rate_max; | ||
| 88 | uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ | ||
| 89 | uint32_t notifier_delay; /⋆ ms ⋆/ | ||
| 90 | fe_caps_t caps; | ||
| 91 | }; | ||
| 92 | </programlisting> | ||
| 93 | </section> | ||
| 94 | |||
| 95 | <section id="frontend_diseqc"> | ||
| 96 | <title>diseqc master command</title> | ||
| 97 | |||
| 98 | <para>A message sent from the frontend to DiSEqC capable equipment.</para> | ||
| 99 | <programlisting> | ||
| 100 | struct dvb_diseqc_master_cmd { | ||
| 101 | uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ | ||
| 102 | uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ | ||
| 103 | }; | ||
| 104 | </programlisting> | ||
| 105 | </section> | ||
| 106 | <section role="subsection"> | ||
| 107 | <title>diseqc slave reply</title> | ||
| 108 | |||
| 109 | <para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para> | ||
| 110 | <programlisting> | ||
| 111 | struct dvb_diseqc_slave_reply { | ||
| 112 | uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ | ||
| 113 | uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ | ||
| 114 | int timeout; /⋆ return from ioctl after timeout ms with ⋆/ | ||
| 115 | }; /⋆ errorcode when no message was received ⋆/ | ||
| 116 | </programlisting> | ||
| 117 | </section> | ||
| 118 | |||
| 119 | <section id="frontend_diseqc_slave_reply"> | ||
| 120 | <title>diseqc slave reply</title> | ||
| 121 | <para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation | ||
| 122 | (horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched | ||
| 123 | consistently to the DiSEqC commands as described in the DiSEqC spec.</para> | ||
| 124 | <programlisting> | ||
| 125 | typedef enum fe_sec_voltage { | ||
| 126 | SEC_VOLTAGE_13, | ||
| 127 | SEC_VOLTAGE_18 | ||
| 128 | } fe_sec_voltage_t; | ||
| 129 | </programlisting> | ||
| 130 | </section> | ||
| 131 | |||
| 132 | <section id="frontend_sec_tone"> | ||
| 133 | <title>SEC continuous tone</title> | ||
| 134 | |||
| 135 | <para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the | ||
| 136 | high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to | ||
| 137 | be switched consistently to the DiSEqC commands as described in the DiSEqC | ||
| 138 | spec.</para> | ||
| 139 | <programlisting> | ||
| 140 | typedef enum fe_sec_tone_mode { | ||
| 141 | SEC_TONE_ON, | ||
| 142 | SEC_TONE_OFF | ||
| 143 | } fe_sec_tone_mode_t; | ||
| 144 | </programlisting> | ||
| 145 | </section> | ||
| 146 | |||
| 147 | <section id="frontend_sec_burst"> | ||
| 148 | <title>SEC tone burst</title> | ||
| 149 | |||
| 150 | <para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select | ||
| 151 | between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to | ||
| 152 | be switched consistently to the DiSEqC commands as described in the DiSEqC | ||
| 153 | spec.</para> | ||
| 154 | <programlisting> | ||
| 155 | typedef enum fe_sec_mini_cmd { | ||
| 156 | SEC_MINI_A, | ||
| 157 | SEC_MINI_B | ||
| 158 | } fe_sec_mini_cmd_t; | ||
| 159 | </programlisting> | ||
| 160 | |||
| 161 | <para></para> | ||
| 162 | </section> | ||
| 163 | |||
| 164 | <section id="frontend_status"> | ||
| 165 | <title>frontend status</title> | ||
| 166 | <para>Several functions of the frontend device use the fe_status data type defined | ||
| 167 | by</para> | ||
| 168 | <programlisting> | ||
| 169 | typedef enum fe_status { | ||
| 170 | FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ | ||
| 171 | FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ | ||
| 172 | FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ | ||
| 173 | FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ | ||
| 174 | FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ | ||
| 175 | FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ | ||
| 176 | FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ | ||
| 177 | } fe_status_t; /⋆ application is recommned to reset ⋆/ | ||
| 178 | </programlisting> | ||
| 179 | <para>to indicate the current state and/or state changes of the frontend hardware. | ||
| 180 | </para> | ||
| 181 | |||
| 182 | </section> | ||
| 183 | |||
| 184 | <section id="frontend_params"> | ||
| 185 | <title>frontend parameters</title> | ||
| 186 | <para>The kind of parameters passed to the frontend device for tuning depend on | ||
| 187 | the kind of hardware you are using. All kinds of parameters are combined as an | ||
| 188 | union in the FrontendParameters structure:</para> | ||
| 189 | <programlisting> | ||
| 190 | struct dvb_frontend_parameters { | ||
| 191 | uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ | ||
| 192 | /⋆ intermediate frequency in kHz for QPSK ⋆/ | ||
| 193 | fe_spectral_inversion_t inversion; | ||
| 194 | union { | ||
| 195 | struct dvb_qpsk_parameters qpsk; | ||
| 196 | struct dvb_qam_parameters qam; | ||
| 197 | struct dvb_ofdm_parameters ofdm; | ||
| 198 | } u; | ||
| 199 | }; | ||
| 200 | </programlisting> | ||
| 201 | <para>For satellite QPSK frontends you have to use the <constant>QPSKParameters</constant> member defined by</para> | ||
| 202 | <programlisting> | ||
| 203 | struct dvb_qpsk_parameters { | ||
| 204 | uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ | ||
| 205 | fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ | ||
| 206 | }; | ||
| 207 | </programlisting> | ||
| 208 | <para>for cable QAM frontend you use the <constant>QAMParameters</constant> structure</para> | ||
| 209 | <programlisting> | ||
| 210 | struct dvb_qam_parameters { | ||
| 211 | uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ | ||
| 212 | fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ | ||
| 213 | fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ | ||
| 214 | }; | ||
| 215 | </programlisting> | ||
| 216 | <para>DVB-T frontends are supported by the <constant>OFDMParamters</constant> structure | ||
| 217 | </para> | ||
| 218 | <programlisting> | ||
| 219 | struct dvb_ofdm_parameters { | ||
| 220 | fe_bandwidth_t bandwidth; | ||
| 221 | fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ | ||
| 222 | fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ | ||
| 223 | fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ | ||
| 224 | fe_transmit_mode_t transmission_mode; | ||
| 225 | fe_guard_interval_t guard_interval; | ||
| 226 | fe_hierarchy_t hierarchy_information; | ||
| 227 | }; | ||
| 228 | </programlisting> | ||
| 229 | <para>In the case of QPSK frontends the <constant>Frequency</constant> field specifies the intermediate | ||
| 230 | frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of | ||
| 231 | the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and | ||
| 232 | OFDM frontends the Frequency specifies the absolute frequency and is given in | ||
| 233 | Hz. | ||
| 234 | </para> | ||
| 235 | <para>The Inversion field can take one of these values: | ||
| 236 | </para> | ||
| 237 | <programlisting> | ||
| 238 | typedef enum fe_spectral_inversion { | ||
| 239 | INVERSION_OFF, | ||
| 240 | INVERSION_ON, | ||
| 241 | INVERSION_AUTO | ||
| 242 | } fe_spectral_inversion_t; | ||
| 243 | </programlisting> | ||
| 244 | <para>It indicates if spectral inversion should be presumed or not. In the automatic setting | ||
| 245 | (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by | ||
| 246 | itself. | ||
| 247 | </para> | ||
| 248 | <para>The possible values for the <constant>FEC_inner</constant> field are | ||
| 249 | </para> | ||
| 250 | <programlisting> | ||
| 251 | typedef enum fe_code_rate { | ||
| 252 | FEC_NONE = 0, | ||
| 253 | FEC_1_2, | ||
| 254 | FEC_2_3, | ||
| 255 | FEC_3_4, | ||
| 256 | FEC_4_5, | ||
| 257 | FEC_5_6, | ||
| 258 | FEC_6_7, | ||
| 259 | FEC_7_8, | ||
| 260 | FEC_8_9, | ||
| 261 | FEC_AUTO | ||
| 262 | } fe_code_rate_t; | ||
| 263 | </programlisting> | ||
| 264 | <para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto | ||
| 265 | detection. | ||
| 266 | </para> | ||
| 267 | <para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature | ||
| 268 | modulation mode which can be one of the following: | ||
| 269 | </para> | ||
| 270 | <programlisting> | ||
| 271 | typedef enum fe_modulation { | ||
| 272 | QPSK, | ||
| 273 | QAM_16, | ||
| 274 | QAM_32, | ||
| 275 | QAM_64, | ||
| 276 | QAM_128, | ||
| 277 | QAM_256, | ||
| 278 | QAM_AUTO | ||
| 279 | } fe_modulation_t; | ||
| 280 | </programlisting> | ||
| 281 | <para>Finally, there are several more parameters for OFDM: | ||
| 282 | </para> | ||
| 283 | <programlisting> | ||
| 284 | typedef enum fe_transmit_mode { | ||
| 285 | TRANSMISSION_MODE_2K, | ||
| 286 | TRANSMISSION_MODE_8K, | ||
| 287 | TRANSMISSION_MODE_AUTO | ||
| 288 | } fe_transmit_mode_t; | ||
| 289 | </programlisting> | ||
| 290 | <programlisting> | ||
| 291 | typedef enum fe_bandwidth { | ||
| 292 | BANDWIDTH_8_MHZ, | ||
| 293 | BANDWIDTH_7_MHZ, | ||
| 294 | BANDWIDTH_6_MHZ, | ||
| 295 | BANDWIDTH_AUTO | ||
| 296 | } fe_bandwidth_t; | ||
| 297 | </programlisting> | ||
| 298 | <programlisting> | ||
| 299 | typedef enum fe_guard_interval { | ||
| 300 | GUARD_INTERVAL_1_32, | ||
| 301 | GUARD_INTERVAL_1_16, | ||
| 302 | GUARD_INTERVAL_1_8, | ||
| 303 | GUARD_INTERVAL_1_4, | ||
| 304 | GUARD_INTERVAL_AUTO | ||
| 305 | } fe_guard_interval_t; | ||
| 306 | </programlisting> | ||
| 307 | <programlisting> | ||
| 308 | typedef enum fe_hierarchy { | ||
| 309 | HIERARCHY_NONE, | ||
| 310 | HIERARCHY_1, | ||
| 311 | HIERARCHY_2, | ||
| 312 | HIERARCHY_4, | ||
| 313 | HIERARCHY_AUTO | ||
| 314 | } fe_hierarchy_t; | ||
| 315 | </programlisting> | ||
| 316 | |||
| 317 | </section> | ||
| 318 | |||
| 319 | <section id="frontend_events"> | ||
| 320 | <title>frontend events</title> | ||
| 321 | <programlisting> | ||
| 322 | struct dvb_frontend_event { | ||
| 323 | fe_status_t status; | ||
| 324 | struct dvb_frontend_parameters parameters; | ||
| 325 | }; | ||
| 326 | </programlisting> | ||
| 327 | </section> | ||
| 328 | </section> | ||
| 329 | |||
| 330 | |||
| 331 | <section id="frontend_fcalls"> | ||
| 332 | <title>Frontend Function Calls</title> | ||
| 333 | |||
| 334 | <section id="frontend_f_open"> | ||
| 335 | <title>open()</title> | ||
| 336 | <para>DESCRIPTION</para> | ||
| 337 | <informaltable><tgroup cols="1"><tbody><row> | ||
| 338 | <entry align="char"> | ||
| 339 | <para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) | ||
| 340 | for subsequent use. Usually the first thing to do after a successful open is to | ||
| 341 | find out the frontend type with FE_GET_INFO.</para> | ||
| 342 | <para>The device can be opened in read-only mode, which only allows monitoring of | ||
| 343 | device status and statistics, or read/write mode, which allows any kind of use | ||
| 344 | (e.g. performing tuning operations.) | ||
| 345 | </para> | ||
| 346 | <para>In a system with multiple front-ends, it is usually the case that multiple devices | ||
| 347 | cannot be open in read/write mode simultaneously. As long as a front-end | ||
| 348 | device is opened in read/write mode, other open() calls in read/write mode will | ||
| 349 | either fail or block, depending on whether non-blocking or blocking mode was | ||
| 350 | specified. A front-end device opened in blocking mode can later be put into | ||
| 351 | non-blocking mode (and vice versa) using the F_SETFL command of the fcntl | ||
| 352 | system call. This is a standard system call, documented in the Linux manual | ||
| 353 | page for fcntl. When an open() call has succeeded, the device will be ready | ||
| 354 | for use in the specified mode. This implies that the corresponding hardware is | ||
| 355 | powered up, and that other front-ends may have been powered down to make | ||
| 356 | that possible.</para> | ||
| 357 | </entry> | ||
| 358 | </row></tbody></tgroup></informaltable> | ||
| 359 | |||
| 360 | <para>SYNOPSIS</para> | ||
| 361 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 362 | align="char"> | ||
| 363 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 364 | </entry> | ||
| 365 | </row></tbody></tgroup></informaltable> | ||
| 366 | <para>PARAMETERS | ||
| 367 | </para> | ||
| 368 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 369 | align="char"> | ||
| 370 | <para>const char | ||
| 371 | *deviceName</para> | ||
| 372 | </entry><entry | ||
| 373 | align="char"> | ||
| 374 | <para>Name of specific video device.</para> | ||
| 375 | </entry> | ||
| 376 | </row><row><entry | ||
| 377 | align="char"> | ||
| 378 | <para>int flags</para> | ||
| 379 | </entry><entry | ||
| 380 | align="char"> | ||
| 381 | <para>A bit-wise OR of the following flags:</para> | ||
| 382 | </entry> | ||
| 383 | </row><row><entry | ||
| 384 | align="char"> | ||
| 385 | </entry><entry | ||
| 386 | align="char"> | ||
| 387 | <para>O_RDONLY read-only access</para> | ||
| 388 | </entry> | ||
| 389 | </row><row><entry | ||
| 390 | align="char"> | ||
| 391 | </entry><entry | ||
| 392 | align="char"> | ||
| 393 | <para>O_RDWR read/write access</para> | ||
| 394 | </entry> | ||
| 395 | </row><row><entry | ||
| 396 | align="char"> | ||
| 397 | </entry><entry | ||
| 398 | align="char"> | ||
| 399 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 400 | </entry> | ||
| 401 | </row><row><entry | ||
| 402 | align="char"> | ||
| 403 | </entry><entry | ||
| 404 | align="char"> | ||
| 405 | <para>(blocking mode is the default)</para> | ||
| 406 | </entry> | ||
| 407 | </row></tbody></tgroup></informaltable> | ||
| 408 | <para>ERRORS | ||
| 409 | </para> | ||
| 410 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 411 | align="char"> | ||
| 412 | <para>ENODEV</para> | ||
| 413 | </entry><entry | ||
| 414 | align="char"> | ||
| 415 | <para>Device driver not loaded/available.</para> | ||
| 416 | </entry> | ||
| 417 | </row><row><entry | ||
| 418 | align="char"> | ||
| 419 | <para>EINTERNAL</para> | ||
| 420 | </entry><entry | ||
| 421 | align="char"> | ||
| 422 | <para>Internal error.</para> | ||
| 423 | </entry> | ||
| 424 | </row><row><entry | ||
| 425 | align="char"> | ||
| 426 | <para>EBUSY</para> | ||
| 427 | </entry><entry | ||
| 428 | align="char"> | ||
| 429 | <para>Device or resource busy.</para> | ||
| 430 | </entry> | ||
| 431 | </row><row><entry | ||
| 432 | align="char"> | ||
| 433 | <para>EINVAL</para> | ||
| 434 | </entry><entry | ||
| 435 | align="char"> | ||
| 436 | <para>Invalid argument.</para> | ||
| 437 | </entry> | ||
| 438 | </row></tbody></tgroup></informaltable> | ||
| 439 | </section> | ||
| 440 | |||
| 441 | <section id="frontend_f_close"> | ||
| 442 | <title>close()</title> | ||
| 443 | <para>DESCRIPTION | ||
| 444 | </para> | ||
| 445 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 446 | align="char"> | ||
| 447 | <para>This system call closes a previously opened front-end device. After closing | ||
| 448 | a front-end device, its corresponding hardware might be powered down | ||
| 449 | automatically.</para> | ||
| 450 | </entry> | ||
| 451 | </row></tbody></tgroup></informaltable> | ||
| 452 | <para>SYNOPSIS | ||
| 453 | </para> | ||
| 454 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 455 | align="char"> | ||
| 456 | <para>int close(int fd);</para> | ||
| 457 | </entry> | ||
| 458 | </row></tbody></tgroup></informaltable> | ||
| 459 | <para>PARAMETERS | ||
| 460 | </para> | ||
| 461 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 462 | align="char"> | ||
| 463 | <para>int fd</para> | ||
| 464 | </entry><entry | ||
| 465 | align="char"> | ||
| 466 | <para>File descriptor returned by a previous call to open().</para> | ||
| 467 | </entry> | ||
| 468 | </row></tbody></tgroup></informaltable> | ||
| 469 | <para>ERRORS | ||
| 470 | </para> | ||
| 471 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 472 | align="char"> | ||
| 473 | <para>EBADF</para> | ||
| 474 | </entry><entry | ||
| 475 | align="char"> | ||
| 476 | <para>fd is not a valid open file descriptor.</para> | ||
| 477 | </entry> | ||
| 478 | </row></tbody></tgroup></informaltable> | ||
| 479 | </section> | ||
| 480 | |||
| 481 | <section id="frontend_read_status"> | ||
| 482 | <title>FE_READ_STATUS</title> | ||
| 483 | <para>DESCRIPTION | ||
| 484 | </para> | ||
| 485 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 486 | align="char"> | ||
| 487 | <para>This ioctl call returns status information about the front-end. This call only | ||
| 488 | requires read-only access to the device.</para> | ||
| 489 | </entry> | ||
| 490 | </row></tbody></tgroup></informaltable> | ||
| 491 | <para>SYNOPSIS | ||
| 492 | </para> | ||
| 493 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 494 | align="char"> | ||
| 495 | <para>int ioctl(int fd, int request = FE_READ_STATUS, | ||
| 496 | fe_status_t ⋆status);</para> | ||
| 497 | </entry> | ||
| 498 | </row></tbody></tgroup></informaltable> | ||
| 499 | <para>PARAMETERS | ||
| 500 | </para> | ||
| 501 | |||
| 502 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 503 | align="char"> | ||
| 504 | <para>int fd</para> | ||
| 505 | </entry><entry | ||
| 506 | align="char"> | ||
| 507 | <para>File descriptor returned by a previous call to open().</para> | ||
| 508 | </entry> | ||
| 509 | </row><row><entry | ||
| 510 | align="char"> | ||
| 511 | <para>int request</para> | ||
| 512 | </entry><entry | ||
| 513 | align="char"> | ||
| 514 | <para>Equals FE_READ_STATUS for this command.</para> | ||
| 515 | </entry> | ||
| 516 | </row><row><entry | ||
| 517 | align="char"> | ||
| 518 | <para>struct fe_status_t | ||
| 519 | *status</para> | ||
| 520 | </entry><entry | ||
| 521 | align="char"> | ||
| 522 | <para>Points to the location where the front-end status word is | ||
| 523 | to be stored.</para> | ||
| 524 | </entry> | ||
| 525 | </row></tbody></tgroup></informaltable> | ||
| 526 | <para>ERRORS | ||
| 527 | </para> | ||
| 528 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 529 | align="char"> | ||
| 530 | <para>EBADF</para> | ||
| 531 | </entry><entry | ||
| 532 | align="char"> | ||
| 533 | <para>fd is not a valid open file descriptor.</para> | ||
| 534 | </entry> | ||
| 535 | </row><row><entry | ||
| 536 | align="char"> | ||
| 537 | <para>EFAULT</para> | ||
| 538 | </entry><entry | ||
| 539 | align="char"> | ||
| 540 | <para>status points to invalid address.</para> | ||
| 541 | </entry> | ||
| 542 | </row></tbody></tgroup></informaltable> | ||
| 543 | </section> | ||
| 544 | |||
| 545 | <section id="frontend_read_ber"> | ||
| 546 | <title>FE_READ_BER</title> | ||
| 547 | <para>DESCRIPTION | ||
| 548 | </para> | ||
| 549 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 550 | align="char"> | ||
| 551 | <para>This ioctl call returns the bit error rate for the signal currently | ||
| 552 | received/demodulated by the front-end. For this command, read-only access to | ||
| 553 | the device is sufficient.</para> | ||
| 554 | </entry> | ||
| 555 | </row></tbody></tgroup></informaltable> | ||
| 556 | <para>SYNOPSIS | ||
| 557 | </para> | ||
| 558 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 559 | align="char"> | ||
| 560 | <para>int ioctl(int fd, int request = FE_READ_BER, | ||
| 561 | uint32_t ⋆ber);</para> | ||
| 562 | </entry> | ||
| 563 | </row></tbody></tgroup></informaltable> | ||
| 564 | <para>PARAMETERS | ||
| 565 | </para> | ||
| 566 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 567 | align="char"> | ||
| 568 | <para>int fd</para> | ||
| 569 | </entry><entry | ||
| 570 | align="char"> | ||
| 571 | <para>File descriptor returned by a previous call to open().</para> | ||
| 572 | </entry> | ||
| 573 | </row><row><entry | ||
| 574 | align="char"> | ||
| 575 | <para>int request</para> | ||
| 576 | </entry><entry | ||
| 577 | align="char"> | ||
| 578 | <para>Equals FE_READ_BER for this command.</para> | ||
| 579 | </entry> | ||
| 580 | </row><row><entry | ||
| 581 | align="char"> | ||
| 582 | <para>uint32_t *ber</para> | ||
| 583 | </entry><entry | ||
| 584 | align="char"> | ||
| 585 | <para>The bit error rate is stored into *ber.</para> | ||
| 586 | </entry> | ||
| 587 | </row></tbody></tgroup></informaltable> | ||
| 588 | <para>ERRORS | ||
| 589 | </para> | ||
| 590 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 591 | align="char"> | ||
| 592 | <para>EBADF</para> | ||
| 593 | </entry><entry | ||
| 594 | align="char"> | ||
| 595 | <para>fd is not a valid open file descriptor.</para> | ||
| 596 | </entry> | ||
| 597 | </row><row><entry | ||
| 598 | align="char"> | ||
| 599 | <para>EFAULT</para> | ||
| 600 | </entry><entry | ||
| 601 | align="char"> | ||
| 602 | <para>ber points to invalid address.</para> | ||
| 603 | </entry> | ||
| 604 | </row><row><entry | ||
| 605 | align="char"> | ||
| 606 | <para>ENOSIGNAL</para> | ||
| 607 | </entry><entry | ||
| 608 | align="char"> | ||
| 609 | <para>There is no signal, thus no meaningful bit error rate. Also | ||
| 610 | returned if the front-end is not turned on.</para> | ||
| 611 | </entry> | ||
| 612 | </row><row><entry | ||
| 613 | align="char"> | ||
| 614 | <para>ENOSYS</para> | ||
| 615 | </entry><entry | ||
| 616 | align="char"> | ||
| 617 | <para>Function not available for this device.</para> | ||
| 618 | </entry> | ||
| 619 | </row></tbody></tgroup></informaltable> | ||
| 620 | </section> | ||
| 621 | |||
| 622 | <section id="frontend_read_snr"> | ||
| 623 | <title>FE_READ_SNR</title> | ||
| 624 | |||
| 625 | <para>DESCRIPTION | ||
| 626 | </para> | ||
| 627 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 628 | align="char"> | ||
| 629 | <para>This ioctl call returns the signal-to-noise ratio for the signal currently received | ||
| 630 | by the front-end. For this command, read-only access to the device is sufficient.</para> | ||
| 631 | </entry> | ||
| 632 | </row></tbody></tgroup></informaltable> | ||
| 633 | <para>SYNOPSIS | ||
| 634 | </para> | ||
| 635 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 636 | align="char"> | ||
| 637 | <para>int ioctl(int fd, int request = FE_READ_SNR, int16_t | ||
| 638 | ⋆snr);</para> | ||
| 639 | </entry> | ||
| 640 | </row></tbody></tgroup></informaltable> | ||
| 641 | <para>PARAMETERS | ||
| 642 | </para> | ||
| 643 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 644 | align="char"> | ||
| 645 | <para>int fd</para> | ||
| 646 | </entry><entry | ||
| 647 | align="char"> | ||
| 648 | <para>File descriptor returned by a previous call to open().</para> | ||
| 649 | </entry> | ||
| 650 | </row><row><entry | ||
| 651 | align="char"> | ||
| 652 | <para>int request</para> | ||
| 653 | </entry><entry | ||
| 654 | align="char"> | ||
| 655 | <para>Equals FE_READ_SNR for this command.</para> | ||
| 656 | </entry> | ||
| 657 | </row><row><entry | ||
| 658 | align="char"> | ||
| 659 | <para>int16_t *snr</para> | ||
| 660 | </entry><entry | ||
| 661 | align="char"> | ||
| 662 | <para>The signal-to-noise ratio is stored into *snr.</para> | ||
| 663 | </entry> | ||
| 664 | </row></tbody></tgroup></informaltable> | ||
| 665 | |||
| 666 | <para>ERRORS | ||
| 667 | </para> | ||
| 668 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 669 | align="char"> | ||
| 670 | <para>EBADF</para> | ||
| 671 | </entry><entry | ||
| 672 | align="char"> | ||
| 673 | <para>fd is not a valid open file descriptor.</para> | ||
| 674 | </entry> | ||
| 675 | </row><row><entry | ||
| 676 | align="char"> | ||
| 677 | <para>EFAULT</para> | ||
| 678 | </entry><entry | ||
| 679 | align="char"> | ||
| 680 | <para>snr points to invalid address.</para> | ||
| 681 | </entry> | ||
| 682 | </row><row><entry | ||
| 683 | align="char"> | ||
| 684 | <para>ENOSIGNAL</para> | ||
| 685 | </entry><entry | ||
| 686 | align="char"> | ||
| 687 | <para>There is no signal, thus no meaningful signal strength | ||
| 688 | value. Also returned if front-end is not turned on.</para> | ||
| 689 | </entry> | ||
| 690 | </row><row><entry | ||
| 691 | align="char"> | ||
| 692 | <para>ENOSYS</para> | ||
| 693 | </entry><entry | ||
| 694 | align="char"> | ||
| 695 | <para>Function not available for this device.</para> | ||
| 696 | </entry> | ||
| 697 | </row></tbody></tgroup></informaltable> | ||
| 698 | </section> | ||
| 699 | |||
| 700 | <section id="frontend_read_signal_strength"> | ||
| 701 | <title>FE_READ_SIGNAL_STRENGTH</title> | ||
| 702 | <para>DESCRIPTION | ||
| 703 | </para> | ||
| 704 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 705 | align="char"> | ||
| 706 | <para>This ioctl call returns the signal strength value for the signal currently received | ||
| 707 | by the front-end. For this command, read-only access to the device is sufficient.</para> | ||
| 708 | </entry> | ||
| 709 | </row></tbody></tgroup></informaltable> | ||
| 710 | <para>SYNOPSIS | ||
| 711 | </para> | ||
| 712 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 713 | align="char"> | ||
| 714 | <para>int ioctl( int fd, int request = | ||
| 715 | FE_READ_SIGNAL_STRENGTH, int16_t ⋆strength);</para> | ||
| 716 | </entry> | ||
| 717 | </row></tbody></tgroup></informaltable> | ||
| 718 | |||
| 719 | <para>PARAMETERS | ||
| 720 | </para> | ||
| 721 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 722 | align="char"> | ||
| 723 | <para>int fd</para> | ||
| 724 | </entry><entry | ||
| 725 | align="char"> | ||
| 726 | <para>File descriptor returned by a previous call to open().</para> | ||
| 727 | </entry> | ||
| 728 | </row><row><entry | ||
| 729 | align="char"> | ||
| 730 | <para>int request</para> | ||
| 731 | </entry><entry | ||
| 732 | align="char"> | ||
| 733 | <para>Equals FE_READ_SIGNAL_STRENGTH for this | ||
| 734 | command.</para> | ||
| 735 | </entry> | ||
| 736 | </row><row><entry | ||
| 737 | align="char"> | ||
| 738 | <para>int16_t *strength</para> | ||
| 739 | </entry><entry | ||
| 740 | align="char"> | ||
| 741 | <para>The signal strength value is stored into *strength.</para> | ||
| 742 | </entry> | ||
| 743 | </row></tbody></tgroup></informaltable> | ||
| 744 | <para>ERRORS | ||
| 745 | </para> | ||
| 746 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>EBADF</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>fd is not a valid open file descriptor.</para> | ||
| 752 | </entry> | ||
| 753 | </row><row><entry | ||
| 754 | align="char"> | ||
| 755 | <para>EFAULT</para> | ||
| 756 | </entry><entry | ||
| 757 | align="char"> | ||
| 758 | <para>status points to invalid address.</para> | ||
| 759 | </entry> | ||
| 760 | </row><row><entry | ||
| 761 | align="char"> | ||
| 762 | <para>ENOSIGNAL</para> | ||
| 763 | </entry><entry | ||
| 764 | align="char"> | ||
| 765 | <para>There is no signal, thus no meaningful signal strength | ||
| 766 | value. Also returned if front-end is not turned on.</para> | ||
| 767 | </entry> | ||
| 768 | </row><row><entry | ||
| 769 | align="char"> | ||
| 770 | <para>ENOSYS</para> | ||
| 771 | </entry><entry | ||
| 772 | align="char"> | ||
| 773 | <para>Function not available for this device.</para> | ||
| 774 | </entry> | ||
| 775 | </row></tbody></tgroup></informaltable> | ||
| 776 | </section> | ||
| 777 | |||
| 778 | <section id="frontend_read_ub"> | ||
| 779 | <title>FE_READ_UNCORRECTED_BLOCKS</title> | ||
| 780 | <para>DESCRIPTION | ||
| 781 | </para> | ||
| 782 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>This ioctl call returns the number of uncorrected blocks detected by the device | ||
| 785 | driver during its lifetime. For meaningful measurements, the increment in block | ||
| 786 | count during a specific time interval should be calculated. For this command, | ||
| 787 | read-only access to the device is sufficient.</para> | ||
| 788 | </entry> | ||
| 789 | </row><row><entry | ||
| 790 | align="char"> | ||
| 791 | <para>Note that the counter will wrap to zero after its maximum count has been | ||
| 792 | reached.</para> | ||
| 793 | </entry> | ||
| 794 | </row></tbody></tgroup></informaltable> | ||
| 795 | <para>SYNOPSIS | ||
| 796 | </para> | ||
| 797 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 798 | align="char"> | ||
| 799 | <para>int ioctl( int fd, int request = | ||
| 800 | FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks);</para> | ||
| 801 | </entry> | ||
| 802 | </row></tbody></tgroup></informaltable> | ||
| 803 | <para>PARAMETERS | ||
| 804 | </para> | ||
| 805 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 806 | align="char"> | ||
| 807 | <para>int fd</para> | ||
| 808 | </entry><entry | ||
| 809 | align="char"> | ||
| 810 | <para>File descriptor returned by a previous call to open().</para> | ||
| 811 | </entry> | ||
| 812 | </row><row><entry | ||
| 813 | align="char"> | ||
| 814 | <para>int request</para> | ||
| 815 | </entry><entry | ||
| 816 | align="char"> | ||
| 817 | <para>Equals FE_READ_UNCORRECTED_BLOCKS for this | ||
| 818 | command.</para> | ||
| 819 | </entry> | ||
| 820 | </row><row><entry | ||
| 821 | align="char"> | ||
| 822 | <para>uint32_t *ublocks</para> | ||
| 823 | </entry><entry | ||
| 824 | align="char"> | ||
| 825 | <para>The total number of uncorrected blocks seen by the driver | ||
| 826 | so far.</para> | ||
| 827 | </entry> | ||
| 828 | </row></tbody></tgroup></informaltable> | ||
| 829 | <para>ERRORS | ||
| 830 | </para> | ||
| 831 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 832 | align="char"> | ||
| 833 | <para>EBADF</para> | ||
| 834 | </entry><entry | ||
| 835 | align="char"> | ||
| 836 | <para>fd is not a valid open file descriptor.</para> | ||
| 837 | </entry> | ||
| 838 | </row><row><entry | ||
| 839 | align="char"> | ||
| 840 | <para>EFAULT</para> | ||
| 841 | </entry><entry | ||
| 842 | align="char"> | ||
| 843 | <para>ublocks points to invalid address.</para> | ||
| 844 | </entry> | ||
| 845 | </row><row><entry | ||
| 846 | align="char"> | ||
| 847 | <para>ENOSYS</para> | ||
| 848 | </entry><entry | ||
| 849 | align="char"> | ||
| 850 | <para>Function not available for this device.</para> | ||
| 851 | </entry> | ||
| 852 | </row></tbody></tgroup></informaltable> | ||
| 853 | </section> | ||
| 854 | |||
| 855 | <section id="frontend_set_fe"> | ||
| 856 | <title>FE_SET_FRONTEND</title> | ||
| 857 | <para>DESCRIPTION | ||
| 858 | </para> | ||
| 859 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 860 | align="char"> | ||
| 861 | <para>This ioctl call starts a tuning operation using specified parameters. The result | ||
| 862 | of this call will be successful if the parameters were valid and the tuning could | ||
| 863 | be initiated. The result of the tuning operation in itself, however, will arrive | ||
| 864 | asynchronously as an event (see documentation for FE_GET_EVENT and | ||
| 865 | FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before | ||
| 866 | the previous one was completed, the previous operation will be aborted in favor | ||
| 867 | of the new one. This command requires read/write access to the device.</para> | ||
| 868 | </entry> | ||
| 869 | </row></tbody></tgroup></informaltable> | ||
| 870 | |||
| 871 | <para>SYNOPSIS | ||
| 872 | </para> | ||
| 873 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 874 | align="char"> | ||
| 875 | <para>int ioctl(int fd, int request = FE_SET_FRONTEND, | ||
| 876 | struct dvb_frontend_parameters ⋆p);</para> | ||
| 877 | </entry> | ||
| 878 | </row></tbody></tgroup></informaltable> | ||
| 879 | <para>PARAMETERS | ||
| 880 | </para> | ||
| 881 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 882 | align="char"> | ||
| 883 | <para>int fd</para> | ||
| 884 | </entry><entry | ||
| 885 | align="char"> | ||
| 886 | <para>File descriptor returned by a previous call to open().</para> | ||
| 887 | </entry> | ||
| 888 | </row><row><entry | ||
| 889 | align="char"> | ||
| 890 | <para>int request</para> | ||
| 891 | </entry><entry | ||
| 892 | align="char"> | ||
| 893 | <para>Equals FE_SET_FRONTEND for this command.</para> | ||
| 894 | </entry> | ||
| 895 | </row><row><entry | ||
| 896 | align="char"> | ||
| 897 | <para>struct | ||
| 898 | dvb_frontend_parameters | ||
| 899 | *p</para> | ||
| 900 | </entry><entry | ||
| 901 | align="char"> | ||
| 902 | <para>Points to parameters for tuning operation.</para> | ||
| 903 | </entry> | ||
| 904 | </row></tbody></tgroup></informaltable> | ||
| 905 | <para>ERRORS | ||
| 906 | </para> | ||
| 907 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 908 | align="char"> | ||
| 909 | <para>EBADF</para> | ||
| 910 | </entry><entry | ||
| 911 | align="char"> | ||
| 912 | <para>fd is not a valid open file descriptor.</para> | ||
| 913 | </entry> | ||
| 914 | </row><row><entry | ||
| 915 | align="char"> | ||
| 916 | <para>EFAULT</para> | ||
| 917 | </entry><entry | ||
| 918 | align="char"> | ||
| 919 | <para>p points to invalid address.</para> | ||
| 920 | </entry> | ||
| 921 | </row><row><entry | ||
| 922 | align="char"> | ||
| 923 | <para>EINVAL</para> | ||
| 924 | </entry><entry | ||
| 925 | align="char"> | ||
| 926 | <para>Maximum supported symbol rate reached.</para> | ||
| 927 | </entry> | ||
| 928 | </row></tbody></tgroup></informaltable> | ||
| 929 | </section> | ||
| 930 | |||
| 931 | <section id="frontend_get_fe"> | ||
| 932 | <title>FE_GET_FRONTEND</title> | ||
| 933 | <para>DESCRIPTION | ||
| 934 | </para> | ||
| 935 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 936 | align="char"> | ||
| 937 | <para>This ioctl call queries the currently effective frontend parameters. For this | ||
| 938 | command, read-only access to the device is sufficient.</para> | ||
| 939 | </entry> | ||
| 940 | </row></tbody></tgroup></informaltable> | ||
| 941 | |||
| 942 | <para>SYNOPSIS | ||
| 943 | </para> | ||
| 944 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 945 | align="char"> | ||
| 946 | <para>int ioctl(int fd, int request = FE_GET_FRONTEND, | ||
| 947 | struct dvb_frontend_parameters ⋆p);</para> | ||
| 948 | </entry> | ||
| 949 | </row></tbody></tgroup></informaltable> | ||
| 950 | |||
| 951 | <para>PARAMETERS | ||
| 952 | </para> | ||
| 953 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 954 | align="char"> | ||
| 955 | <para>int fd</para> | ||
| 956 | </entry><entry | ||
| 957 | align="char"> | ||
| 958 | <para>File descriptor returned by a previous call to open().</para> | ||
| 959 | </entry> | ||
| 960 | </row><row><entry | ||
| 961 | align="char"> | ||
| 962 | <para>int request</para> | ||
| 963 | </entry><entry | ||
| 964 | align="char"> | ||
| 965 | <para>Equals FE_SET_FRONTEND for this command.</para> | ||
| 966 | </entry> | ||
| 967 | </row><row><entry | ||
| 968 | align="char"> | ||
| 969 | <para>struct | ||
| 970 | dvb_frontend_parameters | ||
| 971 | *p</para> | ||
| 972 | </entry><entry | ||
| 973 | align="char"> | ||
| 974 | <para>Points to parameters for tuning operation.</para> | ||
| 975 | </entry> | ||
| 976 | </row></tbody></tgroup></informaltable> | ||
| 977 | |||
| 978 | <para>ERRORS | ||
| 979 | </para> | ||
| 980 | |||
| 981 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 982 | align="char"> | ||
| 983 | <para>EBADF</para> | ||
| 984 | </entry><entry | ||
| 985 | align="char"> | ||
| 986 | <para>fd is not a valid open file descriptor.</para> | ||
| 987 | </entry> | ||
| 988 | </row><row><entry | ||
| 989 | align="char"> | ||
| 990 | <para>EFAULT</para> | ||
| 991 | </entry><entry | ||
| 992 | align="char"> | ||
| 993 | <para>p points to invalid address.</para> | ||
| 994 | </entry> | ||
| 995 | </row><row><entry | ||
| 996 | align="char"> | ||
| 997 | <para>EINVAL</para> | ||
| 998 | </entry><entry | ||
| 999 | align="char"> | ||
| 1000 | <para>Maximum supported symbol rate reached.</para> | ||
| 1001 | </entry> | ||
| 1002 | </row></tbody></tgroup></informaltable> | ||
| 1003 | |||
| 1004 | </section> | ||
| 1005 | |||
| 1006 | <section id="frontend_get_event"> | ||
| 1007 | <title>FE_GET_EVENT</title> | ||
| 1008 | <para>DESCRIPTION | ||
| 1009 | </para> | ||
| 1010 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1011 | align="char"> | ||
| 1012 | <para>This ioctl call returns a frontend event if available. If an event is not | ||
| 1013 | available, the behavior depends on whether the device is in blocking or | ||
| 1014 | non-blocking mode. In the latter case, the call fails immediately with errno | ||
| 1015 | set to EWOULDBLOCK. In the former case, the call blocks until an event | ||
| 1016 | becomes available.</para> | ||
| 1017 | </entry> | ||
| 1018 | </row><row><entry | ||
| 1019 | align="char"> | ||
| 1020 | <para>The standard Linux poll() and/or select() system calls can be used with the | ||
| 1021 | device file descriptor to watch for new events. For select(), the file descriptor | ||
| 1022 | should be included in the exceptfds argument, and for poll(), POLLPRI should | ||
| 1023 | be specified as the wake-up condition. Since the event queue allocated is | ||
| 1024 | rather small (room for 8 events), the queue must be serviced regularly to avoid | ||
| 1025 | overflow. If an overflow happens, the oldest event is discarded from the queue, | ||
| 1026 | and an error (EOVERFLOW) occurs the next time the queue is read. After | ||
| 1027 | reporting the error condition in this fashion, subsequent FE_GET_EVENT | ||
| 1028 | calls will return events from the queue as usual.</para> | ||
| 1029 | </entry> | ||
| 1030 | </row><row><entry | ||
| 1031 | align="char"> | ||
| 1032 | <para>For the sake of implementation simplicity, this command requires read/write | ||
| 1033 | access to the device.</para> | ||
| 1034 | </entry> | ||
| 1035 | </row></tbody></tgroup></informaltable> | ||
| 1036 | |||
| 1037 | <para>SYNOPSIS | ||
| 1038 | </para> | ||
| 1039 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1040 | align="char"> | ||
| 1041 | <para>int ioctl(int fd, int request = QPSK_GET_EVENT, | ||
| 1042 | struct dvb_frontend_event ⋆ev);</para> | ||
| 1043 | </entry> | ||
| 1044 | </row></tbody></tgroup></informaltable> | ||
| 1045 | |||
| 1046 | <para>PARAMETERS | ||
| 1047 | </para> | ||
| 1048 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1049 | align="char"> | ||
| 1050 | <para>int fd</para> | ||
| 1051 | </entry><entry | ||
| 1052 | align="char"> | ||
| 1053 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1054 | </entry> | ||
| 1055 | </row><row><entry | ||
| 1056 | align="char"> | ||
| 1057 | <para>int request</para> | ||
| 1058 | </entry><entry | ||
| 1059 | align="char"> | ||
| 1060 | <para>Equals FE_GET_EVENT for this command.</para> | ||
| 1061 | </entry> | ||
| 1062 | </row><row><entry | ||
| 1063 | align="char"> | ||
| 1064 | <para>struct | ||
| 1065 | dvb_frontend_event | ||
| 1066 | *ev</para> | ||
| 1067 | </entry><entry | ||
| 1068 | align="char"> | ||
| 1069 | <para>Points to the location where the event,</para> | ||
| 1070 | </entry> | ||
| 1071 | </row><row><entry | ||
| 1072 | align="char"> | ||
| 1073 | </entry><entry | ||
| 1074 | align="char"> | ||
| 1075 | <para>if any, is to be stored.</para> | ||
| 1076 | </entry> | ||
| 1077 | </row></tbody></tgroup></informaltable> | ||
| 1078 | |||
| 1079 | <para>ERRORS | ||
| 1080 | </para> | ||
| 1081 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1082 | align="char"> | ||
| 1083 | <para>EBADF</para> | ||
| 1084 | </entry><entry | ||
| 1085 | align="char"> | ||
| 1086 | <para>fd is not a valid open file descriptor.</para> | ||
| 1087 | </entry> | ||
| 1088 | </row><row><entry | ||
| 1089 | align="char"> | ||
| 1090 | <para>EFAULT</para> | ||
| 1091 | </entry><entry | ||
| 1092 | align="char"> | ||
| 1093 | <para>ev points to invalid address.</para> | ||
| 1094 | </entry> | ||
| 1095 | </row><row><entry | ||
| 1096 | align="char"> | ||
| 1097 | <para>EWOULDBLOCK</para> | ||
| 1098 | </entry><entry | ||
| 1099 | align="char"> | ||
| 1100 | <para>There is no event pending, and the device is in | ||
| 1101 | non-blocking mode.</para> | ||
| 1102 | </entry> | ||
| 1103 | </row><row><entry | ||
| 1104 | align="char"> | ||
| 1105 | <para>EOVERFLOW</para> | ||
| 1106 | </entry><entry | ||
| 1107 | align="char"> | ||
| 1108 | </entry> | ||
| 1109 | </row><row><entry | ||
| 1110 | align="char"> | ||
| 1111 | </entry><entry | ||
| 1112 | align="char"> | ||
| 1113 | <para>Overflow in event queue - one or more events were lost.</para> | ||
| 1114 | </entry> | ||
| 1115 | </row></tbody></tgroup></informaltable> | ||
| 1116 | </section> | ||
| 1117 | |||
| 1118 | <section id="frontend_get_info"> | ||
| 1119 | <title>FE_GET_INFO</title> | ||
| 1120 | <para>DESCRIPTION | ||
| 1121 | </para> | ||
| 1122 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1123 | align="char"> | ||
| 1124 | <para>This ioctl call returns information about the front-end. This call only requires | ||
| 1125 | read-only access to the device.</para> | ||
| 1126 | </entry> | ||
| 1127 | </row></tbody></tgroup></informaltable> | ||
| 1128 | <para>SYNOPSIS | ||
| 1129 | </para> | ||
| 1130 | |||
| 1131 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para> int ioctl(int fd, int request = FE_GET_INFO, struct | ||
| 1134 | dvb_frontend_info ⋆info);</para> | ||
| 1135 | </entry> | ||
| 1136 | </row></tbody></tgroup></informaltable> | ||
| 1137 | <para>PARAMETERS | ||
| 1138 | </para> | ||
| 1139 | |||
| 1140 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1141 | align="char"> | ||
| 1142 | <para>int fd</para> | ||
| 1143 | </entry><entry | ||
| 1144 | align="char"> | ||
| 1145 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1146 | </entry> | ||
| 1147 | </row><row><entry | ||
| 1148 | align="char"> | ||
| 1149 | <para>int request</para> | ||
| 1150 | </entry><entry | ||
| 1151 | align="char"> | ||
| 1152 | <para>Equals FE_GET_INFO for this command.</para> | ||
| 1153 | </entry> | ||
| 1154 | </row><row><entry | ||
| 1155 | align="char"> | ||
| 1156 | <para>struct | ||
| 1157 | dvb_frontend_info | ||
| 1158 | *info</para> | ||
| 1159 | </entry><entry | ||
| 1160 | align="char"> | ||
| 1161 | <para>Points to the location where the front-end information is | ||
| 1162 | to be stored.</para> | ||
| 1163 | </entry> | ||
| 1164 | </row></tbody></tgroup></informaltable> | ||
| 1165 | <para>ERRORS | ||
| 1166 | </para> | ||
| 1167 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1168 | align="char"> | ||
| 1169 | <para>EBADF</para> | ||
| 1170 | </entry><entry | ||
| 1171 | align="char"> | ||
| 1172 | <para>fd is not a valid open file descriptor.</para> | ||
| 1173 | </entry> | ||
| 1174 | </row><row><entry | ||
| 1175 | align="char"> | ||
| 1176 | <para>EFAULT</para> | ||
| 1177 | </entry><entry | ||
| 1178 | align="char"> | ||
| 1179 | <para>info points to invalid address.</para> | ||
| 1180 | </entry> | ||
| 1181 | </row></tbody></tgroup></informaltable> | ||
| 1182 | </section> | ||
| 1183 | |||
| 1184 | <section id="frontend_diseqc_reset_overload"> | ||
| 1185 | <title>FE_DISEQC_RESET_OVERLOAD</title> | ||
| 1186 | <para>DESCRIPTION | ||
| 1187 | </para> | ||
| 1188 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1189 | align="char"> | ||
| 1190 | <para>If the bus has been automatically powered off due to power overload, this ioctl | ||
| 1191 | call restores the power to the bus. The call requires read/write access to the | ||
| 1192 | device. This call has no effect if the device is manually powered off. Not all | ||
| 1193 | DVB adapters support this ioctl.</para> | ||
| 1194 | </entry> | ||
| 1195 | </row></tbody></tgroup></informaltable> | ||
| 1196 | |||
| 1197 | <para>SYNOPSIS | ||
| 1198 | </para> | ||
| 1199 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1200 | align="char"> | ||
| 1201 | <para>int ioctl(int fd, int request = | ||
| 1202 | FE_DISEQC_RESET_OVERLOAD);</para> | ||
| 1203 | </entry> | ||
| 1204 | </row></tbody></tgroup></informaltable> | ||
| 1205 | <para>PARAMETERS | ||
| 1206 | </para> | ||
| 1207 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>int fd</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1213 | </entry> | ||
| 1214 | </row><row><entry | ||
| 1215 | align="char"> | ||
| 1216 | <para>int request</para> | ||
| 1217 | </entry><entry | ||
| 1218 | align="char"> | ||
| 1219 | <para>Equals FE_DISEQC_RESET_OVERLOAD for this | ||
| 1220 | command.</para> | ||
| 1221 | </entry> | ||
| 1222 | </row></tbody></tgroup></informaltable> | ||
| 1223 | |||
| 1224 | <para>ERRORS | ||
| 1225 | </para> | ||
| 1226 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1227 | align="char"> | ||
| 1228 | <para>EBADF</para> | ||
| 1229 | </entry><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>fd is not a valid file descriptor.</para> | ||
| 1232 | </entry> | ||
| 1233 | </row><row><entry | ||
| 1234 | align="char"> | ||
| 1235 | <para>EPERM</para> | ||
| 1236 | </entry><entry | ||
| 1237 | align="char"> | ||
| 1238 | <para>Permission denied (needs read/write access).</para> | ||
| 1239 | </entry> | ||
| 1240 | </row><row><entry | ||
| 1241 | align="char"> | ||
| 1242 | <para>EINTERNAL</para> | ||
| 1243 | </entry><entry | ||
| 1244 | align="char"> | ||
| 1245 | <para>Internal error in the device driver.</para> | ||
| 1246 | </entry> | ||
| 1247 | </row></tbody></tgroup></informaltable> | ||
| 1248 | </section> | ||
| 1249 | |||
| 1250 | <section id="frontend_diseqc_send_master_cmd"> | ||
| 1251 | <title>FE_DISEQC_SEND_MASTER_CMD</title> | ||
| 1252 | <para>DESCRIPTION | ||
| 1253 | </para> | ||
| 1254 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1255 | align="char"> | ||
| 1256 | <para>This ioctl call is used to send a a DiSEqC command.</para> | ||
| 1257 | </entry> | ||
| 1258 | </row></tbody></tgroup></informaltable> | ||
| 1259 | <para>SYNOPSIS | ||
| 1260 | </para> | ||
| 1261 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1262 | align="char"> | ||
| 1263 | <para>int ioctl(int fd, int request = | ||
| 1264 | FE_DISEQC_SEND_MASTER_CMD, struct | ||
| 1265 | dvb_diseqc_master_cmd ⋆cmd);</para> | ||
| 1266 | </entry> | ||
| 1267 | </row></tbody></tgroup></informaltable> | ||
| 1268 | |||
| 1269 | <para>PARAMETERS | ||
| 1270 | </para> | ||
| 1271 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1272 | align="char"> | ||
| 1273 | <para>int fd</para> | ||
| 1274 | </entry><entry | ||
| 1275 | align="char"> | ||
| 1276 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1277 | </entry> | ||
| 1278 | </row><row><entry | ||
| 1279 | align="char"> | ||
| 1280 | <para>int request</para> | ||
| 1281 | </entry><entry | ||
| 1282 | align="char"> | ||
| 1283 | <para>Equals FE_DISEQC_SEND_MASTER_CMD for this | ||
| 1284 | command.</para> | ||
| 1285 | </entry> | ||
| 1286 | </row><row><entry | ||
| 1287 | align="char"> | ||
| 1288 | <para>struct | ||
| 1289 | dvb_diseqc_master_cmd | ||
| 1290 | *cmd</para> | ||
| 1291 | </entry><entry | ||
| 1292 | align="char"> | ||
| 1293 | <para>Pointer to the command to be transmitted.</para> | ||
| 1294 | </entry> | ||
| 1295 | </row></tbody></tgroup></informaltable> | ||
| 1296 | |||
| 1297 | <para>ERRORS | ||
| 1298 | </para> | ||
| 1299 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1300 | align="char"> | ||
| 1301 | <para>EBADF</para> | ||
| 1302 | </entry><entry | ||
| 1303 | align="char"> | ||
| 1304 | <para>fd is not a valid file descriptor.</para> | ||
| 1305 | </entry> | ||
| 1306 | </row><row><entry | ||
| 1307 | align="char"> | ||
| 1308 | <para>EFAULT</para> | ||
| 1309 | </entry><entry | ||
| 1310 | align="char"> | ||
| 1311 | <para>Seq points to an invalid address.</para> | ||
| 1312 | </entry> | ||
| 1313 | </row><row><entry | ||
| 1314 | align="char"> | ||
| 1315 | <para>EINVAL</para> | ||
| 1316 | </entry><entry | ||
| 1317 | align="char"> | ||
| 1318 | <para>The data structure referred to by seq is invalid in some | ||
| 1319 | way.</para> | ||
| 1320 | </entry> | ||
| 1321 | </row><row><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>EPERM</para> | ||
| 1324 | </entry><entry | ||
| 1325 | align="char"> | ||
| 1326 | <para>Permission denied (needs read/write access).</para> | ||
| 1327 | </entry> | ||
| 1328 | </row><row><entry | ||
| 1329 | align="char"> | ||
| 1330 | <para>EINTERNAL</para> | ||
| 1331 | </entry><entry | ||
| 1332 | align="char"> | ||
| 1333 | <para>Internal error in the device driver.</para> | ||
| 1334 | </entry> | ||
| 1335 | </row></tbody></tgroup></informaltable> | ||
| 1336 | </section> | ||
| 1337 | |||
| 1338 | <section id="frontend_diseqc_recv_slave_reply"> | ||
| 1339 | <title>FE_DISEQC_RECV_SLAVE_REPLY</title> | ||
| 1340 | <para>DESCRIPTION | ||
| 1341 | </para> | ||
| 1342 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1343 | align="char"> | ||
| 1344 | <para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para> | ||
| 1345 | </entry> | ||
| 1346 | </row></tbody></tgroup></informaltable> | ||
| 1347 | |||
| 1348 | <para>SYNOPSIS | ||
| 1349 | </para> | ||
| 1350 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1351 | align="char"> | ||
| 1352 | <para>int ioctl(int fd, int request = | ||
| 1353 | FE_DISEQC_RECV_SLAVE_REPLY, struct | ||
| 1354 | dvb_diseqc_slave_reply ⋆reply);</para> | ||
| 1355 | </entry> | ||
| 1356 | </row></tbody></tgroup></informaltable> | ||
| 1357 | |||
| 1358 | <para>PARAMETERS | ||
| 1359 | </para> | ||
| 1360 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1361 | align="char"> | ||
| 1362 | <para>int fd</para> | ||
| 1363 | </entry><entry | ||
| 1364 | align="char"> | ||
| 1365 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1366 | </entry> | ||
| 1367 | </row><row><entry | ||
| 1368 | align="char"> | ||
| 1369 | <para>int request</para> | ||
| 1370 | </entry><entry | ||
| 1371 | align="char"> | ||
| 1372 | <para>Equals FE_DISEQC_RECV_SLAVE_REPLY for this | ||
| 1373 | command.</para> | ||
| 1374 | </entry> | ||
| 1375 | </row><row><entry | ||
| 1376 | align="char"> | ||
| 1377 | <para>struct | ||
| 1378 | dvb_diseqc_slave_reply | ||
| 1379 | *reply</para> | ||
| 1380 | </entry><entry | ||
| 1381 | align="char"> | ||
| 1382 | <para>Pointer to the command to be received.</para> | ||
| 1383 | </entry> | ||
| 1384 | </row></tbody></tgroup></informaltable> | ||
| 1385 | <para>ERRORS | ||
| 1386 | </para> | ||
| 1387 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1388 | align="char"> | ||
| 1389 | <para>EBADF</para> | ||
| 1390 | </entry><entry | ||
| 1391 | align="char"> | ||
| 1392 | <para>fd is not a valid file descriptor.</para> | ||
| 1393 | </entry> | ||
| 1394 | </row><row><entry | ||
| 1395 | align="char"> | ||
| 1396 | <para>EFAULT</para> | ||
| 1397 | </entry><entry | ||
| 1398 | align="char"> | ||
| 1399 | <para>Seq points to an invalid address.</para> | ||
| 1400 | </entry> | ||
| 1401 | </row><row><entry | ||
| 1402 | align="char"> | ||
| 1403 | <para>EINVAL</para> | ||
| 1404 | </entry><entry | ||
| 1405 | align="char"> | ||
| 1406 | <para>The data structure referred to by seq is invalid in some | ||
| 1407 | way.</para> | ||
| 1408 | </entry> | ||
| 1409 | </row><row><entry | ||
| 1410 | align="char"> | ||
| 1411 | <para>EPERM</para> | ||
| 1412 | </entry><entry | ||
| 1413 | align="char"> | ||
| 1414 | <para>Permission denied (needs read/write access).</para> | ||
| 1415 | </entry> | ||
| 1416 | </row><row><entry | ||
| 1417 | align="char"> | ||
| 1418 | <para>EINTERNAL</para> | ||
| 1419 | </entry><entry | ||
| 1420 | align="char"> | ||
| 1421 | <para>Internal error in the device driver.</para> | ||
| 1422 | </entry> | ||
| 1423 | </row></tbody></tgroup></informaltable> | ||
| 1424 | </section> | ||
| 1425 | |||
| 1426 | <section id="frontend_diseqc_send_burst"> | ||
| 1427 | <title>FE_DISEQC_SEND_BURST</title> | ||
| 1428 | <para>DESCRIPTION | ||
| 1429 | </para> | ||
| 1430 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1431 | align="char"> | ||
| 1432 | <para>This ioctl call is used to send a 22KHz tone burst.</para> | ||
| 1433 | </entry> | ||
| 1434 | </row></tbody></tgroup></informaltable> | ||
| 1435 | |||
| 1436 | <para>SYNOPSIS | ||
| 1437 | </para> | ||
| 1438 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1439 | align="char"> | ||
| 1440 | <para>int ioctl(int fd, int request = | ||
| 1441 | FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst);</para> | ||
| 1442 | </entry> | ||
| 1443 | </row></tbody></tgroup></informaltable> | ||
| 1444 | |||
| 1445 | <para>PARAMETERS | ||
| 1446 | </para> | ||
| 1447 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1448 | align="char"> | ||
| 1449 | <para>int fd</para> | ||
| 1450 | </entry><entry | ||
| 1451 | align="char"> | ||
| 1452 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1453 | </entry> | ||
| 1454 | </row><row><entry | ||
| 1455 | align="char"> | ||
| 1456 | <para>int request</para> | ||
| 1457 | </entry><entry | ||
| 1458 | align="char"> | ||
| 1459 | <para>Equals FE_DISEQC_SEND_BURST for this command.</para> | ||
| 1460 | </entry> | ||
| 1461 | </row><row><entry | ||
| 1462 | align="char"> | ||
| 1463 | <para>fe_sec_mini_cmd_t | ||
| 1464 | burst</para> | ||
| 1465 | </entry><entry | ||
| 1466 | align="char"> | ||
| 1467 | <para>burst A or B.</para> | ||
| 1468 | </entry> | ||
| 1469 | </row></tbody></tgroup></informaltable> | ||
| 1470 | |||
| 1471 | <para>ERRORS | ||
| 1472 | </para> | ||
| 1473 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1474 | align="char"> | ||
| 1475 | <para>EBADF</para> | ||
| 1476 | </entry><entry | ||
| 1477 | align="char"> | ||
| 1478 | <para>fd is not a valid file descriptor.</para> | ||
| 1479 | </entry> | ||
| 1480 | </row><row><entry | ||
| 1481 | align="char"> | ||
| 1482 | <para>EFAULT</para> | ||
| 1483 | </entry><entry | ||
| 1484 | align="char"> | ||
| 1485 | <para>Seq points to an invalid address.</para> | ||
| 1486 | </entry> | ||
| 1487 | </row><row><entry | ||
| 1488 | align="char"> | ||
| 1489 | <para>EINVAL</para> | ||
| 1490 | </entry><entry | ||
| 1491 | align="char"> | ||
| 1492 | <para>The data structure referred to by seq is invalid in some | ||
| 1493 | way.</para> | ||
| 1494 | </entry> | ||
| 1495 | </row><row><entry | ||
| 1496 | align="char"> | ||
| 1497 | <para>EPERM</para> | ||
| 1498 | </entry><entry | ||
| 1499 | align="char"> | ||
| 1500 | <para>Permission denied (needs read/write access).</para> | ||
| 1501 | </entry> | ||
| 1502 | </row><row><entry | ||
| 1503 | align="char"> | ||
| 1504 | <para>EINTERNAL</para> | ||
| 1505 | </entry><entry | ||
| 1506 | align="char"> | ||
| 1507 | <para>Internal error in the device driver.</para> | ||
| 1508 | </entry> | ||
| 1509 | </row></tbody></tgroup></informaltable> | ||
| 1510 | </section> | ||
| 1511 | |||
| 1512 | <section id="frontend_set_tone"> | ||
| 1513 | <title>FE_SET_TONE</title> | ||
| 1514 | <para>DESCRIPTION | ||
| 1515 | </para> | ||
| 1516 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1517 | align="char"> | ||
| 1518 | <para>This call is used to set the generation of the continuous 22kHz tone. This call | ||
| 1519 | requires read/write permissions.</para> | ||
| 1520 | </entry> | ||
| 1521 | </row></tbody></tgroup></informaltable> | ||
| 1522 | <para>SYNOPSIS | ||
| 1523 | </para> | ||
| 1524 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1525 | align="char"> | ||
| 1526 | <para>int ioctl(int fd, int request = FE_SET_TONE, | ||
| 1527 | fe_sec_tone_mode_t tone);</para> | ||
| 1528 | </entry> | ||
| 1529 | </row></tbody></tgroup></informaltable> | ||
| 1530 | <para>PARAMETERS | ||
| 1531 | </para> | ||
| 1532 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1533 | align="char"> | ||
| 1534 | <para>int fd</para> | ||
| 1535 | </entry><entry | ||
| 1536 | align="char"> | ||
| 1537 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1538 | </entry> | ||
| 1539 | </row><row><entry | ||
| 1540 | align="char"> | ||
| 1541 | <para>int request</para> | ||
| 1542 | </entry><entry | ||
| 1543 | align="char"> | ||
| 1544 | <para>Equals FE_SET_TONE for this command.</para> | ||
| 1545 | </entry> | ||
| 1546 | </row><row><entry | ||
| 1547 | align="char"> | ||
| 1548 | <para>fe_sec_tone_mode_t | ||
| 1549 | tone</para> | ||
| 1550 | </entry><entry | ||
| 1551 | align="char"> | ||
| 1552 | <para>The requested tone generation mode (on/off).</para> | ||
| 1553 | </entry> | ||
| 1554 | </row></tbody></tgroup></informaltable> | ||
| 1555 | <para>ERRORS | ||
| 1556 | </para> | ||
| 1557 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1558 | align="char"> | ||
| 1559 | <para>ENODEV</para> | ||
| 1560 | </entry><entry | ||
| 1561 | align="char"> | ||
| 1562 | <para>Device driver not loaded/available.</para> | ||
| 1563 | </entry> | ||
| 1564 | </row><row><entry | ||
| 1565 | align="char"> | ||
| 1566 | <para>EBUSY</para> | ||
| 1567 | </entry><entry | ||
| 1568 | align="char"> | ||
| 1569 | <para>Device or resource busy.</para> | ||
| 1570 | </entry> | ||
| 1571 | </row><row><entry | ||
| 1572 | align="char"> | ||
| 1573 | <para>EINVAL</para> | ||
| 1574 | </entry><entry | ||
| 1575 | align="char"> | ||
| 1576 | <para>Invalid argument.</para> | ||
| 1577 | </entry> | ||
| 1578 | </row><row><entry | ||
| 1579 | align="char"> | ||
| 1580 | <para>EPERM</para> | ||
| 1581 | </entry><entry | ||
| 1582 | align="char"> | ||
| 1583 | <para>File not opened with read permissions.</para> | ||
| 1584 | </entry> | ||
| 1585 | </row><row><entry | ||
| 1586 | align="char"> | ||
| 1587 | <para>EINTERNAL</para> | ||
| 1588 | </entry><entry | ||
| 1589 | align="char"> | ||
| 1590 | <para>Internal error in the device driver.</para> | ||
| 1591 | </entry> | ||
| 1592 | </row></tbody></tgroup></informaltable> | ||
| 1593 | </section> | ||
| 1594 | |||
| 1595 | <section id="fe_set_voltage"> | ||
| 1596 | <title>FE_SET_VOLTAGE</title> | ||
| 1597 | <para>DESCRIPTION | ||
| 1598 | </para> | ||
| 1599 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1600 | align="char"> | ||
| 1601 | <para>This call is used to set the bus voltage. This call requires read/write | ||
| 1602 | permissions.</para> | ||
| 1603 | </entry> | ||
| 1604 | </row></tbody></tgroup></informaltable> | ||
| 1605 | <para>SYNOPSIS | ||
| 1606 | </para> | ||
| 1607 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1608 | align="char"> | ||
| 1609 | <para>int ioctl(int fd, int request = FE_SET_VOLTAGE, | ||
| 1610 | fe_sec_voltage_t voltage);</para> | ||
| 1611 | </entry> | ||
| 1612 | </row></tbody></tgroup></informaltable> | ||
| 1613 | |||
| 1614 | <para>PARAMETERS | ||
| 1615 | </para> | ||
| 1616 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1617 | align="char"> | ||
| 1618 | <para>int fd</para> | ||
| 1619 | </entry><entry | ||
| 1620 | align="char"> | ||
| 1621 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1622 | </entry> | ||
| 1623 | </row><row><entry | ||
| 1624 | align="char"> | ||
| 1625 | <para>int request</para> | ||
| 1626 | </entry><entry | ||
| 1627 | align="char"> | ||
| 1628 | <para>Equals FE_SET_VOLTAGE for this command.</para> | ||
| 1629 | </entry> | ||
| 1630 | </row><row><entry | ||
| 1631 | align="char"> | ||
| 1632 | <para>fe_sec_voltage_t | ||
| 1633 | voltage</para> | ||
| 1634 | </entry><entry | ||
| 1635 | align="char"> | ||
| 1636 | <para>The requested bus voltage.</para> | ||
| 1637 | </entry> | ||
| 1638 | </row></tbody></tgroup></informaltable> | ||
| 1639 | |||
| 1640 | <para>ERRORS | ||
| 1641 | </para> | ||
| 1642 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1643 | align="char"> | ||
| 1644 | <para>ENODEV</para> | ||
| 1645 | </entry><entry | ||
| 1646 | align="char"> | ||
| 1647 | <para>Device driver not loaded/available.</para> | ||
| 1648 | </entry> | ||
| 1649 | </row><row><entry | ||
| 1650 | align="char"> | ||
| 1651 | <para>EBUSY</para> | ||
| 1652 | </entry><entry | ||
| 1653 | align="char"> | ||
| 1654 | <para>Device or resource busy.</para> | ||
| 1655 | </entry> | ||
| 1656 | </row><row><entry | ||
| 1657 | align="char"> | ||
| 1658 | <para>EINVAL</para> | ||
| 1659 | </entry><entry | ||
| 1660 | align="char"> | ||
| 1661 | <para>Invalid argument.</para> | ||
| 1662 | </entry> | ||
| 1663 | </row><row><entry | ||
| 1664 | align="char"> | ||
| 1665 | <para>EPERM</para> | ||
| 1666 | </entry><entry | ||
| 1667 | align="char"> | ||
| 1668 | <para>File not opened with read permissions.</para> | ||
| 1669 | </entry> | ||
| 1670 | </row><row><entry | ||
| 1671 | align="char"> | ||
| 1672 | <para>EINTERNAL</para> | ||
| 1673 | </entry><entry | ||
| 1674 | align="char"> | ||
| 1675 | <para>Internal error in the device driver.</para> | ||
| 1676 | </entry> | ||
| 1677 | </row></tbody></tgroup></informaltable> | ||
| 1678 | </section> | ||
| 1679 | |||
| 1680 | <section id="frontend_enable_high_lnb_volt"> | ||
| 1681 | <title>FE_ENABLE_HIGH_LNB_VOLTAGE</title> | ||
| 1682 | <para>DESCRIPTION | ||
| 1683 | </para> | ||
| 1684 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1685 | align="char"> | ||
| 1686 | <para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate | ||
| 1687 | for long cables). This call requires read/write permissions. Not all DVB | ||
| 1688 | adapters support this ioctl.</para> | ||
| 1689 | </entry> | ||
| 1690 | </row></tbody></tgroup></informaltable> | ||
| 1691 | |||
| 1692 | <para>SYNOPSIS | ||
| 1693 | </para> | ||
| 1694 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1695 | align="char"> | ||
| 1696 | <para>int ioctl(int fd, int request = | ||
| 1697 | FE_ENABLE_HIGH_LNB_VOLTAGE, int high);</para> | ||
| 1698 | </entry> | ||
| 1699 | </row></tbody></tgroup></informaltable> | ||
| 1700 | |||
| 1701 | <para>PARAMETERS | ||
| 1702 | </para> | ||
| 1703 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1704 | align="char"> | ||
| 1705 | <para>int fd</para> | ||
| 1706 | </entry><entry | ||
| 1707 | align="char"> | ||
| 1708 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1709 | </entry> | ||
| 1710 | </row><row><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>int request</para> | ||
| 1713 | </entry><entry | ||
| 1714 | align="char"> | ||
| 1715 | <para>Equals FE_SET_VOLTAGE for this command.</para> | ||
| 1716 | </entry> | ||
| 1717 | </row><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>int high</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>The requested bus voltage.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row></tbody></tgroup></informaltable> | ||
| 1725 | |||
| 1726 | <para>ERRORS | ||
| 1727 | </para> | ||
| 1728 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1729 | align="char"> | ||
| 1730 | <para>ENODEV</para> | ||
| 1731 | </entry><entry | ||
| 1732 | align="char"> | ||
| 1733 | <para>Device driver not loaded/available.</para> | ||
| 1734 | </entry> | ||
| 1735 | </row><row><entry | ||
| 1736 | align="char"> | ||
| 1737 | <para>EBUSY</para> | ||
| 1738 | </entry><entry | ||
| 1739 | align="char"> | ||
| 1740 | <para>Device or resource busy.</para> | ||
| 1741 | </entry> | ||
| 1742 | </row><row><entry | ||
| 1743 | align="char"> | ||
| 1744 | <para>EINVAL</para> | ||
| 1745 | </entry><entry | ||
| 1746 | align="char"> | ||
| 1747 | <para>Invalid argument.</para> | ||
| 1748 | </entry> | ||
| 1749 | </row><row><entry | ||
| 1750 | align="char"> | ||
| 1751 | <para>EPERM</para> | ||
| 1752 | </entry><entry | ||
| 1753 | align="char"> | ||
| 1754 | <para>File not opened with read permissions.</para> | ||
| 1755 | </entry> | ||
| 1756 | </row><row><entry | ||
| 1757 | align="char"> | ||
| 1758 | <para>EINTERNAL</para> | ||
| 1759 | </entry><entry | ||
| 1760 | align="char"> | ||
| 1761 | <para>Internal error in the device driver.</para> | ||
| 1762 | </entry> | ||
| 1763 | </row></tbody></tgroup></informaltable> | ||
| 1764 | </section> | ||
| 1765 | </section> | ||
| 1766 | &sub-isdbt; | ||
diff --git a/Documentation/DocBook/dvb/intro.xml b/Documentation/DocBook/dvb/intro.xml new file mode 100644 index 000000000000..0dc83f672ea2 --- /dev/null +++ b/Documentation/DocBook/dvb/intro.xml | |||
| @@ -0,0 +1,191 @@ | |||
| 1 | <title>Introduction</title> | ||
| 2 | |||
| 3 | <section id="requisites"> | ||
| 4 | <title>What you need to know</title> | ||
| 5 | |||
| 6 | <para>The reader of this document is required to have some knowledge in | ||
| 7 | the area of digital video broadcasting (DVB) and should be familiar with | ||
| 8 | part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e | ||
| 9 | you should know what a program/transport stream (PS/TS) is and what is | ||
| 10 | meant by a packetized elementary stream (PES) or an I-frame.</para> | ||
| 11 | |||
| 12 | <para>Various DVB standards documents are available from | ||
| 13 | <ulink url="http://www.dvb.org" /> and/or | ||
| 14 | <ulink url="http://www.etsi.org" />.</para> | ||
| 15 | |||
| 16 | <para>It is also necessary to know how to access unix/linux devices and | ||
| 17 | how to use ioctl calls. This also includes the knowledge of C or C++. | ||
| 18 | </para> | ||
| 19 | </section> | ||
| 20 | |||
| 21 | <section id="history"> | ||
| 22 | <title>History</title> | ||
| 23 | |||
| 24 | <para>The first API for DVB cards we used at Convergence in late 1999 | ||
| 25 | was an extension of the Video4Linux API which was primarily developed | ||
| 26 | for frame grabber cards. As such it was not really well suited to be | ||
| 27 | used for DVB cards and their new features like recording MPEG streams | ||
| 28 | and filtering several section and PES data streams at the same time. | ||
| 29 | </para> | ||
| 30 | |||
| 31 | <para>In early 2000, we were approached by Nokia with a proposal for a | ||
| 32 | new standard Linux DVB API. As a commitment to the development of | ||
| 33 | terminals based on open standards, Nokia and Convergence made it | ||
| 34 | available to all Linux developers and published it on | ||
| 35 | <ulink url="http://www.linuxtv.org/" /> in September 2000. | ||
| 36 | Convergence is the maintainer of the Linux DVB API. Together with the | ||
| 37 | LinuxTV community (i.e. you, the reader of this document), the Linux DVB | ||
| 38 | API will be constantly reviewed and improved. With the Linux driver for | ||
| 39 | the Siemens/Hauppauge DVB PCI card Convergence provides a first | ||
| 40 | implementation of the Linux DVB API.</para> | ||
| 41 | </section> | ||
| 42 | |||
| 43 | <section id="overview"> | ||
| 44 | <title>Overview</title> | ||
| 45 | |||
| 46 | <figure id="stb_components"> | ||
| 47 | <title>Components of a DVB card/STB</title> | ||
| 48 | <mediaobject> | ||
| 49 | <imageobject> | ||
| 50 | <imagedata fileref="dvbstb.pdf" format="PS" /> | ||
| 51 | </imageobject> | ||
| 52 | <imageobject> | ||
| 53 | <imagedata fileref="dvbstb.png" format="PNG" /> | ||
| 54 | </imageobject> | ||
| 55 | </mediaobject> | ||
| 56 | </figure> | ||
| 57 | |||
| 58 | <para>A DVB PCI card or DVB set-top-box (STB) usually consists of the | ||
| 59 | following main hardware components: </para> | ||
| 60 | |||
| 61 | <itemizedlist> | ||
| 62 | <listitem> | ||
| 63 | |||
| 64 | <para>Frontend consisting of tuner and DVB demodulator</para> | ||
| 65 | |||
| 66 | <para>Here the raw signal reaches the DVB hardware from a satellite dish | ||
| 67 | or antenna or directly from cable. The frontend down-converts and | ||
| 68 | demodulates this signal into an MPEG transport stream (TS). In case of a | ||
| 69 | satellite frontend, this includes a facility for satellite equipment | ||
| 70 | control (SEC), which allows control of LNB polarization, multi feed | ||
| 71 | switches or dish rotors.</para> | ||
| 72 | |||
| 73 | </listitem> | ||
| 74 | <listitem> | ||
| 75 | |||
| 76 | <para>Conditional Access (CA) hardware like CI adapters and smartcard slots | ||
| 77 | </para> | ||
| 78 | |||
| 79 | <para>The complete TS is passed through the CA hardware. Programs to | ||
| 80 | which the user has access (controlled by the smart card) are decoded in | ||
| 81 | real time and re-inserted into the TS.</para> | ||
| 82 | |||
| 83 | </listitem> | ||
| 84 | <listitem> | ||
| 85 | <para>Demultiplexer which filters the incoming DVB stream</para> | ||
| 86 | |||
| 87 | <para>The demultiplexer splits the TS into its components like audio and | ||
| 88 | video streams. Besides usually several of such audio and video streams | ||
| 89 | it also contains data streams with information about the programs | ||
| 90 | offered in this or other streams of the same provider.</para> | ||
| 91 | |||
| 92 | </listitem> | ||
| 93 | <listitem> | ||
| 94 | |||
| 95 | <para>MPEG2 audio and video decoder</para> | ||
| 96 | |||
| 97 | <para>The main targets of the demultiplexer are the MPEG2 audio and | ||
| 98 | video decoders. After decoding they pass on the uncompressed audio and | ||
| 99 | video to the computer screen or (through a PAL/NTSC encoder) to a TV | ||
| 100 | set.</para> | ||
| 101 | |||
| 102 | |||
| 103 | </listitem> | ||
| 104 | </itemizedlist> | ||
| 105 | |||
| 106 | <para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow | ||
| 107 | between those components.</para> | ||
| 108 | |||
| 109 | <para>On a DVB PCI card not all of these have to be present since some | ||
| 110 | functionality can be provided by the main CPU of the PC (e.g. MPEG | ||
| 111 | picture and sound decoding) or is not needed (e.g. for data-only uses | ||
| 112 | like “internet over satellite”). Also not every card or STB | ||
| 113 | provides conditional access hardware.</para> | ||
| 114 | |||
| 115 | </section> | ||
| 116 | |||
| 117 | <section id="dvb_devices"> | ||
| 118 | <title>Linux DVB Devices</title> | ||
| 119 | |||
| 120 | <para>The Linux DVB API lets you control these hardware components | ||
| 121 | through currently six Unix-style character devices for video, audio, | ||
| 122 | frontend, demux, CA and IP-over-DVB networking. The video and audio | ||
| 123 | devices control the MPEG2 decoder hardware, the frontend device the | ||
| 124 | tuner and the DVB demodulator. The demux device gives you control over | ||
| 125 | the PES and section filters of the hardware. If the hardware does not | ||
| 126 | support filtering these filters can be implemented in software. Finally, | ||
| 127 | the CA device controls all the conditional access capabilities of the | ||
| 128 | hardware. It can depend on the individual security requirements of the | ||
| 129 | platform, if and how many of the CA functions are made available to the | ||
| 130 | application through this device.</para> | ||
| 131 | |||
| 132 | <para>All devices can be found in the <emphasis role="tt">/dev</emphasis> | ||
| 133 | tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices | ||
| 134 | are called:</para> | ||
| 135 | |||
| 136 | <itemizedlist> | ||
| 137 | <listitem> | ||
| 138 | |||
| 139 | <para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para> | ||
| 140 | </listitem> | ||
| 141 | <listitem> | ||
| 142 | <para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para> | ||
| 143 | </listitem> | ||
| 144 | <listitem> | ||
| 145 | <para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para> | ||
| 146 | </listitem> | ||
| 147 | <listitem> | ||
| 148 | |||
| 149 | <para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para> | ||
| 150 | </listitem> | ||
| 151 | <listitem> | ||
| 152 | |||
| 153 | <para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para> | ||
| 154 | </listitem> | ||
| 155 | <listitem> | ||
| 156 | |||
| 157 | <para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> | ||
| 158 | |||
| 159 | <para>where N enumerates the DVB PCI cards in a system starting | ||
| 160 | from 0, and M enumerates the devices of each type within each | ||
| 161 | adapter, starting from 0, too. We will omit the “<emphasis | ||
| 162 | role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion | ||
| 163 | of these devices. The naming scheme for the devices is the same wheter | ||
| 164 | devfs is used or not.</para> | ||
| 165 | |||
| 166 | <para>More details about the data structures and function calls of all | ||
| 167 | the devices are described in the following chapters.</para> | ||
| 168 | |||
| 169 | </section> | ||
| 170 | |||
| 171 | <section id="include_files"> | ||
| 172 | <title>API include files</title> | ||
| 173 | |||
| 174 | <para>For each of the DVB devices a corresponding include file exists. | ||
| 175 | The DVB API include files should be included in application sources with | ||
| 176 | a partial path like:</para> | ||
| 177 | |||
| 178 | |||
| 179 | <programlisting> | ||
| 180 | #include <linux/dvb/frontend.h> | ||
| 181 | </programlisting> | ||
| 182 | |||
| 183 | <para>To enable applications to support different API version, an | ||
| 184 | additional include file <emphasis | ||
| 185 | role="tt">linux/dvb/version.h</emphasis> exists, which defines the | ||
| 186 | constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document | ||
| 187 | describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. | ||
| 188 | </para> | ||
| 189 | |||
| 190 | </section> | ||
| 191 | |||
diff --git a/Documentation/DocBook/dvb/isdbt.xml b/Documentation/DocBook/dvb/isdbt.xml new file mode 100644 index 000000000000..92855222fccb --- /dev/null +++ b/Documentation/DocBook/dvb/isdbt.xml | |||
| @@ -0,0 +1,314 @@ | |||
| 1 | <section id="isdbt"> | ||
| 2 | <title>ISDB-T frontend</title> | ||
| 3 | <para>This section describes shortly what are the possible parameters in the Linux | ||
| 4 | DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb | ||
| 5 | demodulator:</para> | ||
| 6 | |||
| 7 | <para>This ISDB-T/ISDB-Tsb API extension should reflect all information | ||
| 8 | needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible | ||
| 9 | that some very sophisticated devices won't need certain parameters to | ||
| 10 | tune.</para> | ||
| 11 | |||
| 12 | <para>The information given here should help application writers to know how | ||
| 13 | to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> | ||
| 14 | |||
| 15 | <para>The details given here about ISDB-T and ISDB-Tsb are just enough to | ||
| 16 | basically show the dependencies between the needed parameter values, | ||
| 17 | but surely some information is left out. For more detailed information | ||
| 18 | see the following documents:</para> | ||
| 19 | |||
| 20 | <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial | ||
| 21 | Television Broadcasting" and</para> | ||
| 22 | <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial | ||
| 23 | Television Broadcasting".</para> | ||
| 24 | |||
| 25 | <para>In order to read this document one has to have some knowledge the | ||
| 26 | channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to | ||
| 27 | the reader that an ISDB-T channel consists of 13 segments, that it can | ||
| 28 | have up to 3 layer sharing those segments, and things like that.</para> | ||
| 29 | |||
| 30 | <para>Parameters used by ISDB-T and ISDB-Tsb.</para> | ||
| 31 | |||
| 32 | <section id="isdbt-parms"> | ||
| 33 | <title>Parameters that are common with DVB-T and ATSC</title> | ||
| 34 | |||
| 35 | <section id="isdbt-freq"> | ||
| 36 | <title><constant>DTV_FREQUENCY</constant></title> | ||
| 37 | |||
| 38 | <para>Central frequency of the channel.</para> | ||
| 39 | |||
| 40 | <para>For ISDB-T the channels are usally transmitted with an offset of 143kHz. E.g. a | ||
| 41 | valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of | ||
| 42 | the channel which is 6MHz.</para> | ||
| 43 | |||
| 44 | <para>As in ISDB-Tsb the channel consists of only one or three segments the | ||
| 45 | frequency step is 429kHz, 3*429 respectively. As for ISDB-T the | ||
| 46 | central frequency of the channel is expected.</para> | ||
| 47 | </section> | ||
| 48 | |||
| 49 | <section id="isdbt-bw"> | ||
| 50 | <title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title> | ||
| 51 | |||
| 52 | <para>Possible values:</para> | ||
| 53 | |||
| 54 | <para>For ISDB-T it should be always 6000000Hz (6MHz)</para> | ||
| 55 | <para>For ISDB-Tsb it can vary depending on the number of connected segments</para> | ||
| 56 | |||
| 57 | <para>Note: Hardware specific values might be given here, but standard | ||
| 58 | applications should not bother to set a value to this field as | ||
| 59 | standard demods are ignoring it anyway.</para> | ||
| 60 | |||
| 61 | <para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from | ||
| 62 | other parameters (DTV_ISDBT_SB_SEGMENT_IDX, | ||
| 63 | DTV_ISDBT_SB_SEGMENT_COUNT).</para> | ||
| 64 | </section> | ||
| 65 | |||
| 66 | <section id="isdbt-delivery-sys"> | ||
| 67 | <title><constant>DTV_DELIVERY_SYSTEM</constant></title> | ||
| 68 | |||
| 69 | <para>Possible values: <constant>SYS_ISDBT</constant></para> | ||
| 70 | </section> | ||
| 71 | |||
| 72 | <section id="isdbt-tx-mode"> | ||
| 73 | <title><constant>DTV_TRANSMISSION_MODE</constant></title> | ||
| 74 | |||
| 75 | <para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called | ||
| 76 | 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> | ||
| 77 | |||
| 78 | <para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>, | ||
| 79 | <constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para> | ||
| 80 | |||
| 81 | <para>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the | ||
| 82 | hardware will try to find the correct FFT-size (if capable) and will | ||
| 83 | use TMCC to fill in the missing parameters.</para> | ||
| 84 | |||
| 85 | <para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para> | ||
| 86 | </section> | ||
| 87 | |||
| 88 | <section id="isdbt-guard-interval"> | ||
| 89 | <title><constant>DTV_GUARD_INTERVAL</constant></title> | ||
| 90 | |||
| 91 | <para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>, | ||
| 92 | <constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para> | ||
| 93 | |||
| 94 | <para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will | ||
| 95 | try to find the correct guard interval (if capable) and will use TMCC to fill | ||
| 96 | in the missing parameters.</para> | ||
| 97 | </section> | ||
| 98 | </section> | ||
| 99 | <section id="isdbt-new-parms"> | ||
| 100 | <title>ISDB-T only parameters</title> | ||
| 101 | |||
| 102 | <section id="isdbt-part-rec"> | ||
| 103 | <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> | ||
| 104 | |||
| 105 | <para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether | ||
| 106 | the channel is in partial reception mode or not.</para> | ||
| 107 | |||
| 108 | <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and | ||
| 109 | <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para> | ||
| 110 | |||
| 111 | <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1' | ||
| 112 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel | ||
| 113 | is consisting of one segment and layer or three segments and two layers.</para> | ||
| 114 | |||
| 115 | <para>Possible values: 0, 1, -1 (AUTO)</para> | ||
| 116 | </section> | ||
| 117 | |||
| 118 | <section id="isdbt-sound-bcast"> | ||
| 119 | <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title> | ||
| 120 | |||
| 121 | <para>This field represents whether the other DTV_ISDBT_*-parameters are | ||
| 122 | referring to an ISDB-T and an ISDB-Tsb channel. (See also | ||
| 123 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para> | ||
| 124 | |||
| 125 | <para>Possible values: 0, 1, -1 (AUTO)</para> | ||
| 126 | </section> | ||
| 127 | |||
| 128 | <section id="isdbt-sb-ch-id"> | ||
| 129 | <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title> | ||
| 130 | |||
| 131 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 132 | |||
| 133 | <para>(Note of the author: This might not be the correct description of the | ||
| 134 | <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical | ||
| 135 | background needed to program a device)</para> | ||
| 136 | |||
| 137 | <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a | ||
| 138 | set of connected ISDB-Tsb channels. In this set of channels every | ||
| 139 | channel can be received independently. The number of connected | ||
| 140 | ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum | ||
| 141 | bandwidth available.</para> | ||
| 142 | |||
| 143 | <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The | ||
| 144 | broadcaster has several possibilities to put those channels in the | ||
| 145 | air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8 | ||
| 146 | segments from position 1-8 to 5-13 or anything in between.</para> | ||
| 147 | |||
| 148 | <para>The underlying layer of segments are subchannels: each segment is | ||
| 149 | consisting of several subchannels with a predefined IDs. A sub-channel | ||
| 150 | is used to help the demodulator to synchronize on the channel.</para> | ||
| 151 | |||
| 152 | <para>An ISDB-T channel is always centered over all sub-channels. As for | ||
| 153 | the example above, in ISDB-Tsb it is no longer as simple as that.</para> | ||
| 154 | |||
| 155 | <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the | ||
| 156 | sub-channel ID of the segment to be demodulated.</para> | ||
| 157 | |||
| 158 | <para>Possible values: 0 .. 41, -1 (AUTO)</para> | ||
| 159 | </section> | ||
| 160 | |||
| 161 | <section id="isdbt-sb-seg-idx"> | ||
| 162 | |||
| 163 | <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title> | ||
| 164 | |||
| 165 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 166 | |||
| 167 | <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be | ||
| 168 | demodulated for an ISDB-Tsb channel where several of them are | ||
| 169 | transmitted in the connected manner.</para> | ||
| 170 | |||
| 171 | <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para> | ||
| 172 | |||
| 173 | <para>Note: This value cannot be determined by an automatic channel search.</para> | ||
| 174 | </section> | ||
| 175 | |||
| 176 | <section id="isdbt-sb-seg-cnt"> | ||
| 177 | <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title> | ||
| 178 | |||
| 179 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 180 | |||
| 181 | <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb | ||
| 182 | channels.</para> | ||
| 183 | |||
| 184 | <para>Possible values: 1 .. 13</para> | ||
| 185 | |||
| 186 | <para>Note: This value cannot be determined by an automatic channel search.</para> | ||
| 187 | </section> | ||
| 188 | |||
| 189 | <section id="isdb-hierq-layers"> | ||
| 190 | <title>Hierarchical layers</title> | ||
| 191 | |||
| 192 | <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in | ||
| 193 | ISDB-T hierarchical layers can be decoded simultaneously. For that | ||
| 194 | reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para> | ||
| 195 | |||
| 196 | <para>ISDB-T has 3 hierarchical layers which each can use a part of the | ||
| 197 | available segments. The total number of segments over all layers has | ||
| 198 | to 13 in ISDB-T.</para> | ||
| 199 | |||
| 200 | <section id="isdbt-layer-ena"> | ||
| 201 | <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title> | ||
| 202 | |||
| 203 | <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling | ||
| 204 | layers in the decoding process. Setting all bits of | ||
| 205 | <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be | ||
| 206 | demodulated. This is the default.</para> | ||
| 207 | |||
| 208 | <para>If the channel is in the partial reception mode | ||
| 209 | (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded | ||
| 210 | independently of the other 12 segments. In that mode layer A has to | ||
| 211 | have a <constant>SEGMENT_COUNT</constant> of 1.</para> | ||
| 212 | |||
| 213 | <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb | ||
| 214 | according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled | ||
| 215 | accordingly.</para> | ||
| 216 | |||
| 217 | <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para> | ||
| 218 | |||
| 219 | <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para> | ||
| 220 | <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para> | ||
| 221 | <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para> | ||
| 222 | <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para> | ||
| 223 | </section> | ||
| 224 | |||
| 225 | <section id="isdbt-layer-fec"> | ||
| 226 | <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title> | ||
| 227 | |||
| 228 | <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para> | ||
| 229 | </section> | ||
| 230 | |||
| 231 | <section id="isdbt-layer-mod"> | ||
| 232 | <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title> | ||
| 233 | |||
| 234 | <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para> | ||
| 235 | |||
| 236 | <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant> | ||
| 237 | and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para> | ||
| 238 | </section> | ||
| 239 | |||
| 240 | <section id="isdbt-layer-seg-cnt"> | ||
| 241 | <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title> | ||
| 242 | |||
| 243 | <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para> | ||
| 244 | |||
| 245 | <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and | ||
| 246 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para> | ||
| 247 | |||
| 248 | <informaltable id="isdbt-layer_seg-cnt-table"> | ||
| 249 | <tgroup cols="6"> | ||
| 250 | |||
| 251 | <tbody> | ||
| 252 | <row> | ||
| 253 | <entry>PR</entry> | ||
| 254 | <entry>SB</entry> | ||
| 255 | <entry>Layer A width</entry> | ||
| 256 | <entry>Layer B width</entry> | ||
| 257 | <entry>Layer C width</entry> | ||
| 258 | <entry>total width</entry> | ||
| 259 | </row> | ||
| 260 | |||
| 261 | <row> | ||
| 262 | <entry>0</entry> | ||
| 263 | <entry>0</entry> | ||
| 264 | <entry>1 .. 13</entry> | ||
| 265 | <entry>1 .. 13</entry> | ||
| 266 | <entry>1 .. 13</entry> | ||
| 267 | <entry>13</entry> | ||
| 268 | </row> | ||
| 269 | |||
| 270 | <row> | ||
| 271 | <entry>1</entry> | ||
| 272 | <entry>0</entry> | ||
| 273 | <entry>1</entry> | ||
| 274 | <entry>1 .. 13</entry> | ||
| 275 | <entry>1 .. 13</entry> | ||
| 276 | <entry>13</entry> | ||
| 277 | </row> | ||
| 278 | |||
| 279 | <row> | ||
| 280 | <entry>0</entry> | ||
| 281 | <entry>1</entry> | ||
| 282 | <entry>1</entry> | ||
| 283 | <entry>0</entry> | ||
| 284 | <entry>0</entry> | ||
| 285 | <entry>1</entry> | ||
| 286 | </row> | ||
| 287 | |||
| 288 | <row> | ||
| 289 | <entry>1</entry> | ||
| 290 | <entry>1</entry> | ||
| 291 | <entry>1</entry> | ||
| 292 | <entry>2</entry> | ||
| 293 | <entry>0</entry> | ||
| 294 | <entry>13</entry> | ||
| 295 | </row> | ||
| 296 | </tbody> | ||
| 297 | |||
| 298 | </tgroup> | ||
| 299 | </informaltable> | ||
| 300 | |||
| 301 | </section> | ||
| 302 | |||
| 303 | <section id="isdbt_layer_t_interl"> | ||
| 304 | <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> | ||
| 305 | |||
| 306 | <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> | ||
| 307 | |||
| 308 | <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values | ||
| 309 | here are referring to what can be found in the TMCC-structure - | ||
| 310 | independent of the mode.</para> | ||
| 311 | </section> | ||
| 312 | </section> | ||
| 313 | </section> | ||
| 314 | </section> | ||
diff --git a/Documentation/DocBook/dvb/kdapi.xml b/Documentation/DocBook/dvb/kdapi.xml new file mode 100644 index 000000000000..6c67481eaa4b --- /dev/null +++ b/Documentation/DocBook/dvb/kdapi.xml | |||
| @@ -0,0 +1,2309 @@ | |||
| 1 | <title>Kernel Demux API</title> | ||
| 2 | <para>The kernel demux API defines a driver-internal interface for registering low-level, | ||
| 3 | hardware specific driver to a hardware independent demux layer. It is only of interest for | ||
| 4 | DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in | ||
| 5 | <emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. | ||
| 6 | </para> | ||
| 7 | <para>Maintainer note: This section must be reviewed. It is probably out of date. | ||
| 8 | </para> | ||
| 9 | |||
| 10 | <section id="kernel_demux_data_types"> | ||
| 11 | <title>Kernel Demux Data Types</title> | ||
| 12 | |||
| 13 | |||
| 14 | <section id="dmx_success_t"> | ||
| 15 | <title>dmx_success_t</title> | ||
| 16 | <programlisting> | ||
| 17 | typedef enum { | ||
| 18 | DMX_OK = 0, /⋆ Received Ok ⋆/ | ||
| 19 | DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ | ||
| 20 | DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ | ||
| 21 | DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ | ||
| 22 | DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ | ||
| 23 | DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ | ||
| 24 | DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ | ||
| 25 | } dmx_success_t; | ||
| 26 | </programlisting> | ||
| 27 | |||
| 28 | </section> | ||
| 29 | <section id="ts_filter_types"> | ||
| 30 | <title>TS filter types</title> | ||
| 31 | <programlisting> | ||
| 32 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 33 | /⋆ TS packet reception ⋆/ | ||
| 34 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 35 | |||
| 36 | /⋆ TS filter type for set_type() ⋆/ | ||
| 37 | |||
| 38 | #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ | ||
| 39 | #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS | ||
| 40 | payload (<=184 bytes per packet) to callback ⋆/ | ||
| 41 | #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ | ||
| 42 | </programlisting> | ||
| 43 | |||
| 44 | </section> | ||
| 45 | <section id="dmx_ts_pes_t"> | ||
| 46 | <title>dmx_ts_pes_t</title> | ||
| 47 | <para>The structure | ||
| 48 | </para> | ||
| 49 | <programlisting> | ||
| 50 | typedef enum | ||
| 51 | { | ||
| 52 | DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ | ||
| 53 | DMX_TS_PES_VIDEO, /⋆ ... ⋆/ | ||
| 54 | DMX_TS_PES_TELETEXT, | ||
| 55 | DMX_TS_PES_SUBTITLE, | ||
| 56 | DMX_TS_PES_PCR, | ||
| 57 | DMX_TS_PES_OTHER, | ||
| 58 | } dmx_ts_pes_t; | ||
| 59 | </programlisting> | ||
| 60 | <para>describes the PES type for filters which write to a built-in decoder. The correspond (and | ||
| 61 | should be kept identical) to the types in the demux device. | ||
| 62 | </para> | ||
| 63 | <programlisting> | ||
| 64 | struct dmx_ts_feed_s { | ||
| 65 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 66 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 67 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 68 | int (⋆set) (struct dmx_ts_feed_s⋆ feed, | ||
| 69 | __u16 pid, | ||
| 70 | size_t callback_length, | ||
| 71 | size_t circular_buffer_size, | ||
| 72 | int descramble, | ||
| 73 | struct timespec timeout); | ||
| 74 | int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); | ||
| 75 | int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); | ||
| 76 | int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, | ||
| 77 | int type, | ||
| 78 | dmx_ts_pes_t pes_type); | ||
| 79 | }; | ||
| 80 | |||
| 81 | typedef struct dmx_ts_feed_s dmx_ts_feed_t; | ||
| 82 | </programlisting> | ||
| 83 | <programlisting> | ||
| 84 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 85 | /⋆ PES packet reception (not supported yet) ⋆/ | ||
| 86 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 87 | |||
| 88 | typedef struct dmx_pes_filter_s { | ||
| 89 | struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 90 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 91 | } dmx_pes_filter_t; | ||
| 92 | </programlisting> | ||
| 93 | <programlisting> | ||
| 94 | typedef struct dmx_pes_feed_s { | ||
| 95 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 96 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 97 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 98 | int (⋆set) (struct dmx_pes_feed_s⋆ feed, | ||
| 99 | __u16 pid, | ||
| 100 | size_t circular_buffer_size, | ||
| 101 | int descramble, | ||
| 102 | struct timespec timeout); | ||
| 103 | int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); | ||
| 104 | int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); | ||
| 105 | int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, | ||
| 106 | dmx_pes_filter_t⋆⋆ filter); | ||
| 107 | int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, | ||
| 108 | dmx_pes_filter_t⋆ filter); | ||
| 109 | } dmx_pes_feed_t; | ||
| 110 | </programlisting> | ||
| 111 | <programlisting> | ||
| 112 | typedef struct { | ||
| 113 | __u8 filter_value [DMX_MAX_FILTER_SIZE]; | ||
| 114 | __u8 filter_mask [DMX_MAX_FILTER_SIZE]; | ||
| 115 | struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 116 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 117 | } dmx_section_filter_t; | ||
| 118 | </programlisting> | ||
| 119 | <programlisting> | ||
| 120 | struct dmx_section_feed_s { | ||
| 121 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 122 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 123 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 124 | int (⋆set) (struct dmx_section_feed_s⋆ feed, | ||
| 125 | __u16 pid, | ||
| 126 | size_t circular_buffer_size, | ||
| 127 | int descramble, | ||
| 128 | int check_crc); | ||
| 129 | int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, | ||
| 130 | dmx_section_filter_t⋆⋆ filter); | ||
| 131 | int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, | ||
| 132 | dmx_section_filter_t⋆ filter); | ||
| 133 | int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); | ||
| 134 | int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); | ||
| 135 | }; | ||
| 136 | typedef struct dmx_section_feed_s dmx_section_feed_t; | ||
| 137 | |||
| 138 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 139 | /⋆ Callback functions ⋆/ | ||
| 140 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 141 | |||
| 142 | typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, | ||
| 143 | size_t buffer1_length, | ||
| 144 | __u8 ⋆ buffer2, | ||
| 145 | size_t buffer2_length, | ||
| 146 | dmx_ts_feed_t⋆ source, | ||
| 147 | dmx_success_t success); | ||
| 148 | |||
| 149 | typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, | ||
| 150 | size_t buffer1_len, | ||
| 151 | __u8 ⋆ buffer2, | ||
| 152 | size_t buffer2_len, | ||
| 153 | dmx_section_filter_t ⋆ source, | ||
| 154 | dmx_success_t success); | ||
| 155 | |||
| 156 | typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, | ||
| 157 | size_t buffer1_len, | ||
| 158 | __u8 ⋆ buffer2, | ||
| 159 | size_t buffer2_len, | ||
| 160 | dmx_pes_filter_t⋆ source, | ||
| 161 | dmx_success_t success); | ||
| 162 | |||
| 163 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 164 | /⋆ DVB Front-End ⋆/ | ||
| 165 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 166 | |||
| 167 | typedef enum { | ||
| 168 | DMX_OTHER_FE = 0, | ||
| 169 | DMX_SATELLITE_FE, | ||
| 170 | DMX_CABLE_FE, | ||
| 171 | DMX_TERRESTRIAL_FE, | ||
| 172 | DMX_LVDS_FE, | ||
| 173 | DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ | ||
| 174 | DMX_MEMORY_FE | ||
| 175 | } dmx_frontend_source_t; | ||
| 176 | |||
| 177 | typedef struct { | ||
| 178 | /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ | ||
| 179 | char⋆ id; /⋆ Unique front-end identifier ⋆/ | ||
| 180 | char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ | ||
| 181 | char⋆ model; /⋆ Name of the front-end model ⋆/ | ||
| 182 | struct list_head connectivity_list; /⋆ List of front-ends that can | ||
| 183 | be connected to a particular | ||
| 184 | demux ⋆/ | ||
| 185 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 186 | dmx_frontend_source_t source; | ||
| 187 | } dmx_frontend_t; | ||
| 188 | |||
| 189 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 190 | /⋆ MPEG-2 TS Demux ⋆/ | ||
| 191 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 192 | |||
| 193 | /⋆ | ||
| 194 | ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. | ||
| 195 | ⋆/ | ||
| 196 | |||
| 197 | #define DMX_TS_FILTERING 1 | ||
| 198 | #define DMX_PES_FILTERING 2 | ||
| 199 | #define DMX_SECTION_FILTERING 4 | ||
| 200 | #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ | ||
| 201 | #define DMX_CRC_CHECKING 16 | ||
| 202 | #define DMX_TS_DESCRAMBLING 32 | ||
| 203 | #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 | ||
| 204 | #define DMX_MAC_ADDRESS_DESCRAMBLING 128 | ||
| 205 | </programlisting> | ||
| 206 | |||
| 207 | </section> | ||
| 208 | <section id="demux_demux_t"> | ||
| 209 | <title>demux_demux_t</title> | ||
| 210 | <programlisting> | ||
| 211 | /⋆ | ||
| 212 | ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered | ||
| 213 | ⋆ front-ends from the generic type struct list_head | ||
| 214 | ⋆ to the type ⋆ dmx_frontend_t | ||
| 215 | ⋆. | ||
| 216 | ⋆/ | ||
| 217 | |||
| 218 | #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) | ||
| 219 | |||
| 220 | struct dmx_demux_s { | ||
| 221 | /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ | ||
| 222 | char⋆ id; /⋆ Unique demux identifier ⋆/ | ||
| 223 | char⋆ vendor; /⋆ Name of the demux vendor ⋆/ | ||
| 224 | char⋆ model; /⋆ Name of the demux model ⋆/ | ||
| 225 | __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ | ||
| 226 | dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ | ||
| 227 | struct list_head reg_list; /⋆ List of registered demuxes ⋆/ | ||
| 228 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 229 | int users; /⋆ Number of users ⋆/ | ||
| 230 | int (⋆open) (struct dmx_demux_s⋆ demux); | ||
| 231 | int (⋆close) (struct dmx_demux_s⋆ demux); | ||
| 232 | int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); | ||
| 233 | int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, | ||
| 234 | dmx_ts_feed_t⋆⋆ feed, | ||
| 235 | dmx_ts_cb callback); | ||
| 236 | int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, | ||
| 237 | dmx_ts_feed_t⋆ feed); | ||
| 238 | int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, | ||
| 239 | dmx_pes_feed_t⋆⋆ feed, | ||
| 240 | dmx_pes_cb callback); | ||
| 241 | int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, | ||
| 242 | dmx_pes_feed_t⋆ feed); | ||
| 243 | int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, | ||
| 244 | dmx_section_feed_t⋆⋆ feed, | ||
| 245 | dmx_section_cb callback); | ||
| 246 | int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, | ||
| 247 | dmx_section_feed_t⋆ feed); | ||
| 248 | int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, | ||
| 249 | __u8⋆ buffer1, | ||
| 250 | size_t buffer1_length, | ||
| 251 | __u8⋆ buffer2, | ||
| 252 | size_t buffer2_length, | ||
| 253 | __u16 pid); | ||
| 254 | int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, | ||
| 255 | __u8⋆ buffer1, | ||
| 256 | size_t buffer1_length, | ||
| 257 | __u8⋆ buffer2, size_t buffer2_length, | ||
| 258 | __u16 pid); | ||
| 259 | int (⋆add_frontend) (struct dmx_demux_s⋆ demux, | ||
| 260 | dmx_frontend_t⋆ frontend); | ||
| 261 | int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, | ||
| 262 | dmx_frontend_t⋆ frontend); | ||
| 263 | struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); | ||
| 264 | int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, | ||
| 265 | dmx_frontend_t⋆ frontend); | ||
| 266 | int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); | ||
| 267 | |||
| 268 | |||
| 269 | /⋆ added because js cannot keep track of these himself ⋆/ | ||
| 270 | int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); | ||
| 271 | }; | ||
| 272 | typedef struct dmx_demux_s dmx_demux_t; | ||
| 273 | </programlisting> | ||
| 274 | |||
| 275 | </section> | ||
| 276 | <section id="demux_directory"> | ||
| 277 | <title>Demux directory</title> | ||
| 278 | <programlisting> | ||
| 279 | /⋆ | ||
| 280 | ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered | ||
| 281 | ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t | ||
| 282 | ⋆. | ||
| 283 | ⋆/ | ||
| 284 | |||
| 285 | #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) | ||
| 286 | |||
| 287 | int dmx_register_demux (dmx_demux_t⋆ demux); | ||
| 288 | int dmx_unregister_demux (dmx_demux_t⋆ demux); | ||
| 289 | struct list_head⋆ dmx_get_demuxes (void); | ||
| 290 | </programlisting> | ||
| 291 | </section></section> | ||
| 292 | <section id="demux_directory_api"> | ||
| 293 | <title>Demux Directory API</title> | ||
| 294 | <para>The demux directory is a Linux kernel-wide facility for registering and accessing the | ||
| 295 | MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers | ||
| 296 | is possible using this API. | ||
| 297 | </para> | ||
| 298 | <para>All demux drivers in the directory implement the abstract interface dmx_demux_t. | ||
| 299 | </para> | ||
| 300 | |||
| 301 | <section | ||
| 302 | role="subsection"><title>dmx_register_demux()</title> | ||
| 303 | <para>DESCRIPTION | ||
| 304 | </para> | ||
| 305 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 306 | align="char"> | ||
| 307 | <para>This function makes a demux driver interface available to the Linux kernel. It is | ||
| 308 | usually called by the init_module() function of the kernel module that contains | ||
| 309 | the demux driver. The caller of this function is responsible for allocating | ||
| 310 | dynamic or static memory for the demux structure and for initializing its fields | ||
| 311 | before calling this function. The memory allocated for the demux structure | ||
| 312 | must not be freed before calling dmx_unregister_demux(),</para> | ||
| 313 | </entry> | ||
| 314 | </row></tbody></tgroup></informaltable> | ||
| 315 | <para>SYNOPSIS | ||
| 316 | </para> | ||
| 317 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 318 | align="char"> | ||
| 319 | <para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> | ||
| 320 | </entry> | ||
| 321 | </row></tbody></tgroup></informaltable> | ||
| 322 | <para>PARAMETERS | ||
| 323 | </para> | ||
| 324 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 325 | align="char"> | ||
| 326 | <para>dmx_demux_t* | ||
| 327 | demux</para> | ||
| 328 | </entry><entry | ||
| 329 | align="char"> | ||
| 330 | <para>Pointer to the demux structure.</para> | ||
| 331 | </entry> | ||
| 332 | </row></tbody></tgroup></informaltable> | ||
| 333 | <para>RETURNS | ||
| 334 | </para> | ||
| 335 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 336 | align="char"> | ||
| 337 | <para>0</para> | ||
| 338 | </entry><entry | ||
| 339 | align="char"> | ||
| 340 | <para>The function was completed without errors.</para> | ||
| 341 | </entry> | ||
| 342 | </row><row><entry | ||
| 343 | align="char"> | ||
| 344 | <para>-EEXIST</para> | ||
| 345 | </entry><entry | ||
| 346 | align="char"> | ||
| 347 | <para>A demux with the same value of the id field already stored | ||
| 348 | in the directory.</para> | ||
| 349 | </entry> | ||
| 350 | </row><row><entry | ||
| 351 | align="char"> | ||
| 352 | <para>-ENOSPC</para> | ||
| 353 | </entry><entry | ||
| 354 | align="char"> | ||
| 355 | <para>No space left in the directory.</para> | ||
| 356 | </entry> | ||
| 357 | </row></tbody></tgroup></informaltable> | ||
| 358 | |||
| 359 | </section><section | ||
| 360 | role="subsection"><title>dmx_unregister_demux()</title> | ||
| 361 | <para>DESCRIPTION | ||
| 362 | </para> | ||
| 363 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 364 | align="char"> | ||
| 365 | <para>This function is called to indicate that the given demux interface is no | ||
| 366 | longer available. The caller of this function is responsible for freeing the | ||
| 367 | memory of the demux structure, if it was dynamically allocated before calling | ||
| 368 | dmx_register_demux(). The cleanup_module() function of the kernel module | ||
| 369 | that contains the demux driver should call this function. Note that this function | ||
| 370 | fails if the demux is currently in use, i.e., release_demux() has not been called | ||
| 371 | for the interface.</para> | ||
| 372 | </entry> | ||
| 373 | </row></tbody></tgroup></informaltable> | ||
| 374 | <para>SYNOPSIS | ||
| 375 | </para> | ||
| 376 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 377 | align="char"> | ||
| 378 | <para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> | ||
| 379 | </entry> | ||
| 380 | </row></tbody></tgroup></informaltable> | ||
| 381 | <para>PARAMETERS | ||
| 382 | </para> | ||
| 383 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 384 | align="char"> | ||
| 385 | <para>dmx_demux_t* | ||
| 386 | demux</para> | ||
| 387 | </entry><entry | ||
| 388 | align="char"> | ||
| 389 | <para>Pointer to the demux structure which is to be | ||
| 390 | unregistered.</para> | ||
| 391 | </entry> | ||
| 392 | </row></tbody></tgroup></informaltable> | ||
| 393 | <para>RETURNS | ||
| 394 | </para> | ||
| 395 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 396 | align="char"> | ||
| 397 | <para>0</para> | ||
| 398 | </entry><entry | ||
| 399 | align="char"> | ||
| 400 | <para>The function was completed without errors.</para> | ||
| 401 | </entry> | ||
| 402 | </row><row><entry | ||
| 403 | align="char"> | ||
| 404 | <para>ENODEV</para> | ||
| 405 | </entry><entry | ||
| 406 | align="char"> | ||
| 407 | <para>The specified demux is not registered in the demux | ||
| 408 | directory.</para> | ||
| 409 | </entry> | ||
| 410 | </row><row><entry | ||
| 411 | align="char"> | ||
| 412 | <para>EBUSY</para> | ||
| 413 | </entry><entry | ||
| 414 | align="char"> | ||
| 415 | <para>The specified demux is currently in use.</para> | ||
| 416 | </entry> | ||
| 417 | </row></tbody></tgroup></informaltable> | ||
| 418 | |||
| 419 | </section><section | ||
| 420 | role="subsection"><title>dmx_get_demuxes()</title> | ||
| 421 | <para>DESCRIPTION | ||
| 422 | </para> | ||
| 423 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 424 | align="char"> | ||
| 425 | <para>Provides the caller with the list of registered demux interfaces, using the | ||
| 426 | standard list structure defined in the include file linux/list.h. The include file | ||
| 427 | demux.h defines the macro DMX_DIR_ENTRY() for converting an element of | ||
| 428 | the generic type struct list_head* to the type dmx_demux_t*. The caller must | ||
| 429 | not free the memory of any of the elements obtained via this function call.</para> | ||
| 430 | </entry> | ||
| 431 | </row></tbody></tgroup></informaltable> | ||
| 432 | <para>SYNOPSIS | ||
| 433 | </para> | ||
| 434 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 435 | align="char"> | ||
| 436 | <para>struct list_head ⋆dmx_get_demuxes ()</para> | ||
| 437 | </entry> | ||
| 438 | </row></tbody></tgroup></informaltable> | ||
| 439 | <para>PARAMETERS | ||
| 440 | </para> | ||
| 441 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 442 | align="char"> | ||
| 443 | <para>none</para> | ||
| 444 | </entry> | ||
| 445 | </row></tbody></tgroup></informaltable> | ||
| 446 | <para>RETURNS | ||
| 447 | </para> | ||
| 448 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 449 | align="char"> | ||
| 450 | <para>struct list_head *</para> | ||
| 451 | </entry><entry | ||
| 452 | align="char"> | ||
| 453 | <para>A list of demux interfaces, or NULL in the case of an | ||
| 454 | empty list.</para> | ||
| 455 | </entry> | ||
| 456 | </row></tbody></tgroup></informaltable> | ||
| 457 | </section></section> | ||
| 458 | <section id="demux_api"> | ||
| 459 | <title>Demux API</title> | ||
| 460 | <para>The demux API should be implemented for each demux in the system. It is used to select | ||
| 461 | the TS source of a demux and to manage the demux resources. When the demux | ||
| 462 | client allocates a resource via the demux API, it receives a pointer to the API of that | ||
| 463 | resource. | ||
| 464 | </para> | ||
| 465 | <para>Each demux receives its TS input from a DVB front-end or from memory, as set via the | ||
| 466 | demux API. In a system with more than one front-end, the API can be used to select one of | ||
| 467 | the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The | ||
| 468 | demux API only controls front-ends regarding their connections with demuxes; the APIs | ||
| 469 | used to set the other front-end parameters, such as tuning, are not defined in this | ||
| 470 | document. | ||
| 471 | </para> | ||
| 472 | <para>The functions that implement the abstract interface demux should be defined static or | ||
| 473 | module private and registered to the Demux Directory for external access. It is not necessary | ||
| 474 | to implement every function in the demux_t struct, however (for example, a demux interface | ||
| 475 | might support Section filtering, but not TS or PES filtering). The API client is expected to | ||
| 476 | check the value of any function pointer before calling the function: the value of NULL means | ||
| 477 | “function not available”. | ||
| 478 | </para> | ||
| 479 | <para>Whenever the functions of the demux API modify shared data, the possibilities of lost | ||
| 480 | update and race condition problems should be addressed, e.g. by protecting parts of code with | ||
| 481 | mutexes. This is especially important on multi-processor hosts. | ||
| 482 | </para> | ||
| 483 | <para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x | ||
| 484 | kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if | ||
| 485 | swapping is needed. For example, the Linux kernel calls the functions of a network device | ||
| 486 | interface from a bottom half context. Thus, if a demux API function is called from network | ||
| 487 | device code, the function must not sleep. | ||
| 488 | </para> | ||
| 489 | |||
| 490 | |||
| 491 | <section id="kdapi_fopen"> | ||
| 492 | <title>open()</title> | ||
| 493 | <para>DESCRIPTION | ||
| 494 | </para> | ||
| 495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 496 | align="char"> | ||
| 497 | <para>This function reserves the demux for use by the caller and, if necessary, | ||
| 498 | initializes the demux. When the demux is no longer needed, the function close() | ||
| 499 | should be called. It should be possible for multiple clients to access the demux | ||
| 500 | at the same time. Thus, the function implementation should increment the | ||
| 501 | demux usage count when open() is called and decrement it when close() is | ||
| 502 | called.</para> | ||
| 503 | </entry> | ||
| 504 | </row></tbody></tgroup></informaltable> | ||
| 505 | <para>SYNOPSIS | ||
| 506 | </para> | ||
| 507 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 508 | align="char"> | ||
| 509 | <para>int open ( demux_t⋆ demux );</para> | ||
| 510 | </entry> | ||
| 511 | </row></tbody></tgroup></informaltable> | ||
| 512 | <para>PARAMETERS | ||
| 513 | </para> | ||
| 514 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 515 | align="char"> | ||
| 516 | <para>demux_t* demux</para> | ||
| 517 | </entry><entry | ||
| 518 | align="char"> | ||
| 519 | <para>Pointer to the demux API and instance data.</para> | ||
| 520 | </entry> | ||
| 521 | </row></tbody></tgroup></informaltable> | ||
| 522 | <para>RETURNS | ||
| 523 | </para> | ||
| 524 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 525 | align="char"> | ||
| 526 | <para>0</para> | ||
| 527 | </entry><entry | ||
| 528 | align="char"> | ||
| 529 | <para>The function was completed without errors.</para> | ||
| 530 | </entry> | ||
| 531 | </row><row><entry | ||
| 532 | align="char"> | ||
| 533 | <para>-EUSERS</para> | ||
| 534 | </entry><entry | ||
| 535 | align="char"> | ||
| 536 | <para>Maximum usage count reached.</para> | ||
| 537 | </entry> | ||
| 538 | </row><row><entry | ||
| 539 | align="char"> | ||
| 540 | <para>-EINVAL</para> | ||
| 541 | </entry><entry | ||
| 542 | align="char"> | ||
| 543 | <para>Bad parameter.</para> | ||
| 544 | </entry> | ||
| 545 | </row></tbody></tgroup></informaltable> | ||
| 546 | |||
| 547 | </section> | ||
| 548 | <section id="kdapi_fclose"> | ||
| 549 | <title>close()</title> | ||
| 550 | <para>DESCRIPTION | ||
| 551 | </para> | ||
| 552 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 553 | align="char"> | ||
| 554 | <para>This function reserves the demux for use by the caller and, if necessary, | ||
| 555 | initializes the demux. When the demux is no longer needed, the function close() | ||
| 556 | should be called. It should be possible for multiple clients to access the demux | ||
| 557 | at the same time. Thus, the function implementation should increment the | ||
| 558 | demux usage count when open() is called and decrement it when close() is | ||
| 559 | called.</para> | ||
| 560 | </entry> | ||
| 561 | </row></tbody></tgroup></informaltable> | ||
| 562 | <para>SYNOPSIS | ||
| 563 | </para> | ||
| 564 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 565 | align="char"> | ||
| 566 | <para>int close(demux_t⋆ demux);</para> | ||
| 567 | </entry> | ||
| 568 | </row></tbody></tgroup></informaltable> | ||
| 569 | <para>PARAMETERS | ||
| 570 | </para> | ||
| 571 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 572 | align="char"> | ||
| 573 | <para>demux_t* demux</para> | ||
| 574 | </entry><entry | ||
| 575 | align="char"> | ||
| 576 | <para>Pointer to the demux API and instance data.</para> | ||
| 577 | </entry> | ||
| 578 | </row></tbody></tgroup></informaltable> | ||
| 579 | <para>RETURNS | ||
| 580 | </para> | ||
| 581 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 582 | align="char"> | ||
| 583 | <para>0</para> | ||
| 584 | </entry><entry | ||
| 585 | align="char"> | ||
| 586 | <para>The function was completed without errors.</para> | ||
| 587 | </entry> | ||
| 588 | </row><row><entry | ||
| 589 | align="char"> | ||
| 590 | <para>-ENODEV</para> | ||
| 591 | </entry><entry | ||
| 592 | align="char"> | ||
| 593 | <para>The demux was not in use.</para> | ||
| 594 | </entry> | ||
| 595 | </row><row><entry | ||
| 596 | align="char"> | ||
| 597 | <para>-EINVAL</para> | ||
| 598 | </entry><entry | ||
| 599 | align="char"> | ||
| 600 | <para>Bad parameter.</para> | ||
| 601 | </entry> | ||
| 602 | </row></tbody></tgroup></informaltable> | ||
| 603 | |||
| 604 | </section> | ||
| 605 | <section id="kdapi_fwrite"> | ||
| 606 | <title>write()</title> | ||
| 607 | <para>DESCRIPTION | ||
| 608 | </para> | ||
| 609 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 610 | align="char"> | ||
| 611 | <para>This function provides the demux driver with a memory buffer containing TS | ||
| 612 | packets. Instead of receiving TS packets from the DVB front-end, the demux | ||
| 613 | driver software will read packets from memory. Any clients of this demux | ||
| 614 | with active TS, PES or Section filters will receive filtered data via the Demux | ||
| 615 | callback API (see 0). The function returns when all the data in the buffer has | ||
| 616 | been consumed by the demux. Demux hardware typically cannot read TS from | ||
| 617 | memory. If this is the case, memory-based filtering has to be implemented | ||
| 618 | entirely in software.</para> | ||
| 619 | </entry> | ||
| 620 | </row></tbody></tgroup></informaltable> | ||
| 621 | <para>SYNOPSIS | ||
| 622 | </para> | ||
| 623 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 624 | align="char"> | ||
| 625 | <para>int write(demux_t⋆ demux, const char⋆ buf, size_t | ||
| 626 | count);</para> | ||
| 627 | </entry> | ||
| 628 | </row></tbody></tgroup></informaltable> | ||
| 629 | <para>PARAMETERS | ||
| 630 | </para> | ||
| 631 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 632 | align="char"> | ||
| 633 | <para>demux_t* demux</para> | ||
| 634 | </entry><entry | ||
| 635 | align="char"> | ||
| 636 | <para>Pointer to the demux API and instance data.</para> | ||
| 637 | </entry> | ||
| 638 | </row><row><entry | ||
| 639 | align="char"> | ||
| 640 | <para>const char* buf</para> | ||
| 641 | </entry><entry | ||
| 642 | align="char"> | ||
| 643 | <para>Pointer to the TS data in kernel-space memory.</para> | ||
| 644 | </entry> | ||
| 645 | </row><row><entry | ||
| 646 | align="char"> | ||
| 647 | <para>size_t length</para> | ||
| 648 | </entry><entry | ||
| 649 | align="char"> | ||
| 650 | <para>Length of the TS data.</para> | ||
| 651 | </entry> | ||
| 652 | </row></tbody></tgroup></informaltable> | ||
| 653 | <para>RETURNS | ||
| 654 | </para> | ||
| 655 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 656 | align="char"> | ||
| 657 | <para>0</para> | ||
| 658 | </entry><entry | ||
| 659 | align="char"> | ||
| 660 | <para>The function was completed without errors.</para> | ||
| 661 | </entry> | ||
| 662 | </row><row><entry | ||
| 663 | align="char"> | ||
| 664 | <para>-ENOSYS</para> | ||
| 665 | </entry><entry | ||
| 666 | align="char"> | ||
| 667 | <para>The command is not implemented.</para> | ||
| 668 | </entry> | ||
| 669 | </row><row><entry | ||
| 670 | align="char"> | ||
| 671 | <para>-EINVAL</para> | ||
| 672 | </entry><entry | ||
| 673 | align="char"> | ||
| 674 | <para>Bad parameter.</para> | ||
| 675 | </entry> | ||
| 676 | </row></tbody></tgroup></informaltable> | ||
| 677 | |||
| 678 | </section><section | ||
| 679 | role="subsection"><title>allocate_ts_feed()</title> | ||
| 680 | <para>DESCRIPTION | ||
| 681 | </para> | ||
| 682 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 683 | align="char"> | ||
| 684 | <para>Allocates a new TS feed, which is used to filter the TS packets carrying a | ||
| 685 | certain PID. The TS feed normally corresponds to a hardware PID filter on the | ||
| 686 | demux chip.</para> | ||
| 687 | </entry> | ||
| 688 | </row></tbody></tgroup></informaltable> | ||
| 689 | <para>SYNOPSIS | ||
| 690 | </para> | ||
| 691 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 692 | align="char"> | ||
| 693 | <para>int allocate_ts_feed(dmx_demux_t⋆ demux, | ||
| 694 | dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> | ||
| 695 | </entry> | ||
| 696 | </row></tbody></tgroup></informaltable> | ||
| 697 | <para>PARAMETERS | ||
| 698 | </para> | ||
| 699 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 700 | align="char"> | ||
| 701 | <para>demux_t* demux</para> | ||
| 702 | </entry><entry | ||
| 703 | align="char"> | ||
| 704 | <para>Pointer to the demux API and instance data.</para> | ||
| 705 | </entry> | ||
| 706 | </row><row><entry | ||
| 707 | align="char"> | ||
| 708 | <para>dmx_ts_feed_t** | ||
| 709 | feed</para> | ||
| 710 | </entry><entry | ||
| 711 | align="char"> | ||
| 712 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 713 | </entry> | ||
| 714 | </row><row><entry | ||
| 715 | align="char"> | ||
| 716 | <para>dmx_ts_cb callback</para> | ||
| 717 | </entry><entry | ||
| 718 | align="char"> | ||
| 719 | <para>Pointer to the callback function for passing received TS | ||
| 720 | packet</para> | ||
| 721 | </entry> | ||
| 722 | </row></tbody></tgroup></informaltable> | ||
| 723 | <para>RETURNS | ||
| 724 | </para> | ||
| 725 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 726 | align="char"> | ||
| 727 | <para>0</para> | ||
| 728 | </entry><entry | ||
| 729 | align="char"> | ||
| 730 | <para>The function was completed without errors.</para> | ||
| 731 | </entry> | ||
| 732 | </row><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>-EBUSY</para> | ||
| 735 | </entry><entry | ||
| 736 | align="char"> | ||
| 737 | <para>No more TS feeds available.</para> | ||
| 738 | </entry> | ||
| 739 | </row><row><entry | ||
| 740 | align="char"> | ||
| 741 | <para>-ENOSYS</para> | ||
| 742 | </entry><entry | ||
| 743 | align="char"> | ||
| 744 | <para>The command is not implemented.</para> | ||
| 745 | </entry> | ||
| 746 | </row><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>-EINVAL</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>Bad parameter.</para> | ||
| 752 | </entry> | ||
| 753 | </row></tbody></tgroup></informaltable> | ||
| 754 | |||
| 755 | </section><section | ||
| 756 | role="subsection"><title>release_ts_feed()</title> | ||
| 757 | <para>DESCRIPTION | ||
| 758 | </para> | ||
| 759 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 760 | align="char"> | ||
| 761 | <para>Releases the resources allocated with allocate_ts_feed(). Any filtering in | ||
| 762 | progress on the TS feed should be stopped before calling this function.</para> | ||
| 763 | </entry> | ||
| 764 | </row></tbody></tgroup></informaltable> | ||
| 765 | <para>SYNOPSIS | ||
| 766 | </para> | ||
| 767 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 768 | align="char"> | ||
| 769 | <para>int release_ts_feed(dmx_demux_t⋆ demux, | ||
| 770 | dmx_ts_feed_t⋆ feed);</para> | ||
| 771 | </entry> | ||
| 772 | </row></tbody></tgroup></informaltable> | ||
| 773 | <para>PARAMETERS | ||
| 774 | </para> | ||
| 775 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 776 | align="char"> | ||
| 777 | <para>demux_t* demux</para> | ||
| 778 | </entry><entry | ||
| 779 | align="char"> | ||
| 780 | <para>Pointer to the demux API and instance data.</para> | ||
| 781 | </entry> | ||
| 782 | </row><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>dmx_ts_feed_t* feed</para> | ||
| 785 | </entry><entry | ||
| 786 | align="char"> | ||
| 787 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 788 | </entry> | ||
| 789 | </row></tbody></tgroup></informaltable> | ||
| 790 | <para>RETURNS | ||
| 791 | </para> | ||
| 792 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 793 | align="char"> | ||
| 794 | <para>0</para> | ||
| 795 | </entry><entry | ||
| 796 | align="char"> | ||
| 797 | <para>The function was completed without errors.</para> | ||
| 798 | </entry> | ||
| 799 | </row><row><entry | ||
| 800 | align="char"> | ||
| 801 | <para>-EINVAL</para> | ||
| 802 | </entry><entry | ||
| 803 | align="char"> | ||
| 804 | <para>Bad parameter.</para> | ||
| 805 | </entry> | ||
| 806 | </row></tbody></tgroup></informaltable> | ||
| 807 | |||
| 808 | </section><section | ||
| 809 | role="subsection"><title>allocate_section_feed()</title> | ||
| 810 | <para>DESCRIPTION | ||
| 811 | </para> | ||
| 812 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 813 | align="char"> | ||
| 814 | <para>Allocates a new section feed, i.e. a demux resource for filtering and receiving | ||
| 815 | sections. On platforms with hardware support for section filtering, a section | ||
| 816 | feed is directly mapped to the demux HW. On other platforms, TS packets are | ||
| 817 | first PID filtered in hardware and a hardware section filter then emulated in | ||
| 818 | software. The caller obtains an API pointer of type dmx_section_feed_t as an | ||
| 819 | out parameter. Using this API the caller can set filtering parameters and start | ||
| 820 | receiving sections.</para> | ||
| 821 | </entry> | ||
| 822 | </row></tbody></tgroup></informaltable> | ||
| 823 | <para>SYNOPSIS | ||
| 824 | </para> | ||
| 825 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 826 | align="char"> | ||
| 827 | <para>int allocate_section_feed(dmx_demux_t⋆ demux, | ||
| 828 | dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> | ||
| 829 | </entry> | ||
| 830 | </row></tbody></tgroup></informaltable> | ||
| 831 | <para>PARAMETERS | ||
| 832 | </para> | ||
| 833 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 834 | align="char"> | ||
| 835 | <para>demux_t *demux</para> | ||
| 836 | </entry><entry | ||
| 837 | align="char"> | ||
| 838 | <para>Pointer to the demux API and instance data.</para> | ||
| 839 | </entry> | ||
| 840 | </row><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>dmx_section_feed_t | ||
| 843 | **feed</para> | ||
| 844 | </entry><entry | ||
| 845 | align="char"> | ||
| 846 | <para>Pointer to the section feed API and instance data.</para> | ||
| 847 | </entry> | ||
| 848 | </row><row><entry | ||
| 849 | align="char"> | ||
| 850 | <para>dmx_section_cb | ||
| 851 | callback</para> | ||
| 852 | </entry><entry | ||
| 853 | align="char"> | ||
| 854 | <para>Pointer to the callback function for passing received | ||
| 855 | sections.</para> | ||
| 856 | </entry> | ||
| 857 | </row></tbody></tgroup></informaltable> | ||
| 858 | <para>RETURNS | ||
| 859 | </para> | ||
| 860 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 861 | align="char"> | ||
| 862 | <para>0</para> | ||
| 863 | </entry><entry | ||
| 864 | align="char"> | ||
| 865 | <para>The function was completed without errors.</para> | ||
| 866 | </entry> | ||
| 867 | </row><row><entry | ||
| 868 | align="char"> | ||
| 869 | <para>-EBUSY</para> | ||
| 870 | </entry><entry | ||
| 871 | align="char"> | ||
| 872 | <para>No more section feeds available.</para> | ||
| 873 | </entry> | ||
| 874 | </row><row><entry | ||
| 875 | align="char"> | ||
| 876 | <para>-ENOSYS</para> | ||
| 877 | </entry><entry | ||
| 878 | align="char"> | ||
| 879 | <para>The command is not implemented.</para> | ||
| 880 | </entry> | ||
| 881 | </row><row><entry | ||
| 882 | align="char"> | ||
| 883 | <para>-EINVAL</para> | ||
| 884 | </entry><entry | ||
| 885 | align="char"> | ||
| 886 | <para>Bad parameter.</para> | ||
| 887 | </entry> | ||
| 888 | </row></tbody></tgroup></informaltable> | ||
| 889 | |||
| 890 | </section><section | ||
| 891 | role="subsection"><title>release_section_feed()</title> | ||
| 892 | <para>DESCRIPTION | ||
| 893 | </para> | ||
| 894 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 895 | align="char"> | ||
| 896 | <para>Releases the resources allocated with allocate_section_feed(), including | ||
| 897 | allocated filters. Any filtering in progress on the section feed should be stopped | ||
| 898 | before calling this function.</para> | ||
| 899 | </entry> | ||
| 900 | </row></tbody></tgroup></informaltable> | ||
| 901 | <para>SYNOPSIS | ||
| 902 | </para> | ||
| 903 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 904 | align="char"> | ||
| 905 | <para>int release_section_feed(dmx_demux_t⋆ demux, | ||
| 906 | dmx_section_feed_t ⋆feed);</para> | ||
| 907 | </entry> | ||
| 908 | </row></tbody></tgroup></informaltable> | ||
| 909 | <para>PARAMETERS | ||
| 910 | </para> | ||
| 911 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 912 | align="char"> | ||
| 913 | <para>demux_t *demux</para> | ||
| 914 | </entry><entry | ||
| 915 | align="char"> | ||
| 916 | <para>Pointer to the demux API and instance data.</para> | ||
| 917 | </entry> | ||
| 918 | </row><row><entry | ||
| 919 | align="char"> | ||
| 920 | <para>dmx_section_feed_t | ||
| 921 | *feed</para> | ||
| 922 | </entry><entry | ||
| 923 | align="char"> | ||
| 924 | <para>Pointer to the section feed API and instance data.</para> | ||
| 925 | </entry> | ||
| 926 | </row></tbody></tgroup></informaltable> | ||
| 927 | <para>RETURNS | ||
| 928 | </para> | ||
| 929 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 930 | align="char"> | ||
| 931 | <para>0</para> | ||
| 932 | </entry><entry | ||
| 933 | align="char"> | ||
| 934 | <para>The function was completed without errors.</para> | ||
| 935 | </entry> | ||
| 936 | </row><row><entry | ||
| 937 | align="char"> | ||
| 938 | <para>-EINVAL</para> | ||
| 939 | </entry><entry | ||
| 940 | align="char"> | ||
| 941 | <para>Bad parameter.</para> | ||
| 942 | </entry> | ||
| 943 | </row></tbody></tgroup></informaltable> | ||
| 944 | |||
| 945 | </section><section | ||
| 946 | role="subsection"><title>descramble_mac_address()</title> | ||
| 947 | <para>DESCRIPTION | ||
| 948 | </para> | ||
| 949 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 950 | align="char"> | ||
| 951 | <para>This function runs a descrambling algorithm on the destination MAC | ||
| 952 | address field of a DVB Datagram Section, replacing the original address | ||
| 953 | with its un-encrypted version. Otherwise, the description on the function | ||
| 954 | descramble_section_payload() applies also to this function.</para> | ||
| 955 | </entry> | ||
| 956 | </row></tbody></tgroup></informaltable> | ||
| 957 | <para>SYNOPSIS | ||
| 958 | </para> | ||
| 959 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 960 | align="char"> | ||
| 961 | <para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 | ||
| 962 | ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, | ||
| 963 | size_t buffer2_length, __u16 pid);</para> | ||
| 964 | </entry> | ||
| 965 | </row></tbody></tgroup></informaltable> | ||
| 966 | <para>PARAMETERS | ||
| 967 | </para> | ||
| 968 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 969 | align="char"> | ||
| 970 | <para>dmx_demux_t | ||
| 971 | *demux</para> | ||
| 972 | </entry><entry | ||
| 973 | align="char"> | ||
| 974 | <para>Pointer to the demux API and instance data.</para> | ||
| 975 | </entry> | ||
| 976 | </row><row><entry | ||
| 977 | align="char"> | ||
| 978 | <para>__u8 *buffer1</para> | ||
| 979 | </entry><entry | ||
| 980 | align="char"> | ||
| 981 | <para>Pointer to the first byte of the section.</para> | ||
| 982 | </entry> | ||
| 983 | </row><row><entry | ||
| 984 | align="char"> | ||
| 985 | <para>size_t buffer1_length</para> | ||
| 986 | </entry><entry | ||
| 987 | align="char"> | ||
| 988 | <para>Length of the section data, including headers and CRC, | ||
| 989 | in buffer1.</para> | ||
| 990 | </entry> | ||
| 991 | </row><row><entry | ||
| 992 | align="char"> | ||
| 993 | <para>__u8* buffer2</para> | ||
| 994 | </entry><entry | ||
| 995 | align="char"> | ||
| 996 | <para>Pointer to the tail of the section data, or NULL. The | ||
| 997 | pointer has a non-NULL value if the section wraps past | ||
| 998 | the end of a circular buffer.</para> | ||
| 999 | </entry> | ||
| 1000 | </row><row><entry | ||
| 1001 | align="char"> | ||
| 1002 | <para>size_t buffer2_length</para> | ||
| 1003 | </entry><entry | ||
| 1004 | align="char"> | ||
| 1005 | <para>Length of the section data, including headers and CRC, | ||
| 1006 | in buffer2.</para> | ||
| 1007 | </entry> | ||
| 1008 | </row><row><entry | ||
| 1009 | align="char"> | ||
| 1010 | <para>__u16 pid</para> | ||
| 1011 | </entry><entry | ||
| 1012 | align="char"> | ||
| 1013 | <para>The PID on which the section was received. Useful | ||
| 1014 | for obtaining the descrambling key, e.g. from a DVB | ||
| 1015 | Common Access facility.</para> | ||
| 1016 | </entry> | ||
| 1017 | </row></tbody></tgroup></informaltable> | ||
| 1018 | <para>RETURNS | ||
| 1019 | </para> | ||
| 1020 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1021 | align="char"> | ||
| 1022 | <para>0</para> | ||
| 1023 | </entry><entry | ||
| 1024 | align="char"> | ||
| 1025 | <para>The function was completed without errors.</para> | ||
| 1026 | </entry> | ||
| 1027 | </row><row><entry | ||
| 1028 | align="char"> | ||
| 1029 | <para>-ENOSYS</para> | ||
| 1030 | </entry><entry | ||
| 1031 | align="char"> | ||
| 1032 | <para>No descrambling facility available.</para> | ||
| 1033 | </entry> | ||
| 1034 | </row><row><entry | ||
| 1035 | align="char"> | ||
| 1036 | <para>-EINVAL</para> | ||
| 1037 | </entry><entry | ||
| 1038 | align="char"> | ||
| 1039 | <para>Bad parameter.</para> | ||
| 1040 | </entry> | ||
| 1041 | </row></tbody></tgroup></informaltable> | ||
| 1042 | |||
| 1043 | </section><section | ||
| 1044 | role="subsection"><title>descramble_section_payload()</title> | ||
| 1045 | <para>DESCRIPTION | ||
| 1046 | </para> | ||
| 1047 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1048 | align="char"> | ||
| 1049 | <para>This function runs a descrambling algorithm on the payload of a DVB | ||
| 1050 | Datagram Section, replacing the original payload with its un-encrypted | ||
| 1051 | version. The function will be called from the demux API implementation; | ||
| 1052 | the API client need not call this function directly. Section-level scrambling | ||
| 1053 | algorithms are currently standardized only for DVB-RCC (return channel | ||
| 1054 | over 2-directional cable TV network) systems. For all other DVB networks, | ||
| 1055 | encryption schemes are likely to be proprietary to each data broadcaster. Thus, | ||
| 1056 | it is expected that this function pointer will have the value of NULL (i.e., | ||
| 1057 | function not available) in most demux API implementations. Nevertheless, it | ||
| 1058 | should be possible to use the function pointer as a hook for dynamically adding | ||
| 1059 | a “plug-in” descrambling facility to a demux driver.</para> | ||
| 1060 | </entry> | ||
| 1061 | </row><row><entry | ||
| 1062 | align="char"> | ||
| 1063 | <para>While this function is not needed with hardware-based section descrambling, | ||
| 1064 | the descramble_section_payload function pointer can be used to override the | ||
| 1065 | default hardware-based descrambling algorithm: if the function pointer has a | ||
| 1066 | non-NULL value, the corresponding function should be used instead of any | ||
| 1067 | descrambling hardware.</para> | ||
| 1068 | </entry> | ||
| 1069 | </row></tbody></tgroup></informaltable> | ||
| 1070 | <para>SYNOPSIS | ||
| 1071 | </para> | ||
| 1072 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1073 | align="char"> | ||
| 1074 | <para>int descramble_section_payload(dmx_demux_t⋆ demux, | ||
| 1075 | __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, | ||
| 1076 | size_t buffer2_length, __u16 pid);</para> | ||
| 1077 | </entry> | ||
| 1078 | </row></tbody></tgroup></informaltable> | ||
| 1079 | <para>PARAMETERS | ||
| 1080 | </para> | ||
| 1081 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1082 | align="char"> | ||
| 1083 | <para>dmx_demux_t | ||
| 1084 | *demux</para> | ||
| 1085 | </entry><entry | ||
| 1086 | align="char"> | ||
| 1087 | <para>Pointer to the demux API and instance data.</para> | ||
| 1088 | </entry> | ||
| 1089 | </row><row><entry | ||
| 1090 | align="char"> | ||
| 1091 | <para>__u8 *buffer1</para> | ||
| 1092 | </entry><entry | ||
| 1093 | align="char"> | ||
| 1094 | <para>Pointer to the first byte of the section.</para> | ||
| 1095 | </entry> | ||
| 1096 | </row><row><entry | ||
| 1097 | align="char"> | ||
| 1098 | <para>size_t buffer1_length</para> | ||
| 1099 | </entry><entry | ||
| 1100 | align="char"> | ||
| 1101 | <para>Length of the section data, including headers and CRC, | ||
| 1102 | in buffer1.</para> | ||
| 1103 | </entry> | ||
| 1104 | </row><row><entry | ||
| 1105 | align="char"> | ||
| 1106 | <para>__u8 *buffer2</para> | ||
| 1107 | </entry><entry | ||
| 1108 | align="char"> | ||
| 1109 | <para>Pointer to the tail of the section data, or NULL. The | ||
| 1110 | pointer has a non-NULL value if the section wraps past | ||
| 1111 | the end of a circular buffer.</para> | ||
| 1112 | </entry> | ||
| 1113 | </row><row><entry | ||
| 1114 | align="char"> | ||
| 1115 | <para>size_t buffer2_length</para> | ||
| 1116 | </entry><entry | ||
| 1117 | align="char"> | ||
| 1118 | <para>Length of the section data, including headers and CRC, | ||
| 1119 | in buffer2.</para> | ||
| 1120 | </entry> | ||
| 1121 | </row><row><entry | ||
| 1122 | align="char"> | ||
| 1123 | <para>__u16 pid</para> | ||
| 1124 | </entry><entry | ||
| 1125 | align="char"> | ||
| 1126 | <para>The PID on which the section was received. Useful | ||
| 1127 | for obtaining the descrambling key, e.g. from a DVB | ||
| 1128 | Common Access facility.</para> | ||
| 1129 | </entry> | ||
| 1130 | </row></tbody></tgroup></informaltable> | ||
| 1131 | <para>RETURNS | ||
| 1132 | </para> | ||
| 1133 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1134 | align="char"> | ||
| 1135 | <para>0</para> | ||
| 1136 | </entry><entry | ||
| 1137 | align="char"> | ||
| 1138 | <para>The function was completed without errors.</para> | ||
| 1139 | </entry> | ||
| 1140 | </row><row><entry | ||
| 1141 | align="char"> | ||
| 1142 | <para>-ENOSYS</para> | ||
| 1143 | </entry><entry | ||
| 1144 | align="char"> | ||
| 1145 | <para>No descrambling facility available.</para> | ||
| 1146 | </entry> | ||
| 1147 | </row><row><entry | ||
| 1148 | align="char"> | ||
| 1149 | <para>-EINVAL</para> | ||
| 1150 | </entry><entry | ||
| 1151 | align="char"> | ||
| 1152 | <para>Bad parameter.</para> | ||
| 1153 | </entry> | ||
| 1154 | </row></tbody></tgroup></informaltable> | ||
| 1155 | |||
| 1156 | </section><section | ||
| 1157 | role="subsection"><title>add_frontend()</title> | ||
| 1158 | <para>DESCRIPTION | ||
| 1159 | </para> | ||
| 1160 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1161 | align="char"> | ||
| 1162 | <para>Registers a connectivity between a demux and a front-end, i.e., indicates that | ||
| 1163 | the demux can be connected via a call to connect_frontend() to use the given | ||
| 1164 | front-end as a TS source. The client of this function has to allocate dynamic or | ||
| 1165 | static memory for the frontend structure and initialize its fields before calling | ||
| 1166 | this function. This function is normally called during the driver initialization. | ||
| 1167 | The caller must not free the memory of the frontend struct before successfully | ||
| 1168 | calling remove_frontend().</para> | ||
| 1169 | </entry> | ||
| 1170 | </row></tbody></tgroup></informaltable> | ||
| 1171 | <para>SYNOPSIS | ||
| 1172 | </para> | ||
| 1173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1174 | align="char"> | ||
| 1175 | <para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t | ||
| 1176 | ⋆frontend);</para> | ||
| 1177 | </entry> | ||
| 1178 | </row></tbody></tgroup></informaltable> | ||
| 1179 | <para>PARAMETERS | ||
| 1180 | </para> | ||
| 1181 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1182 | align="char"> | ||
| 1183 | <para>dmx_demux_t* | ||
| 1184 | demux</para> | ||
| 1185 | </entry><entry | ||
| 1186 | align="char"> | ||
| 1187 | <para>Pointer to the demux API and instance data.</para> | ||
| 1188 | </entry> | ||
| 1189 | </row><row><entry | ||
| 1190 | align="char"> | ||
| 1191 | <para>dmx_frontend_t* | ||
| 1192 | frontend</para> | ||
| 1193 | </entry><entry | ||
| 1194 | align="char"> | ||
| 1195 | <para>Pointer to the front-end instance data.</para> | ||
| 1196 | </entry> | ||
| 1197 | </row></tbody></tgroup></informaltable> | ||
| 1198 | <para>RETURNS | ||
| 1199 | </para> | ||
| 1200 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1201 | align="char"> | ||
| 1202 | <para>0</para> | ||
| 1203 | </entry><entry | ||
| 1204 | align="char"> | ||
| 1205 | <para>The function was completed without errors.</para> | ||
| 1206 | </entry> | ||
| 1207 | </row><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>-EEXIST</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>A front-end with the same value of the id field already | ||
| 1213 | registered.</para> | ||
| 1214 | </entry> | ||
| 1215 | </row><row><entry | ||
| 1216 | align="char"> | ||
| 1217 | <para>-EINUSE</para> | ||
| 1218 | </entry><entry | ||
| 1219 | align="char"> | ||
| 1220 | <para>The demux is in use.</para> | ||
| 1221 | </entry> | ||
| 1222 | </row><row><entry | ||
| 1223 | align="char"> | ||
| 1224 | <para>-ENOMEM</para> | ||
| 1225 | </entry><entry | ||
| 1226 | align="char"> | ||
| 1227 | <para>No more front-ends can be added.</para> | ||
| 1228 | </entry> | ||
| 1229 | </row><row><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>-EINVAL</para> | ||
| 1232 | </entry><entry | ||
| 1233 | align="char"> | ||
| 1234 | <para>Bad parameter.</para> | ||
| 1235 | </entry> | ||
| 1236 | </row></tbody></tgroup></informaltable> | ||
| 1237 | |||
| 1238 | </section><section | ||
| 1239 | role="subsection"><title>remove_frontend()</title> | ||
| 1240 | <para>DESCRIPTION | ||
| 1241 | </para> | ||
| 1242 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1243 | align="char"> | ||
| 1244 | <para>Indicates that the given front-end, registered by a call to add_frontend(), can | ||
| 1245 | no longer be connected as a TS source by this demux. The function should be | ||
| 1246 | called when a front-end driver or a demux driver is removed from the system. | ||
| 1247 | If the front-end is in use, the function fails with the return value of -EBUSY. | ||
| 1248 | After successfully calling this function, the caller can free the memory of | ||
| 1249 | the frontend struct if it was dynamically allocated before the add_frontend() | ||
| 1250 | operation.</para> | ||
| 1251 | </entry> | ||
| 1252 | </row></tbody></tgroup></informaltable> | ||
| 1253 | <para>SYNOPSIS | ||
| 1254 | </para> | ||
| 1255 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1256 | align="char"> | ||
| 1257 | <para>int remove_frontend(dmx_demux_t⋆ demux, | ||
| 1258 | dmx_frontend_t⋆ frontend);</para> | ||
| 1259 | </entry> | ||
| 1260 | </row></tbody></tgroup></informaltable> | ||
| 1261 | <para>PARAMETERS | ||
| 1262 | </para> | ||
| 1263 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1264 | align="char"> | ||
| 1265 | <para>dmx_demux_t* | ||
| 1266 | demux</para> | ||
| 1267 | </entry><entry | ||
| 1268 | align="char"> | ||
| 1269 | <para>Pointer to the demux API and instance data.</para> | ||
| 1270 | </entry> | ||
| 1271 | </row><row><entry | ||
| 1272 | align="char"> | ||
| 1273 | <para>dmx_frontend_t* | ||
| 1274 | frontend</para> | ||
| 1275 | </entry><entry | ||
| 1276 | align="char"> | ||
| 1277 | <para>Pointer to the front-end instance data.</para> | ||
| 1278 | </entry> | ||
| 1279 | </row></tbody></tgroup></informaltable> | ||
| 1280 | <para>RETURNS | ||
| 1281 | </para> | ||
| 1282 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>0</para> | ||
| 1285 | </entry><entry | ||
| 1286 | align="char"> | ||
| 1287 | <para>The function was completed without errors.</para> | ||
| 1288 | </entry> | ||
| 1289 | </row><row><entry | ||
| 1290 | align="char"> | ||
| 1291 | <para>-EINVAL</para> | ||
| 1292 | </entry><entry | ||
| 1293 | align="char"> | ||
| 1294 | <para>Bad parameter.</para> | ||
| 1295 | </entry> | ||
| 1296 | </row><row><entry | ||
| 1297 | align="char"> | ||
| 1298 | <para>-EBUSY</para> | ||
| 1299 | </entry><entry | ||
| 1300 | align="char"> | ||
| 1301 | <para>The front-end is in use, i.e. a call to connect_frontend() | ||
| 1302 | has not been followed by a call to disconnect_frontend().</para> | ||
| 1303 | </entry> | ||
| 1304 | </row></tbody></tgroup></informaltable> | ||
| 1305 | |||
| 1306 | </section><section | ||
| 1307 | role="subsection"><title>get_frontends()</title> | ||
| 1308 | <para>DESCRIPTION | ||
| 1309 | </para> | ||
| 1310 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1311 | align="char"> | ||
| 1312 | <para>Provides the APIs of the front-ends that have been registered for this demux. | ||
| 1313 | Any of the front-ends obtained with this call can be used as a parameter for | ||
| 1314 | connect_frontend().</para> | ||
| 1315 | </entry> | ||
| 1316 | </row><row><entry | ||
| 1317 | align="char"> | ||
| 1318 | <para>The include file demux.h contains the macro DMX_FE_ENTRY() for | ||
| 1319 | converting an element of the generic type struct list_head* to the type | ||
| 1320 | dmx_frontend_t*. The caller must not free the memory of any of the elements | ||
| 1321 | obtained via this function call.</para> | ||
| 1322 | </entry> | ||
| 1323 | </row></tbody></tgroup></informaltable> | ||
| 1324 | <para>SYNOPSIS | ||
| 1325 | </para> | ||
| 1326 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1327 | align="char"> | ||
| 1328 | <para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> | ||
| 1329 | </entry> | ||
| 1330 | </row></tbody></tgroup></informaltable> | ||
| 1331 | <para>PARAMETERS | ||
| 1332 | </para> | ||
| 1333 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1334 | align="char"> | ||
| 1335 | <para>dmx_demux_t* | ||
| 1336 | demux</para> | ||
| 1337 | </entry><entry | ||
| 1338 | align="char"> | ||
| 1339 | <para>Pointer to the demux API and instance data.</para> | ||
| 1340 | </entry> | ||
| 1341 | </row></tbody></tgroup></informaltable> | ||
| 1342 | <para>RETURNS | ||
| 1343 | </para> | ||
| 1344 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1345 | align="char"> | ||
| 1346 | <para>dmx_demux_t*</para> | ||
| 1347 | </entry><entry | ||
| 1348 | align="char"> | ||
| 1349 | <para>A list of front-end interfaces, or NULL in the case of an | ||
| 1350 | empty list.</para> | ||
| 1351 | </entry> | ||
| 1352 | </row></tbody></tgroup></informaltable> | ||
| 1353 | |||
| 1354 | </section><section | ||
| 1355 | role="subsection"><title>connect_frontend()</title> | ||
| 1356 | <para>DESCRIPTION | ||
| 1357 | </para> | ||
| 1358 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1359 | align="char"> | ||
| 1360 | <para>Connects the TS output of the front-end to the input of the demux. A demux | ||
| 1361 | can only be connected to a front-end registered to the demux with the function | ||
| 1362 | add_frontend().</para> | ||
| 1363 | </entry> | ||
| 1364 | </row><row><entry | ||
| 1365 | align="char"> | ||
| 1366 | <para>It may or may not be possible to connect multiple demuxes to the same | ||
| 1367 | front-end, depending on the capabilities of the HW platform. When not used, | ||
| 1368 | the front-end should be released by calling disconnect_frontend().</para> | ||
| 1369 | </entry> | ||
| 1370 | </row></tbody></tgroup></informaltable> | ||
| 1371 | <para>SYNOPSIS | ||
| 1372 | </para> | ||
| 1373 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1374 | align="char"> | ||
| 1375 | <para>int connect_frontend(dmx_demux_t⋆ demux, | ||
| 1376 | dmx_frontend_t⋆ frontend);</para> | ||
| 1377 | </entry> | ||
| 1378 | </row></tbody></tgroup></informaltable> | ||
| 1379 | <para>PARAMETERS | ||
| 1380 | </para> | ||
| 1381 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1382 | align="char"> | ||
| 1383 | <para>dmx_demux_t* | ||
| 1384 | demux</para> | ||
| 1385 | </entry><entry | ||
| 1386 | align="char"> | ||
| 1387 | <para>Pointer to the demux API and instance data.</para> | ||
| 1388 | </entry> | ||
| 1389 | </row><row><entry | ||
| 1390 | align="char"> | ||
| 1391 | <para>dmx_frontend_t* | ||
| 1392 | frontend</para> | ||
| 1393 | </entry><entry | ||
| 1394 | align="char"> | ||
| 1395 | <para>Pointer to the front-end instance data.</para> | ||
| 1396 | </entry> | ||
| 1397 | </row></tbody></tgroup></informaltable> | ||
| 1398 | <para>RETURNS | ||
| 1399 | </para> | ||
| 1400 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1401 | align="char"> | ||
| 1402 | <para>0</para> | ||
| 1403 | </entry><entry | ||
| 1404 | align="char"> | ||
| 1405 | <para>The function was completed without errors.</para> | ||
| 1406 | </entry> | ||
| 1407 | </row><row><entry | ||
| 1408 | align="char"> | ||
| 1409 | <para>-EINVAL</para> | ||
| 1410 | </entry><entry | ||
| 1411 | align="char"> | ||
| 1412 | <para>Bad parameter.</para> | ||
| 1413 | </entry> | ||
| 1414 | </row><row><entry | ||
| 1415 | align="char"> | ||
| 1416 | <para>-EBUSY</para> | ||
| 1417 | </entry><entry | ||
| 1418 | align="char"> | ||
| 1419 | <para>The front-end is in use.</para> | ||
| 1420 | </entry> | ||
| 1421 | </row></tbody></tgroup></informaltable> | ||
| 1422 | |||
| 1423 | </section><section | ||
| 1424 | role="subsection"><title>disconnect_frontend()</title> | ||
| 1425 | <para>DESCRIPTION | ||
| 1426 | </para> | ||
| 1427 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1428 | align="char"> | ||
| 1429 | <para>Disconnects the demux and a front-end previously connected by a | ||
| 1430 | connect_frontend() call.</para> | ||
| 1431 | </entry> | ||
| 1432 | </row></tbody></tgroup></informaltable> | ||
| 1433 | <para>SYNOPSIS | ||
| 1434 | </para> | ||
| 1435 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1436 | align="char"> | ||
| 1437 | <para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> | ||
| 1438 | </entry> | ||
| 1439 | </row></tbody></tgroup></informaltable> | ||
| 1440 | <para>PARAMETERS | ||
| 1441 | </para> | ||
| 1442 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1443 | align="char"> | ||
| 1444 | <para>dmx_demux_t* | ||
| 1445 | demux</para> | ||
| 1446 | </entry><entry | ||
| 1447 | align="char"> | ||
| 1448 | <para>Pointer to the demux API and instance data.</para> | ||
| 1449 | </entry> | ||
| 1450 | </row></tbody></tgroup></informaltable> | ||
| 1451 | <para>RETURNS | ||
| 1452 | </para> | ||
| 1453 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1454 | align="char"> | ||
| 1455 | <para>0</para> | ||
| 1456 | </entry><entry | ||
| 1457 | align="char"> | ||
| 1458 | <para>The function was completed without errors.</para> | ||
| 1459 | </entry> | ||
| 1460 | </row><row><entry | ||
| 1461 | align="char"> | ||
| 1462 | <para>-EINVAL</para> | ||
| 1463 | </entry><entry | ||
| 1464 | align="char"> | ||
| 1465 | <para>Bad parameter.</para> | ||
| 1466 | </entry> | ||
| 1467 | </row></tbody></tgroup></informaltable> | ||
| 1468 | </section></section> | ||
| 1469 | <section id="demux_callback_api"> | ||
| 1470 | <title>Demux Callback API</title> | ||
| 1471 | <para>This kernel-space API comprises the callback functions that deliver filtered data to the | ||
| 1472 | demux client. Unlike the other APIs, these API functions are provided by the client and called | ||
| 1473 | from the demux code. | ||
| 1474 | </para> | ||
| 1475 | <para>The function pointers of this abstract interface are not packed into a structure as in the | ||
| 1476 | other demux APIs, because the callback functions are registered and used independent | ||
| 1477 | of each other. As an example, it is possible for the API client to provide several | ||
| 1478 | callback functions for receiving TS packets and no callbacks for PES packets or | ||
| 1479 | sections. | ||
| 1480 | </para> | ||
| 1481 | <para>The functions that implement the callback API need not be re-entrant: when a demux | ||
| 1482 | driver calls one of these functions, the driver is not allowed to call the function again before | ||
| 1483 | the original call returns. If a callback is triggered by a hardware interrupt, it is recommended | ||
| 1484 | to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback | ||
| 1485 | function call directly from a hardware interrupt. | ||
| 1486 | </para> | ||
| 1487 | |||
| 1488 | <section | ||
| 1489 | role="subsection"><title>dmx_ts_cb()</title> | ||
| 1490 | <para>DESCRIPTION | ||
| 1491 | </para> | ||
| 1492 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1493 | align="char"> | ||
| 1494 | <para>This function, provided by the client of the demux API, is called from the | ||
| 1495 | demux code. The function is only called when filtering on this TS feed has | ||
| 1496 | been enabled using the start_filtering() function.</para> | ||
| 1497 | </entry> | ||
| 1498 | </row><row><entry | ||
| 1499 | align="char"> | ||
| 1500 | <para>Any TS packets that match the filter settings are copied to a circular buffer. The | ||
| 1501 | filtered TS packets are delivered to the client using this callback function. The | ||
| 1502 | size of the circular buffer is controlled by the circular_buffer_size parameter | ||
| 1503 | of the set() function in the TS Feed API. It is expected that the buffer1 and | ||
| 1504 | buffer2 callback parameters point to addresses within the circular buffer, but | ||
| 1505 | other implementations are also possible. Note that the called party should not | ||
| 1506 | try to free the memory the buffer1 and buffer2 parameters point to.</para> | ||
| 1507 | </entry> | ||
| 1508 | </row><row><entry | ||
| 1509 | align="char"> | ||
| 1510 | <para>When this function is called, the buffer1 parameter typically points to the | ||
| 1511 | start of the first undelivered TS packet within a circular buffer. The buffer2 | ||
| 1512 | buffer parameter is normally NULL, except when the received TS packets have | ||
| 1513 | crossed the last address of the circular buffer and ”wrapped” to the beginning | ||
| 1514 | of the buffer. In the latter case the buffer1 parameter would contain an address | ||
| 1515 | within the circular buffer, while the buffer2 parameter would contain the first | ||
| 1516 | address of the circular buffer.</para> | ||
| 1517 | </entry> | ||
| 1518 | </row><row><entry | ||
| 1519 | align="char"> | ||
| 1520 | <para>The number of bytes delivered with this function (i.e. buffer1_length + | ||
| 1521 | buffer2_length) is usually equal to the value of callback_length parameter | ||
| 1522 | given in the set() function, with one exception: if a timeout occurs before | ||
| 1523 | receiving callback_length bytes of TS data, any undelivered packets are | ||
| 1524 | immediately delivered to the client by calling this function. The timeout | ||
| 1525 | duration is controlled by the set() function in the TS Feed API.</para> | ||
| 1526 | </entry> | ||
| 1527 | </row><row><entry | ||
| 1528 | align="char"> | ||
| 1529 | <para>If a TS packet is received with errors that could not be fixed by the TS-level | ||
| 1530 | forward error correction (FEC), the Transport_error_indicator flag of the TS | ||
| 1531 | packet header should be set. The TS packet should not be discarded, as | ||
| 1532 | the error can possibly be corrected by a higher layer protocol. If the called | ||
| 1533 | party is slow in processing the callback, it is possible that the circular buffer | ||
| 1534 | eventually fills up. If this happens, the demux driver should discard any TS | ||
| 1535 | packets received while the buffer is full. The error should be indicated to the | ||
| 1536 | client on the next callback by setting the success parameter to the value of | ||
| 1537 | DMX_OVERRUN_ERROR.</para> | ||
| 1538 | </entry> | ||
| 1539 | </row><row><entry | ||
| 1540 | align="char"> | ||
| 1541 | <para>The type of data returned to the callback can be selected by the new | ||
| 1542 | function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t | ||
| 1543 | pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the | ||
| 1544 | include file ost/demux.h) The type parameter decides if the raw TS packet | ||
| 1545 | (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) | ||
| 1546 | should be returned. If additionally the TS_DECODER bit is set the stream | ||
| 1547 | will also be sent to the hardware MPEG decoder. In this case, the second | ||
| 1548 | flag decides as what kind of data the stream should be interpreted. The | ||
| 1549 | possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, | ||
| 1550 | DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, | ||
| 1551 | DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para> | ||
| 1552 | </entry> | ||
| 1553 | </row></tbody></tgroup></informaltable> | ||
| 1554 | <para>SYNOPSIS | ||
| 1555 | </para> | ||
| 1556 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1557 | align="char"> | ||
| 1558 | <para>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, | ||
| 1559 | __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ | ||
| 1560 | source, dmx_success_t success);</para> | ||
| 1561 | </entry> | ||
| 1562 | </row></tbody></tgroup></informaltable> | ||
| 1563 | <para>PARAMETERS | ||
| 1564 | </para> | ||
| 1565 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1566 | align="char"> | ||
| 1567 | <para>__u8* buffer1</para> | ||
| 1568 | </entry><entry | ||
| 1569 | align="char"> | ||
| 1570 | <para>Pointer to the start of the filtered TS packets.</para> | ||
| 1571 | </entry> | ||
| 1572 | </row><row><entry | ||
| 1573 | align="char"> | ||
| 1574 | <para>size_t buffer1_length</para> | ||
| 1575 | </entry><entry | ||
| 1576 | align="char"> | ||
| 1577 | <para>Length of the TS data in buffer1.</para> | ||
| 1578 | </entry> | ||
| 1579 | </row><row><entry | ||
| 1580 | align="char"> | ||
| 1581 | <para>__u8* buffer2</para> | ||
| 1582 | </entry><entry | ||
| 1583 | align="char"> | ||
| 1584 | <para>Pointer to the tail of the filtered TS packets, or NULL.</para> | ||
| 1585 | </entry> | ||
| 1586 | </row><row><entry | ||
| 1587 | align="char"> | ||
| 1588 | <para>size_t buffer2_length</para> | ||
| 1589 | </entry><entry | ||
| 1590 | align="char"> | ||
| 1591 | <para>Length of the TS data in buffer2.</para> | ||
| 1592 | </entry> | ||
| 1593 | </row><row><entry | ||
| 1594 | align="char"> | ||
| 1595 | <para>dmx_ts_feed_t* | ||
| 1596 | source</para> | ||
| 1597 | </entry><entry | ||
| 1598 | align="char"> | ||
| 1599 | <para>Indicates which TS feed is the source of the callback.</para> | ||
| 1600 | </entry> | ||
| 1601 | </row><row><entry | ||
| 1602 | align="char"> | ||
| 1603 | <para>dmx_success_t | ||
| 1604 | success</para> | ||
| 1605 | </entry><entry | ||
| 1606 | align="char"> | ||
| 1607 | <para>Indicates if there was an error in TS reception.</para> | ||
| 1608 | </entry> | ||
| 1609 | </row></tbody></tgroup></informaltable> | ||
| 1610 | <para>RETURNS | ||
| 1611 | </para> | ||
| 1612 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1613 | align="char"> | ||
| 1614 | <para>0</para> | ||
| 1615 | </entry><entry | ||
| 1616 | align="char"> | ||
| 1617 | <para>Continue filtering.</para> | ||
| 1618 | </entry> | ||
| 1619 | </row><row><entry | ||
| 1620 | align="char"> | ||
| 1621 | <para>-1</para> | ||
| 1622 | </entry><entry | ||
| 1623 | align="char"> | ||
| 1624 | <para>Stop filtering - has the same effect as a call to | ||
| 1625 | stop_filtering() on the TS Feed API.</para> | ||
| 1626 | </entry> | ||
| 1627 | </row></tbody></tgroup></informaltable> | ||
| 1628 | |||
| 1629 | </section><section | ||
| 1630 | role="subsection"><title>dmx_section_cb()</title> | ||
| 1631 | <para>DESCRIPTION | ||
| 1632 | </para> | ||
| 1633 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1634 | align="char"> | ||
| 1635 | <para>This function, provided by the client of the demux API, is called from the | ||
| 1636 | demux code. The function is only called when filtering of sections has been | ||
| 1637 | enabled using the function start_filtering() of the section feed API. When the | ||
| 1638 | demux driver has received a complete section that matches at least one section | ||
| 1639 | filter, the client is notified via this callback function. Normally this function is | ||
| 1640 | called for each received section; however, it is also possible to deliver multiple | ||
| 1641 | sections with one callback, for example when the system load is high. If an | ||
| 1642 | error occurs while receiving a section, this function should be called with | ||
| 1643 | the corresponding error type set in the success field, whether or not there is | ||
| 1644 | data to deliver. The Section Feed implementation should maintain a circular | ||
| 1645 | buffer for received sections. However, this is not necessary if the Section Feed | ||
| 1646 | API is implemented as a client of the TS Feed API, because the TS Feed | ||
| 1647 | implementation then buffers the received data. The size of the circular buffer | ||
| 1648 | can be configured using the set() function in the Section Feed API. If there | ||
| 1649 | is no room in the circular buffer when a new section is received, the section | ||
| 1650 | must be discarded. If this happens, the value of the success parameter should | ||
| 1651 | be DMX_OVERRUN_ERROR on the next callback.</para> | ||
| 1652 | </entry> | ||
| 1653 | </row></tbody></tgroup></informaltable> | ||
| 1654 | <para>SYNOPSIS | ||
| 1655 | </para> | ||
| 1656 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1657 | align="char"> | ||
| 1658 | <para>int dmx_section_cb(__u8⋆ buffer1, size_t | ||
| 1659 | buffer1_length, __u8⋆ buffer2, size_t | ||
| 1660 | buffer2_length, dmx_section_filter_t⋆ source, | ||
| 1661 | dmx_success_t success);</para> | ||
| 1662 | </entry> | ||
| 1663 | </row></tbody></tgroup></informaltable> | ||
| 1664 | <para>PARAMETERS | ||
| 1665 | </para> | ||
| 1666 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1667 | align="char"> | ||
| 1668 | <para>__u8* buffer1</para> | ||
| 1669 | </entry><entry | ||
| 1670 | align="char"> | ||
| 1671 | <para>Pointer to the start of the filtered section, e.g. within the | ||
| 1672 | circular buffer of the demux driver.</para> | ||
| 1673 | </entry> | ||
| 1674 | </row><row><entry | ||
| 1675 | align="char"> | ||
| 1676 | <para>size_t buffer1_length</para> | ||
| 1677 | </entry><entry | ||
| 1678 | align="char"> | ||
| 1679 | <para>Length of the filtered section data in buffer1, including | ||
| 1680 | headers and CRC.</para> | ||
| 1681 | </entry> | ||
| 1682 | </row><row><entry | ||
| 1683 | align="char"> | ||
| 1684 | <para>__u8* buffer2</para> | ||
| 1685 | </entry><entry | ||
| 1686 | align="char"> | ||
| 1687 | <para>Pointer to the tail of the filtered section data, or NULL. | ||
| 1688 | Useful to handle the wrapping of a circular buffer.</para> | ||
| 1689 | </entry> | ||
| 1690 | </row><row><entry | ||
| 1691 | align="char"> | ||
| 1692 | <para>size_t buffer2_length</para> | ||
| 1693 | </entry><entry | ||
| 1694 | align="char"> | ||
| 1695 | <para>Length of the filtered section data in buffer2, including | ||
| 1696 | headers and CRC.</para> | ||
| 1697 | </entry> | ||
| 1698 | </row><row><entry | ||
| 1699 | align="char"> | ||
| 1700 | <para>dmx_section_filter_t* | ||
| 1701 | filter</para> | ||
| 1702 | </entry><entry | ||
| 1703 | align="char"> | ||
| 1704 | <para>Indicates the filter that triggered the callback.</para> | ||
| 1705 | </entry> | ||
| 1706 | </row><row><entry | ||
| 1707 | align="char"> | ||
| 1708 | <para>dmx_success_t | ||
| 1709 | success</para> | ||
| 1710 | </entry><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>Indicates if there was an error in section reception.</para> | ||
| 1713 | </entry> | ||
| 1714 | </row></tbody></tgroup></informaltable> | ||
| 1715 | <para>RETURNS | ||
| 1716 | </para> | ||
| 1717 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>0</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>Continue filtering.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row><row><entry | ||
| 1725 | align="char"> | ||
| 1726 | <para>-1</para> | ||
| 1727 | </entry><entry | ||
| 1728 | align="char"> | ||
| 1729 | <para>Stop filtering - has the same effect as a call to | ||
| 1730 | stop_filtering() on the Section Feed API.</para> | ||
| 1731 | </entry> | ||
| 1732 | </row></tbody></tgroup></informaltable> | ||
| 1733 | </section></section> | ||
| 1734 | <section id="ts_feed_api"> | ||
| 1735 | <title>TS Feed API</title> | ||
| 1736 | <para>A TS feed is typically mapped to a hardware PID filter on the demux chip. | ||
| 1737 | Using this API, the client can set the filtering properties to start/stop filtering TS | ||
| 1738 | packets on a particular TS feed. The API is defined as an abstract interface of the type | ||
| 1739 | dmx_ts_feed_t. | ||
| 1740 | </para> | ||
| 1741 | <para>The functions that implement the interface should be defined static or module private. The | ||
| 1742 | client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the | ||
| 1743 | demux API. | ||
| 1744 | </para> | ||
| 1745 | |||
| 1746 | <section | ||
| 1747 | role="subsection"><title>set()</title> | ||
| 1748 | <para>DESCRIPTION | ||
| 1749 | </para> | ||
| 1750 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1751 | align="char"> | ||
| 1752 | <para>This function sets the parameters of a TS feed. Any filtering in progress on the | ||
| 1753 | TS feed must be stopped before calling this function.</para> | ||
| 1754 | </entry> | ||
| 1755 | </row></tbody></tgroup></informaltable> | ||
| 1756 | <para>SYNOPSIS | ||
| 1757 | </para> | ||
| 1758 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1759 | align="char"> | ||
| 1760 | <para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t | ||
| 1761 | callback_length, size_t circular_buffer_size, int | ||
| 1762 | descramble, struct timespec timeout);</para> | ||
| 1763 | </entry> | ||
| 1764 | </row></tbody></tgroup></informaltable> | ||
| 1765 | <para>PARAMETERS | ||
| 1766 | </para> | ||
| 1767 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1768 | align="char"> | ||
| 1769 | <para>dmx_ts_feed_t* feed</para> | ||
| 1770 | </entry><entry | ||
| 1771 | align="char"> | ||
| 1772 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1773 | </entry> | ||
| 1774 | </row><row><entry | ||
| 1775 | align="char"> | ||
| 1776 | <para>__u16 pid</para> | ||
| 1777 | </entry><entry | ||
| 1778 | align="char"> | ||
| 1779 | <para>PID value to filter. Only the TS packets carrying the | ||
| 1780 | specified PID will be passed to the API client.</para> | ||
| 1781 | </entry> | ||
| 1782 | </row><row><entry | ||
| 1783 | align="char"> | ||
| 1784 | <para>size_t | ||
| 1785 | callback_length</para> | ||
| 1786 | </entry><entry | ||
| 1787 | align="char"> | ||
| 1788 | <para>Number of bytes to deliver with each call to the | ||
| 1789 | dmx_ts_cb() callback function. The value of this | ||
| 1790 | parameter should be a multiple of 188.</para> | ||
| 1791 | </entry> | ||
| 1792 | </row><row><entry | ||
| 1793 | align="char"> | ||
| 1794 | <para>size_t | ||
| 1795 | circular_buffer_size</para> | ||
| 1796 | </entry><entry | ||
| 1797 | align="char"> | ||
| 1798 | <para>Size of the circular buffer for the filtered TS packets.</para> | ||
| 1799 | </entry> | ||
| 1800 | </row><row><entry | ||
| 1801 | align="char"> | ||
| 1802 | <para>int descramble</para> | ||
| 1803 | </entry><entry | ||
| 1804 | align="char"> | ||
| 1805 | <para>If non-zero, descramble the filtered TS packets.</para> | ||
| 1806 | </entry> | ||
| 1807 | </row><row><entry | ||
| 1808 | align="char"> | ||
| 1809 | <para>struct timespec | ||
| 1810 | timeout</para> | ||
| 1811 | </entry><entry | ||
| 1812 | align="char"> | ||
| 1813 | <para>Maximum time to wait before delivering received TS | ||
| 1814 | packets to the client.</para> | ||
| 1815 | </entry> | ||
| 1816 | </row></tbody></tgroup></informaltable> | ||
| 1817 | <para>RETURNS | ||
| 1818 | </para> | ||
| 1819 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1820 | align="char"> | ||
| 1821 | <para>0</para> | ||
| 1822 | </entry><entry | ||
| 1823 | align="char"> | ||
| 1824 | <para>The function was completed without errors.</para> | ||
| 1825 | </entry> | ||
| 1826 | </row><row><entry | ||
| 1827 | align="char"> | ||
| 1828 | <para>-ENOMEM</para> | ||
| 1829 | </entry><entry | ||
| 1830 | align="char"> | ||
| 1831 | <para>Not enough memory for the requested buffer size.</para> | ||
| 1832 | </entry> | ||
| 1833 | </row><row><entry | ||
| 1834 | align="char"> | ||
| 1835 | <para>-ENOSYS</para> | ||
| 1836 | </entry><entry | ||
| 1837 | align="char"> | ||
| 1838 | <para>No descrambling facility available for TS.</para> | ||
| 1839 | </entry> | ||
| 1840 | </row><row><entry | ||
| 1841 | align="char"> | ||
| 1842 | <para>-EINVAL</para> | ||
| 1843 | </entry><entry | ||
| 1844 | align="char"> | ||
| 1845 | <para>Bad parameter.</para> | ||
| 1846 | </entry> | ||
| 1847 | </row></tbody></tgroup></informaltable> | ||
| 1848 | |||
| 1849 | </section><section | ||
| 1850 | role="subsection"><title>start_filtering()</title> | ||
| 1851 | <para>DESCRIPTION | ||
| 1852 | </para> | ||
| 1853 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1854 | align="char"> | ||
| 1855 | <para>Starts filtering TS packets on this TS feed, according to its settings. The PID | ||
| 1856 | value to filter can be set by the API client. All matching TS packets are | ||
| 1857 | delivered asynchronously to the client, using the callback function registered | ||
| 1858 | with allocate_ts_feed().</para> | ||
| 1859 | </entry> | ||
| 1860 | </row></tbody></tgroup></informaltable> | ||
| 1861 | <para>SYNOPSIS | ||
| 1862 | </para> | ||
| 1863 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1864 | align="char"> | ||
| 1865 | <para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> | ||
| 1866 | </entry> | ||
| 1867 | </row></tbody></tgroup></informaltable> | ||
| 1868 | <para>PARAMETERS | ||
| 1869 | </para> | ||
| 1870 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1871 | align="char"> | ||
| 1872 | <para>dmx_ts_feed_t* feed</para> | ||
| 1873 | </entry><entry | ||
| 1874 | align="char"> | ||
| 1875 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1876 | </entry> | ||
| 1877 | </row></tbody></tgroup></informaltable> | ||
| 1878 | <para>RETURNS | ||
| 1879 | </para> | ||
| 1880 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1881 | align="char"> | ||
| 1882 | <para>0</para> | ||
| 1883 | </entry><entry | ||
| 1884 | align="char"> | ||
| 1885 | <para>The function was completed without errors.</para> | ||
| 1886 | </entry> | ||
| 1887 | </row><row><entry | ||
| 1888 | align="char"> | ||
| 1889 | <para>-EINVAL</para> | ||
| 1890 | </entry><entry | ||
| 1891 | align="char"> | ||
| 1892 | <para>Bad parameter.</para> | ||
| 1893 | </entry> | ||
| 1894 | </row></tbody></tgroup></informaltable> | ||
| 1895 | |||
| 1896 | </section><section | ||
| 1897 | role="subsection"><title>stop_filtering()</title> | ||
| 1898 | <para>DESCRIPTION | ||
| 1899 | </para> | ||
| 1900 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1901 | align="char"> | ||
| 1902 | <para>Stops filtering TS packets on this TS feed.</para> | ||
| 1903 | </entry> | ||
| 1904 | </row></tbody></tgroup></informaltable> | ||
| 1905 | <para>SYNOPSIS | ||
| 1906 | </para> | ||
| 1907 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1908 | align="char"> | ||
| 1909 | <para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> | ||
| 1910 | </entry> | ||
| 1911 | </row></tbody></tgroup></informaltable> | ||
| 1912 | <para>PARAMETERS | ||
| 1913 | </para> | ||
| 1914 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1915 | align="char"> | ||
| 1916 | <para>dmx_ts_feed_t* feed</para> | ||
| 1917 | </entry><entry | ||
| 1918 | align="char"> | ||
| 1919 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1920 | </entry> | ||
| 1921 | </row></tbody></tgroup></informaltable> | ||
| 1922 | <para>RETURNS | ||
| 1923 | </para> | ||
| 1924 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1925 | align="char"> | ||
| 1926 | <para>0</para> | ||
| 1927 | </entry><entry | ||
| 1928 | align="char"> | ||
| 1929 | <para>The function was completed without errors.</para> | ||
| 1930 | </entry> | ||
| 1931 | </row><row><entry | ||
| 1932 | align="char"> | ||
| 1933 | <para>-EINVAL</para> | ||
| 1934 | </entry><entry | ||
| 1935 | align="char"> | ||
| 1936 | <para>Bad parameter.</para> | ||
| 1937 | </entry> | ||
| 1938 | </row></tbody></tgroup></informaltable> | ||
| 1939 | </section></section> | ||
| 1940 | <section id="section_feed_api"> | ||
| 1941 | <title>Section Feed API</title> | ||
| 1942 | <para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this | ||
| 1943 | API, the client can set the properties of a section feed and to start/stop filtering. The API is | ||
| 1944 | defined as an abstract interface of the type dmx_section_feed_t. The functions that implement | ||
| 1945 | the interface should be defined static or module private. The client can get the handle of | ||
| 1946 | a section feed API by calling the function allocate_section_feed() in the demux | ||
| 1947 | API. | ||
| 1948 | </para> | ||
| 1949 | <para>On demux platforms that provide section filtering in hardware, the Section Feed API | ||
| 1950 | implementation provides a software wrapper for the demux hardware. Other platforms may | ||
| 1951 | support only PID filtering in hardware, requiring that TS packets are converted to sections in | ||
| 1952 | software. In the latter case the Section Feed API implementation can be a client of the TS | ||
| 1953 | Feed API. | ||
| 1954 | </para> | ||
| 1955 | |||
| 1956 | </section> | ||
| 1957 | <section id="kdapi_set"> | ||
| 1958 | <title>set()</title> | ||
| 1959 | <para>DESCRIPTION | ||
| 1960 | </para> | ||
| 1961 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1962 | align="char"> | ||
| 1963 | <para>This function sets the parameters of a section feed. Any filtering in progress on | ||
| 1964 | the section feed must be stopped before calling this function. If descrambling | ||
| 1965 | is enabled, the payload_scrambling_control and address_scrambling_control | ||
| 1966 | fields of received DVB datagram sections should be observed. If either one is | ||
| 1967 | non-zero, the section should be descrambled either in hardware or using the | ||
| 1968 | functions descramble_mac_address() and descramble_section_payload() of the | ||
| 1969 | demux API. Note that according to the MPEG-2 Systems specification, only | ||
| 1970 | the payloads of private sections can be scrambled while the rest of the section | ||
| 1971 | data must be sent in the clear.</para> | ||
| 1972 | </entry> | ||
| 1973 | </row></tbody></tgroup></informaltable> | ||
| 1974 | <para>SYNOPSIS | ||
| 1975 | </para> | ||
| 1976 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1977 | align="char"> | ||
| 1978 | <para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t | ||
| 1979 | circular_buffer_size, int descramble, int | ||
| 1980 | check_crc);</para> | ||
| 1981 | </entry> | ||
| 1982 | </row></tbody></tgroup></informaltable> | ||
| 1983 | <para>PARAMETERS | ||
| 1984 | </para> | ||
| 1985 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1986 | align="char"> | ||
| 1987 | <para>dmx_section_feed_t* | ||
| 1988 | feed</para> | ||
| 1989 | </entry><entry | ||
| 1990 | align="char"> | ||
| 1991 | <para>Pointer to the section feed API and instance data.</para> | ||
| 1992 | </entry> | ||
| 1993 | </row><row><entry | ||
| 1994 | align="char"> | ||
| 1995 | <para>__u16 pid</para> | ||
| 1996 | </entry><entry | ||
| 1997 | align="char"> | ||
| 1998 | <para>PID value to filter; only the TS packets carrying the | ||
| 1999 | specified PID will be accepted.</para> | ||
| 2000 | </entry> | ||
| 2001 | </row><row><entry | ||
| 2002 | align="char"> | ||
| 2003 | <para>size_t | ||
| 2004 | circular_buffer_size</para> | ||
| 2005 | </entry><entry | ||
| 2006 | align="char"> | ||
| 2007 | <para>Size of the circular buffer for filtered sections.</para> | ||
| 2008 | </entry> | ||
| 2009 | </row><row><entry | ||
| 2010 | align="char"> | ||
| 2011 | <para>int descramble</para> | ||
| 2012 | </entry><entry | ||
| 2013 | align="char"> | ||
| 2014 | <para>If non-zero, descramble any sections that are scrambled.</para> | ||
| 2015 | </entry> | ||
| 2016 | </row><row><entry | ||
| 2017 | align="char"> | ||
| 2018 | <para>int check_crc</para> | ||
| 2019 | </entry><entry | ||
| 2020 | align="char"> | ||
| 2021 | <para>If non-zero, check the CRC values of filtered sections.</para> | ||
| 2022 | </entry> | ||
| 2023 | </row></tbody></tgroup></informaltable> | ||
| 2024 | <para>RETURNS | ||
| 2025 | </para> | ||
| 2026 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2027 | align="char"> | ||
| 2028 | <para>0</para> | ||
| 2029 | </entry><entry | ||
| 2030 | align="char"> | ||
| 2031 | <para>The function was completed without errors.</para> | ||
| 2032 | </entry> | ||
| 2033 | </row><row><entry | ||
| 2034 | align="char"> | ||
| 2035 | <para>-ENOMEM</para> | ||
| 2036 | </entry><entry | ||
| 2037 | align="char"> | ||
| 2038 | <para>Not enough memory for the requested buffer size.</para> | ||
| 2039 | </entry> | ||
| 2040 | </row><row><entry | ||
| 2041 | align="char"> | ||
| 2042 | <para>-ENOSYS</para> | ||
| 2043 | </entry><entry | ||
| 2044 | align="char"> | ||
| 2045 | <para>No descrambling facility available for sections.</para> | ||
| 2046 | </entry> | ||
| 2047 | </row><row><entry | ||
| 2048 | align="char"> | ||
| 2049 | <para>-EINVAL</para> | ||
| 2050 | </entry><entry | ||
| 2051 | align="char"> | ||
| 2052 | <para>Bad parameters.</para> | ||
| 2053 | </entry> | ||
| 2054 | </row></tbody></tgroup></informaltable> | ||
| 2055 | |||
| 2056 | </section><section | ||
| 2057 | role="subsection"><title>allocate_filter()</title> | ||
| 2058 | <para>DESCRIPTION | ||
| 2059 | </para> | ||
| 2060 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2061 | align="char"> | ||
| 2062 | <para>This function is used to allocate a section filter on the demux. It should only be | ||
| 2063 | called when no filtering is in progress on this section feed. If a filter cannot be | ||
| 2064 | allocated, the function fails with -ENOSPC. See in section ?? for the format of | ||
| 2065 | the section filter.</para> | ||
| 2066 | </entry> | ||
| 2067 | </row><row><entry | ||
| 2068 | align="char"> | ||
| 2069 | <para>The bitfields filter_mask and filter_value should only be modified when no | ||
| 2070 | filtering is in progress on this section feed. filter_mask controls which bits of | ||
| 2071 | filter_value are compared with the section headers/payload. On a binary value | ||
| 2072 | of 1 in filter_mask, the corresponding bits are compared. The filter only accepts | ||
| 2073 | sections that are equal to filter_value in all the tested bit positions. Any changes | ||
| 2074 | to the values of filter_mask and filter_value are guaranteed to take effect only | ||
| 2075 | when the start_filtering() function is called next time. The parent pointer in | ||
| 2076 | the struct is initialized by the API implementation to the value of the feed | ||
| 2077 | parameter. The priv pointer is not used by the API implementation, and can | ||
| 2078 | thus be freely utilized by the caller of this function. Any data pointed to by the | ||
| 2079 | priv pointer is available to the recipient of the dmx_section_cb() function call.</para> | ||
| 2080 | </entry> | ||
| 2081 | </row><row><entry | ||
| 2082 | align="char"> | ||
| 2083 | <para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is | ||
| 2084 | currently set at 16 bytes, hardware filters of that size are not available on all | ||
| 2085 | platforms. Therefore, section filtering will often take place first in hardware, | ||
| 2086 | followed by filtering in software for the header bytes that were not covered | ||
| 2087 | by a hardware filter. The filter_mask field can be checked to determine how | ||
| 2088 | many bytes of the section filter are actually used, and if the hardware filter will | ||
| 2089 | suffice. Additionally, software-only section filters can optionally be allocated | ||
| 2090 | to clients when all hardware section filters are in use. Note that on most demux | ||
| 2091 | hardware it is not possible to filter on the section_length field of the section | ||
| 2092 | header – thus this field is ignored, even though it is included in filter_value and | ||
| 2093 | filter_mask fields.</para> | ||
| 2094 | </entry> | ||
| 2095 | </row></tbody></tgroup></informaltable> | ||
| 2096 | <para>SYNOPSIS | ||
| 2097 | </para> | ||
| 2098 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2099 | align="char"> | ||
| 2100 | <para>int allocate_filter(dmx_section_feed_t⋆ feed, | ||
| 2101 | dmx_section_filter_t⋆⋆ filter);</para> | ||
| 2102 | </entry> | ||
| 2103 | </row></tbody></tgroup></informaltable> | ||
| 2104 | <para>PARAMETERS | ||
| 2105 | </para> | ||
| 2106 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2107 | align="char"> | ||
| 2108 | <para>dmx_section_feed_t* | ||
| 2109 | feed</para> | ||
| 2110 | </entry><entry | ||
| 2111 | align="char"> | ||
| 2112 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2113 | </entry> | ||
| 2114 | </row><row><entry | ||
| 2115 | align="char"> | ||
| 2116 | <para>dmx_section_filter_t** | ||
| 2117 | filter</para> | ||
| 2118 | </entry><entry | ||
| 2119 | align="char"> | ||
| 2120 | <para>Pointer to the allocated filter.</para> | ||
| 2121 | </entry> | ||
| 2122 | </row></tbody></tgroup></informaltable> | ||
| 2123 | <para>RETURNS | ||
| 2124 | </para> | ||
| 2125 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2126 | align="char"> | ||
| 2127 | <para>0</para> | ||
| 2128 | </entry><entry | ||
| 2129 | align="char"> | ||
| 2130 | <para>The function was completed without errors.</para> | ||
| 2131 | </entry> | ||
| 2132 | </row><row><entry | ||
| 2133 | align="char"> | ||
| 2134 | <para>-ENOSPC</para> | ||
| 2135 | </entry><entry | ||
| 2136 | align="char"> | ||
| 2137 | <para>No filters of given type and length available.</para> | ||
| 2138 | </entry> | ||
| 2139 | </row><row><entry | ||
| 2140 | align="char"> | ||
| 2141 | <para>-EINVAL</para> | ||
| 2142 | </entry><entry | ||
| 2143 | align="char"> | ||
| 2144 | <para>Bad parameters.</para> | ||
| 2145 | </entry> | ||
| 2146 | </row></tbody></tgroup></informaltable> | ||
| 2147 | |||
| 2148 | </section><section | ||
| 2149 | role="subsection"><title>release_filter()</title> | ||
| 2150 | <para>DESCRIPTION | ||
| 2151 | </para> | ||
| 2152 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2153 | align="char"> | ||
| 2154 | <para>This function releases all the resources of a previously allocated section filter. | ||
| 2155 | The function should not be called while filtering is in progress on this section | ||
| 2156 | feed. After calling this function, the caller should not try to dereference the | ||
| 2157 | filter pointer.</para> | ||
| 2158 | </entry> | ||
| 2159 | </row></tbody></tgroup></informaltable> | ||
| 2160 | <para>SYNOPSIS | ||
| 2161 | </para> | ||
| 2162 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2163 | align="char"> | ||
| 2164 | <para>int release_filter ( dmx_section_feed_t⋆ feed, | ||
| 2165 | dmx_section_filter_t⋆ filter);</para> | ||
| 2166 | </entry> | ||
| 2167 | </row></tbody></tgroup></informaltable> | ||
| 2168 | <para>PARAMETERS | ||
| 2169 | </para> | ||
| 2170 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2171 | align="char"> | ||
| 2172 | <para>dmx_section_feed_t* | ||
| 2173 | feed</para> | ||
| 2174 | </entry><entry | ||
| 2175 | align="char"> | ||
| 2176 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2177 | </entry> | ||
| 2178 | </row><row><entry | ||
| 2179 | align="char"> | ||
| 2180 | <para>dmx_section_filter_t* | ||
| 2181 | filter</para> | ||
| 2182 | </entry><entry | ||
| 2183 | align="char"> | ||
| 2184 | <para>I/O Pointer to the instance data of a section filter.</para> | ||
| 2185 | </entry> | ||
| 2186 | </row></tbody></tgroup></informaltable> | ||
| 2187 | <para>RETURNS | ||
| 2188 | </para> | ||
| 2189 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2190 | align="char"> | ||
| 2191 | <para>0</para> | ||
| 2192 | </entry><entry | ||
| 2193 | align="char"> | ||
| 2194 | <para>The function was completed without errors.</para> | ||
| 2195 | </entry> | ||
| 2196 | </row><row><entry | ||
| 2197 | align="char"> | ||
| 2198 | <para>-ENODEV</para> | ||
| 2199 | </entry><entry | ||
| 2200 | align="char"> | ||
| 2201 | <para>No such filter allocated.</para> | ||
| 2202 | </entry> | ||
| 2203 | </row><row><entry | ||
| 2204 | align="char"> | ||
| 2205 | <para>-EINVAL</para> | ||
| 2206 | </entry><entry | ||
| 2207 | align="char"> | ||
| 2208 | <para>Bad parameter.</para> | ||
| 2209 | </entry> | ||
| 2210 | </row></tbody></tgroup></informaltable> | ||
| 2211 | |||
| 2212 | </section><section | ||
| 2213 | role="subsection"><title>start_filtering()</title> | ||
| 2214 | <para>DESCRIPTION | ||
| 2215 | </para> | ||
| 2216 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2217 | align="char"> | ||
| 2218 | <para>Starts filtering sections on this section feed, according to its settings. Sections | ||
| 2219 | are first filtered based on their PID and then matched with the section | ||
| 2220 | filters allocated for this feed. If the section matches the PID filter and | ||
| 2221 | at least one section filter, it is delivered to the API client. The section | ||
| 2222 | is delivered asynchronously using the callback function registered with | ||
| 2223 | allocate_section_feed().</para> | ||
| 2224 | </entry> | ||
| 2225 | </row></tbody></tgroup></informaltable> | ||
| 2226 | <para>SYNOPSIS | ||
| 2227 | </para> | ||
| 2228 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2229 | align="char"> | ||
| 2230 | <para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> | ||
| 2231 | </entry> | ||
| 2232 | </row></tbody></tgroup></informaltable> | ||
| 2233 | <para>PARAMETERS | ||
| 2234 | </para> | ||
| 2235 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2236 | align="char"> | ||
| 2237 | <para>dmx_section_feed_t* | ||
| 2238 | feed</para> | ||
| 2239 | </entry><entry | ||
| 2240 | align="char"> | ||
| 2241 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2242 | </entry> | ||
| 2243 | </row></tbody></tgroup></informaltable> | ||
| 2244 | <para>RETURNS | ||
| 2245 | </para> | ||
| 2246 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2247 | align="char"> | ||
| 2248 | <para>0</para> | ||
| 2249 | </entry><entry | ||
| 2250 | align="char"> | ||
| 2251 | <para>The function was completed without errors.</para> | ||
| 2252 | </entry> | ||
| 2253 | </row><row><entry | ||
| 2254 | align="char"> | ||
| 2255 | <para>-EINVAL</para> | ||
| 2256 | </entry><entry | ||
| 2257 | align="char"> | ||
| 2258 | <para>Bad parameter.</para> | ||
| 2259 | </entry> | ||
| 2260 | </row></tbody></tgroup></informaltable> | ||
| 2261 | |||
| 2262 | </section><section | ||
| 2263 | role="subsection"><title>stop_filtering()</title> | ||
| 2264 | <para>DESCRIPTION | ||
| 2265 | </para> | ||
| 2266 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2267 | align="char"> | ||
| 2268 | <para>Stops filtering sections on this section feed. Note that any changes to the | ||
| 2269 | filtering parameters (filter_value, filter_mask, etc.) should only be made when | ||
| 2270 | filtering is stopped.</para> | ||
| 2271 | </entry> | ||
| 2272 | </row></tbody></tgroup></informaltable> | ||
| 2273 | <para>SYNOPSIS | ||
| 2274 | </para> | ||
| 2275 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2276 | align="char"> | ||
| 2277 | <para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> | ||
| 2278 | </entry> | ||
| 2279 | </row></tbody></tgroup></informaltable> | ||
| 2280 | <para>PARAMETERS | ||
| 2281 | </para> | ||
| 2282 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2283 | align="char"> | ||
| 2284 | <para>dmx_section_feed_t* | ||
| 2285 | feed</para> | ||
| 2286 | </entry><entry | ||
| 2287 | align="char"> | ||
| 2288 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2289 | </entry> | ||
| 2290 | </row></tbody></tgroup></informaltable> | ||
| 2291 | <para>RETURNS | ||
| 2292 | </para> | ||
| 2293 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2294 | align="char"> | ||
| 2295 | <para>0</para> | ||
| 2296 | </entry><entry | ||
| 2297 | align="char"> | ||
| 2298 | <para>The function was completed without errors.</para> | ||
| 2299 | </entry> | ||
| 2300 | </row><row><entry | ||
| 2301 | align="char"> | ||
| 2302 | <para>-EINVAL</para> | ||
| 2303 | </entry><entry | ||
| 2304 | align="char"> | ||
| 2305 | <para>Bad parameter.</para> | ||
| 2306 | </entry> | ||
| 2307 | </row></tbody></tgroup></informaltable> | ||
| 2308 | |||
| 2309 | </section> | ||
diff --git a/Documentation/DocBook/dvb/net.xml b/Documentation/DocBook/dvb/net.xml new file mode 100644 index 000000000000..94e388d94c0d --- /dev/null +++ b/Documentation/DocBook/dvb/net.xml | |||
| @@ -0,0 +1,12 @@ | |||
| 1 | <title>DVB Network API</title> | ||
| 2 | <para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets | ||
| 3 | received via DVB into the Linux network protocol stack, e.g. for internet via satellite | ||
| 4 | applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and | ||
| 5 | and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your | ||
| 6 | application. | ||
| 7 | </para> | ||
| 8 | <section id="dvb_net_types"> | ||
| 9 | <title>DVB Net Data Types</title> | ||
| 10 | <para>To be written… | ||
| 11 | </para> | ||
| 12 | </section> | ||
diff --git a/Documentation/DocBook/dvb/video.xml b/Documentation/DocBook/dvb/video.xml new file mode 100644 index 000000000000..7bb287e67c8e --- /dev/null +++ b/Documentation/DocBook/dvb/video.xml | |||
| @@ -0,0 +1,1971 @@ | |||
| 1 | <title>DVB Video Device</title> | ||
| 2 | <para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It | ||
| 3 | can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and | ||
| 4 | ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your | ||
| 5 | application. | ||
| 6 | </para> | ||
| 7 | <para>Note that the DVB video device only controls decoding of the MPEG video stream, not | ||
| 8 | its presentation on the TV or computer screen. On PCs this is typically handled by an | ||
| 9 | associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output | ||
| 10 | windows. | ||
| 11 | </para> | ||
| 12 | <para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of | ||
| 13 | the audio and video device as well as the video4linux device. | ||
| 14 | </para> | ||
| 15 | <para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only | ||
| 16 | supported on some MPEG decoders made for DVD playback. | ||
| 17 | </para> | ||
| 18 | <section id="video_types"> | ||
| 19 | <title>Video Data Types</title> | ||
| 20 | |||
| 21 | <section id="video_format_t"> | ||
| 22 | <title>video_format_t</title> | ||
| 23 | <para>The <emphasis role="tt">video_format_t</emphasis> data type defined by | ||
| 24 | </para> | ||
| 25 | <programlisting> | ||
| 26 | typedef enum { | ||
| 27 | VIDEO_FORMAT_4_3, | ||
| 28 | VIDEO_FORMAT_16_9 | ||
| 29 | } video_format_t; | ||
| 30 | </programlisting> | ||
| 31 | <para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio | ||
| 32 | the output hardware (e.g. TV) has. It is also used in the data structures video_status | ||
| 33 | (??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by | ||
| 34 | VIDEO_GET_EVENT (??) which report about the display format of the current video | ||
| 35 | stream. | ||
| 36 | </para> | ||
| 37 | </section> | ||
| 38 | |||
| 39 | <section id="video_display_format_t"> | ||
| 40 | <title>video_display_format_t</title> | ||
| 41 | <para>In case the display format of the video stream and of the display hardware differ the | ||
| 42 | application has to specify how to handle the cropping of the picture. This can be done using | ||
| 43 | the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts | ||
| 44 | </para> | ||
| 45 | <programlisting> | ||
| 46 | typedef enum { | ||
| 47 | VIDEO_PAN_SCAN, | ||
| 48 | VIDEO_LETTER_BOX, | ||
| 49 | VIDEO_CENTER_CUT_OUT | ||
| 50 | } video_display_format_t; | ||
| 51 | </programlisting> | ||
| 52 | <para>as argument. | ||
| 53 | </para> | ||
| 54 | </section> | ||
| 55 | |||
| 56 | <section id="video_stream_source"> | ||
| 57 | <title>video stream source</title> | ||
| 58 | <para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take | ||
| 59 | the following values, depending on whether we are replaying from an internal (demuxer) or | ||
| 60 | external (user write) source. | ||
| 61 | </para> | ||
| 62 | <programlisting> | ||
| 63 | typedef enum { | ||
| 64 | VIDEO_SOURCE_DEMUX, | ||
| 65 | VIDEO_SOURCE_MEMORY | ||
| 66 | } video_stream_source_t; | ||
| 67 | </programlisting> | ||
| 68 | <para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the | ||
| 69 | DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY | ||
| 70 | is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system | ||
| 71 | call. | ||
| 72 | </para> | ||
| 73 | </section> | ||
| 74 | |||
| 75 | <section id="video_play_state"> | ||
| 76 | <title>video play state</title> | ||
| 77 | <para>The following values can be returned by the VIDEO_GET_STATUS call representing the | ||
| 78 | state of video playback. | ||
| 79 | </para> | ||
| 80 | <programlisting> | ||
| 81 | typedef enum { | ||
| 82 | VIDEO_STOPPED, | ||
| 83 | VIDEO_PLAYING, | ||
| 84 | VIDEO_FREEZED | ||
| 85 | } video_play_state_t; | ||
| 86 | </programlisting> | ||
| 87 | </section> | ||
| 88 | |||
| 89 | <section id="video_event"> | ||
| 90 | <title>struct video_event</title> | ||
| 91 | <para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT | ||
| 92 | call. | ||
| 93 | </para> | ||
| 94 | <programlisting> | ||
| 95 | struct video_event { | ||
| 96 | int32_t type; | ||
| 97 | time_t timestamp; | ||
| 98 | union { | ||
| 99 | video_format_t video_format; | ||
| 100 | } u; | ||
| 101 | }; | ||
| 102 | </programlisting> | ||
| 103 | </section> | ||
| 104 | |||
| 105 | <section id="video_status"> | ||
| 106 | <title>struct video_status</title> | ||
| 107 | <para>The VIDEO_GET_STATUS call returns the following structure informing about various | ||
| 108 | states of the playback operation. | ||
| 109 | </para> | ||
| 110 | <programlisting> | ||
| 111 | struct video_status { | ||
| 112 | boolean video_blank; | ||
| 113 | video_play_state_t play_state; | ||
| 114 | video_stream_source_t stream_source; | ||
| 115 | video_format_t video_format; | ||
| 116 | video_displayformat_t display_format; | ||
| 117 | }; | ||
| 118 | </programlisting> | ||
| 119 | <para>If video_blank is set video will be blanked out if the channel is changed or if playback is | ||
| 120 | stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is | ||
| 121 | currently frozen, stopped, or being played back. The stream_source corresponds to the seleted | ||
| 122 | source for the video stream. It can come either from the demultiplexer or from memory. | ||
| 123 | The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently | ||
| 124 | played video stream. Finally, display_format corresponds to the selected cropping | ||
| 125 | mode in case the source video format is not the same as the format of the output | ||
| 126 | device. | ||
| 127 | </para> | ||
| 128 | </section> | ||
| 129 | |||
| 130 | <section id="video_still_picture"> | ||
| 131 | <title>struct video_still_picture</title> | ||
| 132 | <para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the | ||
| 133 | following structure. | ||
| 134 | </para> | ||
| 135 | <programlisting> | ||
| 136 | /⋆ pointer to and size of a single iframe in memory ⋆/ | ||
| 137 | struct video_still_picture { | ||
| 138 | char ⋆iFrame; | ||
| 139 | int32_t size; | ||
| 140 | }; | ||
| 141 | </programlisting> | ||
| 142 | </section> | ||
| 143 | |||
| 144 | <section id="video_caps"> | ||
| 145 | <title>video capabilities</title> | ||
| 146 | <para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following | ||
| 147 | bits set according to the hardwares capabilities. | ||
| 148 | </para> | ||
| 149 | <programlisting> | ||
| 150 | /⋆ bit definitions for capabilities: ⋆/ | ||
| 151 | /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ | ||
| 152 | #define VIDEO_CAP_MPEG1 1 | ||
| 153 | #define VIDEO_CAP_MPEG2 2 | ||
| 154 | /⋆ can you send a system and/or program stream to video device? | ||
| 155 | (you still have to open the video and the audio device but only | ||
| 156 | send the stream to the video device) ⋆/ | ||
| 157 | #define VIDEO_CAP_SYS 4 | ||
| 158 | #define VIDEO_CAP_PROG 8 | ||
| 159 | /⋆ can the driver also handle SPU, NAVI and CSS encoded data? | ||
| 160 | (CSS API is not present yet) ⋆/ | ||
| 161 | #define VIDEO_CAP_SPU 16 | ||
| 162 | #define VIDEO_CAP_NAVI 32 | ||
| 163 | #define VIDEO_CAP_CSS 64 | ||
| 164 | </programlisting> | ||
| 165 | </section> | ||
| 166 | |||
| 167 | <section id="video_system"> | ||
| 168 | <title>video system</title> | ||
| 169 | <para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The | ||
| 170 | following system types can be set: | ||
| 171 | </para> | ||
| 172 | <programlisting> | ||
| 173 | typedef enum { | ||
| 174 | VIDEO_SYSTEM_PAL, | ||
| 175 | VIDEO_SYSTEM_NTSC, | ||
| 176 | VIDEO_SYSTEM_PALN, | ||
| 177 | VIDEO_SYSTEM_PALNc, | ||
| 178 | VIDEO_SYSTEM_PALM, | ||
| 179 | VIDEO_SYSTEM_NTSC60, | ||
| 180 | VIDEO_SYSTEM_PAL60, | ||
| 181 | VIDEO_SYSTEM_PALM60 | ||
| 182 | } video_system_t; | ||
| 183 | </programlisting> | ||
| 184 | </section> | ||
| 185 | |||
| 186 | <section id="video_highlight"> | ||
| 187 | <title>struct video_highlight</title> | ||
| 188 | <para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The | ||
| 189 | call expects the following format for that information: | ||
| 190 | </para> | ||
| 191 | <programlisting> | ||
| 192 | typedef | ||
| 193 | struct video_highlight { | ||
| 194 | boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ | ||
| 195 | uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ | ||
| 196 | /⋆ 3- 0 Background pixel contrast ⋆/ | ||
| 197 | uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ | ||
| 198 | /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ | ||
| 199 | uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ | ||
| 200 | /⋆ 3- 0 Background pixel color ⋆/ | ||
| 201 | uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ | ||
| 202 | /⋆ 3- 0 Emphasis pixel-1 color ⋆/ | ||
| 203 | uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ | ||
| 204 | /⋆ 21-12 start y ⋆/ | ||
| 205 | /⋆ 9- 0 end y ⋆/ | ||
| 206 | uint32_t xpos; /⋆ 23-22 button color number ⋆/ | ||
| 207 | /⋆ 21-12 start x ⋆/ | ||
| 208 | /⋆ 9- 0 end x ⋆/ | ||
| 209 | } video_highlight_t; | ||
| 210 | </programlisting> | ||
| 211 | |||
| 212 | </section> | ||
| 213 | <section id="video_spu"> | ||
| 214 | <title>video SPU</title> | ||
| 215 | <para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the | ||
| 216 | following format: | ||
| 217 | </para> | ||
| 218 | <programlisting> | ||
| 219 | typedef | ||
| 220 | struct video_spu { | ||
| 221 | boolean active; | ||
| 222 | int stream_id; | ||
| 223 | } video_spu_t; | ||
| 224 | </programlisting> | ||
| 225 | |||
| 226 | </section> | ||
| 227 | <section id="video_spu_palette"> | ||
| 228 | <title>video SPU palette</title> | ||
| 229 | <para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: | ||
| 230 | </para> | ||
| 231 | <programlisting> | ||
| 232 | typedef | ||
| 233 | struct video_spu_palette{ | ||
| 234 | int length; | ||
| 235 | uint8_t ⋆palette; | ||
| 236 | } video_spu_palette_t; | ||
| 237 | </programlisting> | ||
| 238 | |||
| 239 | </section> | ||
| 240 | <section id="video_navi_pack"> | ||
| 241 | <title>video NAVI pack</title> | ||
| 242 | <para>In order to get the navigational data the following structure has to be passed to the ioctl | ||
| 243 | VIDEO_GET_NAVI: | ||
| 244 | </para> | ||
| 245 | <programlisting> | ||
| 246 | typedef | ||
| 247 | struct video_navi_pack{ | ||
| 248 | int length; /⋆ 0 ... 1024 ⋆/ | ||
| 249 | uint8_t data[1024]; | ||
| 250 | } video_navi_pack_t; | ||
| 251 | </programlisting> | ||
| 252 | </section> | ||
| 253 | |||
| 254 | |||
| 255 | <section id="video_attributes"> | ||
| 256 | <title>video attributes</title> | ||
| 257 | <para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: | ||
| 258 | </para> | ||
| 259 | <programlisting> | ||
| 260 | typedef uint16_t video_attributes_t; | ||
| 261 | /⋆ bits: descr. ⋆/ | ||
| 262 | /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ | ||
| 263 | /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ | ||
| 264 | /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ | ||
| 265 | /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ | ||
| 266 | /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ | ||
| 267 | /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ | ||
| 268 | /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ | ||
| 269 | /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ | ||
| 270 | /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ | ||
| 271 | </programlisting> | ||
| 272 | </section></section> | ||
| 273 | |||
| 274 | |||
| 275 | <section id="video_function_calls"> | ||
| 276 | <title>Video Function Calls</title> | ||
| 277 | |||
| 278 | |||
| 279 | <section id="video_fopen"> | ||
| 280 | <title>open()</title> | ||
| 281 | <para>DESCRIPTION | ||
| 282 | </para> | ||
| 283 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 284 | align="char"> | ||
| 285 | <para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) | ||
| 286 | for subsequent use.</para> | ||
| 287 | <para>When an open() call has succeeded, the device will be ready for use. | ||
| 288 | The significance of blocking or non-blocking mode is described in the | ||
| 289 | documentation for functions where there is a difference. It does not affect the | ||
| 290 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 291 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 292 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 293 | manual page for fcntl. Only one user can open the Video Device in O_RDWR | ||
| 294 | mode. All other attempts to open the device in this mode will fail, and an | ||
| 295 | error-code will be returned. If the Video Device is opened in O_RDONLY | ||
| 296 | mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other | ||
| 297 | call will return an error code.</para> | ||
| 298 | </entry> | ||
| 299 | </row></tbody></tgroup></informaltable> | ||
| 300 | |||
| 301 | <para>SYNOPSIS | ||
| 302 | </para> | ||
| 303 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 304 | align="char"> | ||
| 305 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 306 | </entry> | ||
| 307 | </row></tbody></tgroup></informaltable> | ||
| 308 | <para>PARAMETERS | ||
| 309 | </para> | ||
| 310 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 311 | align="char"> | ||
| 312 | <para>const char | ||
| 313 | *deviceName</para> | ||
| 314 | </entry><entry | ||
| 315 | align="char"> | ||
| 316 | <para>Name of specific video device.</para> | ||
| 317 | </entry> | ||
| 318 | </row><row><entry | ||
| 319 | align="char"> | ||
| 320 | <para>int flags</para> | ||
| 321 | </entry><entry | ||
| 322 | align="char"> | ||
| 323 | <para>A bit-wise OR of the following flags:</para> | ||
| 324 | </entry> | ||
| 325 | </row><row><entry | ||
| 326 | align="char"> | ||
| 327 | </entry><entry | ||
| 328 | align="char"> | ||
| 329 | <para>O_RDONLY read-only access</para> | ||
| 330 | </entry> | ||
| 331 | </row><row><entry | ||
| 332 | align="char"> | ||
| 333 | </entry><entry | ||
| 334 | align="char"> | ||
| 335 | <para>O_RDWR read/write access</para> | ||
| 336 | </entry> | ||
| 337 | </row><row><entry | ||
| 338 | align="char"> | ||
| 339 | </entry><entry | ||
| 340 | align="char"> | ||
| 341 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 342 | </entry> | ||
| 343 | </row><row><entry | ||
| 344 | align="char"> | ||
| 345 | </entry><entry | ||
| 346 | align="char"> | ||
| 347 | <para>(blocking mode is the default)</para> | ||
| 348 | </entry> | ||
| 349 | </row></tbody></tgroup></informaltable> | ||
| 350 | <para>ERRORS | ||
| 351 | </para> | ||
| 352 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 353 | align="char"> | ||
| 354 | <para>ENODEV</para> | ||
| 355 | </entry><entry | ||
| 356 | align="char"> | ||
| 357 | <para>Device driver not loaded/available.</para> | ||
| 358 | </entry> | ||
| 359 | </row><row><entry | ||
| 360 | align="char"> | ||
| 361 | <para>EINTERNAL</para> | ||
| 362 | </entry><entry | ||
| 363 | align="char"> | ||
| 364 | <para>Internal error.</para> | ||
| 365 | </entry> | ||
| 366 | </row><row><entry | ||
| 367 | align="char"> | ||
| 368 | <para>EBUSY</para> | ||
| 369 | </entry><entry | ||
| 370 | align="char"> | ||
| 371 | <para>Device or resource busy.</para> | ||
| 372 | </entry> | ||
| 373 | </row><row><entry | ||
| 374 | align="char"> | ||
| 375 | <para>EINVAL</para> | ||
| 376 | </entry><entry | ||
| 377 | align="char"> | ||
| 378 | <para>Invalid argument.</para> | ||
| 379 | </entry> | ||
| 380 | </row></tbody></tgroup></informaltable> | ||
| 381 | |||
| 382 | </section> | ||
| 383 | <section id="video_fclose"> | ||
| 384 | <title>close()</title> | ||
| 385 | <para>DESCRIPTION | ||
| 386 | </para> | ||
| 387 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 388 | align="char"> | ||
| 389 | <para>This system call closes a previously opened video device.</para> | ||
| 390 | </entry> | ||
| 391 | </row></tbody></tgroup></informaltable> | ||
| 392 | <para>SYNOPSIS | ||
| 393 | </para> | ||
| 394 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 395 | align="char"> | ||
| 396 | <para>int close(int fd);</para> | ||
| 397 | </entry> | ||
| 398 | </row></tbody></tgroup></informaltable> | ||
| 399 | <para>PARAMETERS | ||
| 400 | </para> | ||
| 401 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 402 | align="char"> | ||
| 403 | <para>int fd</para> | ||
| 404 | </entry><entry | ||
| 405 | align="char"> | ||
| 406 | <para>File descriptor returned by a previous call to open().</para> | ||
| 407 | </entry> | ||
| 408 | </row></tbody></tgroup></informaltable> | ||
| 409 | <para>ERRORS | ||
| 410 | </para> | ||
| 411 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 412 | align="char"> | ||
| 413 | <para>EBADF</para> | ||
| 414 | </entry><entry | ||
| 415 | align="char"> | ||
| 416 | <para>fd is not a valid open file descriptor.</para> | ||
| 417 | </entry> | ||
| 418 | </row></tbody></tgroup></informaltable> | ||
| 419 | |||
| 420 | </section> | ||
| 421 | <section id="video_fwrite"> | ||
| 422 | <title>write()</title> | ||
| 423 | <para>DESCRIPTION | ||
| 424 | </para> | ||
| 425 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 426 | align="char"> | ||
| 427 | <para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected | ||
| 428 | in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in | ||
| 429 | PES format, unless the capability allows other formats. If O_NONBLOCK is | ||
| 430 | not specified the function will block until buffer space is available. The amount | ||
| 431 | of data to be transferred is implied by count.</para> | ||
| 432 | </entry> | ||
| 433 | </row></tbody></tgroup></informaltable> | ||
| 434 | <para>SYNOPSIS | ||
| 435 | </para> | ||
| 436 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 437 | align="char"> | ||
| 438 | <para>size_t write(int fd, const void ⋆buf, size_t count);</para> | ||
| 439 | </entry> | ||
| 440 | </row></tbody></tgroup></informaltable> | ||
| 441 | <para>PARAMETERS | ||
| 442 | </para> | ||
| 443 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 444 | align="char"> | ||
| 445 | <para>int fd</para> | ||
| 446 | </entry><entry | ||
| 447 | align="char"> | ||
| 448 | <para>File descriptor returned by a previous call to open().</para> | ||
| 449 | </entry> | ||
| 450 | </row><row><entry | ||
| 451 | align="char"> | ||
| 452 | <para>void *buf</para> | ||
| 453 | </entry><entry | ||
| 454 | align="char"> | ||
| 455 | <para>Pointer to the buffer containing the PES data.</para> | ||
| 456 | </entry> | ||
| 457 | </row><row><entry | ||
| 458 | align="char"> | ||
| 459 | <para>size_t count</para> | ||
| 460 | </entry><entry | ||
| 461 | align="char"> | ||
| 462 | <para>Size of buf.</para> | ||
| 463 | </entry> | ||
| 464 | </row></tbody></tgroup></informaltable> | ||
| 465 | <para>ERRORS | ||
| 466 | </para> | ||
| 467 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 468 | align="char"> | ||
| 469 | <para>EPERM</para> | ||
| 470 | </entry><entry | ||
| 471 | align="char"> | ||
| 472 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 473 | </entry> | ||
| 474 | </row><row><entry | ||
| 475 | align="char"> | ||
| 476 | <para>ENOMEM</para> | ||
| 477 | </entry><entry | ||
| 478 | align="char"> | ||
| 479 | <para>Attempted to write more data than the internal buffer can | ||
| 480 | hold.</para> | ||
| 481 | </entry> | ||
| 482 | </row><row><entry | ||
| 483 | align="char"> | ||
| 484 | <para>EBADF</para> | ||
| 485 | </entry><entry | ||
| 486 | align="char"> | ||
| 487 | <para>fd is not a valid open file descriptor.</para> | ||
| 488 | </entry> | ||
| 489 | </row></tbody></tgroup></informaltable> | ||
| 490 | |||
| 491 | </section><section | ||
| 492 | role="subsection"><title>VIDEO_STOP</title> | ||
| 493 | <para>DESCRIPTION | ||
| 494 | </para> | ||
| 495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 496 | align="char"> | ||
| 497 | <para>This ioctl call asks the Video Device to stop playing the current stream. | ||
| 498 | Depending on the input parameter, the screen can be blanked out or displaying | ||
| 499 | the last decoded frame.</para> | ||
| 500 | </entry> | ||
| 501 | </row></tbody></tgroup></informaltable> | ||
| 502 | <para>SYNOPSIS | ||
| 503 | </para> | ||
| 504 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 505 | align="char"> | ||
| 506 | <para>int ioctl(fd, int request = VIDEO_STOP, boolean | ||
| 507 | mode);</para> | ||
| 508 | </entry> | ||
| 509 | </row></tbody></tgroup></informaltable> | ||
| 510 | <para>PARAMETERS | ||
| 511 | </para> | ||
| 512 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 513 | align="char"> | ||
| 514 | <para>int fd</para> | ||
| 515 | </entry><entry | ||
| 516 | align="char"> | ||
| 517 | <para>File descriptor returned by a previous call to open().</para> | ||
| 518 | </entry> | ||
| 519 | </row><row><entry | ||
| 520 | align="char"> | ||
| 521 | <para>int request</para> | ||
| 522 | </entry><entry | ||
| 523 | align="char"> | ||
| 524 | <para>Equals VIDEO_STOP for this command.</para> | ||
| 525 | </entry> | ||
| 526 | </row><row><entry | ||
| 527 | align="char"> | ||
| 528 | <para>Boolean mode</para> | ||
| 529 | </entry><entry | ||
| 530 | align="char"> | ||
| 531 | <para>Indicates how the screen shall be handled.</para> | ||
| 532 | </entry> | ||
| 533 | </row><row><entry | ||
| 534 | align="char"> | ||
| 535 | </entry><entry | ||
| 536 | align="char"> | ||
| 537 | <para>TRUE: Blank screen when stop.</para> | ||
| 538 | </entry> | ||
| 539 | </row><row><entry | ||
| 540 | align="char"> | ||
| 541 | </entry><entry | ||
| 542 | align="char"> | ||
| 543 | <para>FALSE: Show last decoded frame.</para> | ||
| 544 | </entry> | ||
| 545 | </row></tbody></tgroup></informaltable> | ||
| 546 | <para>ERRORS | ||
| 547 | </para> | ||
| 548 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 549 | align="char"> | ||
| 550 | <para>EBADF</para> | ||
| 551 | </entry><entry | ||
| 552 | align="char"> | ||
| 553 | <para>fd is not a valid open file descriptor</para> | ||
| 554 | </entry> | ||
| 555 | </row><row><entry | ||
| 556 | align="char"> | ||
| 557 | <para>EINTERNAL</para> | ||
| 558 | </entry><entry | ||
| 559 | align="char"> | ||
| 560 | <para>Internal error, possibly in the communication with the | ||
| 561 | DVB subsystem.</para> | ||
| 562 | </entry> | ||
| 563 | </row></tbody></tgroup></informaltable> | ||
| 564 | |||
| 565 | </section><section | ||
| 566 | role="subsection"><title>VIDEO_PLAY</title> | ||
| 567 | <para>DESCRIPTION | ||
| 568 | </para> | ||
| 569 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 570 | align="char"> | ||
| 571 | <para>This ioctl call asks the Video Device to start playing a video stream from the | ||
| 572 | selected source.</para> | ||
| 573 | </entry> | ||
| 574 | </row></tbody></tgroup></informaltable> | ||
| 575 | <para>SYNOPSIS | ||
| 576 | </para> | ||
| 577 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 578 | align="char"> | ||
| 579 | <para>int ioctl(fd, int request = VIDEO_PLAY);</para> | ||
| 580 | </entry> | ||
| 581 | </row></tbody></tgroup></informaltable> | ||
| 582 | <para>PARAMETERS | ||
| 583 | </para> | ||
| 584 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 585 | align="char"> | ||
| 586 | <para>int fd</para> | ||
| 587 | </entry><entry | ||
| 588 | align="char"> | ||
| 589 | <para>File descriptor returned by a previous call to open().</para> | ||
| 590 | </entry> | ||
| 591 | </row><row><entry | ||
| 592 | align="char"> | ||
| 593 | <para>int request</para> | ||
| 594 | </entry><entry | ||
| 595 | align="char"> | ||
| 596 | <para>Equals VIDEO_PLAY for this command.</para> | ||
| 597 | </entry> | ||
| 598 | </row></tbody></tgroup></informaltable> | ||
| 599 | <para>ERRORS | ||
| 600 | </para> | ||
| 601 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 602 | align="char"> | ||
| 603 | <para>EBADF</para> | ||
| 604 | </entry><entry | ||
| 605 | align="char"> | ||
| 606 | <para>fd is not a valid open file descriptor</para> | ||
| 607 | </entry> | ||
| 608 | </row><row><entry | ||
| 609 | align="char"> | ||
| 610 | <para>EINTERNAL</para> | ||
| 611 | </entry><entry | ||
| 612 | align="char"> | ||
| 613 | <para>Internal error, possibly in the communication with the | ||
| 614 | DVB subsystem.</para> | ||
| 615 | </entry> | ||
| 616 | </row></tbody></tgroup></informaltable> | ||
| 617 | |||
| 618 | </section><section | ||
| 619 | role="subsection"><title>VIDEO_FREEZE</title> | ||
| 620 | <para>DESCRIPTION | ||
| 621 | </para> | ||
| 622 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 623 | align="char"> | ||
| 624 | <para>This ioctl call suspends the live video stream being played. Decoding | ||
| 625 | and playing are frozen. It is then possible to restart the decoding | ||
| 626 | and playing process of the video stream using the VIDEO_CONTINUE | ||
| 627 | command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call | ||
| 628 | VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more | ||
| 629 | data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para> | ||
| 630 | </entry> | ||
| 631 | </row></tbody></tgroup></informaltable> | ||
| 632 | <para>SYNOPSIS | ||
| 633 | </para> | ||
| 634 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 635 | align="char"> | ||
| 636 | <para>int ioctl(fd, int request = VIDEO_FREEZE);</para> | ||
| 637 | </entry> | ||
| 638 | </row></tbody></tgroup></informaltable> | ||
| 639 | <para>PARAMETERS | ||
| 640 | </para> | ||
| 641 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 642 | align="char"> | ||
| 643 | <para>int fd</para> | ||
| 644 | </entry><entry | ||
| 645 | align="char"> | ||
| 646 | <para>File descriptor returned by a previous call to open().</para> | ||
| 647 | </entry> | ||
| 648 | </row><row><entry | ||
| 649 | align="char"> | ||
| 650 | <para>int request</para> | ||
| 651 | </entry><entry | ||
| 652 | align="char"> | ||
| 653 | <para>Equals VIDEO_FREEZE for this command.</para> | ||
| 654 | </entry> | ||
| 655 | </row></tbody></tgroup></informaltable> | ||
| 656 | <para>ERRORS | ||
| 657 | </para> | ||
| 658 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 659 | align="char"> | ||
| 660 | <para>EBADF</para> | ||
| 661 | </entry><entry | ||
| 662 | align="char"> | ||
| 663 | <para>fd is not a valid open file descriptor</para> | ||
| 664 | </entry> | ||
| 665 | </row><row><entry | ||
| 666 | align="char"> | ||
| 667 | <para>EINTERNAL</para> | ||
| 668 | </entry><entry | ||
| 669 | align="char"> | ||
| 670 | <para>Internal error, possibly in the communication with the | ||
| 671 | DVB subsystem.</para> | ||
| 672 | </entry> | ||
| 673 | </row></tbody></tgroup></informaltable> | ||
| 674 | |||
| 675 | </section><section | ||
| 676 | role="subsection"><title>VIDEO_CONTINUE</title> | ||
| 677 | <para>DESCRIPTION | ||
| 678 | </para> | ||
| 679 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 680 | align="char"> | ||
| 681 | <para>This ioctl call restarts decoding and playing processes of the video stream | ||
| 682 | which was played before a call to VIDEO_FREEZE was made.</para> | ||
| 683 | </entry> | ||
| 684 | </row></tbody></tgroup></informaltable> | ||
| 685 | <para>SYNOPSIS | ||
| 686 | </para> | ||
| 687 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 688 | align="char"> | ||
| 689 | <para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> | ||
| 690 | </entry> | ||
| 691 | </row></tbody></tgroup></informaltable> | ||
| 692 | <para>PARAMETERS | ||
| 693 | </para> | ||
| 694 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 695 | align="char"> | ||
| 696 | <para>int fd</para> | ||
| 697 | </entry><entry | ||
| 698 | align="char"> | ||
| 699 | <para>File descriptor returned by a previous call to open().</para> | ||
| 700 | </entry> | ||
| 701 | </row><row><entry | ||
| 702 | align="char"> | ||
| 703 | <para>int request</para> | ||
| 704 | </entry><entry | ||
| 705 | align="char"> | ||
| 706 | <para>Equals VIDEO_CONTINUE for this command.</para> | ||
| 707 | </entry> | ||
| 708 | </row></tbody></tgroup></informaltable> | ||
| 709 | <para>ERRORS | ||
| 710 | </para> | ||
| 711 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 712 | align="char"> | ||
| 713 | <para>EBADF</para> | ||
| 714 | </entry><entry | ||
| 715 | align="char"> | ||
| 716 | <para>fd is not a valid open file descriptor</para> | ||
| 717 | </entry> | ||
| 718 | </row><row><entry | ||
| 719 | align="char"> | ||
| 720 | <para>EINTERNAL</para> | ||
| 721 | </entry><entry | ||
| 722 | align="char"> | ||
| 723 | <para>Internal error, possibly in the communication with the | ||
| 724 | DVB subsystem.</para> | ||
| 725 | </entry> | ||
| 726 | </row></tbody></tgroup></informaltable> | ||
| 727 | |||
| 728 | </section><section | ||
| 729 | role="subsection"><title>VIDEO_SELECT_SOURCE</title> | ||
| 730 | <para>DESCRIPTION | ||
| 731 | </para> | ||
| 732 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>This ioctl call informs the video device which source shall be used for the input | ||
| 735 | data. The possible sources are demux or memory. If memory is selected, the | ||
| 736 | data is fed to the video device through the write command.</para> | ||
| 737 | </entry> | ||
| 738 | </row></tbody></tgroup></informaltable> | ||
| 739 | <para>SYNOPSIS | ||
| 740 | </para> | ||
| 741 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 742 | align="char"> | ||
| 743 | <para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, | ||
| 744 | video_stream_source_t source);</para> | ||
| 745 | </entry> | ||
| 746 | </row></tbody></tgroup></informaltable> | ||
| 747 | <para>PARAMETERS | ||
| 748 | </para> | ||
| 749 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 750 | align="char"> | ||
| 751 | <para>int fd</para> | ||
| 752 | </entry><entry | ||
| 753 | align="char"> | ||
| 754 | <para>File descriptor returned by a previous call to open().</para> | ||
| 755 | </entry> | ||
| 756 | </row><row><entry | ||
| 757 | align="char"> | ||
| 758 | <para>int request</para> | ||
| 759 | </entry><entry | ||
| 760 | align="char"> | ||
| 761 | <para>Equals VIDEO_SELECT_SOURCE for this command.</para> | ||
| 762 | </entry> | ||
| 763 | </row><row><entry | ||
| 764 | align="char"> | ||
| 765 | <para>video_stream_source_t | ||
| 766 | source</para> | ||
| 767 | </entry><entry | ||
| 768 | align="char"> | ||
| 769 | <para>Indicates which source shall be used for the Video stream.</para> | ||
| 770 | </entry> | ||
| 771 | </row></tbody></tgroup></informaltable> | ||
| 772 | <para>ERRORS | ||
| 773 | </para> | ||
| 774 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 775 | align="char"> | ||
| 776 | <para>EBADF</para> | ||
| 777 | </entry><entry | ||
| 778 | align="char"> | ||
| 779 | <para>fd is not a valid open file descriptor</para> | ||
| 780 | </entry> | ||
| 781 | </row><row><entry | ||
| 782 | align="char"> | ||
| 783 | <para>EINTERNAL</para> | ||
| 784 | </entry><entry | ||
| 785 | align="char"> | ||
| 786 | <para>Internal error, possibly in the communication with the | ||
| 787 | DVB subsystem.</para> | ||
| 788 | </entry> | ||
| 789 | </row></tbody></tgroup></informaltable> | ||
| 790 | |||
| 791 | </section><section | ||
| 792 | role="subsection"><title>VIDEO_SET_BLANK</title> | ||
| 793 | <para>DESCRIPTION | ||
| 794 | </para> | ||
| 795 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 796 | align="char"> | ||
| 797 | <para>This ioctl call asks the Video Device to blank out the picture.</para> | ||
| 798 | </entry> | ||
| 799 | </row></tbody></tgroup></informaltable> | ||
| 800 | <para>SYNOPSIS | ||
| 801 | </para> | ||
| 802 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 803 | align="char"> | ||
| 804 | <para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean | ||
| 805 | mode);</para> | ||
| 806 | </entry> | ||
| 807 | </row></tbody></tgroup></informaltable> | ||
| 808 | <para>PARAMETERS | ||
| 809 | </para> | ||
| 810 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 811 | align="char"> | ||
| 812 | <para>int fd</para> | ||
| 813 | </entry><entry | ||
| 814 | align="char"> | ||
| 815 | <para>File descriptor returned by a previous call to open().</para> | ||
| 816 | </entry> | ||
| 817 | </row><row><entry | ||
| 818 | align="char"> | ||
| 819 | <para>int request</para> | ||
| 820 | </entry><entry | ||
| 821 | align="char"> | ||
| 822 | <para>Equals VIDEO_SET_BLANK for this command.</para> | ||
| 823 | </entry> | ||
| 824 | </row><row><entry | ||
| 825 | align="char"> | ||
| 826 | <para>boolean mode</para> | ||
| 827 | </entry><entry | ||
| 828 | align="char"> | ||
| 829 | <para>TRUE: Blank screen when stop.</para> | ||
| 830 | </entry> | ||
| 831 | </row><row><entry | ||
| 832 | align="char"> | ||
| 833 | </entry><entry | ||
| 834 | align="char"> | ||
| 835 | <para>FALSE: Show last decoded frame.</para> | ||
| 836 | </entry> | ||
| 837 | </row></tbody></tgroup></informaltable> | ||
| 838 | <para>ERRORS | ||
| 839 | </para> | ||
| 840 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>EBADF</para> | ||
| 843 | </entry><entry | ||
| 844 | align="char"> | ||
| 845 | <para>fd is not a valid open file descriptor</para> | ||
| 846 | </entry> | ||
| 847 | </row><row><entry | ||
| 848 | align="char"> | ||
| 849 | <para>EINTERNAL</para> | ||
| 850 | </entry><entry | ||
| 851 | align="char"> | ||
| 852 | <para>Internal error, possibly in the communication with the | ||
| 853 | DVB subsystem.</para> | ||
| 854 | </entry> | ||
| 855 | </row><row><entry | ||
| 856 | align="char"> | ||
| 857 | <para>EINVAL</para> | ||
| 858 | </entry><entry | ||
| 859 | align="char"> | ||
| 860 | <para>Illegal input parameter</para> | ||
| 861 | </entry> | ||
| 862 | </row></tbody></tgroup></informaltable> | ||
| 863 | |||
| 864 | </section><section | ||
| 865 | role="subsection"><title>VIDEO_GET_STATUS</title> | ||
| 866 | <para>DESCRIPTION | ||
| 867 | </para> | ||
| 868 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 869 | align="char"> | ||
| 870 | <para>This ioctl call asks the Video Device to return the current status of the device.</para> | ||
| 871 | </entry> | ||
| 872 | </row></tbody></tgroup></informaltable> | ||
| 873 | <para>SYNOPSIS | ||
| 874 | </para> | ||
| 875 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 876 | align="char"> | ||
| 877 | <para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct | ||
| 878 | video_status ⋆status);</para> | ||
| 879 | </entry> | ||
| 880 | </row></tbody></tgroup></informaltable> | ||
| 881 | <para>PARAMETERS | ||
| 882 | </para> | ||
| 883 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 884 | align="char"> | ||
| 885 | <para>int fd</para> | ||
| 886 | </entry><entry | ||
| 887 | align="char"> | ||
| 888 | <para>File descriptor returned by a previous call to open().</para> | ||
| 889 | </entry> | ||
| 890 | </row><row><entry | ||
| 891 | align="char"> | ||
| 892 | <para>int request</para> | ||
| 893 | </entry><entry | ||
| 894 | align="char"> | ||
| 895 | <para>Equals VIDEO_GET_STATUS for this command.</para> | ||
| 896 | </entry> | ||
| 897 | </row><row><entry | ||
| 898 | align="char"> | ||
| 899 | <para>struct video_status | ||
| 900 | *status</para> | ||
| 901 | </entry><entry | ||
| 902 | align="char"> | ||
| 903 | <para>Returns the current status of the Video Device.</para> | ||
| 904 | </entry> | ||
| 905 | </row></tbody></tgroup></informaltable> | ||
| 906 | <para>ERRORS | ||
| 907 | </para> | ||
| 908 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 909 | align="char"> | ||
| 910 | <para>EBADF</para> | ||
| 911 | </entry><entry | ||
| 912 | align="char"> | ||
| 913 | <para>fd is not a valid open file descriptor</para> | ||
| 914 | </entry> | ||
| 915 | </row><row><entry | ||
| 916 | align="char"> | ||
| 917 | <para>EINTERNAL</para> | ||
| 918 | </entry><entry | ||
| 919 | align="char"> | ||
| 920 | <para>Internal error, possibly in the communication with the | ||
| 921 | DVB subsystem.</para> | ||
| 922 | </entry> | ||
| 923 | </row><row><entry | ||
| 924 | align="char"> | ||
| 925 | <para>EFAULT</para> | ||
| 926 | </entry><entry | ||
| 927 | align="char"> | ||
| 928 | <para>status points to invalid address</para> | ||
| 929 | </entry> | ||
| 930 | </row></tbody></tgroup></informaltable> | ||
| 931 | |||
| 932 | </section><section | ||
| 933 | role="subsection"><title>VIDEO_GET_EVENT</title> | ||
| 934 | <para>DESCRIPTION | ||
| 935 | </para> | ||
| 936 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 937 | align="char"> | ||
| 938 | <para>This ioctl call returns an event of type video_event if available. If an event is | ||
| 939 | not available, the behavior depends on whether the device is in blocking or | ||
| 940 | non-blocking mode. In the latter case, the call fails immediately with errno | ||
| 941 | set to EWOULDBLOCK. In the former case, the call blocks until an event | ||
| 942 | becomes available. The standard Linux poll() and/or select() system calls can | ||
| 943 | be used with the device file descriptor to watch for new events. For select(), | ||
| 944 | the file descriptor should be included in the exceptfds argument, and for | ||
| 945 | poll(), POLLPRI should be specified as the wake-up condition. Read-only | ||
| 946 | permissions are sufficient for this ioctl call.</para> | ||
| 947 | </entry> | ||
| 948 | </row></tbody></tgroup></informaltable> | ||
| 949 | <para>SYNOPSIS | ||
| 950 | </para> | ||
| 951 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 952 | align="char"> | ||
| 953 | <para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct | ||
| 954 | video_event ⋆ev);</para> | ||
| 955 | </entry> | ||
| 956 | </row></tbody></tgroup></informaltable> | ||
| 957 | <para>PARAMETERS | ||
| 958 | </para> | ||
| 959 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 960 | align="char"> | ||
| 961 | <para>int fd</para> | ||
| 962 | </entry><entry | ||
| 963 | align="char"> | ||
| 964 | <para>File descriptor returned by a previous call to open().</para> | ||
| 965 | </entry> | ||
| 966 | </row><row><entry | ||
| 967 | align="char"> | ||
| 968 | <para>int request</para> | ||
| 969 | </entry><entry | ||
| 970 | align="char"> | ||
| 971 | <para>Equals VIDEO_GET_EVENT for this command.</para> | ||
| 972 | </entry> | ||
| 973 | </row><row><entry | ||
| 974 | align="char"> | ||
| 975 | <para>struct video_event | ||
| 976 | *ev</para> | ||
| 977 | </entry><entry | ||
| 978 | align="char"> | ||
| 979 | <para>Points to the location where the event, if any, is to be | ||
| 980 | stored.</para> | ||
| 981 | </entry> | ||
| 982 | </row></tbody></tgroup></informaltable> | ||
| 983 | <para>ERRORS | ||
| 984 | </para> | ||
| 985 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 986 | align="char"> | ||
| 987 | <para>EBADF</para> | ||
| 988 | </entry><entry | ||
| 989 | align="char"> | ||
| 990 | <para>fd is not a valid open file descriptor</para> | ||
| 991 | </entry> | ||
| 992 | </row><row><entry | ||
| 993 | align="char"> | ||
| 994 | <para>EFAULT</para> | ||
| 995 | </entry><entry | ||
| 996 | align="char"> | ||
| 997 | <para>ev points to invalid address</para> | ||
| 998 | </entry> | ||
| 999 | </row><row><entry | ||
| 1000 | align="char"> | ||
| 1001 | <para>EWOULDBLOCK</para> | ||
| 1002 | </entry><entry | ||
| 1003 | align="char"> | ||
| 1004 | <para>There is no event pending, and the device is in | ||
| 1005 | non-blocking mode.</para> | ||
| 1006 | </entry> | ||
| 1007 | </row><row><entry | ||
| 1008 | align="char"> | ||
| 1009 | <para>EOVERFLOW</para> | ||
| 1010 | </entry><entry | ||
| 1011 | align="char"> | ||
| 1012 | </entry> | ||
| 1013 | </row><row><entry | ||
| 1014 | align="char"> | ||
| 1015 | </entry><entry | ||
| 1016 | align="char"> | ||
| 1017 | <para>Overflow in event queue - one or more events were lost.</para> | ||
| 1018 | </entry> | ||
| 1019 | </row></tbody></tgroup></informaltable> | ||
| 1020 | |||
| 1021 | </section><section | ||
| 1022 | role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title> | ||
| 1023 | <para>DESCRIPTION | ||
| 1024 | </para> | ||
| 1025 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1026 | align="char"> | ||
| 1027 | <para>This ioctl call asks the Video Device to select the video format to be applied | ||
| 1028 | by the MPEG chip on the video.</para> | ||
| 1029 | </entry> | ||
| 1030 | </row></tbody></tgroup></informaltable> | ||
| 1031 | <para>SYNOPSIS | ||
| 1032 | </para> | ||
| 1033 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1034 | align="char"> | ||
| 1035 | <para> int ioctl(fd, int request = | ||
| 1036 | VIDEO_SET_DISPLAY_FORMAT, video_display_format_t | ||
| 1037 | format);</para> | ||
| 1038 | </entry> | ||
| 1039 | </row></tbody></tgroup></informaltable> | ||
| 1040 | <para>PARAMETERS | ||
| 1041 | </para> | ||
| 1042 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1043 | align="char"> | ||
| 1044 | <para>int fd</para> | ||
| 1045 | </entry><entry | ||
| 1046 | align="char"> | ||
| 1047 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1048 | </entry> | ||
| 1049 | </row><row><entry | ||
| 1050 | align="char"> | ||
| 1051 | <para>int request</para> | ||
| 1052 | </entry><entry | ||
| 1053 | align="char"> | ||
| 1054 | <para>Equals VIDEO_SET_DISPLAY_FORMAT for this | ||
| 1055 | command.</para> | ||
| 1056 | </entry> | ||
| 1057 | </row><row><entry | ||
| 1058 | align="char"> | ||
| 1059 | <para>video_display_format_t | ||
| 1060 | format</para> | ||
| 1061 | </entry><entry | ||
| 1062 | align="char"> | ||
| 1063 | <para>Selects the video format to be used.</para> | ||
| 1064 | </entry> | ||
| 1065 | </row></tbody></tgroup></informaltable> | ||
| 1066 | <para>ERRORS | ||
| 1067 | </para> | ||
| 1068 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1069 | align="char"> | ||
| 1070 | <para>EBADF</para> | ||
| 1071 | </entry><entry | ||
| 1072 | align="char"> | ||
| 1073 | <para>fd is not a valid open file descriptor</para> | ||
| 1074 | </entry> | ||
| 1075 | </row><row><entry | ||
| 1076 | align="char"> | ||
| 1077 | <para>EINTERNAL</para> | ||
| 1078 | </entry><entry | ||
| 1079 | align="char"> | ||
| 1080 | <para>Internal error.</para> | ||
| 1081 | </entry> | ||
| 1082 | </row><row><entry | ||
| 1083 | align="char"> | ||
| 1084 | <para>EINVAL</para> | ||
| 1085 | </entry><entry | ||
| 1086 | align="char"> | ||
| 1087 | <para>Illegal parameter format.</para> | ||
| 1088 | </entry> | ||
| 1089 | </row></tbody></tgroup></informaltable> | ||
| 1090 | |||
| 1091 | </section><section | ||
| 1092 | role="subsection"><title>VIDEO_STILLPICTURE</title> | ||
| 1093 | <para>DESCRIPTION | ||
| 1094 | </para> | ||
| 1095 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1096 | align="char"> | ||
| 1097 | <para>This ioctl call asks the Video Device to display a still picture (I-frame). The | ||
| 1098 | input data shall contain an I-frame. If the pointer is NULL, then the current | ||
| 1099 | displayed still picture is blanked.</para> | ||
| 1100 | </entry> | ||
| 1101 | </row></tbody></tgroup></informaltable> | ||
| 1102 | <para>SYNOPSIS | ||
| 1103 | </para> | ||
| 1104 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1105 | align="char"> | ||
| 1106 | <para>int ioctl(fd, int request = VIDEO_STILLPICTURE, | ||
| 1107 | struct video_still_picture ⋆sp);</para> | ||
| 1108 | </entry> | ||
| 1109 | </row></tbody></tgroup></informaltable> | ||
| 1110 | <para>PARAMETERS | ||
| 1111 | </para> | ||
| 1112 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1113 | align="char"> | ||
| 1114 | <para>int fd</para> | ||
| 1115 | </entry><entry | ||
| 1116 | align="char"> | ||
| 1117 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1118 | </entry> | ||
| 1119 | </row><row><entry | ||
| 1120 | align="char"> | ||
| 1121 | <para>int request</para> | ||
| 1122 | </entry><entry | ||
| 1123 | align="char"> | ||
| 1124 | <para>Equals VIDEO_STILLPICTURE for this command.</para> | ||
| 1125 | </entry> | ||
| 1126 | </row><row><entry | ||
| 1127 | align="char"> | ||
| 1128 | <para>struct | ||
| 1129 | video_still_picture | ||
| 1130 | *sp</para> | ||
| 1131 | </entry><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para>Pointer to a location where an I-frame and size is stored.</para> | ||
| 1134 | </entry> | ||
| 1135 | </row></tbody></tgroup></informaltable> | ||
| 1136 | <para>ERRORS | ||
| 1137 | </para> | ||
| 1138 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1139 | align="char"> | ||
| 1140 | <para>EBADF</para> | ||
| 1141 | </entry><entry | ||
| 1142 | align="char"> | ||
| 1143 | <para>fd is not a valid open file descriptor</para> | ||
| 1144 | </entry> | ||
| 1145 | </row><row><entry | ||
| 1146 | align="char"> | ||
| 1147 | <para>EINTERNAL</para> | ||
| 1148 | </entry><entry | ||
| 1149 | align="char"> | ||
| 1150 | <para>Internal error.</para> | ||
| 1151 | </entry> | ||
| 1152 | </row><row><entry | ||
| 1153 | align="char"> | ||
| 1154 | <para>EFAULT</para> | ||
| 1155 | </entry><entry | ||
| 1156 | align="char"> | ||
| 1157 | <para>sp points to an invalid iframe.</para> | ||
| 1158 | </entry> | ||
| 1159 | </row></tbody></tgroup></informaltable> | ||
| 1160 | |||
| 1161 | </section><section | ||
| 1162 | role="subsection"><title>VIDEO_FAST_FORWARD</title> | ||
| 1163 | <para>DESCRIPTION | ||
| 1164 | </para> | ||
| 1165 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1166 | align="char"> | ||
| 1167 | <para>This ioctl call asks the Video Device to skip decoding of N number of I-frames. | ||
| 1168 | This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> | ||
| 1169 | </entry> | ||
| 1170 | </row></tbody></tgroup></informaltable> | ||
| 1171 | <para>SYNOPSIS | ||
| 1172 | </para> | ||
| 1173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1174 | align="char"> | ||
| 1175 | <para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int | ||
| 1176 | nFrames);</para> | ||
| 1177 | </entry> | ||
| 1178 | </row></tbody></tgroup></informaltable> | ||
| 1179 | <para>PARAMETERS | ||
| 1180 | </para> | ||
| 1181 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1182 | align="char"> | ||
| 1183 | <para>int fd</para> | ||
| 1184 | </entry><entry | ||
| 1185 | align="char"> | ||
| 1186 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1187 | </entry> | ||
| 1188 | </row><row><entry | ||
| 1189 | align="char"> | ||
| 1190 | <para>int request</para> | ||
| 1191 | </entry><entry | ||
| 1192 | align="char"> | ||
| 1193 | <para>Equals VIDEO_FAST_FORWARD for this command.</para> | ||
| 1194 | </entry> | ||
| 1195 | </row><row><entry | ||
| 1196 | align="char"> | ||
| 1197 | <para>int nFrames</para> | ||
| 1198 | </entry><entry | ||
| 1199 | align="char"> | ||
| 1200 | <para>The number of frames to skip.</para> | ||
| 1201 | </entry> | ||
| 1202 | </row></tbody></tgroup></informaltable> | ||
| 1203 | <para>ERRORS | ||
| 1204 | </para> | ||
| 1205 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1206 | align="char"> | ||
| 1207 | <para>EBADF</para> | ||
| 1208 | </entry><entry | ||
| 1209 | align="char"> | ||
| 1210 | <para>fd is not a valid open file descriptor</para> | ||
| 1211 | </entry> | ||
| 1212 | </row><row><entry | ||
| 1213 | align="char"> | ||
| 1214 | <para>EINTERNAL</para> | ||
| 1215 | </entry><entry | ||
| 1216 | align="char"> | ||
| 1217 | <para>Internal error.</para> | ||
| 1218 | </entry> | ||
| 1219 | </row><row><entry | ||
| 1220 | align="char"> | ||
| 1221 | <para>EPERM</para> | ||
| 1222 | </entry><entry | ||
| 1223 | align="char"> | ||
| 1224 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 1225 | </entry> | ||
| 1226 | </row><row><entry | ||
| 1227 | align="char"> | ||
| 1228 | <para>EINVAL</para> | ||
| 1229 | </entry><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>Illegal parameter format.</para> | ||
| 1232 | </entry> | ||
| 1233 | </row></tbody></tgroup></informaltable> | ||
| 1234 | |||
| 1235 | </section><section | ||
| 1236 | role="subsection"><title>VIDEO_SLOWMOTION</title> | ||
| 1237 | <para>DESCRIPTION | ||
| 1238 | </para> | ||
| 1239 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1240 | align="char"> | ||
| 1241 | <para>This ioctl call asks the video device to repeat decoding frames N number of | ||
| 1242 | times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> | ||
| 1243 | </entry> | ||
| 1244 | </row></tbody></tgroup></informaltable> | ||
| 1245 | <para>SYNOPSIS | ||
| 1246 | </para> | ||
| 1247 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1248 | align="char"> | ||
| 1249 | <para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int | ||
| 1250 | nFrames);</para> | ||
| 1251 | </entry> | ||
| 1252 | </row></tbody></tgroup></informaltable> | ||
| 1253 | <para>PARAMETERS | ||
| 1254 | </para> | ||
| 1255 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1256 | align="char"> | ||
| 1257 | <para>int fd</para> | ||
| 1258 | </entry><entry | ||
| 1259 | align="char"> | ||
| 1260 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1261 | </entry> | ||
| 1262 | </row><row><entry | ||
| 1263 | align="char"> | ||
| 1264 | <para>int request</para> | ||
| 1265 | </entry><entry | ||
| 1266 | align="char"> | ||
| 1267 | <para>Equals VIDEO_SLOWMOTION for this command.</para> | ||
| 1268 | </entry> | ||
| 1269 | </row><row><entry | ||
| 1270 | align="char"> | ||
| 1271 | <para>int nFrames</para> | ||
| 1272 | </entry><entry | ||
| 1273 | align="char"> | ||
| 1274 | <para>The number of times to repeat each frame.</para> | ||
| 1275 | </entry> | ||
| 1276 | </row></tbody></tgroup></informaltable> | ||
| 1277 | <para>ERRORS | ||
| 1278 | </para> | ||
| 1279 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1280 | align="char"> | ||
| 1281 | <para>EBADF</para> | ||
| 1282 | </entry><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>fd is not a valid open file descriptor</para> | ||
| 1285 | </entry> | ||
| 1286 | </row><row><entry | ||
| 1287 | align="char"> | ||
| 1288 | <para>EINTERNAL</para> | ||
| 1289 | </entry><entry | ||
| 1290 | align="char"> | ||
| 1291 | <para>Internal error.</para> | ||
| 1292 | </entry> | ||
| 1293 | </row><row><entry | ||
| 1294 | align="char"> | ||
| 1295 | <para>EPERM</para> | ||
| 1296 | </entry><entry | ||
| 1297 | align="char"> | ||
| 1298 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 1299 | </entry> | ||
| 1300 | </row><row><entry | ||
| 1301 | align="char"> | ||
| 1302 | <para>EINVAL</para> | ||
| 1303 | </entry><entry | ||
| 1304 | align="char"> | ||
| 1305 | <para>Illegal parameter format.</para> | ||
| 1306 | </entry> | ||
| 1307 | </row></tbody></tgroup></informaltable> | ||
| 1308 | |||
| 1309 | </section><section | ||
| 1310 | role="subsection"><title>VIDEO_GET_CAPABILITIES</title> | ||
| 1311 | <para>DESCRIPTION | ||
| 1312 | </para> | ||
| 1313 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1314 | align="char"> | ||
| 1315 | <para>This ioctl call asks the video device about its decoding capabilities. On success | ||
| 1316 | it returns and integer which has bits set according to the defines in section ??.</para> | ||
| 1317 | </entry> | ||
| 1318 | </row></tbody></tgroup></informaltable> | ||
| 1319 | <para>SYNOPSIS | ||
| 1320 | </para> | ||
| 1321 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, | ||
| 1324 | unsigned int ⋆cap);</para> | ||
| 1325 | </entry> | ||
| 1326 | </row></tbody></tgroup></informaltable> | ||
| 1327 | <para>PARAMETERS | ||
| 1328 | </para> | ||
| 1329 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1330 | align="char"> | ||
| 1331 | <para>int fd</para> | ||
| 1332 | </entry><entry | ||
| 1333 | align="char"> | ||
| 1334 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1335 | </entry> | ||
| 1336 | </row><row><entry | ||
| 1337 | align="char"> | ||
| 1338 | <para>int request</para> | ||
| 1339 | </entry><entry | ||
| 1340 | align="char"> | ||
| 1341 | <para>Equals VIDEO_GET_CAPABILITIES for this | ||
| 1342 | command.</para> | ||
| 1343 | </entry> | ||
| 1344 | </row><row><entry | ||
| 1345 | align="char"> | ||
| 1346 | <para>unsigned int *cap</para> | ||
| 1347 | </entry><entry | ||
| 1348 | align="char"> | ||
| 1349 | <para>Pointer to a location where to store the capability | ||
| 1350 | information.</para> | ||
| 1351 | </entry> | ||
| 1352 | </row></tbody></tgroup></informaltable> | ||
| 1353 | <para>ERRORS | ||
| 1354 | </para> | ||
| 1355 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1356 | align="char"> | ||
| 1357 | <para>EBADF</para> | ||
| 1358 | </entry><entry | ||
| 1359 | align="char"> | ||
| 1360 | <para>fd is not a valid open file descriptor</para> | ||
| 1361 | </entry> | ||
| 1362 | </row><row><entry | ||
| 1363 | align="char"> | ||
| 1364 | <para>EFAULT</para> | ||
| 1365 | </entry><entry | ||
| 1366 | align="char"> | ||
| 1367 | <para>cap points to an invalid iframe.</para> | ||
| 1368 | </entry> | ||
| 1369 | </row></tbody></tgroup></informaltable> | ||
| 1370 | |||
| 1371 | </section><section | ||
| 1372 | role="subsection"><title>VIDEO_SET_ID</title> | ||
| 1373 | <para>DESCRIPTION | ||
| 1374 | </para> | ||
| 1375 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1376 | align="char"> | ||
| 1377 | <para>This ioctl selects which sub-stream is to be decoded if a program or system | ||
| 1378 | stream is sent to the video device.</para> | ||
| 1379 | </entry> | ||
| 1380 | </row></tbody></tgroup></informaltable> | ||
| 1381 | <para>SYNOPSIS | ||
| 1382 | </para> | ||
| 1383 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1384 | align="char"> | ||
| 1385 | <para>int ioctl(int fd, int request = VIDEO_SET_ID, int | ||
| 1386 | id);</para> | ||
| 1387 | </entry> | ||
| 1388 | </row></tbody></tgroup></informaltable> | ||
| 1389 | <para>PARAMETERS | ||
| 1390 | </para> | ||
| 1391 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1392 | align="char"> | ||
| 1393 | <para>int fd</para> | ||
| 1394 | </entry><entry | ||
| 1395 | align="char"> | ||
| 1396 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1397 | </entry> | ||
| 1398 | </row><row><entry | ||
| 1399 | align="char"> | ||
| 1400 | <para>int request</para> | ||
| 1401 | </entry><entry | ||
| 1402 | align="char"> | ||
| 1403 | <para>Equals VIDEO_SET_ID for this command.</para> | ||
| 1404 | </entry> | ||
| 1405 | </row><row><entry | ||
| 1406 | align="char"> | ||
| 1407 | <para>int id</para> | ||
| 1408 | </entry><entry | ||
| 1409 | align="char"> | ||
| 1410 | <para>video sub-stream id</para> | ||
| 1411 | </entry> | ||
| 1412 | </row></tbody></tgroup></informaltable> | ||
| 1413 | <para>ERRORS | ||
| 1414 | </para> | ||
| 1415 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1416 | align="char"> | ||
| 1417 | <para>EBADF</para> | ||
| 1418 | </entry><entry | ||
| 1419 | align="char"> | ||
| 1420 | <para>fd is not a valid open file descriptor.</para> | ||
| 1421 | </entry> | ||
| 1422 | </row><row><entry | ||
| 1423 | align="char"> | ||
| 1424 | <para>EINTERNAL</para> | ||
| 1425 | </entry><entry | ||
| 1426 | align="char"> | ||
| 1427 | <para>Internal error.</para> | ||
| 1428 | </entry> | ||
| 1429 | </row><row><entry | ||
| 1430 | align="char"> | ||
| 1431 | <para>EINVAL</para> | ||
| 1432 | </entry><entry | ||
| 1433 | align="char"> | ||
| 1434 | <para>Invalid sub-stream id.</para> | ||
| 1435 | </entry> | ||
| 1436 | </row></tbody></tgroup></informaltable> | ||
| 1437 | |||
| 1438 | </section><section | ||
| 1439 | role="subsection"><title>VIDEO_CLEAR_BUFFER</title> | ||
| 1440 | <para>DESCRIPTION | ||
| 1441 | </para> | ||
| 1442 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1443 | align="char"> | ||
| 1444 | <para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> | ||
| 1445 | </entry> | ||
| 1446 | </row></tbody></tgroup></informaltable> | ||
| 1447 | <para>SYNOPSIS | ||
| 1448 | </para> | ||
| 1449 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1450 | align="char"> | ||
| 1451 | <para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> | ||
| 1452 | </entry> | ||
| 1453 | </row></tbody></tgroup></informaltable> | ||
| 1454 | <para>PARAMETERS | ||
| 1455 | </para> | ||
| 1456 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1457 | align="char"> | ||
| 1458 | <para>int fd</para> | ||
| 1459 | </entry><entry | ||
| 1460 | align="char"> | ||
| 1461 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1462 | </entry> | ||
| 1463 | </row><row><entry | ||
| 1464 | align="char"> | ||
| 1465 | <para>int request</para> | ||
| 1466 | </entry><entry | ||
| 1467 | align="char"> | ||
| 1468 | <para>Equals VIDEO_CLEAR_BUFFER for this command.</para> | ||
| 1469 | </entry> | ||
| 1470 | </row></tbody></tgroup></informaltable> | ||
| 1471 | <para>ERRORS | ||
| 1472 | </para> | ||
| 1473 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1474 | align="char"> | ||
| 1475 | <para>EBADF</para> | ||
| 1476 | </entry><entry | ||
| 1477 | align="char"> | ||
| 1478 | <para>fd is not a valid open file descriptor</para> | ||
| 1479 | </entry> | ||
| 1480 | </row></tbody></tgroup></informaltable> | ||
| 1481 | |||
| 1482 | </section><section | ||
| 1483 | role="subsection"><title>VIDEO_SET_STREAMTYPE</title> | ||
| 1484 | <para>DESCRIPTION | ||
| 1485 | </para> | ||
| 1486 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1487 | align="char"> | ||
| 1488 | <para>This ioctl tells the driver which kind of stream to expect being written to it. If | ||
| 1489 | this call is not used the default of video PES is used. Some drivers might not | ||
| 1490 | support this call and always expect PES.</para> | ||
| 1491 | </entry> | ||
| 1492 | </row></tbody></tgroup></informaltable> | ||
| 1493 | <para>SYNOPSIS | ||
| 1494 | </para> | ||
| 1495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1496 | align="char"> | ||
| 1497 | <para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, | ||
| 1498 | int type);</para> | ||
| 1499 | </entry> | ||
| 1500 | </row></tbody></tgroup></informaltable> | ||
| 1501 | <para>PARAMETERS | ||
| 1502 | </para> | ||
| 1503 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1504 | align="char"> | ||
| 1505 | <para>int fd</para> | ||
| 1506 | </entry><entry | ||
| 1507 | align="char"> | ||
| 1508 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1509 | </entry> | ||
| 1510 | </row><row><entry | ||
| 1511 | align="char"> | ||
| 1512 | <para>int request</para> | ||
| 1513 | </entry><entry | ||
| 1514 | align="char"> | ||
| 1515 | <para>Equals VIDEO_SET_STREAMTYPE for this command.</para> | ||
| 1516 | </entry> | ||
| 1517 | </row><row><entry | ||
| 1518 | align="char"> | ||
| 1519 | <para>int type</para> | ||
| 1520 | </entry><entry | ||
| 1521 | align="char"> | ||
| 1522 | <para>stream type</para> | ||
| 1523 | </entry> | ||
| 1524 | </row></tbody></tgroup></informaltable> | ||
| 1525 | <para>ERRORS | ||
| 1526 | </para> | ||
| 1527 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1528 | align="char"> | ||
| 1529 | <para>EBADF</para> | ||
| 1530 | </entry><entry | ||
| 1531 | align="char"> | ||
| 1532 | <para>fd is not a valid open file descriptor</para> | ||
| 1533 | </entry> | ||
| 1534 | </row><row><entry | ||
| 1535 | align="char"> | ||
| 1536 | <para>EINVAL</para> | ||
| 1537 | </entry><entry | ||
| 1538 | align="char"> | ||
| 1539 | <para>type is not a valid or supported stream type.</para> | ||
| 1540 | </entry> | ||
| 1541 | </row></tbody></tgroup></informaltable> | ||
| 1542 | |||
| 1543 | </section><section | ||
| 1544 | role="subsection"><title>VIDEO_SET_FORMAT</title> | ||
| 1545 | <para>DESCRIPTION | ||
| 1546 | </para> | ||
| 1547 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1548 | align="char"> | ||
| 1549 | <para>This ioctl sets the screen format (aspect ratio) of the connected output device | ||
| 1550 | (TV) so that the output of the decoder can be adjusted accordingly.</para> | ||
| 1551 | </entry> | ||
| 1552 | </row></tbody></tgroup></informaltable> | ||
| 1553 | <para>SYNOPSIS | ||
| 1554 | </para> | ||
| 1555 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1556 | align="char"> | ||
| 1557 | <para> int ioctl(fd, int request = VIDEO_SET_FORMAT, | ||
| 1558 | video_format_t format);</para> | ||
| 1559 | </entry> | ||
| 1560 | </row></tbody></tgroup></informaltable> | ||
| 1561 | <para>PARAMETERS | ||
| 1562 | </para> | ||
| 1563 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1564 | align="char"> | ||
| 1565 | <para>int fd</para> | ||
| 1566 | </entry><entry | ||
| 1567 | align="char"> | ||
| 1568 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1569 | </entry> | ||
| 1570 | </row><row><entry | ||
| 1571 | align="char"> | ||
| 1572 | <para>int request</para> | ||
| 1573 | </entry><entry | ||
| 1574 | align="char"> | ||
| 1575 | <para>Equals VIDEO_SET_FORMAT for this command.</para> | ||
| 1576 | </entry> | ||
| 1577 | </row><row><entry | ||
| 1578 | align="char"> | ||
| 1579 | <para>video_format_t | ||
| 1580 | format</para> | ||
| 1581 | </entry><entry | ||
| 1582 | align="char"> | ||
| 1583 | <para>video format of TV as defined in section ??.</para> | ||
| 1584 | </entry> | ||
| 1585 | </row></tbody></tgroup></informaltable> | ||
| 1586 | <para>ERRORS | ||
| 1587 | </para> | ||
| 1588 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1589 | align="char"> | ||
| 1590 | <para>EBADF</para> | ||
| 1591 | </entry><entry | ||
| 1592 | align="char"> | ||
| 1593 | <para>fd is not a valid open file descriptor</para> | ||
| 1594 | </entry> | ||
| 1595 | </row><row><entry | ||
| 1596 | align="char"> | ||
| 1597 | <para>EINVAL</para> | ||
| 1598 | </entry><entry | ||
| 1599 | align="char"> | ||
| 1600 | <para>format is not a valid video format.</para> | ||
| 1601 | </entry> | ||
| 1602 | </row></tbody></tgroup></informaltable> | ||
| 1603 | |||
| 1604 | </section><section | ||
| 1605 | role="subsection"><title>VIDEO_SET_SYSTEM</title> | ||
| 1606 | <para>DESCRIPTION | ||
| 1607 | </para> | ||
| 1608 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1609 | align="char"> | ||
| 1610 | <para>This ioctl sets the television output format. The format (see section ??) may | ||
| 1611 | vary from the color format of the displayed MPEG stream. If the hardware is | ||
| 1612 | not able to display the requested format the call will return an error.</para> | ||
| 1613 | </entry> | ||
| 1614 | </row></tbody></tgroup></informaltable> | ||
| 1615 | <para>SYNOPSIS | ||
| 1616 | </para> | ||
| 1617 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1618 | align="char"> | ||
| 1619 | <para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , | ||
| 1620 | video_system_t system);</para> | ||
| 1621 | </entry> | ||
| 1622 | </row></tbody></tgroup></informaltable> | ||
| 1623 | <para>PARAMETERS | ||
| 1624 | </para> | ||
| 1625 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1626 | align="char"> | ||
| 1627 | <para>int fd</para> | ||
| 1628 | </entry><entry | ||
| 1629 | align="char"> | ||
| 1630 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1631 | </entry> | ||
| 1632 | </row><row><entry | ||
| 1633 | align="char"> | ||
| 1634 | <para>int request</para> | ||
| 1635 | </entry><entry | ||
| 1636 | align="char"> | ||
| 1637 | <para>Equals VIDEO_SET_FORMAT for this command.</para> | ||
| 1638 | </entry> | ||
| 1639 | </row><row><entry | ||
| 1640 | align="char"> | ||
| 1641 | <para>video_system_t | ||
| 1642 | system</para> | ||
| 1643 | </entry><entry | ||
| 1644 | align="char"> | ||
| 1645 | <para>video system of TV output.</para> | ||
| 1646 | </entry> | ||
| 1647 | </row></tbody></tgroup></informaltable> | ||
| 1648 | <para>ERRORS | ||
| 1649 | </para> | ||
| 1650 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1651 | align="char"> | ||
| 1652 | <para>EBADF</para> | ||
| 1653 | </entry><entry | ||
| 1654 | align="char"> | ||
| 1655 | <para>fd is not a valid open file descriptor</para> | ||
| 1656 | </entry> | ||
| 1657 | </row><row><entry | ||
| 1658 | align="char"> | ||
| 1659 | <para>EINVAL</para> | ||
| 1660 | </entry><entry | ||
| 1661 | align="char"> | ||
| 1662 | <para>system is not a valid or supported video system.</para> | ||
| 1663 | </entry> | ||
| 1664 | </row></tbody></tgroup></informaltable> | ||
| 1665 | |||
| 1666 | </section><section | ||
| 1667 | role="subsection"><title>VIDEO_SET_HIGHLIGHT</title> | ||
| 1668 | <para>DESCRIPTION | ||
| 1669 | </para> | ||
| 1670 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1671 | align="char"> | ||
| 1672 | <para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> | ||
| 1673 | </entry> | ||
| 1674 | </row></tbody></tgroup></informaltable> | ||
| 1675 | <para>SYNOPSIS | ||
| 1676 | </para> | ||
| 1677 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1678 | align="char"> | ||
| 1679 | <para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT | ||
| 1680 | ,video_highlight_t ⋆vhilite)</para> | ||
| 1681 | </entry> | ||
| 1682 | </row></tbody></tgroup></informaltable> | ||
| 1683 | <para>PARAMETERS | ||
| 1684 | </para> | ||
| 1685 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1686 | align="char"> | ||
| 1687 | <para>int fd</para> | ||
| 1688 | </entry><entry | ||
| 1689 | align="char"> | ||
| 1690 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1691 | </entry> | ||
| 1692 | </row><row><entry | ||
| 1693 | align="char"> | ||
| 1694 | <para>int request</para> | ||
| 1695 | </entry><entry | ||
| 1696 | align="char"> | ||
| 1697 | <para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> | ||
| 1698 | </entry> | ||
| 1699 | </row><row><entry | ||
| 1700 | align="char"> | ||
| 1701 | <para>video_highlight_t | ||
| 1702 | *vhilite</para> | ||
| 1703 | </entry><entry | ||
| 1704 | align="char"> | ||
| 1705 | <para>SPU Highlight information according to section ??.</para> | ||
| 1706 | </entry> | ||
| 1707 | </row></tbody></tgroup></informaltable> | ||
| 1708 | <para>ERRORS | ||
| 1709 | </para> | ||
| 1710 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>EBADF</para> | ||
| 1713 | </entry><entry | ||
| 1714 | align="char"> | ||
| 1715 | <para>fd is not a valid open file descriptor.</para> | ||
| 1716 | </entry> | ||
| 1717 | </row><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>EINVAL</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>input is not a valid highlight setting.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row></tbody></tgroup></informaltable> | ||
| 1725 | |||
| 1726 | </section><section | ||
| 1727 | role="subsection"><title>VIDEO_SET_SPU</title> | ||
| 1728 | <para>DESCRIPTION | ||
| 1729 | </para> | ||
| 1730 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1731 | align="char"> | ||
| 1732 | <para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can | ||
| 1733 | only be used, if the driver is able to handle a DVD stream.</para> | ||
| 1734 | </entry> | ||
| 1735 | </row></tbody></tgroup></informaltable> | ||
| 1736 | <para>SYNOPSIS | ||
| 1737 | </para> | ||
| 1738 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1739 | align="char"> | ||
| 1740 | <para> int ioctl(fd, int request = VIDEO_SET_SPU , | ||
| 1741 | video_spu_t ⋆spu)</para> | ||
| 1742 | </entry> | ||
| 1743 | </row></tbody></tgroup></informaltable> | ||
| 1744 | <para>PARAMETERS | ||
| 1745 | </para> | ||
| 1746 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1747 | align="char"> | ||
| 1748 | <para>int fd</para> | ||
| 1749 | </entry><entry | ||
| 1750 | align="char"> | ||
| 1751 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1752 | </entry> | ||
| 1753 | </row><row><entry | ||
| 1754 | align="char"> | ||
| 1755 | <para>int request</para> | ||
| 1756 | </entry><entry | ||
| 1757 | align="char"> | ||
| 1758 | <para>Equals VIDEO_SET_SPU for this command.</para> | ||
| 1759 | </entry> | ||
| 1760 | </row><row><entry | ||
| 1761 | align="char"> | ||
| 1762 | <para>video_spu_t *spu</para> | ||
| 1763 | </entry><entry | ||
| 1764 | align="char"> | ||
| 1765 | <para>SPU decoding (de)activation and subid setting according | ||
| 1766 | to section ??.</para> | ||
| 1767 | </entry> | ||
| 1768 | </row></tbody></tgroup></informaltable> | ||
| 1769 | <para>ERRORS | ||
| 1770 | </para> | ||
| 1771 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1772 | align="char"> | ||
| 1773 | <para>EBADF</para> | ||
| 1774 | </entry><entry | ||
| 1775 | align="char"> | ||
| 1776 | <para>fd is not a valid open file descriptor</para> | ||
| 1777 | </entry> | ||
| 1778 | </row><row><entry | ||
| 1779 | align="char"> | ||
| 1780 | <para>EINVAL</para> | ||
| 1781 | </entry><entry | ||
| 1782 | align="char"> | ||
| 1783 | <para>input is not a valid spu setting or driver cannot handle | ||
| 1784 | SPU.</para> | ||
| 1785 | </entry> | ||
| 1786 | </row></tbody></tgroup></informaltable> | ||
| 1787 | |||
| 1788 | </section><section | ||
| 1789 | role="subsection"><title>VIDEO_SET_SPU_PALETTE</title> | ||
| 1790 | <para>DESCRIPTION | ||
| 1791 | </para> | ||
| 1792 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1793 | align="char"> | ||
| 1794 | <para>This ioctl sets the SPU color palette.</para> | ||
| 1795 | </entry> | ||
| 1796 | </row></tbody></tgroup></informaltable> | ||
| 1797 | <para>SYNOPSIS | ||
| 1798 | </para> | ||
| 1799 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1800 | align="char"> | ||
| 1801 | <para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE | ||
| 1802 | ,video_spu_palette_t ⋆palette )</para> | ||
| 1803 | </entry> | ||
| 1804 | </row></tbody></tgroup></informaltable> | ||
| 1805 | <para>PARAMETERS | ||
| 1806 | </para> | ||
| 1807 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1808 | align="char"> | ||
| 1809 | <para>int fd</para> | ||
| 1810 | </entry><entry | ||
| 1811 | align="char"> | ||
| 1812 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1813 | </entry> | ||
| 1814 | </row><row><entry | ||
| 1815 | align="char"> | ||
| 1816 | <para>int request</para> | ||
| 1817 | </entry><entry | ||
| 1818 | align="char"> | ||
| 1819 | <para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> | ||
| 1820 | </entry> | ||
| 1821 | </row><row><entry | ||
| 1822 | align="char"> | ||
| 1823 | <para>video_spu_palette_t | ||
| 1824 | *palette</para> | ||
| 1825 | </entry><entry | ||
| 1826 | align="char"> | ||
| 1827 | <para>SPU palette according to section ??.</para> | ||
| 1828 | </entry> | ||
| 1829 | </row></tbody></tgroup></informaltable> | ||
| 1830 | <para>ERRORS | ||
| 1831 | </para> | ||
| 1832 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1833 | align="char"> | ||
| 1834 | <para>EBADF</para> | ||
| 1835 | </entry><entry | ||
| 1836 | align="char"> | ||
| 1837 | <para>fd is not a valid open file descriptor</para> | ||
| 1838 | </entry> | ||
| 1839 | </row><row><entry | ||
| 1840 | align="char"> | ||
| 1841 | <para>EINVAL</para> | ||
| 1842 | </entry><entry | ||
| 1843 | align="char"> | ||
| 1844 | <para>input is not a valid palette or driver doesn’t handle SPU.</para> | ||
| 1845 | </entry> | ||
| 1846 | </row></tbody></tgroup></informaltable> | ||
| 1847 | |||
| 1848 | </section><section | ||
| 1849 | role="subsection"><title>VIDEO_GET_NAVI</title> | ||
| 1850 | <para>DESCRIPTION | ||
| 1851 | </para> | ||
| 1852 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1853 | align="char"> | ||
| 1854 | <para>This ioctl returns navigational information from the DVD stream. This is | ||
| 1855 | especially needed if an encoded stream has to be decoded by the hardware.</para> | ||
| 1856 | </entry> | ||
| 1857 | </row></tbody></tgroup></informaltable> | ||
| 1858 | <para>SYNOPSIS | ||
| 1859 | </para> | ||
| 1860 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1861 | align="char"> | ||
| 1862 | <para> int ioctl(fd, int request = VIDEO_GET_NAVI , | ||
| 1863 | video_navi_pack_t ⋆navipack)</para> | ||
| 1864 | </entry> | ||
| 1865 | </row></tbody></tgroup></informaltable> | ||
| 1866 | <para>PARAMETERS | ||
| 1867 | </para> | ||
| 1868 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1869 | align="char"> | ||
| 1870 | <para>int fd</para> | ||
| 1871 | </entry><entry | ||
| 1872 | align="char"> | ||
| 1873 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1874 | </entry> | ||
| 1875 | </row><row><entry | ||
| 1876 | align="char"> | ||
| 1877 | <para>int request</para> | ||
| 1878 | </entry><entry | ||
| 1879 | align="char"> | ||
| 1880 | <para>Equals VIDEO_GET_NAVI for this command.</para> | ||
| 1881 | </entry> | ||
| 1882 | </row><row><entry | ||
| 1883 | align="char"> | ||
| 1884 | <para>video_navi_pack_t | ||
| 1885 | *navipack</para> | ||
| 1886 | </entry><entry | ||
| 1887 | align="char"> | ||
| 1888 | <para>PCI or DSI pack (private stream 2) according to section | ||
| 1889 | ??.</para> | ||
| 1890 | </entry> | ||
| 1891 | </row></tbody></tgroup></informaltable> | ||
| 1892 | <para>ERRORS | ||
| 1893 | </para> | ||
| 1894 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1895 | align="char"> | ||
| 1896 | <para>EBADF</para> | ||
| 1897 | </entry><entry | ||
| 1898 | align="char"> | ||
| 1899 | <para>fd is not a valid open file descriptor</para> | ||
| 1900 | </entry> | ||
| 1901 | </row><row><entry | ||
| 1902 | align="char"> | ||
| 1903 | <para>EFAULT</para> | ||
| 1904 | </entry><entry | ||
| 1905 | align="char"> | ||
| 1906 | <para>driver is not able to return navigational information</para> | ||
| 1907 | </entry> | ||
| 1908 | </row></tbody></tgroup></informaltable> | ||
| 1909 | |||
| 1910 | </section><section | ||
| 1911 | role="subsection"><title>VIDEO_SET_ATTRIBUTES</title> | ||
| 1912 | <para>DESCRIPTION | ||
| 1913 | </para> | ||
| 1914 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1915 | align="char"> | ||
| 1916 | <para>This ioctl is intended for DVD playback and allows you to set certain | ||
| 1917 | information about the stream. Some hardware may not need this information, | ||
| 1918 | but the call also tells the hardware to prepare for DVD playback.</para> | ||
| 1919 | </entry> | ||
| 1920 | </row></tbody></tgroup></informaltable> | ||
| 1921 | <para>SYNOPSIS | ||
| 1922 | </para> | ||
| 1923 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1924 | align="char"> | ||
| 1925 | <para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE | ||
| 1926 | ,video_attributes_t vattr)</para> | ||
| 1927 | </entry> | ||
| 1928 | </row></tbody></tgroup></informaltable> | ||
| 1929 | <para>PARAMETERS | ||
| 1930 | </para> | ||
| 1931 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1932 | align="char"> | ||
| 1933 | <para>int fd</para> | ||
| 1934 | </entry><entry | ||
| 1935 | align="char"> | ||
| 1936 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1937 | </entry> | ||
| 1938 | </row><row><entry | ||
| 1939 | align="char"> | ||
| 1940 | <para>int request</para> | ||
| 1941 | </entry><entry | ||
| 1942 | align="char"> | ||
| 1943 | <para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> | ||
| 1944 | </entry> | ||
| 1945 | </row><row><entry | ||
| 1946 | align="char"> | ||
| 1947 | <para>video_attributes_t | ||
| 1948 | vattr</para> | ||
| 1949 | </entry><entry | ||
| 1950 | align="char"> | ||
| 1951 | <para>video attributes according to section ??.</para> | ||
| 1952 | </entry> | ||
| 1953 | </row></tbody></tgroup></informaltable> | ||
| 1954 | <para>ERRORS | ||
| 1955 | </para> | ||
| 1956 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1957 | align="char"> | ||
| 1958 | <para>EBADF</para> | ||
| 1959 | </entry><entry | ||
| 1960 | align="char"> | ||
| 1961 | <para>fd is not a valid open file descriptor</para> | ||
| 1962 | </entry> | ||
| 1963 | </row><row><entry | ||
| 1964 | align="char"> | ||
| 1965 | <para>EINVAL</para> | ||
| 1966 | </entry><entry | ||
| 1967 | align="char"> | ||
| 1968 | <para>input is not a valid attribute setting.</para> | ||
| 1969 | </entry> | ||
| 1970 | </row></tbody></tgroup></informaltable> | ||
| 1971 | </section></section> | ||
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index a50d6cd58573..992e67e6be7f 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl | |||
| @@ -449,8 +449,8 @@ printk(KERN_INFO "i = %u\n", i); | |||
| 449 | </para> | 449 | </para> |
| 450 | 450 | ||
| 451 | <programlisting> | 451 | <programlisting> |
| 452 | __u32 ipaddress; | 452 | __be32 ipaddress; |
| 453 | printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress)); | 453 | printk(KERN_INFO "my ip: %pI4\n", &ipaddress); |
| 454 | </programlisting> | 454 | </programlisting> |
| 455 | 455 | ||
| 456 | <para> | 456 | <para> |
diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl index e36986663570..f3f37f141dbd 100644 --- a/Documentation/DocBook/mac80211.tmpl +++ b/Documentation/DocBook/mac80211.tmpl | |||
| @@ -184,8 +184,6 @@ usage should require reading the full document. | |||
| 184 | !Finclude/net/mac80211.h ieee80211_ctstoself_get | 184 | !Finclude/net/mac80211.h ieee80211_ctstoself_get |
| 185 | !Finclude/net/mac80211.h ieee80211_ctstoself_duration | 185 | !Finclude/net/mac80211.h ieee80211_ctstoself_duration |
| 186 | !Finclude/net/mac80211.h ieee80211_generic_frame_duration | 186 | !Finclude/net/mac80211.h ieee80211_generic_frame_duration |
| 187 | !Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb | ||
| 188 | !Finclude/net/mac80211.h ieee80211_hdrlen | ||
| 189 | !Finclude/net/mac80211.h ieee80211_wake_queue | 187 | !Finclude/net/mac80211.h ieee80211_wake_queue |
| 190 | !Finclude/net/mac80211.h ieee80211_stop_queue | 188 | !Finclude/net/mac80211.h ieee80211_stop_queue |
| 191 | !Finclude/net/mac80211.h ieee80211_wake_queues | 189 | !Finclude/net/mac80211.h ieee80211_wake_queues |
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl new file mode 100644 index 000000000000..0eb43c1970bb --- /dev/null +++ b/Documentation/DocBook/media-entities.tmpl | |||
| @@ -0,0 +1,364 @@ | |||
| 1 | <!-- Generated file! Do not edit. --> | ||
| 2 | |||
| 3 | <!-- Functions --> | ||
| 4 | <!ENTITY func-close "<link linkend='func-close'><function>close()</function></link>"> | ||
| 5 | <!ENTITY func-ioctl "<link linkend='func-ioctl'><function>ioctl()</function></link>"> | ||
| 6 | <!ENTITY func-mmap "<link linkend='func-mmap'><function>mmap()</function></link>"> | ||
| 7 | <!ENTITY func-munmap "<link linkend='func-munmap'><function>munmap()</function></link>"> | ||
| 8 | <!ENTITY func-open "<link linkend='func-open'><function>open()</function></link>"> | ||
| 9 | <!ENTITY func-poll "<link linkend='func-poll'><function>poll()</function></link>"> | ||
| 10 | <!ENTITY func-read "<link linkend='func-read'><function>read()</function></link>"> | ||
| 11 | <!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>"> | ||
| 12 | <!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>"> | ||
| 13 | |||
| 14 | <!-- Ioctls --> | ||
| 15 | <!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>"> | ||
| 16 | <!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>"> | ||
| 17 | <!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>"> | ||
| 18 | <!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>"> | ||
| 19 | <!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>"> | ||
| 20 | <!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>"> | ||
| 21 | <!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>"> | ||
| 22 | <!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>"> | ||
| 23 | <!ENTITY VIDIOC-ENUMINPUT "<link linkend='vidioc-enuminput'><constant>VIDIOC_ENUMINPUT</constant></link>"> | ||
| 24 | <!ENTITY VIDIOC-ENUMOUTPUT "<link linkend='vidioc-enumoutput'><constant>VIDIOC_ENUMOUTPUT</constant></link>"> | ||
| 25 | <!ENTITY VIDIOC-ENUMSTD "<link linkend='vidioc-enumstd'><constant>VIDIOC_ENUMSTD</constant></link>"> | ||
| 26 | <!ENTITY VIDIOC-ENUM-FMT "<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>"> | ||
| 27 | <!ENTITY VIDIOC-ENUM-FRAMEINTERVALS "<link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>"> | ||
| 28 | <!ENTITY VIDIOC-ENUM-FRAMESIZES "<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>"> | ||
| 29 | <!ENTITY VIDIOC-G-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_G_AUDIO</constant></link>"> | ||
| 30 | <!ENTITY VIDIOC-G-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_G_AUDOUT</constant></link>"> | ||
| 31 | <!ENTITY VIDIOC-G-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_G_CROP</constant></link>"> | ||
| 32 | <!ENTITY VIDIOC-G-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_G_CTRL</constant></link>"> | ||
| 33 | <!ENTITY VIDIOC-G-ENC-INDEX "<link linkend='vidioc-g-enc-index'><constant>VIDIOC_G_ENC_INDEX</constant></link>"> | ||
| 34 | <!ENTITY VIDIOC-G-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_G_EXT_CTRLS</constant></link>"> | ||
| 35 | <!ENTITY VIDIOC-G-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_G_FBUF</constant></link>"> | ||
| 36 | <!ENTITY VIDIOC-G-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>"> | ||
| 37 | <!ENTITY VIDIOC-G-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_G_FREQUENCY</constant></link>"> | ||
| 38 | <!ENTITY VIDIOC-G-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_G_INPUT</constant></link>"> | ||
| 39 | <!ENTITY VIDIOC-G-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_G_JPEGCOMP</constant></link>"> | ||
| 40 | <!ENTITY VIDIOC-G-MPEGCOMP "<link linkend=''><constant>VIDIOC_G_MPEGCOMP</constant></link>"> | ||
| 41 | <!ENTITY VIDIOC-G-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_G_MODULATOR</constant></link>"> | ||
| 42 | <!ENTITY VIDIOC-G-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_G_OUTPUT</constant></link>"> | ||
| 43 | <!ENTITY VIDIOC-G-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_G_PARM</constant></link>"> | ||
| 44 | <!ENTITY VIDIOC-G-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_G_PRIORITY</constant></link>"> | ||
| 45 | <!ENTITY VIDIOC-G-SLICED-VBI-CAP "<link linkend='vidioc-g-sliced-vbi-cap'><constant>VIDIOC_G_SLICED_VBI_CAP</constant></link>"> | ||
| 46 | <!ENTITY VIDIOC-G-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_G_STD</constant></link>"> | ||
| 47 | <!ENTITY VIDIOC-G-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_G_TUNER</constant></link>"> | ||
| 48 | <!ENTITY VIDIOC-LOG-STATUS "<link linkend='vidioc-log-status'><constant>VIDIOC_LOG_STATUS</constant></link>"> | ||
| 49 | <!ENTITY VIDIOC-OVERLAY "<link linkend='vidioc-overlay'><constant>VIDIOC_OVERLAY</constant></link>"> | ||
| 50 | <!ENTITY VIDIOC-QBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_QBUF</constant></link>"> | ||
| 51 | <!ENTITY VIDIOC-QUERYBUF "<link linkend='vidioc-querybuf'><constant>VIDIOC_QUERYBUF</constant></link>"> | ||
| 52 | <!ENTITY VIDIOC-QUERYCAP "<link linkend='vidioc-querycap'><constant>VIDIOC_QUERYCAP</constant></link>"> | ||
| 53 | <!ENTITY VIDIOC-QUERYCTRL "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYCTRL</constant></link>"> | ||
| 54 | <!ENTITY VIDIOC-QUERYMENU "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYMENU</constant></link>"> | ||
| 55 | <!ENTITY VIDIOC-QUERYSTD "<link linkend='vidioc-querystd'><constant>VIDIOC_QUERYSTD</constant></link>"> | ||
| 56 | <!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>"> | ||
| 57 | <!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>"> | ||
| 58 | <!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>"> | ||
| 59 | <!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>"> | ||
| 60 | <!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>"> | ||
| 61 | <!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>"> | ||
| 62 | <!ENTITY VIDIOC-S-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_S_CTRL</constant></link>"> | ||
| 63 | <!ENTITY VIDIOC-S-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_S_EXT_CTRLS</constant></link>"> | ||
| 64 | <!ENTITY VIDIOC-S-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_S_FBUF</constant></link>"> | ||
| 65 | <!ENTITY VIDIOC-S-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>"> | ||
| 66 | <!ENTITY VIDIOC-S-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_S_FREQUENCY</constant></link>"> | ||
| 67 | <!ENTITY VIDIOC-S-HW-FREQ-SEEK "<link linkend='vidioc-s-hw-freq-seek'><constant>VIDIOC_S_HW_FREQ_SEEK</constant></link>"> | ||
| 68 | <!ENTITY VIDIOC-S-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_S_INPUT</constant></link>"> | ||
| 69 | <!ENTITY VIDIOC-S-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_S_JPEGCOMP</constant></link>"> | ||
| 70 | <!ENTITY VIDIOC-S-MPEGCOMP "<link linkend=''><constant>VIDIOC_S_MPEGCOMP</constant></link>"> | ||
| 71 | <!ENTITY VIDIOC-S-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_S_MODULATOR</constant></link>"> | ||
| 72 | <!ENTITY VIDIOC-S-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_S_OUTPUT</constant></link>"> | ||
| 73 | <!ENTITY VIDIOC-S-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_S_PARM</constant></link>"> | ||
| 74 | <!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>"> | ||
| 75 | <!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>"> | ||
| 76 | <!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>"> | ||
| 77 | <!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>"> | ||
| 78 | <!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>"> | ||
| 79 | <!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> | ||
| 80 | |||
| 81 | <!-- Types --> | ||
| 82 | <!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> | ||
| 83 | |||
| 84 | <!-- Enums --> | ||
| 85 | <!ENTITY v4l2-buf-type "enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link>"> | ||
| 86 | <!ENTITY v4l2-colorspace "enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link>"> | ||
| 87 | <!ENTITY v4l2-ctrl-type "enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link>"> | ||
| 88 | <!ENTITY v4l2-exposure-auto-type "enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link>"> | ||
| 89 | <!ENTITY v4l2-field "enum <link linkend='v4l2-field'>v4l2_field</link>"> | ||
| 90 | <!ENTITY v4l2-frmivaltypes "enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>"> | ||
| 91 | <!ENTITY v4l2-frmsizetypes "enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>"> | ||
| 92 | <!ENTITY v4l2-memory "enum <link linkend='v4l2-memory'>v4l2_memory</link>"> | ||
| 93 | <!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>"> | ||
| 94 | <!ENTITY v4l2-mpeg-audio-crc "enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>"> | ||
| 95 | <!ENTITY v4l2-mpeg-audio-emphasis "enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link>"> | ||
| 96 | <!ENTITY v4l2-mpeg-audio-encoding "enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link>"> | ||
| 97 | <!ENTITY v4l2-mpeg-audio-l1-bitrate "enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link>"> | ||
| 98 | <!ENTITY v4l2-mpeg-audio-l2-bitrate "enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link>"> | ||
| 99 | <!ENTITY v4l2-mpeg-audio-l3-bitrate "enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link>"> | ||
| 100 | <!ENTITY v4l2-mpeg-audio-mode "enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link>"> | ||
| 101 | <!ENTITY v4l2-mpeg-audio-mode-extension "enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link>"> | ||
| 102 | <!ENTITY v4l2-mpeg-audio-sampling-freq "enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link>"> | ||
| 103 | <!ENTITY chroma-spatial-filter-type "enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link>"> | ||
| 104 | <!ENTITY luma-spatial-filter-type "enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link>"> | ||
| 105 | <!ENTITY v4l2-mpeg-cx2341x-video-median-filter-type "enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link>"> | ||
| 106 | <!ENTITY v4l2-mpeg-cx2341x-video-spatial-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link>"> | ||
| 107 | <!ENTITY v4l2-mpeg-cx2341x-video-temporal-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link>"> | ||
| 108 | <!ENTITY v4l2-mpeg-stream-type "enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link>"> | ||
| 109 | <!ENTITY v4l2-mpeg-stream-vbi-fmt "enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link>"> | ||
| 110 | <!ENTITY v4l2-mpeg-video-aspect "enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link>"> | ||
| 111 | <!ENTITY v4l2-mpeg-video-bitrate-mode "enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link>"> | ||
| 112 | <!ENTITY v4l2-mpeg-video-encoding "enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>"> | ||
| 113 | <!ENTITY v4l2-power-line-frequency "enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>"> | ||
| 114 | <!ENTITY v4l2-priority "enum <link linkend='v4l2-priority'>v4l2_priority</link>"> | ||
| 115 | <!ENTITY v4l2-tuner-type "enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>"> | ||
| 116 | <!ENTITY v4l2-preemphasis "enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>"> | ||
| 117 | |||
| 118 | <!-- Structures --> | ||
| 119 | <!ENTITY v4l2-audio "struct <link linkend='v4l2-audio'>v4l2_audio</link>"> | ||
| 120 | <!ENTITY v4l2-audioout "struct <link linkend='v4l2-audioout'>v4l2_audioout</link>"> | ||
| 121 | <!ENTITY v4l2-buffer "struct <link linkend='v4l2-buffer'>v4l2_buffer</link>"> | ||
| 122 | <!ENTITY v4l2-capability "struct <link linkend='v4l2-capability'>v4l2_capability</link>"> | ||
| 123 | <!ENTITY v4l2-captureparm "struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link>"> | ||
| 124 | <!ENTITY v4l2-clip "struct <link linkend='v4l2-clip'>v4l2_clip</link>"> | ||
| 125 | <!ENTITY v4l2-control "struct <link linkend='v4l2-control'>v4l2_control</link>"> | ||
| 126 | <!ENTITY v4l2-crop "struct <link linkend='v4l2-crop'>v4l2_crop</link>"> | ||
| 127 | <!ENTITY v4l2-cropcap "struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link>"> | ||
| 128 | <!ENTITY v4l2-dbg-chip-ident "struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>"> | ||
| 129 | <!ENTITY v4l2-dbg-match "struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>"> | ||
| 130 | <!ENTITY v4l2-dbg-register "struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>"> | ||
| 131 | <!ENTITY v4l2-enc-idx "struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>"> | ||
| 132 | <!ENTITY v4l2-enc-idx-entry "struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>"> | ||
| 133 | <!ENTITY v4l2-encoder-cmd "struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>"> | ||
| 134 | <!ENTITY v4l2-ext-control "struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link>"> | ||
| 135 | <!ENTITY v4l2-ext-controls "struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>"> | ||
| 136 | <!ENTITY v4l2-fmtdesc "struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>"> | ||
| 137 | <!ENTITY v4l2-format "struct <link linkend='v4l2-format'>v4l2_format</link>"> | ||
| 138 | <!ENTITY v4l2-fract "struct <link linkend='v4l2-fract'>v4l2_fract</link>"> | ||
| 139 | <!ENTITY v4l2-framebuffer "struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link>"> | ||
| 140 | <!ENTITY v4l2-frequency "struct <link linkend='v4l2-frequency'>v4l2_frequency</link>"> | ||
| 141 | <!ENTITY v4l2-frmival-stepwise "struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link>"> | ||
| 142 | <!ENTITY v4l2-frmivalenum "struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link>"> | ||
| 143 | <!ENTITY v4l2-frmsize-discrete "struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link>"> | ||
| 144 | <!ENTITY v4l2-frmsize-stepwise "struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link>"> | ||
| 145 | <!ENTITY v4l2-frmsizeenum "struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link>"> | ||
| 146 | <!ENTITY v4l2-hw-freq-seek "struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>"> | ||
| 147 | <!ENTITY v4l2-input "struct <link linkend='v4l2-input'>v4l2_input</link>"> | ||
| 148 | <!ENTITY v4l2-jpegcompression "struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>"> | ||
| 149 | <!ENTITY v4l2-modulator "struct <link linkend='v4l2-modulator'>v4l2_modulator</link>"> | ||
| 150 | <!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>"> | ||
| 151 | <!ENTITY v4l2-output "struct <link linkend='v4l2-output'>v4l2_output</link>"> | ||
| 152 | <!ENTITY v4l2-outputparm "struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link>"> | ||
| 153 | <!ENTITY v4l2-pix-format "struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link>"> | ||
| 154 | <!ENTITY v4l2-queryctrl "struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>"> | ||
| 155 | <!ENTITY v4l2-querymenu "struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link>"> | ||
| 156 | <!ENTITY v4l2-rect "struct <link linkend='v4l2-rect'>v4l2_rect</link>"> | ||
| 157 | <!ENTITY v4l2-requestbuffers "struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link>"> | ||
| 158 | <!ENTITY v4l2-sliced-vbi-cap "struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>"> | ||
| 159 | <!ENTITY v4l2-sliced-vbi-data "struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>"> | ||
| 160 | <!ENTITY v4l2-sliced-vbi-format "struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>"> | ||
| 161 | <!ENTITY v4l2-standard "struct <link linkend='v4l2-standard'>v4l2_standard</link>"> | ||
| 162 | <!ENTITY v4l2-streamparm "struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link>"> | ||
| 163 | <!ENTITY v4l2-timecode "struct <link linkend='v4l2-timecode'>v4l2_timecode</link>"> | ||
| 164 | <!ENTITY v4l2-tuner "struct <link linkend='v4l2-tuner'>v4l2_tuner</link>"> | ||
| 165 | <!ENTITY v4l2-vbi-format "struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>"> | ||
| 166 | <!ENTITY v4l2-window "struct <link linkend='v4l2-window'>v4l2_window</link>"> | ||
| 167 | |||
| 168 | <!-- Error Codes --> | ||
| 169 | <!ENTITY EACCES "<errorcode>EACCES</errorcode> error code"> | ||
| 170 | <!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code"> | ||
| 171 | <!ENTITY EBADF "<errorcode>EBADF</errorcode> error code"> | ||
| 172 | <!ENTITY EBUSY "<errorcode>EBUSY</errorcode> error code"> | ||
| 173 | <!ENTITY EFAULT "<errorcode>EFAULT</errorcode> error code"> | ||
| 174 | <!ENTITY EIO "<errorcode>EIO</errorcode> error code"> | ||
| 175 | <!ENTITY EINTR "<errorcode>EINTR</errorcode> error code"> | ||
| 176 | <!ENTITY EINVAL "<errorcode>EINVAL</errorcode> error code"> | ||
| 177 | <!ENTITY ENFILE "<errorcode>ENFILE</errorcode> error code"> | ||
| 178 | <!ENTITY ENOMEM "<errorcode>ENOMEM</errorcode> error code"> | ||
| 179 | <!ENTITY ENOSPC "<errorcode>ENOSPC</errorcode> error code"> | ||
| 180 | <!ENTITY ENOTTY "<errorcode>ENOTTY</errorcode> error code"> | ||
| 181 | <!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code"> | ||
| 182 | <!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code"> | ||
| 183 | <!ENTITY EPERM "<errorcode>EPERM</errorcode> error code"> | ||
| 184 | <!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code"> | ||
| 185 | |||
| 186 | <!-- Subsections --> | ||
| 187 | <!ENTITY sub-biblio SYSTEM "v4l/biblio.xml"> | ||
| 188 | <!ENTITY sub-common SYSTEM "v4l/common.xml"> | ||
| 189 | <!ENTITY sub-compat SYSTEM "v4l/compat.xml"> | ||
| 190 | <!ENTITY sub-controls SYSTEM "v4l/controls.xml"> | ||
| 191 | <!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml"> | ||
| 192 | <!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml"> | ||
| 193 | <!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml"> | ||
| 194 | <!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml"> | ||
| 195 | <!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml"> | ||
| 196 | <!ENTITY sub-dev-overlay SYSTEM "v4l/dev-overlay.xml"> | ||
| 197 | <!ENTITY sub-dev-radio SYSTEM "v4l/dev-radio.xml"> | ||
| 198 | <!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml"> | ||
| 199 | <!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml"> | ||
| 200 | <!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml"> | ||
| 201 | <!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml"> | ||
| 202 | <!ENTITY sub-driver SYSTEM "v4l/driver.xml"> | ||
| 203 | <!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml"> | ||
| 204 | <!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml"> | ||
| 205 | <!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml"> | ||
| 206 | <!ENTITY sub-close SYSTEM "v4l/func-close.xml"> | ||
| 207 | <!ENTITY sub-ioctl SYSTEM "v4l/func-ioctl.xml"> | ||
| 208 | <!ENTITY sub-mmap SYSTEM "v4l/func-mmap.xml"> | ||
| 209 | <!ENTITY sub-munmap SYSTEM "v4l/func-munmap.xml"> | ||
| 210 | <!ENTITY sub-open SYSTEM "v4l/func-open.xml"> | ||
| 211 | <!ENTITY sub-poll SYSTEM "v4l/func-poll.xml"> | ||
| 212 | <!ENTITY sub-read SYSTEM "v4l/func-read.xml"> | ||
| 213 | <!ENTITY sub-select SYSTEM "v4l/func-select.xml"> | ||
| 214 | <!ENTITY sub-write SYSTEM "v4l/func-write.xml"> | ||
| 215 | <!ENTITY sub-io SYSTEM "v4l/io.xml"> | ||
| 216 | <!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml"> | ||
| 217 | <!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml"> | ||
| 218 | <!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml"> | ||
| 219 | <!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> | ||
| 220 | <!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> | ||
| 221 | <!ENTITY sub-sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml"> | ||
| 222 | <!ENTITY sub-sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml"> | ||
| 223 | <!ENTITY sub-sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml"> | ||
| 224 | <!ENTITY sub-sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml"> | ||
| 225 | <!ENTITY sub-uyvy SYSTEM "v4l/pixfmt-uyvy.xml"> | ||
| 226 | <!ENTITY sub-vyuy SYSTEM "v4l/pixfmt-vyuy.xml"> | ||
| 227 | <!ENTITY sub-y16 SYSTEM "v4l/pixfmt-y16.xml"> | ||
| 228 | <!ENTITY sub-y41p SYSTEM "v4l/pixfmt-y41p.xml"> | ||
| 229 | <!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> | ||
| 230 | <!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> | ||
| 231 | <!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> | ||
| 232 | <!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> | ||
| 233 | <!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> | ||
| 234 | <!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> | ||
| 235 | <!ENTITY sub-pixfmt SYSTEM "v4l/pixfmt.xml"> | ||
| 236 | <!ENTITY sub-cropcap SYSTEM "v4l/vidioc-cropcap.xml"> | ||
| 237 | <!ENTITY sub-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> | ||
| 238 | <!ENTITY sub-encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml"> | ||
| 239 | <!ENTITY sub-enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml"> | ||
| 240 | <!ENTITY sub-enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml"> | ||
| 241 | <!ENTITY sub-enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml"> | ||
| 242 | <!ENTITY sub-enumaudio SYSTEM "v4l/vidioc-enumaudio.xml"> | ||
| 243 | <!ENTITY sub-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml"> | ||
| 244 | <!ENTITY sub-enuminput SYSTEM "v4l/vidioc-enuminput.xml"> | ||
| 245 | <!ENTITY sub-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml"> | ||
| 246 | <!ENTITY sub-enumstd SYSTEM "v4l/vidioc-enumstd.xml"> | ||
| 247 | <!ENTITY sub-g-audio SYSTEM "v4l/vidioc-g-audio.xml"> | ||
| 248 | <!ENTITY sub-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml"> | ||
| 249 | <!ENTITY sub-dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml"> | ||
| 250 | <!ENTITY sub-g-crop SYSTEM "v4l/vidioc-g-crop.xml"> | ||
| 251 | <!ENTITY sub-g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml"> | ||
| 252 | <!ENTITY sub-g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml"> | ||
| 253 | <!ENTITY sub-g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml"> | ||
| 254 | <!ENTITY sub-g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml"> | ||
| 255 | <!ENTITY sub-g-fmt SYSTEM "v4l/vidioc-g-fmt.xml"> | ||
| 256 | <!ENTITY sub-g-frequency SYSTEM "v4l/vidioc-g-frequency.xml"> | ||
| 257 | <!ENTITY sub-g-input SYSTEM "v4l/vidioc-g-input.xml"> | ||
| 258 | <!ENTITY sub-g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml"> | ||
| 259 | <!ENTITY sub-g-modulator SYSTEM "v4l/vidioc-g-modulator.xml"> | ||
| 260 | <!ENTITY sub-g-output SYSTEM "v4l/vidioc-g-output.xml"> | ||
| 261 | <!ENTITY sub-g-parm SYSTEM "v4l/vidioc-g-parm.xml"> | ||
| 262 | <!ENTITY sub-g-priority SYSTEM "v4l/vidioc-g-priority.xml"> | ||
| 263 | <!ENTITY sub-g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml"> | ||
| 264 | <!ENTITY sub-g-std SYSTEM "v4l/vidioc-g-std.xml"> | ||
| 265 | <!ENTITY sub-g-tuner SYSTEM "v4l/vidioc-g-tuner.xml"> | ||
| 266 | <!ENTITY sub-log-status SYSTEM "v4l/vidioc-log-status.xml"> | ||
| 267 | <!ENTITY sub-overlay SYSTEM "v4l/vidioc-overlay.xml"> | ||
| 268 | <!ENTITY sub-qbuf SYSTEM "v4l/vidioc-qbuf.xml"> | ||
| 269 | <!ENTITY sub-querybuf SYSTEM "v4l/vidioc-querybuf.xml"> | ||
| 270 | <!ENTITY sub-querycap SYSTEM "v4l/vidioc-querycap.xml"> | ||
| 271 | <!ENTITY sub-queryctrl SYSTEM "v4l/vidioc-queryctrl.xml"> | ||
| 272 | <!ENTITY sub-querystd SYSTEM "v4l/vidioc-querystd.xml"> | ||
| 273 | <!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> | ||
| 274 | <!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> | ||
| 275 | <!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml"> | ||
| 276 | <!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml"> | ||
| 277 | <!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml"> | ||
| 278 | <!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml"> | ||
| 279 | <!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml"> | ||
| 280 | <!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml"> | ||
| 281 | <!ENTITY sub-intro SYSTEM "dvb/intro.xml"> | ||
| 282 | <!ENTITY sub-frontend SYSTEM "dvb/frontend.xml"> | ||
| 283 | <!ENTITY sub-isdbt SYSTEM "dvb/isdbt.xml"> | ||
| 284 | <!ENTITY sub-demux SYSTEM "dvb/demux.xml"> | ||
| 285 | <!ENTITY sub-video SYSTEM "dvb/video.xml"> | ||
| 286 | <!ENTITY sub-audio SYSTEM "dvb/audio.xml"> | ||
| 287 | <!ENTITY sub-ca SYSTEM "dvb/ca.xml"> | ||
| 288 | <!ENTITY sub-net SYSTEM "dvb/net.xml"> | ||
| 289 | <!ENTITY sub-kdapi SYSTEM "dvb/kdapi.xml"> | ||
| 290 | <!ENTITY sub-examples SYSTEM "dvb/examples.xml"> | ||
| 291 | <!ENTITY sub-dvbapi SYSTEM "dvb/dvbapi.xml"> | ||
| 292 | <!ENTITY sub-media SYSTEM "media.xml"> | ||
| 293 | <!ENTITY sub-media-entities SYSTEM "media-entities.tmpl"> | ||
| 294 | <!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> | ||
| 295 | |||
| 296 | <!-- Function Reference --> | ||
| 297 | <!ENTITY close SYSTEM "v4l/func-close.xml"> | ||
| 298 | <!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml"> | ||
| 299 | <!ENTITY mmap SYSTEM "v4l/func-mmap.xml"> | ||
| 300 | <!ENTITY munmap SYSTEM "v4l/func-munmap.xml"> | ||
| 301 | <!ENTITY open SYSTEM "v4l/func-open.xml"> | ||
| 302 | <!ENTITY poll SYSTEM "v4l/func-poll.xml"> | ||
| 303 | <!ENTITY read SYSTEM "v4l/func-read.xml"> | ||
| 304 | <!ENTITY select SYSTEM "v4l/func-select.xml"> | ||
| 305 | <!ENTITY write SYSTEM "v4l/func-write.xml"> | ||
| 306 | <!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml"> | ||
| 307 | <!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml"> | ||
| 308 | <!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml"> | ||
| 309 | <!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> | ||
| 310 | <!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> | ||
| 311 | <!ENTITY sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml"> | ||
| 312 | <!ENTITY sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml"> | ||
| 313 | <!ENTITY sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml"> | ||
| 314 | <!ENTITY sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml"> | ||
| 315 | <!ENTITY uyvy SYSTEM "v4l/pixfmt-uyvy.xml"> | ||
| 316 | <!ENTITY vyuy SYSTEM "v4l/pixfmt-vyuy.xml"> | ||
| 317 | <!ENTITY y16 SYSTEM "v4l/pixfmt-y16.xml"> | ||
| 318 | <!ENTITY y41p SYSTEM "v4l/pixfmt-y41p.xml"> | ||
| 319 | <!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> | ||
| 320 | <!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> | ||
| 321 | <!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> | ||
| 322 | <!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> | ||
| 323 | <!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> | ||
| 324 | <!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> | ||
| 325 | <!ENTITY cropcap SYSTEM "v4l/vidioc-cropcap.xml"> | ||
| 326 | <!ENTITY dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> | ||
| 327 | <!ENTITY encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml"> | ||
| 328 | <!ENTITY enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml"> | ||
| 329 | <!ENTITY enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml"> | ||
| 330 | <!ENTITY enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml"> | ||
| 331 | <!ENTITY enumaudio SYSTEM "v4l/vidioc-enumaudio.xml"> | ||
| 332 | <!ENTITY enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml"> | ||
| 333 | <!ENTITY enuminput SYSTEM "v4l/vidioc-enuminput.xml"> | ||
| 334 | <!ENTITY enumoutput SYSTEM "v4l/vidioc-enumoutput.xml"> | ||
| 335 | <!ENTITY enumstd SYSTEM "v4l/vidioc-enumstd.xml"> | ||
| 336 | <!ENTITY g-audio SYSTEM "v4l/vidioc-g-audio.xml"> | ||
| 337 | <!ENTITY g-audioout SYSTEM "v4l/vidioc-g-audioout.xml"> | ||
| 338 | <!ENTITY dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml"> | ||
| 339 | <!ENTITY g-crop SYSTEM "v4l/vidioc-g-crop.xml"> | ||
| 340 | <!ENTITY g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml"> | ||
| 341 | <!ENTITY g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml"> | ||
| 342 | <!ENTITY g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml"> | ||
| 343 | <!ENTITY g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml"> | ||
| 344 | <!ENTITY g-fmt SYSTEM "v4l/vidioc-g-fmt.xml"> | ||
| 345 | <!ENTITY g-frequency SYSTEM "v4l/vidioc-g-frequency.xml"> | ||
| 346 | <!ENTITY g-input SYSTEM "v4l/vidioc-g-input.xml"> | ||
| 347 | <!ENTITY g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml"> | ||
| 348 | <!ENTITY g-modulator SYSTEM "v4l/vidioc-g-modulator.xml"> | ||
| 349 | <!ENTITY g-output SYSTEM "v4l/vidioc-g-output.xml"> | ||
| 350 | <!ENTITY g-parm SYSTEM "v4l/vidioc-g-parm.xml"> | ||
| 351 | <!ENTITY g-priority SYSTEM "v4l/vidioc-g-priority.xml"> | ||
| 352 | <!ENTITY g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml"> | ||
| 353 | <!ENTITY g-std SYSTEM "v4l/vidioc-g-std.xml"> | ||
| 354 | <!ENTITY g-tuner SYSTEM "v4l/vidioc-g-tuner.xml"> | ||
| 355 | <!ENTITY log-status SYSTEM "v4l/vidioc-log-status.xml"> | ||
| 356 | <!ENTITY overlay SYSTEM "v4l/vidioc-overlay.xml"> | ||
| 357 | <!ENTITY qbuf SYSTEM "v4l/vidioc-qbuf.xml"> | ||
| 358 | <!ENTITY querybuf SYSTEM "v4l/vidioc-querybuf.xml"> | ||
| 359 | <!ENTITY querycap SYSTEM "v4l/vidioc-querycap.xml"> | ||
| 360 | <!ENTITY queryctrl SYSTEM "v4l/vidioc-queryctrl.xml"> | ||
| 361 | <!ENTITY querystd SYSTEM "v4l/vidioc-querystd.xml"> | ||
| 362 | <!ENTITY reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> | ||
| 363 | <!ENTITY s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> | ||
| 364 | <!ENTITY streamon SYSTEM "v4l/vidioc-streamon.xml"> | ||
diff --git a/Documentation/DocBook/media-indices.tmpl b/Documentation/DocBook/media-indices.tmpl new file mode 100644 index 000000000000..9e30a236d74f --- /dev/null +++ b/Documentation/DocBook/media-indices.tmpl | |||
| @@ -0,0 +1,85 @@ | |||
| 1 | <!-- Generated file! Do not edit. --> | ||
| 2 | |||
| 3 | <index><title>List of Types</title> | ||
| 4 | <indexentry><primaryie><link linkend='v4l2-std-id'>v4l2_std_id</link></primaryie></indexentry> | ||
| 5 | <indexentry><primaryie>enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link></primaryie></indexentry> | ||
| 6 | <indexentry><primaryie>enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link></primaryie></indexentry> | ||
| 7 | <indexentry><primaryie>enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link></primaryie></indexentry> | ||
| 8 | <indexentry><primaryie>enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link></primaryie></indexentry> | ||
| 9 | <indexentry><primaryie>enum <link linkend='v4l2-field'>v4l2_field</link></primaryie></indexentry> | ||
| 10 | <indexentry><primaryie>enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link></primaryie></indexentry> | ||
| 11 | <indexentry><primaryie>enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link></primaryie></indexentry> | ||
| 12 | <indexentry><primaryie>enum <link linkend='v4l2-memory'>v4l2_memory</link></primaryie></indexentry> | ||
| 13 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link></primaryie></indexentry> | ||
| 14 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link></primaryie></indexentry> | ||
| 15 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link></primaryie></indexentry> | ||
| 16 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link></primaryie></indexentry> | ||
| 17 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link></primaryie></indexentry> | ||
| 18 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link></primaryie></indexentry> | ||
| 19 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link></primaryie></indexentry> | ||
| 20 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link></primaryie></indexentry> | ||
| 21 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link></primaryie></indexentry> | ||
| 22 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link></primaryie></indexentry> | ||
| 23 | <indexentry><primaryie>enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link></primaryie></indexentry> | ||
| 24 | <indexentry><primaryie>enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link></primaryie></indexentry> | ||
| 25 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link></primaryie></indexentry> | ||
| 26 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link></primaryie></indexentry> | ||
| 27 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link></primaryie></indexentry> | ||
| 28 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link></primaryie></indexentry> | ||
| 29 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link></primaryie></indexentry> | ||
| 30 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link></primaryie></indexentry> | ||
| 31 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link></primaryie></indexentry> | ||
| 32 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link></primaryie></indexentry> | ||
| 33 | <indexentry><primaryie>enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link></primaryie></indexentry> | ||
| 34 | <indexentry><primaryie>enum <link linkend='v4l2-priority'>v4l2_priority</link></primaryie></indexentry> | ||
| 35 | <indexentry><primaryie>enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link></primaryie></indexentry> | ||
| 36 | <indexentry><primaryie>enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry> | ||
| 37 | <indexentry><primaryie>struct <link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry> | ||
| 38 | <indexentry><primaryie>struct <link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry> | ||
| 39 | <indexentry><primaryie>struct <link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry> | ||
| 40 | <indexentry><primaryie>struct <link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry> | ||
| 41 | <indexentry><primaryie>struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry> | ||
| 42 | <indexentry><primaryie>struct <link linkend='v4l2-clip'>v4l2_clip</link></primaryie></indexentry> | ||
| 43 | <indexentry><primaryie>struct <link linkend='v4l2-control'>v4l2_control</link></primaryie></indexentry> | ||
| 44 | <indexentry><primaryie>struct <link linkend='v4l2-crop'>v4l2_crop</link></primaryie></indexentry> | ||
| 45 | <indexentry><primaryie>struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link></primaryie></indexentry> | ||
| 46 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry> | ||
| 47 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry> | ||
| 48 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry> | ||
| 49 | <indexentry><primaryie>struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry> | ||
| 50 | <indexentry><primaryie>struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry> | ||
| 51 | <indexentry><primaryie>struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry> | ||
| 52 | <indexentry><primaryie>struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link></primaryie></indexentry> | ||
| 53 | <indexentry><primaryie>struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link></primaryie></indexentry> | ||
| 54 | <indexentry><primaryie>struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link></primaryie></indexentry> | ||
| 55 | <indexentry><primaryie>struct <link linkend='v4l2-format'>v4l2_format</link></primaryie></indexentry> | ||
| 56 | <indexentry><primaryie>struct <link linkend='v4l2-fract'>v4l2_fract</link></primaryie></indexentry> | ||
| 57 | <indexentry><primaryie>struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link></primaryie></indexentry> | ||
| 58 | <indexentry><primaryie>struct <link linkend='v4l2-frequency'>v4l2_frequency</link></primaryie></indexentry> | ||
| 59 | <indexentry><primaryie>struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link></primaryie></indexentry> | ||
| 60 | <indexentry><primaryie>struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link></primaryie></indexentry> | ||
| 61 | <indexentry><primaryie>struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link></primaryie></indexentry> | ||
| 62 | <indexentry><primaryie>struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link></primaryie></indexentry> | ||
| 63 | <indexentry><primaryie>struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link></primaryie></indexentry> | ||
| 64 | <indexentry><primaryie>struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link></primaryie></indexentry> | ||
| 65 | <indexentry><primaryie>struct <link linkend='v4l2-input'>v4l2_input</link></primaryie></indexentry> | ||
| 66 | <indexentry><primaryie>struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link></primaryie></indexentry> | ||
| 67 | <indexentry><primaryie>struct <link linkend='v4l2-modulator'>v4l2_modulator</link></primaryie></indexentry> | ||
| 68 | <indexentry><primaryie>struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link></primaryie></indexentry> | ||
| 69 | <indexentry><primaryie>struct <link linkend='v4l2-output'>v4l2_output</link></primaryie></indexentry> | ||
| 70 | <indexentry><primaryie>struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link></primaryie></indexentry> | ||
| 71 | <indexentry><primaryie>struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link></primaryie></indexentry> | ||
| 72 | <indexentry><primaryie>struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link></primaryie></indexentry> | ||
| 73 | <indexentry><primaryie>struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link></primaryie></indexentry> | ||
| 74 | <indexentry><primaryie>struct <link linkend='v4l2-rect'>v4l2_rect</link></primaryie></indexentry> | ||
| 75 | <indexentry><primaryie>struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link></primaryie></indexentry> | ||
| 76 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link></primaryie></indexentry> | ||
| 77 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link></primaryie></indexentry> | ||
| 78 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link></primaryie></indexentry> | ||
| 79 | <indexentry><primaryie>struct <link linkend='v4l2-standard'>v4l2_standard</link></primaryie></indexentry> | ||
| 80 | <indexentry><primaryie>struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link></primaryie></indexentry> | ||
| 81 | <indexentry><primaryie>struct <link linkend='v4l2-timecode'>v4l2_timecode</link></primaryie></indexentry> | ||
| 82 | <indexentry><primaryie>struct <link linkend='v4l2-tuner'>v4l2_tuner</link></primaryie></indexentry> | ||
| 83 | <indexentry><primaryie>struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link></primaryie></indexentry> | ||
| 84 | <indexentry><primaryie>struct <link linkend='v4l2-window'>v4l2_window</link></primaryie></indexentry> | ||
| 85 | </index> | ||
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl new file mode 100644 index 000000000000..eea564bb12cb --- /dev/null +++ b/Documentation/DocBook/media.tmpl | |||
| @@ -0,0 +1,112 @@ | |||
| 1 | <?xml version="1.0"?> | ||
| 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | ||
| 3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ | ||
| 4 | <!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities; | ||
| 5 | <!ENTITY media-indices SYSTEM "./media-indices.tmpl"> | ||
| 6 | |||
| 7 | <!ENTITY eg "e. g."> | ||
| 8 | <!ENTITY ie "i. e."> | ||
| 9 | <!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>."> | ||
| 10 | <!ENTITY i2c "I<superscript>2</superscript>C"> | ||
| 11 | <!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately:</para>"> | ||
| 12 | <!ENTITY manvol "<manvolnum>2</manvolnum>"> | ||
| 13 | |||
| 14 | <!-- Table templates: structs, structs w/union, defines. --> | ||
| 15 | <!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> | ||
| 16 | <!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />"> | ||
| 17 | <!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> | ||
| 18 | |||
| 19 | <!-- Video for Linux mailing list address. --> | ||
| 20 | <!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>"> | ||
| 21 | |||
| 22 | <!-- LinuxTV v4l-dvb repository. --> | ||
| 23 | <!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>"> | ||
| 24 | ]> | ||
| 25 | |||
| 26 | <book id="media_api"> | ||
| 27 | <bookinfo> | ||
| 28 | <title>LINUX MEDIA INFRASTRUCTURE API</title> | ||
| 29 | |||
| 30 | <copyright> | ||
| 31 | <year>2009</year> | ||
| 32 | <holder>LinuxTV Developers</holder> | ||
| 33 | </copyright> | ||
| 34 | |||
| 35 | <legalnotice> | ||
| 36 | |||
| 37 | <para>Permission is granted to copy, distribute and/or modify | ||
| 38 | this document under the terms of the GNU Free Documentation License, | ||
| 39 | Version 1.1 or any later version published by the Free Software | ||
| 40 | Foundation. A copy of the license is included in the chapter entitled | ||
| 41 | "GNU Free Documentation License"</para> | ||
| 42 | </legalnotice> | ||
| 43 | |||
| 44 | </bookinfo> | ||
| 45 | |||
| 46 | <toc></toc> <!-- autogenerated --> | ||
| 47 | |||
| 48 | <preface> | ||
| 49 | <title>Introduction</title> | ||
| 50 | |||
| 51 | <para>This document covers the Linux Kernel to Userspace API's used by | ||
| 52 | video and radio straming devices, including video cameras, | ||
| 53 | analog and digital TV receiver cards, AM/FM receiver cards, | ||
| 54 | streaming capture devices.</para> | ||
| 55 | <para>It is divided into three parts.</para> | ||
| 56 | <para>The first part covers radio, capture, | ||
| 57 | cameras and analog TV devices.</para> | ||
| 58 | <para>The second part covers the | ||
| 59 | API used for digital TV and Internet reception via one of the | ||
| 60 | several digital tv standards. While it is called as DVB API, | ||
| 61 | in fact it covers several different video standards including | ||
| 62 | DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated | ||
| 63 | to documment support also for DVB-S2, ISDB-T and ISDB-S.</para> | ||
| 64 | <para>The third part covers other API's used by all media infrastructure devices</para> | ||
| 65 | <para>For additional information and for the latest development code, | ||
| 66 | see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> | ||
| 67 | <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> | ||
| 68 | |||
| 69 | </preface> | ||
| 70 | |||
| 71 | <part id="v4l2spec"> | ||
| 72 | &sub-v4l2; | ||
| 73 | </part> | ||
| 74 | <part id="dvbapi"> | ||
| 75 | &sub-dvbapi; | ||
| 76 | </part> | ||
| 77 | <part id="v4ldvb_common"> | ||
| 78 | <partinfo> | ||
| 79 | <authorgroup> | ||
| 80 | <author> | ||
| 81 | <firstname>Mauro</firstname> | ||
| 82 | <surname>Chehab</surname> | ||
| 83 | <othername role="mi">Carvalho</othername> | ||
| 84 | <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> | ||
| 85 | <contrib>Initial version.</contrib> | ||
| 86 | </author> | ||
| 87 | </authorgroup> | ||
| 88 | <copyright> | ||
| 89 | <year>2009</year> | ||
| 90 | <holder>Mauro Carvalho Chehab</holder> | ||
| 91 | </copyright> | ||
| 92 | |||
| 93 | <revhistory> | ||
| 94 | <!-- Put document revisions here, newest first. --> | ||
| 95 | <revision> | ||
| 96 | <revnumber>1.0.0</revnumber> | ||
| 97 | <date>2009-09-06</date> | ||
| 98 | <authorinitials>mcc</authorinitials> | ||
| 99 | <revremark>Initial revision</revremark> | ||
| 100 | </revision> | ||
| 101 | </revhistory> | ||
| 102 | </partinfo> | ||
| 103 | |||
| 104 | <title>Other API's used by media infrastructure drivers</title> | ||
| 105 | <chapter id="remote_controllers"> | ||
| 106 | &sub-remote_controllers; | ||
| 107 | </chapter> | ||
| 108 | </part> | ||
| 109 | |||
| 110 | &sub-fdl-appendix; | ||
| 111 | |||
| 112 | </book> | ||
diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 8e145857fc9d..df0d089d0fb9 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl | |||
| @@ -568,7 +568,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) | |||
| 568 | <para> | 568 | <para> |
| 569 | The blocks in which the tables are stored are procteted against | 569 | The blocks in which the tables are stored are procteted against |
| 570 | accidental access by marking them bad in the memory bad block | 570 | accidental access by marking them bad in the memory bad block |
| 571 | table. The bad block table managment functions are allowed | 571 | table. The bad block table management functions are allowed |
| 572 | to circumvernt this protection. | 572 | to circumvernt this protection. |
| 573 | </para> | 573 | </para> |
| 574 | <para> | 574 | <para> |
diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl index 10a150ae2a7e..d87f4569e768 100644 --- a/Documentation/DocBook/scsi.tmpl +++ b/Documentation/DocBook/scsi.tmpl | |||
| @@ -317,7 +317,7 @@ | |||
| 317 | <para> | 317 | <para> |
| 318 | The SAS transport class contains common code to deal with SAS HBAs, | 318 | The SAS transport class contains common code to deal with SAS HBAs, |
| 319 | an aproximated representation of SAS topologies in the driver model, | 319 | an aproximated representation of SAS topologies in the driver model, |
| 320 | and various sysfs attributes to expose these topologies and managment | 320 | and various sysfs attributes to expose these topologies and management |
| 321 | interfaces to userspace. | 321 | interfaces to userspace. |
| 322 | </para> | 322 | </para> |
| 323 | <para> | 323 | <para> |
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 974e17ccf106..254c1d5d2e50 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl | |||
| @@ -3,6 +3,7 @@ | |||
| 3 | <param name="chunk.quietly">1</param> | 3 | <param name="chunk.quietly">1</param> |
| 4 | <param name="funcsynopsis.style">ansi</param> | 4 | <param name="funcsynopsis.style">ansi</param> |
| 5 | <param name="funcsynopsis.tabular.threshold">80</param> | 5 | <param name="funcsynopsis.tabular.threshold">80</param> |
| 6 | <param name="callout.graphics">0</param> | ||
| 6 | <!-- <param name="paper.type">A4</param> --> | 7 | <!-- <param name="paper.type">A4</param> --> |
| 7 | <param name="generate.section.toc.level">2</param> | 8 | <param name="generate.section.toc.level">2</param> |
| 8 | </stylesheet> | 9 | </stylesheet> |
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 8f6e3b2403c7..4d4ce0e61e42 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl | |||
| @@ -25,6 +25,10 @@ | |||
| 25 | <year>2006-2008</year> | 25 | <year>2006-2008</year> |
| 26 | <holder>Hans-Jürgen Koch.</holder> | 26 | <holder>Hans-Jürgen Koch.</holder> |
| 27 | </copyright> | 27 | </copyright> |
| 28 | <copyright> | ||
| 29 | <year>2009</year> | ||
| 30 | <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> | ||
| 31 | </copyright> | ||
| 28 | 32 | ||
| 29 | <legalnotice> | 33 | <legalnotice> |
| 30 | <para> | 34 | <para> |
| @@ -42,6 +46,13 @@ GPL version 2. | |||
| 42 | 46 | ||
| 43 | <revhistory> | 47 | <revhistory> |
| 44 | <revision> | 48 | <revision> |
| 49 | <revnumber>0.9</revnumber> | ||
| 50 | <date>2009-07-16</date> | ||
| 51 | <authorinitials>mst</authorinitials> | ||
| 52 | <revremark>Added generic pci driver | ||
| 53 | </revremark> | ||
| 54 | </revision> | ||
| 55 | <revision> | ||
| 45 | <revnumber>0.8</revnumber> | 56 | <revnumber>0.8</revnumber> |
| 46 | <date>2008-12-24</date> | 57 | <date>2008-12-24</date> |
| 47 | <authorinitials>hjk</authorinitials> | 58 | <authorinitials>hjk</authorinitials> |
| @@ -809,6 +820,158 @@ framework to set up sysfs files for this region. Simply leave it alone. | |||
| 809 | 820 | ||
| 810 | </chapter> | 821 | </chapter> |
| 811 | 822 | ||
| 823 | <chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> | ||
| 824 | <?dbhtml filename="uio_pci_generic.html"?> | ||
| 825 | <title>Generic PCI UIO driver</title> | ||
| 826 | <para> | ||
| 827 | The generic driver is a kernel module named uio_pci_generic. | ||
| 828 | It can work with any device compliant to PCI 2.3 (circa 2002) and | ||
| 829 | any compliant PCI Express device. Using this, you only need to | ||
| 830 | write the userspace driver, removing the need to write | ||
| 831 | a hardware-specific kernel module. | ||
| 832 | </para> | ||
| 833 | |||
| 834 | <sect1 id="uio_pci_generic_binding"> | ||
| 835 | <title>Making the driver recognize the device</title> | ||
| 836 | <para> | ||
| 837 | Since the driver does not declare any device ids, it will not get loaded | ||
| 838 | automatically and will not automatically bind to any devices, you must load it | ||
| 839 | and allocate id to the driver yourself. For example: | ||
| 840 | <programlisting> | ||
| 841 | modprobe uio_pci_generic | ||
| 842 | echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id | ||
| 843 | </programlisting> | ||
| 844 | </para> | ||
| 845 | <para> | ||
| 846 | If there already is a hardware specific kernel driver for your device, the | ||
| 847 | generic driver still won't bind to it, in this case if you want to use the | ||
| 848 | generic driver (why would you?) you'll have to manually unbind the hardware | ||
| 849 | specific driver and bind the generic driver, like this: | ||
| 850 | <programlisting> | ||
| 851 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind | ||
| 852 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind | ||
| 853 | </programlisting> | ||
| 854 | </para> | ||
| 855 | <para> | ||
| 856 | You can verify that the device has been bound to the driver | ||
| 857 | by looking for it in sysfs, for example like the following: | ||
| 858 | <programlisting> | ||
| 859 | ls -l /sys/bus/pci/devices/0000:00:19.0/driver | ||
| 860 | </programlisting> | ||
| 861 | Which if successful should print | ||
| 862 | <programlisting> | ||
| 863 | .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic | ||
| 864 | </programlisting> | ||
| 865 | Note that the generic driver will not bind to old PCI 2.2 devices. | ||
| 866 | If binding the device failed, run the following command: | ||
| 867 | <programlisting> | ||
| 868 | dmesg | ||
| 869 | </programlisting> | ||
| 870 | and look in the output for failure reasons | ||
| 871 | </para> | ||
| 872 | </sect1> | ||
| 873 | |||
| 874 | <sect1 id="uio_pci_generic_internals"> | ||
| 875 | <title>Things to know about uio_pci_generic</title> | ||
| 876 | <para> | ||
| 877 | Interrupts are handled using the Interrupt Disable bit in the PCI command | ||
| 878 | register and Interrupt Status bit in the PCI status register. All devices | ||
| 879 | compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should | ||
| 880 | support these bits. uio_pci_generic detects this support, and won't bind to | ||
| 881 | devices which do not support the Interrupt Disable Bit in the command register. | ||
| 882 | </para> | ||
| 883 | <para> | ||
| 884 | On each interrupt, uio_pci_generic sets the Interrupt Disable bit. | ||
| 885 | This prevents the device from generating further interrupts | ||
| 886 | until the bit is cleared. The userspace driver should clear this | ||
| 887 | bit before blocking and waiting for more interrupts. | ||
| 888 | </para> | ||
| 889 | </sect1> | ||
| 890 | <sect1 id="uio_pci_generic_userspace"> | ||
| 891 | <title>Writing userspace driver using uio_pci_generic</title> | ||
| 892 | <para> | ||
| 893 | Userspace driver can use pci sysfs interface, or the | ||
| 894 | libpci libray that wraps it, to talk to the device and to | ||
| 895 | re-enable interrupts by writing to the command register. | ||
| 896 | </para> | ||
| 897 | </sect1> | ||
| 898 | <sect1 id="uio_pci_generic_example"> | ||
| 899 | <title>Example code using uio_pci_generic</title> | ||
| 900 | <para> | ||
| 901 | Here is some sample userspace driver code using uio_pci_generic: | ||
| 902 | <programlisting> | ||
| 903 | #include <stdlib.h> | ||
| 904 | #include <stdio.h> | ||
| 905 | #include <unistd.h> | ||
| 906 | #include <sys/types.h> | ||
| 907 | #include <sys/stat.h> | ||
| 908 | #include <fcntl.h> | ||
| 909 | #include <errno.h> | ||
| 910 | |||
| 911 | int main() | ||
| 912 | { | ||
| 913 | int uiofd; | ||
| 914 | int configfd; | ||
| 915 | int err; | ||
| 916 | int i; | ||
| 917 | unsigned icount; | ||
| 918 | unsigned char command_high; | ||
| 919 | |||
| 920 | uiofd = open("/dev/uio0", O_RDONLY); | ||
| 921 | if (uiofd < 0) { | ||
| 922 | perror("uio open:"); | ||
| 923 | return errno; | ||
| 924 | } | ||
| 925 | configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); | ||
| 926 | if (uiofd < 0) { | ||
| 927 | perror("config open:"); | ||
| 928 | return errno; | ||
| 929 | } | ||
| 930 | |||
| 931 | /* Read and cache command value */ | ||
| 932 | err = pread(configfd, &command_high, 1, 5); | ||
| 933 | if (err != 1) { | ||
| 934 | perror("command config read:"); | ||
| 935 | return errno; | ||
| 936 | } | ||
| 937 | command_high &= ~0x4; | ||
| 938 | |||
| 939 | for(i = 0;; ++i) { | ||
| 940 | /* Print out a message, for debugging. */ | ||
| 941 | if (i == 0) | ||
| 942 | fprintf(stderr, "Started uio test driver.\n"); | ||
| 943 | else | ||
| 944 | fprintf(stderr, "Interrupts: %d\n", icount); | ||
| 945 | |||
| 946 | /****************************************/ | ||
| 947 | /* Here we got an interrupt from the | ||
| 948 | device. Do something to it. */ | ||
| 949 | /****************************************/ | ||
| 950 | |||
| 951 | /* Re-enable interrupts. */ | ||
| 952 | err = pwrite(configfd, &command_high, 1, 5); | ||
| 953 | if (err != 1) { | ||
| 954 | perror("config write:"); | ||
| 955 | break; | ||
| 956 | } | ||
| 957 | |||
| 958 | /* Wait for next interrupt. */ | ||
| 959 | err = read(uiofd, &icount, 4); | ||
| 960 | if (err != 4) { | ||
| 961 | perror("uio read:"); | ||
| 962 | break; | ||
| 963 | } | ||
| 964 | |||
| 965 | } | ||
| 966 | return errno; | ||
| 967 | } | ||
| 968 | |||
| 969 | </programlisting> | ||
| 970 | </para> | ||
| 971 | </sect1> | ||
| 972 | |||
| 973 | </chapter> | ||
| 974 | |||
| 812 | <appendix id="app1"> | 975 | <appendix id="app1"> |
| 813 | <title>Further information</title> | 976 | <title>Further information</title> |
| 814 | <itemizedlist> | 977 | <itemizedlist> |
diff --git a/Documentation/DocBook/v4l/.gitignore b/Documentation/DocBook/v4l/.gitignore new file mode 100644 index 000000000000..d7ec32eafac9 --- /dev/null +++ b/Documentation/DocBook/v4l/.gitignore | |||
| @@ -0,0 +1 @@ | |||
| !*.xml | |||
diff --git a/Documentation/DocBook/v4l/biblio.xml b/Documentation/DocBook/v4l/biblio.xml new file mode 100644 index 000000000000..afc8a0dd2601 --- /dev/null +++ b/Documentation/DocBook/v4l/biblio.xml | |||
| @@ -0,0 +1,188 @@ | |||
| 1 | <bibliography> | ||
| 2 | <title>References</title> | ||
| 3 | |||
| 4 | <biblioentry id="eia608"> | ||
| 5 | <abbrev>EIA 608-B</abbrev> | ||
| 6 | <authorgroup> | ||
| 7 | <corpauthor>Electronic Industries Alliance (<ulink | ||
| 8 | url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor> | ||
| 9 | </authorgroup> | ||
| 10 | <title>EIA 608-B "Recommended Practice for Line 21 Data | ||
| 11 | Service"</title> | ||
| 12 | </biblioentry> | ||
| 13 | |||
| 14 | <biblioentry id="en300294"> | ||
| 15 | <abbrev>EN 300 294</abbrev> | ||
| 16 | <authorgroup> | ||
| 17 | <corpauthor>European Telecommunication Standards Institute | ||
| 18 | (<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 19 | </authorgroup> | ||
| 20 | <title>EN 300 294 "625-line television Wide Screen Signalling | ||
| 21 | (WSS)"</title> | ||
| 22 | </biblioentry> | ||
| 23 | |||
| 24 | <biblioentry id="ets300231"> | ||
| 25 | <abbrev>ETS 300 231</abbrev> | ||
| 26 | <authorgroup> | ||
| 27 | <corpauthor>European Telecommunication Standards Institute | ||
| 28 | (<ulink | ||
| 29 | url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 30 | </authorgroup> | ||
| 31 | <title>ETS 300 231 "Specification of the domestic video | ||
| 32 | Programme Delivery Control system (PDC)"</title> | ||
| 33 | </biblioentry> | ||
| 34 | |||
| 35 | <biblioentry id="ets300706"> | ||
| 36 | <abbrev>ETS 300 706</abbrev> | ||
| 37 | <authorgroup> | ||
| 38 | <corpauthor>European Telecommunication Standards Institute | ||
| 39 | (<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 40 | </authorgroup> | ||
| 41 | <title>ETS 300 706 "Enhanced Teletext specification"</title> | ||
| 42 | </biblioentry> | ||
| 43 | |||
| 44 | <biblioentry id="mpeg2part1"> | ||
| 45 | <abbrev>ISO 13818-1</abbrev> | ||
| 46 | <authorgroup> | ||
| 47 | <corpauthor>International Telecommunication Union (<ulink | ||
| 48 | url="http://www.itu.ch">http://www.itu.ch</ulink>), International | ||
| 49 | Organisation for Standardisation (<ulink | ||
| 50 | url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> | ||
| 51 | </authorgroup> | ||
| 52 | <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information | ||
| 53 | technology — Generic coding of moving pictures and associated | ||
| 54 | audio information: Systems"</title> | ||
| 55 | </biblioentry> | ||
| 56 | |||
| 57 | <biblioentry id="mpeg2part2"> | ||
| 58 | <abbrev>ISO 13818-2</abbrev> | ||
| 59 | <authorgroup> | ||
| 60 | <corpauthor>International Telecommunication Union (<ulink | ||
| 61 | url="http://www.itu.ch">http://www.itu.ch</ulink>), International | ||
| 62 | Organisation for Standardisation (<ulink | ||
| 63 | url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> | ||
| 64 | </authorgroup> | ||
| 65 | <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information | ||
| 66 | technology — Generic coding of moving pictures and associated | ||
| 67 | audio information: Video"</title> | ||
| 68 | </biblioentry> | ||
| 69 | |||
| 70 | <biblioentry id="itu470"> | ||
| 71 | <abbrev>ITU BT.470</abbrev> | ||
| 72 | <authorgroup> | ||
| 73 | <corpauthor>International Telecommunication Union (<ulink | ||
| 74 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 75 | </authorgroup> | ||
| 76 | <title>ITU-R Recommendation BT.470-6 "Conventional Television | ||
| 77 | Systems"</title> | ||
| 78 | </biblioentry> | ||
| 79 | |||
| 80 | <biblioentry id="itu601"> | ||
| 81 | <abbrev>ITU BT.601</abbrev> | ||
| 82 | <authorgroup> | ||
| 83 | <corpauthor>International Telecommunication Union (<ulink | ||
| 84 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 85 | </authorgroup> | ||
| 86 | <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters | ||
| 87 | of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect | ||
| 88 | Ratios"</title> | ||
| 89 | </biblioentry> | ||
| 90 | |||
| 91 | <biblioentry id="itu653"> | ||
| 92 | <abbrev>ITU BT.653</abbrev> | ||
| 93 | <authorgroup> | ||
| 94 | <corpauthor>International Telecommunication Union (<ulink | ||
| 95 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 96 | </authorgroup> | ||
| 97 | <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title> | ||
| 98 | </biblioentry> | ||
| 99 | |||
| 100 | <biblioentry id="itu709"> | ||
| 101 | <abbrev>ITU BT.709</abbrev> | ||
| 102 | <authorgroup> | ||
| 103 | <corpauthor>International Telecommunication Union (<ulink | ||
| 104 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 105 | </authorgroup> | ||
| 106 | <title>ITU-R Recommendation BT.709-5 "Parameter values for the | ||
| 107 | HDTV standards for production and international programme | ||
| 108 | exchange"</title> | ||
| 109 | </biblioentry> | ||
| 110 | |||
| 111 | <biblioentry id="itu1119"> | ||
| 112 | <abbrev>ITU BT.1119</abbrev> | ||
| 113 | <authorgroup> | ||
| 114 | <corpauthor>International Telecommunication Union (<ulink | ||
| 115 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 116 | </authorgroup> | ||
| 117 | <title>ITU-R Recommendation BT.1119 "625-line | ||
| 118 | television Wide Screen Signalling (WSS)"</title> | ||
| 119 | </biblioentry> | ||
| 120 | |||
| 121 | <biblioentry id="jfif"> | ||
| 122 | <abbrev>JFIF</abbrev> | ||
| 123 | <authorgroup> | ||
| 124 | <corpauthor>Independent JPEG Group (<ulink | ||
| 125 | url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor> | ||
| 126 | </authorgroup> | ||
| 127 | <title>JPEG File Interchange Format</title> | ||
| 128 | <subtitle>Version 1.02</subtitle> | ||
| 129 | </biblioentry> | ||
| 130 | |||
| 131 | <biblioentry id="smpte12m"> | ||
| 132 | <abbrev>SMPTE 12M</abbrev> | ||
| 133 | <authorgroup> | ||
| 134 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 135 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 136 | </authorgroup> | ||
| 137 | <title>SMPTE 12M-1999 "Television, Audio and Film - Time and | ||
| 138 | Control Code"</title> | ||
| 139 | </biblioentry> | ||
| 140 | |||
| 141 | <biblioentry id="smpte170m"> | ||
| 142 | <abbrev>SMPTE 170M</abbrev> | ||
| 143 | <authorgroup> | ||
| 144 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 145 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 146 | </authorgroup> | ||
| 147 | <title>SMPTE 170M-1999 "Television - Composite Analog Video | ||
| 148 | Signal - NTSC for Studio Applications"</title> | ||
| 149 | </biblioentry> | ||
| 150 | |||
| 151 | <biblioentry id="smpte240m"> | ||
| 152 | <abbrev>SMPTE 240M</abbrev> | ||
| 153 | <authorgroup> | ||
| 154 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 155 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 156 | </authorgroup> | ||
| 157 | <title>SMPTE 240M-1999 "Television - Signal Parameters - | ||
| 158 | 1125-Line High-Definition Production"</title> | ||
| 159 | </biblioentry> | ||
| 160 | |||
| 161 | <biblioentry id="en50067"> | ||
| 162 | <abbrev>EN 50067</abbrev> | ||
| 163 | <authorgroup> | ||
| 164 | <corpauthor>European Committee for Electrotechnical Standardization | ||
| 165 | (<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor> | ||
| 166 | </authorgroup> | ||
| 167 | <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting | ||
| 168 | in the frequency range from 87,5 to 108,0 MHz</title> | ||
| 169 | </biblioentry> | ||
| 170 | |||
| 171 | <biblioentry id="nrsc4"> | ||
| 172 | <abbrev>NRSC-4</abbrev> | ||
| 173 | <authorgroup> | ||
| 174 | <corpauthor>National Radio Systems Committee | ||
| 175 | (<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> | ||
| 176 | </authorgroup> | ||
| 177 | <title>NTSC-4: United States RBDS Standard</title> | ||
| 178 | </biblioentry> | ||
| 179 | |||
| 180 | </bibliography> | ||
| 181 | |||
| 182 | <!-- | ||
| 183 | Local Variables: | ||
| 184 | mode: sgml | ||
| 185 | sgml-parent-document: "v4l2.sgml" | ||
| 186 | indent-tabs-mode: nil | ||
| 187 | End: | ||
| 188 | --> | ||
diff --git a/Documentation/DocBook/v4l/capture.c.xml b/Documentation/DocBook/v4l/capture.c.xml new file mode 100644 index 000000000000..1c5c49a2de59 --- /dev/null +++ b/Documentation/DocBook/v4l/capture.c.xml | |||
| @@ -0,0 +1,659 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* | ||
| 3 | * V4L2 video capture example | ||
| 4 | * | ||
| 5 | * This program can be used and distributed without restrictions. | ||
| 6 | * | ||
| 7 | * This program is provided with the V4L2 API | ||
| 8 | * see http://linuxtv.org/docs.php for more information | ||
| 9 | */ | ||
| 10 | |||
| 11 | #include <stdio.h> | ||
| 12 | #include <stdlib.h> | ||
| 13 | #include <string.h> | ||
| 14 | #include <assert.h> | ||
| 15 | |||
| 16 | #include <getopt.h> /* getopt_long() */ | ||
| 17 | |||
| 18 | #include <fcntl.h> /* low-level i/o */ | ||
| 19 | #include <unistd.h> | ||
| 20 | #include <errno.h> | ||
| 21 | #include <sys/stat.h> | ||
| 22 | #include <sys/types.h> | ||
| 23 | #include <sys/time.h> | ||
| 24 | #include <sys/mman.h> | ||
| 25 | #include <sys/ioctl.h> | ||
| 26 | |||
| 27 | #include <linux/videodev2.h> | ||
| 28 | |||
| 29 | #define CLEAR(x) memset(&(x), 0, sizeof(x)) | ||
| 30 | |||
| 31 | enum io_method { | ||
| 32 | IO_METHOD_READ, | ||
| 33 | IO_METHOD_MMAP, | ||
| 34 | IO_METHOD_USERPTR, | ||
| 35 | }; | ||
| 36 | |||
| 37 | struct buffer { | ||
| 38 | void *start; | ||
| 39 | size_t length; | ||
| 40 | }; | ||
| 41 | |||
| 42 | static char *dev_name; | ||
| 43 | static enum io_method io = IO_METHOD_MMAP; | ||
| 44 | static int fd = -1; | ||
| 45 | struct buffer *buffers; | ||
| 46 | static unsigned int n_buffers; | ||
| 47 | static int out_buf; | ||
| 48 | static int force_format; | ||
| 49 | static int frame_count = 70; | ||
| 50 | |||
| 51 | static void errno_exit(const char *s) | ||
| 52 | { | ||
| 53 | fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); | ||
| 54 | exit(EXIT_FAILURE); | ||
| 55 | } | ||
| 56 | |||
| 57 | static int xioctl(int fh, int request, void *arg) | ||
| 58 | { | ||
| 59 | int r; | ||
| 60 | |||
| 61 | do { | ||
| 62 | r = ioctl(fh, request, arg); | ||
| 63 | } while (-1 == r && EINTR == errno); | ||
| 64 | |||
| 65 | return r; | ||
| 66 | } | ||
| 67 | |||
| 68 | static void process_image(const void *p, int size) | ||
| 69 | { | ||
| 70 | if (out_buf) | ||
| 71 | fwrite(p, size, 1, stdout); | ||
| 72 | |||
| 73 | fflush(stderr); | ||
| 74 | fprintf(stderr, "."); | ||
| 75 | fflush(stdout); | ||
| 76 | } | ||
| 77 | |||
| 78 | static int read_frame(void) | ||
| 79 | { | ||
| 80 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 81 | unsigned int i; | ||
| 82 | |||
| 83 | switch (io) { | ||
| 84 | case IO_METHOD_READ: | ||
| 85 | if (-1 == read(fd, buffers[0].start, buffers[0].length)) { | ||
| 86 | switch (errno) { | ||
| 87 | case EAGAIN: | ||
| 88 | return 0; | ||
| 89 | |||
| 90 | case EIO: | ||
| 91 | /* Could ignore EIO, see spec. */ | ||
| 92 | |||
| 93 | /* fall through */ | ||
| 94 | |||
| 95 | default: | ||
| 96 | errno_exit("read"); | ||
| 97 | } | ||
| 98 | } | ||
| 99 | |||
| 100 | process_image(buffers[0].start, buffers[0].length); | ||
| 101 | break; | ||
| 102 | |||
| 103 | case IO_METHOD_MMAP: | ||
| 104 | CLEAR(buf); | ||
| 105 | |||
| 106 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 107 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 108 | |||
| 109 | if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { | ||
| 110 | switch (errno) { | ||
| 111 | case EAGAIN: | ||
| 112 | return 0; | ||
| 113 | |||
| 114 | case EIO: | ||
| 115 | /* Could ignore EIO, see spec. */ | ||
| 116 | |||
| 117 | /* fall through */ | ||
| 118 | |||
| 119 | default: | ||
| 120 | errno_exit("VIDIOC_DQBUF"); | ||
| 121 | } | ||
| 122 | } | ||
| 123 | |||
| 124 | assert(buf.index < n_buffers); | ||
| 125 | |||
| 126 | process_image(buffers[buf.index].start, buf.bytesused); | ||
| 127 | |||
| 128 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 129 | errno_exit("VIDIOC_QBUF"); | ||
| 130 | break; | ||
| 131 | |||
| 132 | case IO_METHOD_USERPTR: | ||
| 133 | CLEAR(buf); | ||
| 134 | |||
| 135 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 136 | buf.memory = V4L2_MEMORY_USERPTR; | ||
| 137 | |||
| 138 | if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { | ||
| 139 | switch (errno) { | ||
| 140 | case EAGAIN: | ||
| 141 | return 0; | ||
| 142 | |||
| 143 | case EIO: | ||
| 144 | /* Could ignore EIO, see spec. */ | ||
| 145 | |||
| 146 | /* fall through */ | ||
| 147 | |||
| 148 | default: | ||
| 149 | errno_exit("VIDIOC_DQBUF"); | ||
| 150 | } | ||
| 151 | } | ||
| 152 | |||
| 153 | for (i = 0; i < n_buffers; ++i) | ||
| 154 | if (buf.m.userptr == (unsigned long)buffers[i].start | ||
| 155 | && buf.length == buffers[i].length) | ||
| 156 | break; | ||
| 157 | |||
| 158 | assert(i < n_buffers); | ||
| 159 | |||
| 160 | process_image((void *)buf.m.userptr, buf.bytesused); | ||
| 161 | |||
| 162 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 163 | errno_exit("VIDIOC_QBUF"); | ||
| 164 | break; | ||
| 165 | } | ||
| 166 | |||
| 167 | return 1; | ||
| 168 | } | ||
| 169 | |||
| 170 | static void mainloop(void) | ||
| 171 | { | ||
| 172 | unsigned int count; | ||
| 173 | |||
| 174 | count = frame_count; | ||
| 175 | |||
| 176 | while (count-- > 0) { | ||
| 177 | for (;;) { | ||
| 178 | fd_set fds; | ||
| 179 | struct timeval tv; | ||
| 180 | int r; | ||
| 181 | |||
| 182 | FD_ZERO(&fds); | ||
| 183 | FD_SET(fd, &fds); | ||
| 184 | |||
| 185 | /* Timeout. */ | ||
| 186 | tv.tv_sec = 2; | ||
| 187 | tv.tv_usec = 0; | ||
| 188 | |||
| 189 | r = select(fd + 1, &fds, NULL, NULL, &tv); | ||
| 190 | |||
| 191 | if (-1 == r) { | ||
| 192 | if (EINTR == errno) | ||
| 193 | continue; | ||
| 194 | errno_exit("select"); | ||
| 195 | } | ||
| 196 | |||
| 197 | if (0 == r) { | ||
| 198 | fprintf(stderr, "select timeout\n"); | ||
| 199 | exit(EXIT_FAILURE); | ||
| 200 | } | ||
| 201 | |||
| 202 | if (read_frame()) | ||
| 203 | break; | ||
| 204 | /* EAGAIN - continue select loop. */ | ||
| 205 | } | ||
| 206 | } | ||
| 207 | } | ||
| 208 | |||
| 209 | static void stop_capturing(void) | ||
| 210 | { | ||
| 211 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 212 | |||
| 213 | switch (io) { | ||
| 214 | case IO_METHOD_READ: | ||
| 215 | /* Nothing to do. */ | ||
| 216 | break; | ||
| 217 | |||
| 218 | case IO_METHOD_MMAP: | ||
| 219 | case IO_METHOD_USERPTR: | ||
| 220 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 221 | if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) | ||
| 222 | errno_exit("VIDIOC_STREAMOFF"); | ||
| 223 | break; | ||
| 224 | } | ||
| 225 | } | ||
| 226 | |||
| 227 | static void start_capturing(void) | ||
| 228 | { | ||
| 229 | unsigned int i; | ||
| 230 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 231 | |||
| 232 | switch (io) { | ||
| 233 | case IO_METHOD_READ: | ||
| 234 | /* Nothing to do. */ | ||
| 235 | break; | ||
| 236 | |||
| 237 | case IO_METHOD_MMAP: | ||
| 238 | for (i = 0; i < n_buffers; ++i) { | ||
| 239 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 240 | |||
| 241 | CLEAR(buf); | ||
| 242 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 243 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 244 | buf.index = i; | ||
| 245 | |||
| 246 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 247 | errno_exit("VIDIOC_QBUF"); | ||
| 248 | } | ||
| 249 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 250 | if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) | ||
| 251 | errno_exit("VIDIOC_STREAMON"); | ||
| 252 | break; | ||
| 253 | |||
| 254 | case IO_METHOD_USERPTR: | ||
| 255 | for (i = 0; i < n_buffers; ++i) { | ||
| 256 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 257 | |||
| 258 | CLEAR(buf); | ||
| 259 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 260 | buf.memory = V4L2_MEMORY_USERPTR; | ||
| 261 | buf.index = i; | ||
| 262 | buf.m.userptr = (unsigned long)buffers[i].start; | ||
| 263 | buf.length = buffers[i].length; | ||
| 264 | |||
| 265 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 266 | errno_exit("VIDIOC_QBUF"); | ||
| 267 | } | ||
| 268 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 269 | if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) | ||
| 270 | errno_exit("VIDIOC_STREAMON"); | ||
| 271 | break; | ||
| 272 | } | ||
| 273 | } | ||
| 274 | |||
| 275 | static void uninit_device(void) | ||
| 276 | { | ||
| 277 | unsigned int i; | ||
| 278 | |||
| 279 | switch (io) { | ||
| 280 | case IO_METHOD_READ: | ||
| 281 | free(buffers[0].start); | ||
| 282 | break; | ||
| 283 | |||
| 284 | case IO_METHOD_MMAP: | ||
| 285 | for (i = 0; i < n_buffers; ++i) | ||
| 286 | if (-1 == munmap(buffers[i].start, buffers[i].length)) | ||
| 287 | errno_exit("munmap"); | ||
| 288 | break; | ||
| 289 | |||
| 290 | case IO_METHOD_USERPTR: | ||
| 291 | for (i = 0; i < n_buffers; ++i) | ||
| 292 | free(buffers[i].start); | ||
| 293 | break; | ||
| 294 | } | ||
| 295 | |||
| 296 | free(buffers); | ||
| 297 | } | ||
| 298 | |||
| 299 | static void init_read(unsigned int buffer_size) | ||
| 300 | { | ||
| 301 | buffers = calloc(1, sizeof(*buffers)); | ||
| 302 | |||
| 303 | if (!buffers) { | ||
| 304 | fprintf(stderr, "Out of memory\n"); | ||
| 305 | exit(EXIT_FAILURE); | ||
| 306 | } | ||
| 307 | |||
| 308 | buffers[0].length = buffer_size; | ||
| 309 | buffers[0].start = malloc(buffer_size); | ||
| 310 | |||
| 311 | if (!buffers[0].start) { | ||
| 312 | fprintf(stderr, "Out of memory\n"); | ||
| 313 | exit(EXIT_FAILURE); | ||
| 314 | } | ||
| 315 | } | ||
| 316 | |||
| 317 | static void init_mmap(void) | ||
| 318 | { | ||
| 319 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 320 | |||
| 321 | CLEAR(req); | ||
| 322 | |||
| 323 | req.count = 4; | ||
| 324 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 325 | req.memory = V4L2_MEMORY_MMAP; | ||
| 326 | |||
| 327 | if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { | ||
| 328 | if (EINVAL == errno) { | ||
| 329 | fprintf(stderr, "%s does not support " | ||
| 330 | "memory mapping\n", dev_name); | ||
| 331 | exit(EXIT_FAILURE); | ||
| 332 | } else { | ||
| 333 | errno_exit("VIDIOC_REQBUFS"); | ||
| 334 | } | ||
| 335 | } | ||
| 336 | |||
| 337 | if (req.count < 2) { | ||
| 338 | fprintf(stderr, "Insufficient buffer memory on %s\n", | ||
| 339 | dev_name); | ||
| 340 | exit(EXIT_FAILURE); | ||
| 341 | } | ||
| 342 | |||
| 343 | buffers = calloc(req.count, sizeof(*buffers)); | ||
| 344 | |||
| 345 | if (!buffers) { | ||
| 346 | fprintf(stderr, "Out of memory\n"); | ||
| 347 | exit(EXIT_FAILURE); | ||
| 348 | } | ||
| 349 | |||
| 350 | for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { | ||
| 351 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 352 | |||
| 353 | CLEAR(buf); | ||
| 354 | |||
| 355 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 356 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 357 | buf.index = n_buffers; | ||
| 358 | |||
| 359 | if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) | ||
| 360 | errno_exit("VIDIOC_QUERYBUF"); | ||
| 361 | |||
| 362 | buffers[n_buffers].length = buf.length; | ||
| 363 | buffers[n_buffers].start = | ||
| 364 | mmap(NULL /* start anywhere */, | ||
| 365 | buf.length, | ||
| 366 | PROT_READ | PROT_WRITE /* required */, | ||
| 367 | MAP_SHARED /* recommended */, | ||
| 368 | fd, buf.m.offset); | ||
| 369 | |||
| 370 | if (MAP_FAILED == buffers[n_buffers].start) | ||
| 371 | errno_exit("mmap"); | ||
| 372 | } | ||
| 373 | } | ||
| 374 | |||
| 375 | static void init_userp(unsigned int buffer_size) | ||
| 376 | { | ||
| 377 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 378 | |||
| 379 | CLEAR(req); | ||
| 380 | |||
| 381 | req.count = 4; | ||
| 382 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 383 | req.memory = V4L2_MEMORY_USERPTR; | ||
| 384 | |||
| 385 | if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { | ||
| 386 | if (EINVAL == errno) { | ||
| 387 | fprintf(stderr, "%s does not support " | ||
| 388 | "user pointer i/o\n", dev_name); | ||
| 389 | exit(EXIT_FAILURE); | ||
| 390 | } else { | ||
| 391 | errno_exit("VIDIOC_REQBUFS"); | ||
| 392 | } | ||
| 393 | } | ||
| 394 | |||
| 395 | buffers = calloc(4, sizeof(*buffers)); | ||
| 396 | |||
| 397 | if (!buffers) { | ||
| 398 | fprintf(stderr, "Out of memory\n"); | ||
| 399 | exit(EXIT_FAILURE); | ||
| 400 | } | ||
| 401 | |||
| 402 | for (n_buffers = 0; n_buffers < 4; ++n_buffers) { | ||
| 403 | buffers[n_buffers].length = buffer_size; | ||
| 404 | buffers[n_buffers].start = malloc(buffer_size); | ||
| 405 | |||
| 406 | if (!buffers[n_buffers].start) { | ||
| 407 | fprintf(stderr, "Out of memory\n"); | ||
| 408 | exit(EXIT_FAILURE); | ||
| 409 | } | ||
| 410 | } | ||
| 411 | } | ||
| 412 | |||
| 413 | static void init_device(void) | ||
| 414 | { | ||
| 415 | struct <link linkend="v4l2-capability">v4l2_capability</link> cap; | ||
| 416 | struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap; | ||
| 417 | struct <link linkend="v4l2-crop">v4l2_crop</link> crop; | ||
| 418 | struct <link linkend="v4l2-format">v4l2_format</link> fmt; | ||
| 419 | unsigned int min; | ||
| 420 | |||
| 421 | if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { | ||
| 422 | if (EINVAL == errno) { | ||
| 423 | fprintf(stderr, "%s is no V4L2 device\n", | ||
| 424 | dev_name); | ||
| 425 | exit(EXIT_FAILURE); | ||
| 426 | } else { | ||
| 427 | errno_exit("VIDIOC_QUERYCAP"); | ||
| 428 | } | ||
| 429 | } | ||
| 430 | |||
| 431 | if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { | ||
| 432 | fprintf(stderr, "%s is no video capture device\n", | ||
| 433 | dev_name); | ||
| 434 | exit(EXIT_FAILURE); | ||
| 435 | } | ||
| 436 | |||
| 437 | switch (io) { | ||
| 438 | case IO_METHOD_READ: | ||
| 439 | if (!(cap.capabilities & V4L2_CAP_READWRITE)) { | ||
| 440 | fprintf(stderr, "%s does not support read i/o\n", | ||
| 441 | dev_name); | ||
| 442 | exit(EXIT_FAILURE); | ||
| 443 | } | ||
| 444 | break; | ||
| 445 | |||
| 446 | case IO_METHOD_MMAP: | ||
| 447 | case IO_METHOD_USERPTR: | ||
| 448 | if (!(cap.capabilities & V4L2_CAP_STREAMING)) { | ||
| 449 | fprintf(stderr, "%s does not support streaming i/o\n", | ||
| 450 | dev_name); | ||
| 451 | exit(EXIT_FAILURE); | ||
| 452 | } | ||
| 453 | break; | ||
| 454 | } | ||
| 455 | |||
| 456 | |||
| 457 | /* Select video input, video standard and tune here. */ | ||
| 458 | |||
| 459 | |||
| 460 | CLEAR(cropcap); | ||
| 461 | |||
| 462 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 463 | |||
| 464 | if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { | ||
| 465 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 466 | crop.c = cropcap.defrect; /* reset to default */ | ||
| 467 | |||
| 468 | if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { | ||
| 469 | switch (errno) { | ||
| 470 | case EINVAL: | ||
| 471 | /* Cropping not supported. */ | ||
| 472 | break; | ||
| 473 | default: | ||
| 474 | /* Errors ignored. */ | ||
| 475 | break; | ||
| 476 | } | ||
| 477 | } | ||
| 478 | } else { | ||
| 479 | /* Errors ignored. */ | ||
| 480 | } | ||
| 481 | |||
| 482 | |||
| 483 | CLEAR(fmt); | ||
| 484 | |||
| 485 | fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 486 | if (force_format) { | ||
| 487 | fmt.fmt.pix.width = 640; | ||
| 488 | fmt.fmt.pix.height = 480; | ||
| 489 | fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; | ||
| 490 | fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; | ||
| 491 | |||
| 492 | if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) | ||
| 493 | errno_exit("VIDIOC_S_FMT"); | ||
| 494 | |||
| 495 | /* Note VIDIOC_S_FMT may change width and height. */ | ||
| 496 | } else { | ||
| 497 | /* Preserve original settings as set by v4l2-ctl for example */ | ||
| 498 | if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) | ||
| 499 | errno_exit("VIDIOC_G_FMT"); | ||
| 500 | } | ||
| 501 | |||
| 502 | /* Buggy driver paranoia. */ | ||
| 503 | min = fmt.fmt.pix.width * 2; | ||
| 504 | if (fmt.fmt.pix.bytesperline < min) | ||
| 505 | fmt.fmt.pix.bytesperline = min; | ||
| 506 | min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; | ||
| 507 | if (fmt.fmt.pix.sizeimage < min) | ||
| 508 | fmt.fmt.pix.sizeimage = min; | ||
| 509 | |||
| 510 | switch (io) { | ||
| 511 | case IO_METHOD_READ: | ||
| 512 | init_read(fmt.fmt.pix.sizeimage); | ||
| 513 | break; | ||
| 514 | |||
| 515 | case IO_METHOD_MMAP: | ||
| 516 | init_mmap(); | ||
| 517 | break; | ||
| 518 | |||
| 519 | case IO_METHOD_USERPTR: | ||
| 520 | init_userp(fmt.fmt.pix.sizeimage); | ||
| 521 | break; | ||
| 522 | } | ||
| 523 | } | ||
| 524 | |||
| 525 | static void close_device(void) | ||
| 526 | { | ||
| 527 | if (-1 == close(fd)) | ||
| 528 | errno_exit("close"); | ||
| 529 | |||
| 530 | fd = -1; | ||
| 531 | } | ||
| 532 | |||
| 533 | static void open_device(void) | ||
| 534 | { | ||
| 535 | struct stat st; | ||
| 536 | |||
| 537 | if (-1 == stat(dev_name, &st)) { | ||
| 538 | fprintf(stderr, "Cannot identify '%s': %d, %s\n", | ||
| 539 | dev_name, errno, strerror(errno)); | ||
| 540 | exit(EXIT_FAILURE); | ||
| 541 | } | ||
| 542 | |||
| 543 | if (!S_ISCHR(st.st_mode)) { | ||
| 544 | fprintf(stderr, "%s is no device\n", dev_name); | ||
| 545 | exit(EXIT_FAILURE); | ||
| 546 | } | ||
| 547 | |||
| 548 | fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); | ||
| 549 | |||
| 550 | if (-1 == fd) { | ||
| 551 | fprintf(stderr, "Cannot open '%s': %d, %s\n", | ||
| 552 | dev_name, errno, strerror(errno)); | ||
| 553 | exit(EXIT_FAILURE); | ||
| 554 | } | ||
| 555 | } | ||
| 556 | |||
| 557 | static void usage(FILE *fp, int argc, char **argv) | ||
| 558 | { | ||
| 559 | fprintf(fp, | ||
| 560 | "Usage: %s [options]\n\n" | ||
| 561 | "Version 1.3\n" | ||
| 562 | "Options:\n" | ||
| 563 | "-d | --device name Video device name [%s]\n" | ||
| 564 | "-h | --help Print this message\n" | ||
| 565 | "-m | --mmap Use memory mapped buffers [default]\n" | ||
| 566 | "-r | --read Use read() calls\n" | ||
| 567 | "-u | --userp Use application allocated buffers\n" | ||
| 568 | "-o | --output Outputs stream to stdout\n" | ||
| 569 | "-f | --format Force format to 640x480 YUYV\n" | ||
| 570 | "-c | --count Number of frames to grab [%i]\n" | ||
| 571 | "", | ||
| 572 | argv[0], dev_name, frame_count); | ||
| 573 | } | ||
| 574 | |||
| 575 | static const char short_options[] = "d:hmruofc:"; | ||
| 576 | |||
| 577 | static const struct option | ||
| 578 | long_options[] = { | ||
| 579 | { "device", required_argument, NULL, 'd' }, | ||
| 580 | { "help", no_argument, NULL, 'h' }, | ||
| 581 | { "mmap", no_argument, NULL, 'm' }, | ||
| 582 | { "read", no_argument, NULL, 'r' }, | ||
| 583 | { "userp", no_argument, NULL, 'u' }, | ||
| 584 | { "output", no_argument, NULL, 'o' }, | ||
| 585 | { "format", no_argument, NULL, 'f' }, | ||
| 586 | { "count", required_argument, NULL, 'c' }, | ||
| 587 | { 0, 0, 0, 0 } | ||
| 588 | }; | ||
| 589 | |||
| 590 | int main(int argc, char **argv) | ||
| 591 | { | ||
| 592 | dev_name = "/dev/video0"; | ||
| 593 | |||
| 594 | for (;;) { | ||
| 595 | int idx; | ||
| 596 | int c; | ||
| 597 | |||
| 598 | c = getopt_long(argc, argv, | ||
| 599 | short_options, long_options, &idx); | ||
| 600 | |||
| 601 | if (-1 == c) | ||
| 602 | break; | ||
| 603 | |||
| 604 | switch (c) { | ||
| 605 | case 0: /* getopt_long() flag */ | ||
| 606 | break; | ||
| 607 | |||
| 608 | case 'd': | ||
| 609 | dev_name = optarg; | ||
| 610 | break; | ||
| 611 | |||
| 612 | case 'h': | ||
| 613 | usage(stdout, argc, argv); | ||
| 614 | exit(EXIT_SUCCESS); | ||
| 615 | |||
| 616 | case 'm': | ||
| 617 | io = IO_METHOD_MMAP; | ||
| 618 | break; | ||
| 619 | |||
| 620 | case 'r': | ||
| 621 | io = IO_METHOD_READ; | ||
| 622 | break; | ||
| 623 | |||
| 624 | case 'u': | ||
| 625 | io = IO_METHOD_USERPTR; | ||
| 626 | break; | ||
| 627 | |||
| 628 | case 'o': | ||
| 629 | out_buf++; | ||
| 630 | break; | ||
| 631 | |||
| 632 | case 'f': | ||
| 633 | force_format++; | ||
| 634 | break; | ||
| 635 | |||
| 636 | case 'c': | ||
| 637 | errno = 0; | ||
| 638 | frame_count = strtol(optarg, NULL, 0); | ||
| 639 | if (errno) | ||
| 640 | errno_exit(optarg); | ||
| 641 | break; | ||
| 642 | |||
| 643 | default: | ||
| 644 | usage(stderr, argc, argv); | ||
| 645 | exit(EXIT_FAILURE); | ||
| 646 | } | ||
| 647 | } | ||
| 648 | |||
| 649 | open_device(); | ||
| 650 | init_device(); | ||
| 651 | start_capturing(); | ||
| 652 | mainloop(); | ||
| 653 | stop_capturing(); | ||
| 654 | uninit_device(); | ||
| 655 | close_device(); | ||
| 656 | fprintf(stderr, "\n"); | ||
| 657 | return 0; | ||
| 658 | } | ||
| 659 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml new file mode 100644 index 000000000000..b1a81d246d58 --- /dev/null +++ b/Documentation/DocBook/v4l/common.xml | |||
| @@ -0,0 +1,1160 @@ | |||
| 1 | <title>Common API Elements</title> | ||
| 2 | |||
| 3 | <para>Programming a V4L2 device consists of these | ||
| 4 | steps:</para> | ||
| 5 | |||
| 6 | <itemizedlist> | ||
| 7 | <listitem> | ||
| 8 | <para>Opening the device</para> | ||
| 9 | </listitem> | ||
| 10 | <listitem> | ||
| 11 | <para>Changing device properties, selecting a video and audio | ||
| 12 | input, video standard, picture brightness a. o.</para> | ||
| 13 | </listitem> | ||
| 14 | <listitem> | ||
| 15 | <para>Negotiating a data format</para> | ||
| 16 | </listitem> | ||
| 17 | <listitem> | ||
| 18 | <para>Negotiating an input/output method</para> | ||
| 19 | </listitem> | ||
| 20 | <listitem> | ||
| 21 | <para>The actual input/output loop</para> | ||
| 22 | </listitem> | ||
| 23 | <listitem> | ||
| 24 | <para>Closing the device</para> | ||
| 25 | </listitem> | ||
| 26 | </itemizedlist> | ||
| 27 | |||
| 28 | <para>In practice most steps are optional and can be executed out of | ||
| 29 | order. It depends on the V4L2 device type, you can read about the | ||
| 30 | details in <xref linkend="devices" />. In this chapter we will discuss | ||
| 31 | the basic concepts applicable to all devices.</para> | ||
| 32 | |||
| 33 | <section id="open"> | ||
| 34 | <title>Opening and Closing Devices</title> | ||
| 35 | |||
| 36 | <section> | ||
| 37 | <title>Device Naming</title> | ||
| 38 | |||
| 39 | <para>V4L2 drivers are implemented as kernel modules, loaded | ||
| 40 | manually by the system administrator or automatically when a device is | ||
| 41 | first opened. The driver modules plug into the "videodev" kernel | ||
| 42 | module. It provides helper functions and a common application | ||
| 43 | interface specified in this document.</para> | ||
| 44 | |||
| 45 | <para>Each driver thus loaded registers one or more device nodes | ||
| 46 | with major number 81 and a minor number between 0 and 255. Assigning | ||
| 47 | minor numbers to V4L2 devices is entirely up to the system administrator, | ||
| 48 | this is primarily intended to solve conflicts between devices.<footnote> | ||
| 49 | <para>Access permissions are associated with character | ||
| 50 | device special files, hence we must ensure device numbers cannot | ||
| 51 | change with the module load order. To this end minor numbers are no | ||
| 52 | longer automatically assigned by the "videodev" module as in V4L but | ||
| 53 | requested by the driver. The defaults will suffice for most people | ||
| 54 | unless two drivers compete for the same minor numbers.</para> | ||
| 55 | </footnote> The module options to select minor numbers are named | ||
| 56 | after the device special file with a "_nr" suffix. For example "video_nr" | ||
| 57 | for <filename>/dev/video</filename> video capture devices. The number is | ||
| 58 | an offset to the base minor number associated with the device type. | ||
| 59 | <footnote> | ||
| 60 | <para>In earlier versions of the V4L2 API the module options | ||
| 61 | where named after the device special file with a "unit_" prefix, expressing | ||
| 62 | the minor number itself, not an offset. Rationale for this change is unknown. | ||
| 63 | Lastly the naming and semantics are just a convention among driver writers, | ||
| 64 | the point to note is that minor numbers are not supposed to be hardcoded | ||
| 65 | into drivers.</para> | ||
| 66 | </footnote> When the driver supports multiple devices of the same | ||
| 67 | type more than one minor number can be assigned, separated by commas: | ||
| 68 | <informalexample> | ||
| 69 | <screen> | ||
| 70 | > insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen> | ||
| 71 | </informalexample></para> | ||
| 72 | |||
| 73 | <para>In <filename>/etc/modules.conf</filename> this may be | ||
| 74 | written as: <informalexample> | ||
| 75 | <screen> | ||
| 76 | alias char-major-81-0 mydriver | ||
| 77 | alias char-major-81-1 mydriver | ||
| 78 | alias char-major-81-64 mydriver <co id="alias" /> | ||
| 79 | options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" /> | ||
| 80 | </screen> | ||
| 81 | <calloutlist> | ||
| 82 | <callout arearefs="alias"> | ||
| 83 | <para>When an application attempts to open a device | ||
| 84 | special file with major number 81 and minor number 0, 1, or 64, load | ||
| 85 | "mydriver" (and the "videodev" module it depends upon).</para> | ||
| 86 | </callout> | ||
| 87 | <callout arearefs="options"> | ||
| 88 | <para>Register the first two video capture devices with | ||
| 89 | minor number 0 and 1 (base number is 0), the first two radio device | ||
| 90 | with minor number 64 and 65 (base 64).</para> | ||
| 91 | </callout> | ||
| 92 | </calloutlist> | ||
| 93 | </informalexample> When no minor number is given as module | ||
| 94 | option the driver supplies a default. <xref linkend="devices" /> | ||
| 95 | recommends the base minor numbers to be used for the various device | ||
| 96 | types. Obviously minor numbers must be unique. When the number is | ||
| 97 | already in use the <emphasis>offending device</emphasis> will not be | ||
| 98 | registered. <!-- Blessed by Linus Torvalds on | ||
| 99 | linux-kernel@vger.kernel.org, 2002-11-20. --></para> | ||
| 100 | |||
| 101 | <para>By convention system administrators create various | ||
| 102 | character device special files with these major and minor numbers in | ||
| 103 | the <filename>/dev</filename> directory. The names recomended for the | ||
| 104 | different V4L2 device types are listed in <xref linkend="devices" />. | ||
| 105 | </para> | ||
| 106 | |||
| 107 | <para>The creation of character special files (with | ||
| 108 | <application>mknod</application>) is a privileged operation and | ||
| 109 | devices cannot be opened by major and minor number. That means | ||
| 110 | applications cannot <emphasis>reliable</emphasis> scan for loaded or | ||
| 111 | installed drivers. The user must enter a device name, or the | ||
| 112 | application can try the conventional device names.</para> | ||
| 113 | |||
| 114 | <para>Under the device filesystem (devfs) the minor number | ||
| 115 | options are ignored. V4L2 drivers (or by proxy the "videodev" module) | ||
| 116 | automatically create the required device files in the | ||
| 117 | <filename>/dev/v4l</filename> directory using the conventional device | ||
| 118 | names above.</para> | ||
| 119 | </section> | ||
| 120 | |||
| 121 | <section id="related"> | ||
| 122 | <title>Related Devices</title> | ||
| 123 | |||
| 124 | <para>Devices can support several related functions. For example | ||
| 125 | video capturing, video overlay and VBI capturing are related because | ||
| 126 | these functions share, amongst other, the same video input and tuner | ||
| 127 | frequency. V4L and earlier versions of V4L2 used the same device name | ||
| 128 | and minor number for video capturing and overlay, but different ones | ||
| 129 | for VBI. Experience showed this approach has several problems<footnote> | ||
| 130 | <para>Given a device file name one cannot reliable find | ||
| 131 | related devices. For once names are arbitrary and in a system with | ||
| 132 | multiple devices, where only some support VBI capturing, a | ||
| 133 | <filename>/dev/video2</filename> is not necessarily related to | ||
| 134 | <filename>/dev/vbi2</filename>. The V4L | ||
| 135 | <constant>VIDIOCGUNIT</constant> ioctl would require a search for a | ||
| 136 | device file with a particular major and minor number.</para> | ||
| 137 | </footnote>, and to make things worse the V4L videodev module | ||
| 138 | used to prohibit multiple opens of a device.</para> | ||
| 139 | |||
| 140 | <para>As a remedy the present version of the V4L2 API relaxed the | ||
| 141 | concept of device types with specific names and minor numbers. For | ||
| 142 | compatibility with old applications drivers must still register different | ||
| 143 | minor numbers to assign a default function to the device. But if related | ||
| 144 | functions are supported by the driver they must be available under all | ||
| 145 | registered minor numbers. The desired function can be selected after | ||
| 146 | opening the device as described in <xref linkend="devices" />.</para> | ||
| 147 | |||
| 148 | <para>Imagine a driver supporting video capturing, video | ||
| 149 | overlay, raw VBI capturing, and FM radio reception. It registers three | ||
| 150 | devices with minor number 0, 64 and 224 (this numbering scheme is | ||
| 151 | inherited from the V4L API). Regardless if | ||
| 152 | <filename>/dev/video</filename> (81, 0) or | ||
| 153 | <filename>/dev/vbi</filename> (81, 224) is opened the application can | ||
| 154 | select any one of the video capturing, overlay or VBI capturing | ||
| 155 | functions. Without programming (e. g. reading from the device | ||
| 156 | with <application>dd</application> or <application>cat</application>) | ||
| 157 | <filename>/dev/video</filename> captures video images, while | ||
| 158 | <filename>/dev/vbi</filename> captures raw VBI data. | ||
| 159 | <filename>/dev/radio</filename> (81, 64) is invariable a radio device, | ||
| 160 | unrelated to the video functions. Being unrelated does not imply the | ||
| 161 | devices can be used at the same time, however. The &func-open; | ||
| 162 | function may very well return an &EBUSY;.</para> | ||
| 163 | |||
| 164 | <para>Besides video input or output the hardware may also | ||
| 165 | support audio sampling or playback. If so, these functions are | ||
| 166 | implemented as OSS or ALSA PCM devices and eventually OSS or ALSA | ||
| 167 | audio mixer. The V4L2 API makes no provisions yet to find these | ||
| 168 | related devices. If you have an idea please write to the linux-media | ||
| 169 | mailing list: &v4l-ml;.</para> | ||
| 170 | </section> | ||
| 171 | |||
| 172 | <section> | ||
| 173 | <title>Multiple Opens</title> | ||
| 174 | |||
| 175 | <para>In general, V4L2 devices can be opened more than once. | ||
| 176 | When this is supported by the driver, users can for example start a | ||
| 177 | "panel" application to change controls like brightness or audio | ||
| 178 | volume, while another application captures video and audio. In other words, panel | ||
| 179 | applications are comparable to an OSS or ALSA audio mixer application. | ||
| 180 | When a device supports multiple functions like capturing and overlay | ||
| 181 | <emphasis>simultaneously</emphasis>, multiple opens allow concurrent | ||
| 182 | use of the device by forked processes or specialized applications.</para> | ||
| 183 | |||
| 184 | <para>Multiple opens are optional, although drivers should | ||
| 185 | permit at least concurrent accesses without data exchange, &ie; panel | ||
| 186 | applications. This implies &func-open; can return an &EBUSY; when the | ||
| 187 | device is already in use, as well as &func-ioctl; functions initiating | ||
| 188 | data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read; | ||
| 189 | and &func-write; functions.</para> | ||
| 190 | |||
| 191 | <para>Mere opening a V4L2 device does not grant exclusive | ||
| 192 | access.<footnote> | ||
| 193 | <para>Drivers could recognize the | ||
| 194 | <constant>O_EXCL</constant> open flag. Presently this is not required, | ||
| 195 | so applications cannot know if it really works.</para> | ||
| 196 | </footnote> Initiating data exchange however assigns the right | ||
| 197 | to read or write the requested type of data, and to change related | ||
| 198 | properties, to this file descriptor. Applications can request | ||
| 199 | additional access privileges using the priority mechanism described in | ||
| 200 | <xref linkend="app-pri" />.</para> | ||
| 201 | </section> | ||
| 202 | |||
| 203 | <section> | ||
| 204 | <title>Shared Data Streams</title> | ||
| 205 | |||
| 206 | <para>V4L2 drivers should not support multiple applications | ||
| 207 | reading or writing the same data stream on a device by copying | ||
| 208 | buffers, time multiplexing or similar means. This is better handled by | ||
| 209 | a proxy application in user space. When the driver supports stream | ||
| 210 | sharing anyway it must be implemented transparently. The V4L2 API does | ||
| 211 | not specify how conflicts are solved. <!-- For example O_EXCL when the | ||
| 212 | application does not want to be preempted, PROT_READ mmapped buffers | ||
| 213 | which can be mapped twice, what happens when image formats do not | ||
| 214 | match etc.--></para> | ||
| 215 | </section> | ||
| 216 | |||
| 217 | <section> | ||
| 218 | <title>Functions</title> | ||
| 219 | |||
| 220 | <para>To open and close V4L2 devices applications use the | ||
| 221 | &func-open; and &func-close; function, respectively. Devices are | ||
| 222 | programmed using the &func-ioctl; function as explained in the | ||
| 223 | following sections.</para> | ||
| 224 | </section> | ||
| 225 | </section> | ||
| 226 | |||
| 227 | <section id="querycap"> | ||
| 228 | <title>Querying Capabilities</title> | ||
| 229 | |||
| 230 | <para>Because V4L2 covers a wide variety of devices not all | ||
| 231 | aspects of the API are equally applicable to all types of devices. | ||
| 232 | Furthermore devices of the same type have different capabilities and | ||
| 233 | this specification permits the omission of a few complicated and less | ||
| 234 | important parts of the API.</para> | ||
| 235 | |||
| 236 | <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel | ||
| 237 | device is compatible with this specification, and to query the <link | ||
| 238 | linkend="devices">functions</link> and <link linkend="io">I/O | ||
| 239 | methods</link> supported by the device. Other features can be queried | ||
| 240 | by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; | ||
| 241 | to learn about the number, types and names of video connectors on the | ||
| 242 | device. Although abstraction is a major objective of this API, the | ||
| 243 | ioctl also allows driver specific applications to reliable identify | ||
| 244 | the driver.</para> | ||
| 245 | |||
| 246 | <para>All V4L2 drivers must support | ||
| 247 | <constant>VIDIOC_QUERYCAP</constant>. Applications should always call | ||
| 248 | this ioctl after opening the device.</para> | ||
| 249 | </section> | ||
| 250 | |||
| 251 | <section id="app-pri"> | ||
| 252 | <title>Application Priority</title> | ||
| 253 | |||
| 254 | <para>When multiple applications share a device it may be | ||
| 255 | desirable to assign them different priorities. Contrary to the | ||
| 256 | traditional "rm -rf /" school of thought a video recording application | ||
| 257 | could for example block other applications from changing video | ||
| 258 | controls or switching the current TV channel. Another objective is to | ||
| 259 | permit low priority applications working in background, which can be | ||
| 260 | preempted by user controlled applications and automatically regain | ||
| 261 | control of the device at a later time.</para> | ||
| 262 | |||
| 263 | <para>Since these features cannot be implemented entirely in user | ||
| 264 | space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY; | ||
| 265 | ioctls to request and query the access priority associate with a file | ||
| 266 | descriptor. Opening a device assigns a medium priority, compatible | ||
| 267 | with earlier versions of V4L2 and drivers not supporting these ioctls. | ||
| 268 | Applications requiring a different priority will usually call | ||
| 269 | <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with | ||
| 270 | the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 271 | |||
| 272 | <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, | ||
| 273 | return an &EBUSY; after another application obtained higher priority. | ||
| 274 | An event mechanism to notify applications about asynchronous property | ||
| 275 | changes has been proposed but not added yet.</para> | ||
| 276 | </section> | ||
| 277 | |||
| 278 | <section id="video"> | ||
| 279 | <title>Video Inputs and Outputs</title> | ||
| 280 | |||
| 281 | <para>Video inputs and outputs are physical connectors of a | ||
| 282 | device. These can be for example RF connectors (antenna/cable), CVBS | ||
| 283 | a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI | ||
| 284 | capture devices have inputs, output devices have outputs, at least one | ||
| 285 | each. Radio devices have no video inputs or outputs.</para> | ||
| 286 | |||
| 287 | <para>To learn about the number and attributes of the | ||
| 288 | available inputs and outputs applications can enumerate them with the | ||
| 289 | &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The | ||
| 290 | &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant> | ||
| 291 | ioctl also contains signal status information applicable when the | ||
| 292 | current video input is queried.</para> | ||
| 293 | |||
| 294 | <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the | ||
| 295 | index of the current video input or output. To select a different | ||
| 296 | input or output applications call the &VIDIOC-S-INPUT; and | ||
| 297 | &VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls | ||
| 298 | when the device has one or more inputs, all the output ioctls when the | ||
| 299 | device has one or more outputs.</para> | ||
| 300 | |||
| 301 | <!-- | ||
| 302 | <figure id=io-tree> | ||
| 303 | <title>Input and output enumeration is the root of most device properties.</title> | ||
| 304 | <mediaobject> | ||
| 305 | <imageobject> | ||
| 306 | <imagedata fileref="links.pdf" format="ps" /> | ||
| 307 | </imageobject> | ||
| 308 | <imageobject> | ||
| 309 | <imagedata fileref="links.gif" format="gif" /> | ||
| 310 | </imageobject> | ||
| 311 | <textobject> | ||
| 312 | <phrase>Links between various device property structures.</phrase> | ||
| 313 | </textobject> | ||
| 314 | </mediaobject> | ||
| 315 | </figure> | ||
| 316 | --> | ||
| 317 | |||
| 318 | <example> | ||
| 319 | <title>Information about the current video input</title> | ||
| 320 | |||
| 321 | <programlisting> | ||
| 322 | &v4l2-input; input; | ||
| 323 | int index; | ||
| 324 | |||
| 325 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &index)) { | ||
| 326 | perror ("VIDIOC_G_INPUT"); | ||
| 327 | exit (EXIT_FAILURE); | ||
| 328 | } | ||
| 329 | |||
| 330 | memset (&input, 0, sizeof (input)); | ||
| 331 | input.index = index; | ||
| 332 | |||
| 333 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 334 | perror ("VIDIOC_ENUMINPUT"); | ||
| 335 | exit (EXIT_FAILURE); | ||
| 336 | } | ||
| 337 | |||
| 338 | printf ("Current input: %s\n", input.name); | ||
| 339 | </programlisting> | ||
| 340 | </example> | ||
| 341 | |||
| 342 | <example> | ||
| 343 | <title>Switching to the first video input</title> | ||
| 344 | |||
| 345 | <programlisting> | ||
| 346 | int index; | ||
| 347 | |||
| 348 | index = 0; | ||
| 349 | |||
| 350 | if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &index)) { | ||
| 351 | perror ("VIDIOC_S_INPUT"); | ||
| 352 | exit (EXIT_FAILURE); | ||
| 353 | } | ||
| 354 | </programlisting> | ||
| 355 | </example> | ||
| 356 | </section> | ||
| 357 | |||
| 358 | <section id="audio"> | ||
| 359 | <title>Audio Inputs and Outputs</title> | ||
| 360 | |||
| 361 | <para>Audio inputs and outputs are physical connectors of a | ||
| 362 | device. Video capture devices have inputs, output devices have | ||
| 363 | outputs, zero or more each. Radio devices have no audio inputs or | ||
| 364 | outputs. They have exactly one tuner which in fact | ||
| 365 | <emphasis>is</emphasis> an audio source, but this API associates | ||
| 366 | tuners with video inputs or outputs only, and radio devices have | ||
| 367 | none of these.<footnote> | ||
| 368 | <para>Actually &v4l2-audio; ought to have a | ||
| 369 | <structfield>tuner</structfield> field like &v4l2-input;, not only | ||
| 370 | making the API more consistent but also permitting radio devices with | ||
| 371 | multiple tuners.</para> | ||
| 372 | </footnote> A connector on a TV card to loop back the received | ||
| 373 | audio signal to a sound card is not considered an audio output.</para> | ||
| 374 | |||
| 375 | <para>Audio and video inputs and outputs are associated. Selecting | ||
| 376 | a video source also selects an audio source. This is most evident when | ||
| 377 | the video and audio source is a tuner. Further audio connectors can | ||
| 378 | combine with more than one video input or output. Assumed two | ||
| 379 | composite video inputs and two audio inputs exist, there may be up to | ||
| 380 | four valid combinations. The relation of video and audio connectors | ||
| 381 | is defined in the <structfield>audioset</structfield> field of the | ||
| 382 | respective &v4l2-input; or &v4l2-output;, where each bit represents | ||
| 383 | the index number, starting at zero, of one audio input or output.</para> | ||
| 384 | |||
| 385 | <para>To learn about the number and attributes of the | ||
| 386 | available inputs and outputs applications can enumerate them with the | ||
| 387 | &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The | ||
| 388 | &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl | ||
| 389 | also contains signal status information applicable when the current | ||
| 390 | audio input is queried.</para> | ||
| 391 | |||
| 392 | <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report | ||
| 393 | the current audio input and output, respectively. Note that, unlike | ||
| 394 | &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure | ||
| 395 | as <constant>VIDIOC_ENUMAUDIO</constant> and | ||
| 396 | <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para> | ||
| 397 | |||
| 398 | <para>To select an audio input and change its properties | ||
| 399 | applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio | ||
| 400 | output (which presently has no changeable properties) applications | ||
| 401 | call the &VIDIOC-S-AUDOUT; ioctl.</para> | ||
| 402 | |||
| 403 | <para>Drivers must implement all input ioctls when the device | ||
| 404 | has one or more inputs, all output ioctls when the device has one | ||
| 405 | or more outputs. When the device has any audio inputs or outputs the | ||
| 406 | driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the | ||
| 407 | &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 408 | |||
| 409 | <example> | ||
| 410 | <title>Information about the current audio input</title> | ||
| 411 | |||
| 412 | <programlisting> | ||
| 413 | &v4l2-audio; audio; | ||
| 414 | |||
| 415 | memset (&audio, 0, sizeof (audio)); | ||
| 416 | |||
| 417 | if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &audio)) { | ||
| 418 | perror ("VIDIOC_G_AUDIO"); | ||
| 419 | exit (EXIT_FAILURE); | ||
| 420 | } | ||
| 421 | |||
| 422 | printf ("Current input: %s\n", audio.name); | ||
| 423 | </programlisting> | ||
| 424 | </example> | ||
| 425 | |||
| 426 | <example> | ||
| 427 | <title>Switching to the first audio input</title> | ||
| 428 | |||
| 429 | <programlisting> | ||
| 430 | &v4l2-audio; audio; | ||
| 431 | |||
| 432 | memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */ | ||
| 433 | |||
| 434 | audio.index = 0; | ||
| 435 | |||
| 436 | if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &audio)) { | ||
| 437 | perror ("VIDIOC_S_AUDIO"); | ||
| 438 | exit (EXIT_FAILURE); | ||
| 439 | } | ||
| 440 | </programlisting> | ||
| 441 | </example> | ||
| 442 | </section> | ||
| 443 | |||
| 444 | <section id="tuner"> | ||
| 445 | <title>Tuners and Modulators</title> | ||
| 446 | |||
| 447 | <section> | ||
| 448 | <title>Tuners</title> | ||
| 449 | |||
| 450 | <para>Video input devices can have one or more tuners | ||
| 451 | demodulating a RF signal. Each tuner is associated with one or more | ||
| 452 | video inputs, depending on the number of RF connectors on the tuner. | ||
| 453 | The <structfield>type</structfield> field of the respective | ||
| 454 | &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to | ||
| 455 | <constant>V4L2_INPUT_TYPE_TUNER</constant> and its | ||
| 456 | <structfield>tuner</structfield> field contains the index number of | ||
| 457 | the tuner.</para> | ||
| 458 | |||
| 459 | <para>Radio devices have exactly one tuner with index zero, no | ||
| 460 | video inputs.</para> | ||
| 461 | |||
| 462 | <para>To query and change tuner properties applications use the | ||
| 463 | &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The | ||
| 464 | &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also | ||
| 465 | contains signal status information applicable when the tuner of the | ||
| 466 | current video input, or a radio tuner is queried. Note that | ||
| 467 | <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, | ||
| 468 | when there is more than one at all. The tuner is solely determined by | ||
| 469 | the current video input. Drivers must support both ioctls and set the | ||
| 470 | <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability; | ||
| 471 | returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or | ||
| 472 | more tuners.</para> | ||
| 473 | </section> | ||
| 474 | |||
| 475 | <section> | ||
| 476 | <title>Modulators</title> | ||
| 477 | |||
| 478 | <para>Video output devices can have one or more modulators, uh, | ||
| 479 | modulating a video signal for radiation or connection to the antenna | ||
| 480 | input of a TV set or video recorder. Each modulator is associated with | ||
| 481 | one or more video outputs, depending on the number of RF connectors on | ||
| 482 | the modulator. The <structfield>type</structfield> field of the | ||
| 483 | respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is | ||
| 484 | set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its | ||
| 485 | <structfield>modulator</structfield> field contains the index number | ||
| 486 | of the modulator. This specification does not define radio output | ||
| 487 | devices.</para> | ||
| 488 | |||
| 489 | <para>To query and change modulator properties applications use | ||
| 490 | the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that | ||
| 491 | <constant>VIDIOC_S_MODULATOR</constant> does not switch the current | ||
| 492 | modulator, when there is more than one at all. The modulator is solely | ||
| 493 | determined by the current video output. Drivers must support both | ||
| 494 | ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in | ||
| 495 | the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the | ||
| 496 | device has one or more modulators.</para> | ||
| 497 | </section> | ||
| 498 | |||
| 499 | <section> | ||
| 500 | <title>Radio Frequency</title> | ||
| 501 | |||
| 502 | <para>To get and set the tuner or modulator radio frequency | ||
| 503 | applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY; | ||
| 504 | ioctl which both take a pointer to a &v4l2-frequency;. These ioctls | ||
| 505 | are used for TV and radio devices alike. Drivers must support both | ||
| 506 | ioctls when the tuner or modulator ioctls are supported, or | ||
| 507 | when the device is a radio device.</para> | ||
| 508 | </section> | ||
| 509 | </section> | ||
| 510 | |||
| 511 | <section id="standard"> | ||
| 512 | <title>Video Standards</title> | ||
| 513 | |||
| 514 | <para>Video devices typically support one or more different video | ||
| 515 | standards or variations of standards. Each video input and output may | ||
| 516 | support another set of standards. This set is reported by the | ||
| 517 | <structfield>std</structfield> field of &v4l2-input; and | ||
| 518 | &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and | ||
| 519 | &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para> | ||
| 520 | |||
| 521 | <para>V4L2 defines one bit for each analog video standard | ||
| 522 | currently in use worldwide, and sets aside bits for driver defined | ||
| 523 | standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs | ||
| 524 | and vice versa. Applications can use the predefined bits to select a | ||
| 525 | particular standard, although presenting the user a menu of supported | ||
| 526 | standards is preferred. To enumerate and query the attributes of the | ||
| 527 | supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para> | ||
| 528 | |||
| 529 | <para>Many of the defined standards are actually just variations | ||
| 530 | of a few major standards. The hardware may in fact not distinguish | ||
| 531 | between them, or do so internal and switch automatically. Therefore | ||
| 532 | enumerated standards also contain sets of one or more standard | ||
| 533 | bits.</para> | ||
| 534 | |||
| 535 | <para>Assume a hypothetic tuner capable of demodulating B/PAL, | ||
| 536 | G/PAL and I/PAL signals. The first enumerated standard is a set of B | ||
| 537 | and G/PAL, switched automatically depending on the selected radio | ||
| 538 | frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" | ||
| 539 | choice. Similar a Composite input may collapse standards, enumerating | ||
| 540 | "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote> | ||
| 541 | <para>Some users are already confused by technical terms PAL, | ||
| 542 | NTSC and SECAM. There is no point asking them to distinguish between | ||
| 543 | B, G, D, or K when the software or hardware can do that | ||
| 544 | automatically.</para> | ||
| 545 | </footnote></para> | ||
| 546 | |||
| 547 | <para>To query and select the standard used by the current video | ||
| 548 | input or output applications call the &VIDIOC-G-STD; and | ||
| 549 | &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> | ||
| 550 | standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> | ||
| 551 | <para>An alternative to the current scheme is to use pointers | ||
| 552 | to indices as arguments of <constant>VIDIOC_G_STD</constant> and | ||
| 553 | <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and | ||
| 554 | &v4l2-output; <structfield>std</structfield> field would be a set of | ||
| 555 | indices like <structfield>audioset</structfield>.</para> | ||
| 556 | <para>Indices are consistent with the rest of the API | ||
| 557 | and identify the standard unambiguously. In the present scheme of | ||
| 558 | things an enumerated standard is looked up by &v4l2-std-id;. Now the | ||
| 559 | standards supported by the inputs of a device can overlap. Just | ||
| 560 | assume the tuner and composite input in the example above both | ||
| 561 | exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests | ||
| 562 | a choice which does not exist. We cannot merge or omit sets, because | ||
| 563 | applications would be unable to find the standards reported by | ||
| 564 | <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations | ||
| 565 | for each input. Also selecting a standard by &v4l2-std-id; can be | ||
| 566 | ambiguous. Advantage of this method is that applications need not | ||
| 567 | identify the standard indirectly, after enumerating.</para><para>So in | ||
| 568 | summary, the lookup itself is unavoidable. The difference is only | ||
| 569 | whether the lookup is necessary to find an enumerated standard or to | ||
| 570 | switch to a standard by &v4l2-std-id;.</para> | ||
| 571 | </footnote> Drivers must implement all video standard ioctls | ||
| 572 | when the device has one or more video inputs or outputs.</para> | ||
| 573 | |||
| 574 | <para>Special rules apply to USB cameras where the notion of video | ||
| 575 | standards makes little sense. More generally any capture device, | ||
| 576 | output devices accordingly, which is <itemizedlist> | ||
| 577 | <listitem> | ||
| 578 | <para>incapable of capturing fields or frames at the nominal | ||
| 579 | rate of the video standard, or</para> | ||
| 580 | </listitem> | ||
| 581 | <listitem> | ||
| 582 | <para>where <link linkend="buffer">timestamps</link> refer | ||
| 583 | to the instant the field or frame was received by the driver, not the | ||
| 584 | capture time, or</para> | ||
| 585 | </listitem> | ||
| 586 | <listitem> | ||
| 587 | <para>where <link linkend="buffer">sequence numbers</link> | ||
| 588 | refer to the frames received by the driver, not the captured | ||
| 589 | frames.</para> | ||
| 590 | </listitem> | ||
| 591 | </itemizedlist> Here the driver shall set the | ||
| 592 | <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; | ||
| 593 | to zero, the <constant>VIDIOC_G_STD</constant>, | ||
| 594 | <constant>VIDIOC_S_STD</constant>, | ||
| 595 | <constant>VIDIOC_QUERYSTD</constant> and | ||
| 596 | <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the | ||
| 597 | &EINVAL;.<footnote> | ||
| 598 | <para>See <xref linkend="buffer" /> for a rationale. Probably | ||
| 599 | even USB cameras follow some well known video standard. It might have | ||
| 600 | been better to explicitly indicate elsewhere if a device cannot live | ||
| 601 | up to normal expectations, instead of this exception.</para> | ||
| 602 | </footnote></para> | ||
| 603 | |||
| 604 | <example> | ||
| 605 | <title>Information about the current video standard</title> | ||
| 606 | |||
| 607 | <programlisting> | ||
| 608 | &v4l2-std-id; std_id; | ||
| 609 | &v4l2-standard; standard; | ||
| 610 | |||
| 611 | if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { | ||
| 612 | /* Note when VIDIOC_ENUMSTD always returns EINVAL this | ||
| 613 | is no video device or it falls under the USB exception, | ||
| 614 | and VIDIOC_G_STD returning EINVAL is no error. */ | ||
| 615 | |||
| 616 | perror ("VIDIOC_G_STD"); | ||
| 617 | exit (EXIT_FAILURE); | ||
| 618 | } | ||
| 619 | |||
| 620 | memset (&standard, 0, sizeof (standard)); | ||
| 621 | standard.index = 0; | ||
| 622 | |||
| 623 | while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { | ||
| 624 | if (standard.id & std_id) { | ||
| 625 | printf ("Current video standard: %s\n", standard.name); | ||
| 626 | exit (EXIT_SUCCESS); | ||
| 627 | } | ||
| 628 | |||
| 629 | standard.index++; | ||
| 630 | } | ||
| 631 | |||
| 632 | /* EINVAL indicates the end of the enumeration, which cannot be | ||
| 633 | empty unless this device falls under the USB exception. */ | ||
| 634 | |||
| 635 | if (errno == EINVAL || standard.index == 0) { | ||
| 636 | perror ("VIDIOC_ENUMSTD"); | ||
| 637 | exit (EXIT_FAILURE); | ||
| 638 | } | ||
| 639 | </programlisting> | ||
| 640 | </example> | ||
| 641 | |||
| 642 | <example> | ||
| 643 | <title>Listing the video standards supported by the current | ||
| 644 | input</title> | ||
| 645 | |||
| 646 | <programlisting> | ||
| 647 | &v4l2-input; input; | ||
| 648 | &v4l2-standard; standard; | ||
| 649 | |||
| 650 | memset (&input, 0, sizeof (input)); | ||
| 651 | |||
| 652 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { | ||
| 653 | perror ("VIDIOC_G_INPUT"); | ||
| 654 | exit (EXIT_FAILURE); | ||
| 655 | } | ||
| 656 | |||
| 657 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 658 | perror ("VIDIOC_ENUM_INPUT"); | ||
| 659 | exit (EXIT_FAILURE); | ||
| 660 | } | ||
| 661 | |||
| 662 | printf ("Current input %s supports:\n", input.name); | ||
| 663 | |||
| 664 | memset (&standard, 0, sizeof (standard)); | ||
| 665 | standard.index = 0; | ||
| 666 | |||
| 667 | while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { | ||
| 668 | if (standard.id & input.std) | ||
| 669 | printf ("%s\n", standard.name); | ||
| 670 | |||
| 671 | standard.index++; | ||
| 672 | } | ||
| 673 | |||
| 674 | /* EINVAL indicates the end of the enumeration, which cannot be | ||
| 675 | empty unless this device falls under the USB exception. */ | ||
| 676 | |||
| 677 | if (errno != EINVAL || standard.index == 0) { | ||
| 678 | perror ("VIDIOC_ENUMSTD"); | ||
| 679 | exit (EXIT_FAILURE); | ||
| 680 | } | ||
| 681 | </programlisting> | ||
| 682 | </example> | ||
| 683 | |||
| 684 | <example> | ||
| 685 | <title>Selecting a new video standard</title> | ||
| 686 | |||
| 687 | <programlisting> | ||
| 688 | &v4l2-input; input; | ||
| 689 | &v4l2-std-id; std_id; | ||
| 690 | |||
| 691 | memset (&input, 0, sizeof (input)); | ||
| 692 | |||
| 693 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { | ||
| 694 | perror ("VIDIOC_G_INPUT"); | ||
| 695 | exit (EXIT_FAILURE); | ||
| 696 | } | ||
| 697 | |||
| 698 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 699 | perror ("VIDIOC_ENUM_INPUT"); | ||
| 700 | exit (EXIT_FAILURE); | ||
| 701 | } | ||
| 702 | |||
| 703 | if (0 == (input.std & V4L2_STD_PAL_BG)) { | ||
| 704 | fprintf (stderr, "Oops. B/G PAL is not supported.\n"); | ||
| 705 | exit (EXIT_FAILURE); | ||
| 706 | } | ||
| 707 | |||
| 708 | /* Note this is also supposed to work when only B | ||
| 709 | <emphasis>or</emphasis> G/PAL is supported. */ | ||
| 710 | |||
| 711 | std_id = V4L2_STD_PAL_BG; | ||
| 712 | |||
| 713 | if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { | ||
| 714 | perror ("VIDIOC_S_STD"); | ||
| 715 | exit (EXIT_FAILURE); | ||
| 716 | } | ||
| 717 | </programlisting> | ||
| 718 | </example> | ||
| 719 | </section> | ||
| 720 | |||
| 721 | &sub-controls; | ||
| 722 | |||
| 723 | <section id="format"> | ||
| 724 | <title>Data Formats</title> | ||
| 725 | |||
| 726 | <section> | ||
| 727 | <title>Data Format Negotiation</title> | ||
| 728 | |||
| 729 | <para>Different devices exchange different kinds of data with | ||
| 730 | applications, for example video images, raw or sliced VBI data, RDS | ||
| 731 | datagrams. Even within one kind many different formats are possible, | ||
| 732 | in particular an abundance of image formats. Although drivers must | ||
| 733 | provide a default and the selection persists across closing and | ||
| 734 | reopening a device, applications should always negotiate a data format | ||
| 735 | before engaging in data exchange. Negotiation means the application | ||
| 736 | asks for a particular format and the driver selects and reports the | ||
| 737 | best the hardware can do to satisfy the request. Of course | ||
| 738 | applications can also just query the current selection.</para> | ||
| 739 | |||
| 740 | <para>A single mechanism exists to negotiate all data formats | ||
| 741 | using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and | ||
| 742 | &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be | ||
| 743 | used to examine what the hardware <emphasis>could</emphasis> do, | ||
| 744 | without actually selecting a new data format. The data formats | ||
| 745 | supported by the V4L2 API are covered in the respective device section | ||
| 746 | in <xref linkend="devices" />. For a closer look at image formats see | ||
| 747 | <xref linkend="pixfmt" />.</para> | ||
| 748 | |||
| 749 | <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major | ||
| 750 | turning-point in the initialization sequence. Prior to this point | ||
| 751 | multiple panel applications can access the same device concurrently to | ||
| 752 | select the current input, change controls or modify other properties. | ||
| 753 | The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream | ||
| 754 | (video data, VBI data etc.) exclusively to one file descriptor.</para> | ||
| 755 | |||
| 756 | <para>Exclusive means no other application, more precisely no | ||
| 757 | other file descriptor, can grab this stream or change device | ||
| 758 | properties inconsistent with the negotiated parameters. A video | ||
| 759 | standard change for example, when the new standard uses a different | ||
| 760 | number of scan lines, can invalidate the selected image format. | ||
| 761 | Therefore only the file descriptor owning the stream can make | ||
| 762 | invalidating changes. Accordingly multiple file descriptors which | ||
| 763 | grabbed different logical streams prevent each other from interfering | ||
| 764 | with their settings. When for example video overlay is about to start | ||
| 765 | or already in progress, simultaneous video capturing may be restricted | ||
| 766 | to the same cropping and image size.</para> | ||
| 767 | |||
| 768 | <para>When applications omit the | ||
| 769 | <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are | ||
| 770 | implied by the next step, the selection of an I/O method with the | ||
| 771 | &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or | ||
| 772 | &func-write; call.</para> | ||
| 773 | |||
| 774 | <para>Generally only one logical stream can be assigned to a | ||
| 775 | file descriptor, the exception being drivers permitting simultaneous | ||
| 776 | video capturing and overlay using the same file descriptor for | ||
| 777 | compatibility with V4L and earlier versions of V4L2. Switching the | ||
| 778 | logical stream or returning into "panel mode" is possible by closing | ||
| 779 | and reopening the device. Drivers <emphasis>may</emphasis> support a | ||
| 780 | switch using <constant>VIDIOC_S_FMT</constant>.</para> | ||
| 781 | |||
| 782 | <para>All drivers exchanging data with | ||
| 783 | applications must support the <constant>VIDIOC_G_FMT</constant> and | ||
| 784 | <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the | ||
| 785 | <constant>VIDIOC_TRY_FMT</constant> is highly recommended but | ||
| 786 | optional.</para> | ||
| 787 | </section> | ||
| 788 | |||
| 789 | <section> | ||
| 790 | <title>Image Format Enumeration</title> | ||
| 791 | |||
| 792 | <para>Apart of the generic format negotiation functions | ||
| 793 | a special ioctl to enumerate all image formats supported by video | ||
| 794 | capture, overlay or output devices is available.<footnote> | ||
| 795 | <para>Enumerating formats an application has no a-priori | ||
| 796 | knowledge of (otherwise it could explicitly ask for them and need not | ||
| 797 | enumerate) seems useless, but there are applications serving as proxy | ||
| 798 | between drivers and the actual video applications for which this is | ||
| 799 | useful.</para> | ||
| 800 | </footnote></para> | ||
| 801 | |||
| 802 | <para>The &VIDIOC-ENUM-FMT; ioctl must be supported | ||
| 803 | by all drivers exchanging image data with applications.</para> | ||
| 804 | |||
| 805 | <important> | ||
| 806 | <para>Drivers are not supposed to convert image formats in | ||
| 807 | kernel space. They must enumerate only formats directly supported by | ||
| 808 | the hardware. If necessary driver writers should publish an example | ||
| 809 | conversion routine or library for integration into applications.</para> | ||
| 810 | </important> | ||
| 811 | </section> | ||
| 812 | </section> | ||
| 813 | |||
| 814 | <section id="crop"> | ||
| 815 | <title>Image Cropping, Insertion and Scaling</title> | ||
| 816 | |||
| 817 | <para>Some video capture devices can sample a subsection of the | ||
| 818 | picture and shrink or enlarge it to an image of arbitrary size. We | ||
| 819 | call these abilities cropping and scaling. Some video output devices | ||
| 820 | can scale an image up or down and insert it at an arbitrary scan line | ||
| 821 | and horizontal offset into a video signal.</para> | ||
| 822 | |||
| 823 | <para>Applications can use the following API to select an area in | ||
| 824 | the video signal, query the default area and the hardware limits. | ||
| 825 | <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP; | ||
| 826 | and &VIDIOC-S-CROP; ioctls apply to input as well as output | ||
| 827 | devices.</emphasis></para> | ||
| 828 | |||
| 829 | <para>Scaling requires a source and a target. On a video capture | ||
| 830 | or overlay device the source is the video signal, and the cropping | ||
| 831 | ioctls determine the area actually sampled. The target are images | ||
| 832 | read by the application or overlaid onto the graphics screen. Their | ||
| 833 | size (and position for an overlay) is negotiated with the | ||
| 834 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para> | ||
| 835 | |||
| 836 | <para>On a video output device the source are the images passed in | ||
| 837 | by the application, and their size is again negotiated with the | ||
| 838 | <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a | ||
| 839 | compressed video stream. The target is the video signal, and the | ||
| 840 | cropping ioctls determine the area where the images are | ||
| 841 | inserted.</para> | ||
| 842 | |||
| 843 | <para>Source and target rectangles are defined even if the device | ||
| 844 | does not support scaling or the <constant>VIDIOC_G/S_CROP</constant> | ||
| 845 | ioctls. Their size (and position where applicable) will be fixed in | ||
| 846 | this case. <emphasis>All capture and output device must support the | ||
| 847 | <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can | ||
| 848 | determine if scaling takes place.</emphasis></para> | ||
| 849 | |||
| 850 | <section> | ||
| 851 | <title>Cropping Structures</title> | ||
| 852 | |||
| 853 | <figure id="crop-scale"> | ||
| 854 | <title>Image Cropping, Insertion and Scaling</title> | ||
| 855 | <mediaobject> | ||
| 856 | <imageobject> | ||
| 857 | <imagedata fileref="crop.pdf" format="PS" /> | ||
| 858 | </imageobject> | ||
| 859 | <imageobject> | ||
| 860 | <imagedata fileref="crop.gif" format="GIF" /> | ||
| 861 | </imageobject> | ||
| 862 | <textobject> | ||
| 863 | <phrase>The cropping, insertion and scaling process</phrase> | ||
| 864 | </textobject> | ||
| 865 | </mediaobject> | ||
| 866 | </figure> | ||
| 867 | |||
| 868 | <para>For capture devices the coordinates of the top left | ||
| 869 | corner, width and height of the area which can be sampled is given by | ||
| 870 | the <structfield>bounds</structfield> substructure of the | ||
| 871 | &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant> | ||
| 872 | ioctl. To support a wide range of hardware this specification does not | ||
| 873 | define an origin or units. However by convention drivers should | ||
| 874 | horizontally count unscaled samples relative to 0H (the leading edge | ||
| 875 | of the horizontal sync pulse, see <xref linkend="vbi-hsync" />). | ||
| 876 | Vertically ITU-R line | ||
| 877 | numbers of the first field (<xref linkend="vbi-525" />, <xref | ||
| 878 | linkend="vbi-625" />), multiplied by two if the driver can capture both | ||
| 879 | fields.</para> | ||
| 880 | |||
| 881 | <para>The top left corner, width and height of the source | ||
| 882 | rectangle, that is the area actually sampled, is given by &v4l2-crop; | ||
| 883 | using the same coordinate system as &v4l2-cropcap;. Applications can | ||
| 884 | use the <constant>VIDIOC_G_CROP</constant> and | ||
| 885 | <constant>VIDIOC_S_CROP</constant> ioctls to get and set this | ||
| 886 | rectangle. It must lie completely within the capture boundaries and | ||
| 887 | the driver may further adjust the requested size and/or position | ||
| 888 | according to hardware limitations.</para> | ||
| 889 | |||
| 890 | <para>Each capture device has a default source rectangle, given | ||
| 891 | by the <structfield>defrect</structfield> substructure of | ||
| 892 | &v4l2-cropcap;. The center of this rectangle shall align with the | ||
| 893 | center of the active picture area of the video signal, and cover what | ||
| 894 | the driver writer considers the complete picture. Drivers shall reset | ||
| 895 | the source rectangle to the default when the driver is first loaded, | ||
| 896 | but not later.</para> | ||
| 897 | |||
| 898 | <para>For output devices these structures and ioctls are used | ||
| 899 | accordingly, defining the <emphasis>target</emphasis> rectangle where | ||
| 900 | the images will be inserted into the video signal.</para> | ||
| 901 | |||
| 902 | </section> | ||
| 903 | |||
| 904 | <section> | ||
| 905 | <title>Scaling Adjustments</title> | ||
| 906 | |||
| 907 | <para>Video hardware can have various cropping, insertion and | ||
| 908 | scaling limitations. It may only scale up or down, support only | ||
| 909 | discrete scaling factors, or have different scaling abilities in | ||
| 910 | horizontal and vertical direction. Also it may not support scaling at | ||
| 911 | all. At the same time the &v4l2-crop; rectangle may have to be | ||
| 912 | aligned, and both the source and target rectangles may have arbitrary | ||
| 913 | upper and lower size limits. In particular the maximum | ||
| 914 | <structfield>width</structfield> and <structfield>height</structfield> | ||
| 915 | in &v4l2-crop; may be smaller than the | ||
| 916 | &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as | ||
| 917 | usual, drivers are expected to adjust the requested parameters and | ||
| 918 | return the actual values selected.</para> | ||
| 919 | |||
| 920 | <para>Applications can change the source or the target rectangle | ||
| 921 | first, as they may prefer a particular image size or a certain area in | ||
| 922 | the video signal. If the driver has to adjust both to satisfy hardware | ||
| 923 | limitations, the last requested rectangle shall take priority, and the | ||
| 924 | driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT; | ||
| 925 | ioctl however shall not change the driver state and therefore only | ||
| 926 | adjust the requested rectangle.</para> | ||
| 927 | |||
| 928 | <para>Suppose scaling on a video capture device is restricted to | ||
| 929 | a factor 1:1 or 2:1 in either direction and the target image size must | ||
| 930 | be a multiple of 16 × 16 pixels. The source cropping | ||
| 931 | rectangle is set to defaults, which are also the upper limit in this | ||
| 932 | example, of 640 × 400 pixels at offset 0, 0. An | ||
| 933 | application requests an image size of 300 × 225 | ||
| 934 | pixels, assuming video will be scaled down from the "full picture" | ||
| 935 | accordingly. The driver sets the image size to the closest possible | ||
| 936 | values 304 × 224, then chooses the cropping rectangle | ||
| 937 | closest to the requested size, that is 608 × 224 | ||
| 938 | (224 × 2:1 would exceed the limit 400). The offset | ||
| 939 | 0, 0 is still valid, thus unmodified. Given the default cropping | ||
| 940 | rectangle reported by <constant>VIDIOC_CROPCAP</constant> the | ||
| 941 | application can easily propose another offset to center the cropping | ||
| 942 | rectangle.</para> | ||
| 943 | |||
| 944 | <para>Now the application may insist on covering an area using a | ||
| 945 | picture aspect ratio closer to the original request, so it asks for a | ||
| 946 | cropping rectangle of 608 × 456 pixels. The present | ||
| 947 | scaling factors limit cropping to 640 × 384, so the | ||
| 948 | driver returns the cropping size 608 × 384 and adjusts | ||
| 949 | the image size to closest possible 304 × 192.</para> | ||
| 950 | |||
| 951 | </section> | ||
| 952 | |||
| 953 | <section> | ||
| 954 | <title>Examples</title> | ||
| 955 | |||
| 956 | <para>Source and target rectangles shall remain unchanged across | ||
| 957 | closing and reopening a device, such that piping data into or out of a | ||
| 958 | device will work without special preparations. More advanced | ||
| 959 | applications should ensure the parameters are suitable before starting | ||
| 960 | I/O.</para> | ||
| 961 | |||
| 962 | <example> | ||
| 963 | <title>Resetting the cropping parameters</title> | ||
| 964 | |||
| 965 | <para>(A video capture device is assumed; change | ||
| 966 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other | ||
| 967 | devices.)</para> | ||
| 968 | |||
| 969 | <programlisting> | ||
| 970 | &v4l2-cropcap; cropcap; | ||
| 971 | &v4l2-crop; crop; | ||
| 972 | |||
| 973 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 974 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 975 | |||
| 976 | if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { | ||
| 977 | perror ("VIDIOC_CROPCAP"); | ||
| 978 | exit (EXIT_FAILURE); | ||
| 979 | } | ||
| 980 | |||
| 981 | memset (&crop, 0, sizeof (crop)); | ||
| 982 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 983 | crop.c = cropcap.defrect; | ||
| 984 | |||
| 985 | /* Ignore if cropping is not supported (EINVAL). */ | ||
| 986 | |||
| 987 | if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop) | ||
| 988 | && errno != EINVAL) { | ||
| 989 | perror ("VIDIOC_S_CROP"); | ||
| 990 | exit (EXIT_FAILURE); | ||
| 991 | } | ||
| 992 | </programlisting> | ||
| 993 | </example> | ||
| 994 | |||
| 995 | <example> | ||
| 996 | <title>Simple downscaling</title> | ||
| 997 | |||
| 998 | <para>(A video capture device is assumed.)</para> | ||
| 999 | |||
| 1000 | <programlisting> | ||
| 1001 | &v4l2-cropcap; cropcap; | ||
| 1002 | &v4l2-format; format; | ||
| 1003 | |||
| 1004 | reset_cropping_parameters (); | ||
| 1005 | |||
| 1006 | /* Scale down to 1/4 size of full picture. */ | ||
| 1007 | |||
| 1008 | memset (&format, 0, sizeof (format)); /* defaults */ | ||
| 1009 | |||
| 1010 | format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1011 | |||
| 1012 | format.fmt.pix.width = cropcap.defrect.width >> 1; | ||
| 1013 | format.fmt.pix.height = cropcap.defrect.height >> 1; | ||
| 1014 | format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; | ||
| 1015 | |||
| 1016 | if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { | ||
| 1017 | perror ("VIDIOC_S_FORMAT"); | ||
| 1018 | exit (EXIT_FAILURE); | ||
| 1019 | } | ||
| 1020 | |||
| 1021 | /* We could check the actual image size now, the actual scaling factor | ||
| 1022 | or if the driver can scale at all. */ | ||
| 1023 | </programlisting> | ||
| 1024 | </example> | ||
| 1025 | |||
| 1026 | <example> | ||
| 1027 | <title>Selecting an output area</title> | ||
| 1028 | |||
| 1029 | <programlisting> | ||
| 1030 | &v4l2-cropcap; cropcap; | ||
| 1031 | &v4l2-crop; crop; | ||
| 1032 | |||
| 1033 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 1034 | cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; | ||
| 1035 | |||
| 1036 | if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { | ||
| 1037 | perror ("VIDIOC_CROPCAP"); | ||
| 1038 | exit (EXIT_FAILURE); | ||
| 1039 | } | ||
| 1040 | |||
| 1041 | memset (&crop, 0, sizeof (crop)); | ||
| 1042 | |||
| 1043 | crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; | ||
| 1044 | crop.c = cropcap.defrect; | ||
| 1045 | |||
| 1046 | /* Scale the width and height to 50 % of their original size | ||
| 1047 | and center the output. */ | ||
| 1048 | |||
| 1049 | crop.c.width /= 2; | ||
| 1050 | crop.c.height /= 2; | ||
| 1051 | crop.c.left += crop.c.width / 2; | ||
| 1052 | crop.c.top += crop.c.height / 2; | ||
| 1053 | |||
| 1054 | /* Ignore if cropping is not supported (EINVAL). */ | ||
| 1055 | |||
| 1056 | if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) | ||
| 1057 | && errno != EINVAL) { | ||
| 1058 | perror ("VIDIOC_S_CROP"); | ||
| 1059 | exit (EXIT_FAILURE); | ||
| 1060 | } | ||
| 1061 | </programlisting> | ||
| 1062 | </example> | ||
| 1063 | |||
| 1064 | <example> | ||
| 1065 | <title>Current scaling factor and pixel aspect</title> | ||
| 1066 | |||
| 1067 | <para>(A video capture device is assumed.)</para> | ||
| 1068 | |||
| 1069 | <programlisting> | ||
| 1070 | &v4l2-cropcap; cropcap; | ||
| 1071 | &v4l2-crop; crop; | ||
| 1072 | &v4l2-format; format; | ||
| 1073 | double hscale, vscale; | ||
| 1074 | double aspect; | ||
| 1075 | int dwidth, dheight; | ||
| 1076 | |||
| 1077 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 1078 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1079 | |||
| 1080 | if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { | ||
| 1081 | perror ("VIDIOC_CROPCAP"); | ||
| 1082 | exit (EXIT_FAILURE); | ||
| 1083 | } | ||
| 1084 | |||
| 1085 | memset (&crop, 0, sizeof (crop)); | ||
| 1086 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1087 | |||
| 1088 | if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) { | ||
| 1089 | if (errno != EINVAL) { | ||
| 1090 | perror ("VIDIOC_G_CROP"); | ||
| 1091 | exit (EXIT_FAILURE); | ||
| 1092 | } | ||
| 1093 | |||
| 1094 | /* Cropping not supported. */ | ||
| 1095 | crop.c = cropcap.defrect; | ||
| 1096 | } | ||
| 1097 | |||
| 1098 | memset (&format, 0, sizeof (format)); | ||
| 1099 | format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1100 | |||
| 1101 | if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) { | ||
| 1102 | perror ("VIDIOC_G_FMT"); | ||
| 1103 | exit (EXIT_FAILURE); | ||
| 1104 | } | ||
| 1105 | |||
| 1106 | /* The scaling applied by the driver. */ | ||
| 1107 | |||
| 1108 | hscale = format.fmt.pix.width / (double) crop.c.width; | ||
| 1109 | vscale = format.fmt.pix.height / (double) crop.c.height; | ||
| 1110 | |||
| 1111 | aspect = cropcap.pixelaspect.numerator / | ||
| 1112 | (double) cropcap.pixelaspect.denominator; | ||
| 1113 | aspect = aspect * hscale / vscale; | ||
| 1114 | |||
| 1115 | /* Devices following ITU-R BT.601 do not capture | ||
| 1116 | square pixels. For playback on a computer monitor | ||
| 1117 | we should scale the images to this size. */ | ||
| 1118 | |||
| 1119 | dwidth = format.fmt.pix.width / aspect; | ||
| 1120 | dheight = format.fmt.pix.height; | ||
| 1121 | </programlisting> | ||
| 1122 | </example> | ||
| 1123 | </section> | ||
| 1124 | </section> | ||
| 1125 | |||
| 1126 | <section id="streaming-par"> | ||
| 1127 | <title>Streaming Parameters</title> | ||
| 1128 | |||
| 1129 | <para>Streaming parameters are intended to optimize the video | ||
| 1130 | capture process as well as I/O. Presently applications can request a | ||
| 1131 | high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para> | ||
| 1132 | |||
| 1133 | <para>The current video standard determines a nominal number of | ||
| 1134 | frames per second. If less than this number of frames is to be | ||
| 1135 | captured or output, applications can request frame skipping or | ||
| 1136 | duplicating on the driver side. This is especially useful when using | ||
| 1137 | the &func-read; or &func-write;, which are not augmented by timestamps | ||
| 1138 | or sequence counters, and to avoid unneccessary data copying.</para> | ||
| 1139 | |||
| 1140 | <para>Finally these ioctls can be used to determine the number of | ||
| 1141 | buffers used internally by a driver in read/write mode. For | ||
| 1142 | implications see the section discussing the &func-read; | ||
| 1143 | function.</para> | ||
| 1144 | |||
| 1145 | <para>To get and set the streaming parameters applications call | ||
| 1146 | the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take | ||
| 1147 | a pointer to a &v4l2-streamparm;, which contains a union holding | ||
| 1148 | separate parameters for input and output devices.</para> | ||
| 1149 | |||
| 1150 | <para>These ioctls are optional, drivers need not implement | ||
| 1151 | them. If so, they return the &EINVAL;.</para> | ||
| 1152 | </section> | ||
| 1153 | |||
| 1154 | <!-- | ||
| 1155 | Local Variables: | ||
| 1156 | mode: sgml | ||
| 1157 | sgml-parent-document: "v4l2.sgml" | ||
| 1158 | indent-tabs-mode: nil | ||
| 1159 | End: | ||
| 1160 | --> | ||
diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml new file mode 100644 index 000000000000..4d1902a54d61 --- /dev/null +++ b/Documentation/DocBook/v4l/compat.xml | |||
| @@ -0,0 +1,2457 @@ | |||
| 1 | <title>Changes</title> | ||
| 2 | |||
| 3 | <para>The following chapters document the evolution of the V4L2 API, | ||
| 4 | errata or extensions. They are also intended to help application and | ||
| 5 | driver writers to port or update their code.</para> | ||
| 6 | |||
| 7 | <section id="diff-v4l"> | ||
| 8 | <title>Differences between V4L and V4L2</title> | ||
| 9 | |||
| 10 | <para>The Video For Linux API was first introduced in Linux 2.1 to | ||
| 11 | unify and replace various TV and radio device related interfaces, | ||
| 12 | developed independently by driver writers in prior years. Starting | ||
| 13 | with Linux 2.5 the much improved V4L2 API replaces the V4L API, | ||
| 14 | although existing drivers will continue to support V4L applications in | ||
| 15 | the future, either directly or through the V4L2 compatibility layer in | ||
| 16 | the <filename>videodev</filename> kernel module translating ioctls on | ||
| 17 | the fly. For a transition period not all drivers will support the V4L2 | ||
| 18 | API.</para> | ||
| 19 | |||
| 20 | <section> | ||
| 21 | <title>Opening and Closing Devices</title> | ||
| 22 | |||
| 23 | <para>For compatibility reasons the character device file names | ||
| 24 | recommended for V4L2 video capture, overlay, radio, teletext and raw | ||
| 25 | vbi capture devices did not change from those used by V4L. They are | ||
| 26 | listed in <xref linkend="devices" /> and below in <xref | ||
| 27 | linkend="v4l-dev" />.</para> | ||
| 28 | |||
| 29 | <para>The V4L <filename>videodev</filename> module automatically | ||
| 30 | assigns minor numbers to drivers in load order, depending on the | ||
| 31 | registered device type. We recommend that V4L2 drivers by default | ||
| 32 | register devices with the same numbers, but the system administrator | ||
| 33 | can assign arbitrary minor numbers using driver module options. The | ||
| 34 | major device number remains 81.</para> | ||
| 35 | |||
| 36 | <table id="v4l-dev"> | ||
| 37 | <title>V4L Device Types, Names and Numbers</title> | ||
| 38 | <tgroup cols="3"> | ||
| 39 | <thead> | ||
| 40 | <row> | ||
| 41 | <entry>Device Type</entry> | ||
| 42 | <entry>File Name</entry> | ||
| 43 | <entry>Minor Numbers</entry> | ||
| 44 | </row> | ||
| 45 | </thead> | ||
| 46 | <tbody valign="top"> | ||
| 47 | <row> | ||
| 48 | <entry>Video capture and overlay</entry> | ||
| 49 | <entry><para><filename>/dev/video</filename> and | ||
| 50 | <filename>/dev/bttv0</filename><footnote> <para>According to | ||
| 51 | Documentation/devices.txt these should be symbolic links to | ||
| 52 | <filename>/dev/video0</filename>. Note the original bttv interface is | ||
| 53 | not compatible with V4L or V4L2.</para> </footnote>, | ||
| 54 | <filename>/dev/video0</filename> to | ||
| 55 | <filename>/dev/video63</filename></para></entry> | ||
| 56 | <entry>0-63</entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>Radio receiver</entry> | ||
| 60 | <entry><para><filename>/dev/radio</filename><footnote> | ||
| 61 | <para>According to | ||
| 62 | <filename>Documentation/devices.txt</filename> a symbolic link to | ||
| 63 | <filename>/dev/radio0</filename>.</para> | ||
| 64 | </footnote>, <filename>/dev/radio0</filename> to | ||
| 65 | <filename>/dev/radio63</filename></para></entry> | ||
| 66 | <entry>64-127</entry> | ||
| 67 | </row> | ||
| 68 | <row> | ||
| 69 | <entry>Teletext decoder</entry> | ||
| 70 | <entry><para><filename>/dev/vtx</filename>, | ||
| 71 | <filename>/dev/vtx0</filename> to | ||
| 72 | <filename>/dev/vtx31</filename></para></entry> | ||
| 73 | <entry>192-223</entry> | ||
| 74 | </row> | ||
| 75 | <row> | ||
| 76 | <entry>Raw VBI capture</entry> | ||
| 77 | <entry><para><filename>/dev/vbi</filename>, | ||
| 78 | <filename>/dev/vbi0</filename> to | ||
| 79 | <filename>/dev/vbi31</filename></para></entry> | ||
| 80 | <entry>224-255</entry> | ||
| 81 | </row> | ||
| 82 | </tbody> | ||
| 83 | </tgroup> | ||
| 84 | </table> | ||
| 85 | |||
| 86 | <para>V4L prohibits (or used to prohibit) multiple opens of a | ||
| 87 | device file. V4L2 drivers <emphasis>may</emphasis> support multiple | ||
| 88 | opens, see <xref linkend="open" /> for details and consequences.</para> | ||
| 89 | |||
| 90 | <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The | ||
| 91 | compatibility layer in the V4L2 <filename>videodev</filename> module | ||
| 92 | can translate V4L ioctl requests to their V4L2 counterpart, however a | ||
| 93 | V4L2 driver usually needs more preparation to become fully V4L | ||
| 94 | compatible. This is covered in more detail in <xref | ||
| 95 | linkend="driver" />.</para> | ||
| 96 | </section> | ||
| 97 | |||
| 98 | <section> | ||
| 99 | <title>Querying Capabilities</title> | ||
| 100 | |||
| 101 | <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is | ||
| 102 | equivalent to V4L2's &VIDIOC-QUERYCAP;.</para> | ||
| 103 | |||
| 104 | <para>The <structfield>name</structfield> field in struct | ||
| 105 | <structname>video_capability</structname> became | ||
| 106 | <structfield>card</structfield> in &v4l2-capability;, | ||
| 107 | <structfield>type</structfield> was replaced by | ||
| 108 | <structfield>capabilities</structfield>. Note V4L2 does not | ||
| 109 | distinguish between device types like this, better think of basic | ||
| 110 | video input, video output and radio devices supporting a set of | ||
| 111 | related functions like video capturing, video overlay and VBI | ||
| 112 | capturing. See <xref linkend="open" /> for an | ||
| 113 | introduction.<informaltable> | ||
| 114 | <tgroup cols="3"> | ||
| 115 | <thead> | ||
| 116 | <row> | ||
| 117 | <entry>struct | ||
| 118 | <structname>video_capability</structname> | ||
| 119 | <structfield>type</structfield></entry> | ||
| 120 | <entry>&v4l2-capability; | ||
| 121 | <structfield>capabilities</structfield> flags</entry> | ||
| 122 | <entry>Purpose</entry> | ||
| 123 | </row> | ||
| 124 | </thead> | ||
| 125 | <tbody valign="top"> | ||
| 126 | <row> | ||
| 127 | <entry><constant>VID_TYPE_CAPTURE</constant></entry> | ||
| 128 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> | ||
| 129 | <entry>The <link linkend="capture">video | ||
| 130 | capture</link> interface is supported.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry><constant>VID_TYPE_TUNER</constant></entry> | ||
| 134 | <entry><constant>V4L2_CAP_TUNER</constant></entry> | ||
| 135 | <entry>The device has a <link linkend="tuner">tuner or | ||
| 136 | modulator</link>.</entry> | ||
| 137 | </row> | ||
| 138 | <row> | ||
| 139 | <entry><constant>VID_TYPE_TELETEXT</constant></entry> | ||
| 140 | <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> | ||
| 141 | <entry>The <link linkend="raw-vbi">raw VBI | ||
| 142 | capture</link> interface is supported.</entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry><constant>VID_TYPE_OVERLAY</constant></entry> | ||
| 146 | <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> | ||
| 147 | <entry>The <link linkend="overlay">video | ||
| 148 | overlay</link> interface is supported.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry><constant>VID_TYPE_CHROMAKEY</constant></entry> | ||
| 152 | <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in | ||
| 153 | field <structfield>capability</structfield> of | ||
| 154 | &v4l2-framebuffer;</entry> | ||
| 155 | <entry>Whether chromakey overlay is supported. For | ||
| 156 | more information on overlay see | ||
| 157 | <xref linkend="overlay" />.</entry> | ||
| 158 | </row> | ||
| 159 | <row> | ||
| 160 | <entry><constant>VID_TYPE_CLIPPING</constant></entry> | ||
| 161 | <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> | ||
| 162 | and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field | ||
| 163 | <structfield>capability</structfield> of &v4l2-framebuffer;</entry> | ||
| 164 | <entry>Whether clipping the overlaid image is | ||
| 165 | supported, see <xref linkend="overlay" />.</entry> | ||
| 166 | </row> | ||
| 167 | <row> | ||
| 168 | <entry><constant>VID_TYPE_FRAMERAM</constant></entry> | ||
| 169 | <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> | ||
| 170 | <emphasis>not set</emphasis> in field | ||
| 171 | <structfield>capability</structfield> of &v4l2-framebuffer;</entry> | ||
| 172 | <entry>Whether overlay overwrites frame buffer memory, | ||
| 173 | see <xref linkend="overlay" />.</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry><constant>VID_TYPE_SCALES</constant></entry> | ||
| 177 | <entry><constant>-</constant></entry> | ||
| 178 | <entry>This flag indicates if the hardware can scale | ||
| 179 | images. The V4L2 API implies the scale factor by setting the cropping | ||
| 180 | dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT; | ||
| 181 | ioctl, respectively. The driver returns the closest sizes possible. | ||
| 182 | For more information on cropping and scaling see <xref | ||
| 183 | linkend="crop" />.</entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry><constant>VID_TYPE_MONOCHROME</constant></entry> | ||
| 187 | <entry><constant>-</constant></entry> | ||
| 188 | <entry>Applications can enumerate the supported image | ||
| 189 | formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device | ||
| 190 | supports grey scale capturing only. For more information on image | ||
| 191 | formats see <xref linkend="pixfmt" />.</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry> | ||
| 195 | <entry><constant>-</constant></entry> | ||
| 196 | <entry>Applications can call the &VIDIOC-G-CROP; ioctl | ||
| 197 | to determine if the device supports capturing a subsection of the full | ||
| 198 | picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;. | ||
| 199 | For more information on cropping and scaling see <xref | ||
| 200 | linkend="crop" />.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry> | ||
| 204 | <entry><constant>-</constant></entry> | ||
| 205 | <entry>Applications can enumerate the supported image | ||
| 206 | formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device | ||
| 207 | supports MPEG streams.</entry> | ||
| 208 | </row> | ||
| 209 | <row> | ||
| 210 | <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry> | ||
| 211 | <entry><constant>-</constant></entry> | ||
| 212 | <entry>See above.</entry> | ||
| 213 | </row> | ||
| 214 | <row> | ||
| 215 | <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry> | ||
| 216 | <entry><constant>-</constant></entry> | ||
| 217 | <entry>See above.</entry> | ||
| 218 | </row> | ||
| 219 | <row> | ||
| 220 | <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry> | ||
| 221 | <entry><constant>-</constant></entry> | ||
| 222 | <entry>See above.</entry> | ||
| 223 | </row> | ||
| 224 | </tbody> | ||
| 225 | </tgroup> | ||
| 226 | </informaltable></para> | ||
| 227 | |||
| 228 | <para>The <structfield>audios</structfield> field was replaced | ||
| 229 | by <structfield>capabilities</structfield> flag | ||
| 230 | <constant>V4L2_CAP_AUDIO</constant>, indicating | ||
| 231 | <emphasis>if</emphasis> the device has any audio inputs or outputs. To | ||
| 232 | determine their number applications can enumerate audio inputs with | ||
| 233 | the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref | ||
| 234 | linkend="audio" />.</para> | ||
| 235 | |||
| 236 | <para>The <structfield>maxwidth</structfield>, | ||
| 237 | <structfield>maxheight</structfield>, | ||
| 238 | <structfield>minwidth</structfield> and | ||
| 239 | <structfield>minheight</structfield> fields were removed. Calling the | ||
| 240 | &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions | ||
| 241 | returns the closest size possible, taking into account the current | ||
| 242 | video standard, cropping and scaling limitations.</para> | ||
| 243 | </section> | ||
| 244 | |||
| 245 | <section> | ||
| 246 | <title>Video Sources</title> | ||
| 247 | |||
| 248 | <para>V4L provides the <constant>VIDIOCGCHAN</constant> and | ||
| 249 | <constant>VIDIOCSCHAN</constant> ioctl using struct | ||
| 250 | <structname>video_channel</structname> to enumerate | ||
| 251 | the video inputs of a V4L device. The equivalent V4L2 ioctls | ||
| 252 | are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT; | ||
| 253 | using &v4l2-input; as discussed in <xref linkend="video" />.</para> | ||
| 254 | |||
| 255 | <para>The <structfield>channel</structfield> field counting | ||
| 256 | inputs was renamed to <structfield>index</structfield>, the video | ||
| 257 | input types were renamed as follows: <informaltable> | ||
| 258 | <tgroup cols="2"> | ||
| 259 | <thead> | ||
| 260 | <row> | ||
| 261 | <entry>struct <structname>video_channel</structname> | ||
| 262 | <structfield>type</structfield></entry> | ||
| 263 | <entry>&v4l2-input; | ||
| 264 | <structfield>type</structfield></entry> | ||
| 265 | </row> | ||
| 266 | </thead> | ||
| 267 | <tbody valign="top"> | ||
| 268 | <row> | ||
| 269 | <entry><constant>VIDEO_TYPE_TV</constant></entry> | ||
| 270 | <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>VIDEO_TYPE_CAMERA</constant></entry> | ||
| 274 | <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> | ||
| 275 | </row> | ||
| 276 | </tbody> | ||
| 277 | </tgroup> | ||
| 278 | </informaltable></para> | ||
| 279 | |||
| 280 | <para>Unlike the <structfield>tuners</structfield> field | ||
| 281 | expressing the number of tuners of this input, V4L2 assumes each video | ||
| 282 | input is connected to at most one tuner. However a tuner can have more | ||
| 283 | than one input, &ie; RF connectors, and a device can have multiple | ||
| 284 | tuners. The index number of the tuner associated with the input, if | ||
| 285 | any, is stored in field <structfield>tuner</structfield> of | ||
| 286 | &v4l2-input;. Enumeration of tuners is discussed in <xref | ||
| 287 | linkend="tuner" />.</para> | ||
| 288 | |||
| 289 | <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was | ||
| 290 | dropped. Video inputs associated with a tuner are of type | ||
| 291 | <constant>V4L2_INPUT_TYPE_TUNER</constant>. The | ||
| 292 | <constant>VIDEO_VC_AUDIO</constant> flag was replaced by the | ||
| 293 | <structfield>audioset</structfield> field. V4L2 considers devices with | ||
| 294 | up to 32 audio inputs. Each set bit in the | ||
| 295 | <structfield>audioset</structfield> field represents one audio input | ||
| 296 | this video input combines with. For information about audio inputs and | ||
| 297 | how to switch between them see <xref linkend="audio" />.</para> | ||
| 298 | |||
| 299 | <para>The <structfield>norm</structfield> field describing the | ||
| 300 | supported video standards was replaced by | ||
| 301 | <structfield>std</structfield>. The V4L specification mentions a flag | ||
| 302 | <constant>VIDEO_VC_NORM</constant> indicating whether the standard can | ||
| 303 | be changed. This flag was a later addition together with the | ||
| 304 | <structfield>norm</structfield> field and has been removed in the | ||
| 305 | meantime. V4L2 has a similar, albeit more comprehensive approach | ||
| 306 | to video standards, see <xref linkend="standard" /> for more | ||
| 307 | information.</para> | ||
| 308 | </section> | ||
| 309 | |||
| 310 | <section> | ||
| 311 | <title>Tuning</title> | ||
| 312 | |||
| 313 | <para>The V4L <constant>VIDIOCGTUNER</constant> and | ||
| 314 | <constant>VIDIOCSTUNER</constant> ioctl and struct | ||
| 315 | <structname>video_tuner</structname> can be used to enumerate the | ||
| 316 | tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are | ||
| 317 | &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are | ||
| 318 | covered in <xref linkend="tuner" />.</para> | ||
| 319 | |||
| 320 | <para>The <structfield>tuner</structfield> field counting tuners | ||
| 321 | was renamed to <structfield>index</structfield>. The fields | ||
| 322 | <structfield>name</structfield>, <structfield>rangelow</structfield> | ||
| 323 | and <structfield>rangehigh</structfield> remained unchanged.</para> | ||
| 324 | |||
| 325 | <para>The <constant>VIDEO_TUNER_PAL</constant>, | ||
| 326 | <constant>VIDEO_TUNER_NTSC</constant> and | ||
| 327 | <constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported | ||
| 328 | video standards were dropped. This information is now contained in the | ||
| 329 | associated &v4l2-input;. No replacement exists for the | ||
| 330 | <constant>VIDEO_TUNER_NORM</constant> flag indicating whether the | ||
| 331 | video standard can be switched. The <structfield>mode</structfield> | ||
| 332 | field to select a different video standard was replaced by a whole new | ||
| 333 | set of ioctls and structures described in <xref linkend="standard" />. | ||
| 334 | Due to its ubiquity it should be mentioned the BTTV driver supports | ||
| 335 | several standards in addition to the regular | ||
| 336 | <constant>VIDEO_MODE_PAL</constant> (0), | ||
| 337 | <constant>VIDEO_MODE_NTSC</constant>, | ||
| 338 | <constant>VIDEO_MODE_SECAM</constant> and | ||
| 339 | <constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina, | ||
| 340 | M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para> | ||
| 341 | |||
| 342 | <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag | ||
| 343 | indicating stereo reception became | ||
| 344 | <constant>V4L2_TUNER_SUB_STEREO</constant> in field | ||
| 345 | <structfield>rxsubchans</structfield>. This field also permits the | ||
| 346 | detection of monaural and bilingual audio, see the definition of | ||
| 347 | &v4l2-tuner; for details. Presently no replacement exists for the | ||
| 348 | <constant>VIDEO_TUNER_RDS_ON</constant> and | ||
| 349 | <constant>VIDEO_TUNER_MBS_ON</constant> flags.</para> | ||
| 350 | |||
| 351 | <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed | ||
| 352 | to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner; | ||
| 353 | <structfield>capability</structfield> field.</para> | ||
| 354 | |||
| 355 | <para>The <constant>VIDIOCGFREQ</constant> and | ||
| 356 | <constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency | ||
| 357 | where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They | ||
| 358 | take a pointer to a &v4l2-frequency; instead of an unsigned long | ||
| 359 | integer.</para> | ||
| 360 | </section> | ||
| 361 | |||
| 362 | <section id="v4l-image-properties"> | ||
| 363 | <title>Image Properties</title> | ||
| 364 | |||
| 365 | <para>V4L2 has no equivalent of the | ||
| 366 | <constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant> | ||
| 367 | ioctl and struct <structname>video_picture</structname>. The following | ||
| 368 | fields where replaced by V4L2 controls accessible with the | ||
| 369 | &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable> | ||
| 370 | <tgroup cols="2"> | ||
| 371 | <thead> | ||
| 372 | <row> | ||
| 373 | <entry>struct <structname>video_picture</structname></entry> | ||
| 374 | <entry>V4L2 Control ID</entry> | ||
| 375 | </row> | ||
| 376 | </thead> | ||
| 377 | <tbody valign="top"> | ||
| 378 | <row> | ||
| 379 | <entry><structfield>brightness</structfield></entry> | ||
| 380 | <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> | ||
| 381 | </row> | ||
| 382 | <row> | ||
| 383 | <entry><structfield>hue</structfield></entry> | ||
| 384 | <entry><constant>V4L2_CID_HUE</constant></entry> | ||
| 385 | </row> | ||
| 386 | <row> | ||
| 387 | <entry><structfield>colour</structfield></entry> | ||
| 388 | <entry><constant>V4L2_CID_SATURATION</constant></entry> | ||
| 389 | </row> | ||
| 390 | <row> | ||
| 391 | <entry><structfield>contrast</structfield></entry> | ||
| 392 | <entry><constant>V4L2_CID_CONTRAST</constant></entry> | ||
| 393 | </row> | ||
| 394 | <row> | ||
| 395 | <entry><structfield>whiteness</structfield></entry> | ||
| 396 | <entry><constant>V4L2_CID_WHITENESS</constant></entry> | ||
| 397 | </row> | ||
| 398 | </tbody> | ||
| 399 | </tgroup> | ||
| 400 | </informaltable></para> | ||
| 401 | |||
| 402 | <para>The V4L picture controls are assumed to range from 0 to | ||
| 403 | 65535 with no particular reset value. The V4L2 API permits arbitrary | ||
| 404 | limits and defaults which can be queried with the &VIDIOC-QUERYCTRL; | ||
| 405 | ioctl. For general information about controls see <xref | ||
| 406 | linkend="control" />.</para> | ||
| 407 | |||
| 408 | <para>The <structfield>depth</structfield> (average number of | ||
| 409 | bits per pixel) of a video image is implied by the selected image | ||
| 410 | format. V4L2 does not explicitely provide such information assuming | ||
| 411 | applications recognizing the format are aware of the image depth and | ||
| 412 | others need not know. The <structfield>palette</structfield> field | ||
| 413 | moved into the &v4l2-pix-format;:<informaltable> | ||
| 414 | <tgroup cols="2"> | ||
| 415 | <thead> | ||
| 416 | <row> | ||
| 417 | <entry>struct <structname>video_picture</structname> | ||
| 418 | <structfield>palette</structfield></entry> | ||
| 419 | <entry>&v4l2-pix-format; | ||
| 420 | <structfield>pixfmt</structfield></entry> | ||
| 421 | </row> | ||
| 422 | </thead> | ||
| 423 | <tbody valign="top"> | ||
| 424 | <row> | ||
| 425 | <entry><constant>VIDEO_PALETTE_GREY</constant></entry> | ||
| 426 | <entry><para><link | ||
| 427 | linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry> | ||
| 428 | </row> | ||
| 429 | <row> | ||
| 430 | <entry><constant>VIDEO_PALETTE_HI240</constant></entry> | ||
| 431 | <entry><para><link | ||
| 432 | linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote> | ||
| 433 | <para>This is a custom format used by the BTTV | ||
| 434 | driver, not one of the V4L2 standard formats.</para> | ||
| 435 | </footnote></para></entry> | ||
| 436 | </row> | ||
| 437 | <row> | ||
| 438 | <entry><constant>VIDEO_PALETTE_RGB565</constant></entry> | ||
| 439 | <entry><para><link | ||
| 440 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry> | ||
| 441 | </row> | ||
| 442 | <row> | ||
| 443 | <entry><constant>VIDEO_PALETTE_RGB555</constant></entry> | ||
| 444 | <entry><para><link | ||
| 445 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry> | ||
| 446 | </row> | ||
| 447 | <row> | ||
| 448 | <entry><constant>VIDEO_PALETTE_RGB24</constant></entry> | ||
| 449 | <entry><para><link | ||
| 450 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry> | ||
| 451 | </row> | ||
| 452 | <row> | ||
| 453 | <entry><constant>VIDEO_PALETTE_RGB32</constant></entry> | ||
| 454 | <entry><para><link | ||
| 455 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote> | ||
| 456 | <para>Presumably all V4L RGB formats are | ||
| 457 | little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue | ||
| 458 | swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para> | ||
| 459 | </footnote></para></entry> | ||
| 460 | </row> | ||
| 461 | <row> | ||
| 462 | <entry><constant>VIDEO_PALETTE_YUV422</constant></entry> | ||
| 463 | <entry><para><link | ||
| 464 | linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> | ||
| 465 | </row> | ||
| 466 | <row> | ||
| 467 | <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote> | ||
| 468 | <para><constant>VIDEO_PALETTE_YUV422</constant> | ||
| 469 | and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some | ||
| 470 | V4L drivers respond to one, some to the other.</para> | ||
| 471 | </footnote></para></entry> | ||
| 472 | <entry><para><link | ||
| 473 | linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> | ||
| 474 | </row> | ||
| 475 | <row> | ||
| 476 | <entry><constant>VIDEO_PALETTE_UYVY</constant></entry> | ||
| 477 | <entry><para><link | ||
| 478 | linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry> | ||
| 479 | </row> | ||
| 480 | <row> | ||
| 481 | <entry><constant>VIDEO_PALETTE_YUV420</constant></entry> | ||
| 482 | <entry>None</entry> | ||
| 483 | </row> | ||
| 484 | <row> | ||
| 485 | <entry><constant>VIDEO_PALETTE_YUV411</constant></entry> | ||
| 486 | <entry><para><link | ||
| 487 | linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote> | ||
| 488 | <para>Not to be confused with | ||
| 489 | <constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar | ||
| 490 | format.</para> </footnote></para></entry> | ||
| 491 | </row> | ||
| 492 | <row> | ||
| 493 | <entry><constant>VIDEO_PALETTE_RAW</constant></entry> | ||
| 494 | <entry><para>None<footnote> <para>V4L explains this | ||
| 495 | as: "RAW capture (BT848)"</para> </footnote></para></entry> | ||
| 496 | </row> | ||
| 497 | <row> | ||
| 498 | <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry> | ||
| 499 | <entry><para><link | ||
| 500 | linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry> | ||
| 501 | </row> | ||
| 502 | <row> | ||
| 503 | <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry> | ||
| 504 | <entry><para><link | ||
| 505 | linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote> | ||
| 506 | <para>Not to be confused with | ||
| 507 | <constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed | ||
| 508 | format.</para> </footnote></para></entry> | ||
| 509 | </row> | ||
| 510 | <row> | ||
| 511 | <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry> | ||
| 512 | <entry><para><link | ||
| 513 | linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry> | ||
| 514 | </row> | ||
| 515 | <row> | ||
| 516 | <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry> | ||
| 517 | <entry><para><link | ||
| 518 | linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry> | ||
| 519 | </row> | ||
| 520 | </tbody> | ||
| 521 | </tgroup> | ||
| 522 | </informaltable></para> | ||
| 523 | |||
| 524 | <para>V4L2 image formats are defined in <xref | ||
| 525 | linkend="pixfmt" />. The image format can be selected with the | ||
| 526 | &VIDIOC-S-FMT; ioctl.</para> | ||
| 527 | </section> | ||
| 528 | |||
| 529 | <section> | ||
| 530 | <title>Audio</title> | ||
| 531 | |||
| 532 | <para>The <constant>VIDIOCGAUDIO</constant> and | ||
| 533 | <constant>VIDIOCSAUDIO</constant> ioctl and struct | ||
| 534 | <structname>video_audio</structname> are used to enumerate the | ||
| 535 | audio inputs of a V4L device. The equivalent V4L2 ioctls are | ||
| 536 | &VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as | ||
| 537 | discussed in <xref linkend="audio" />.</para> | ||
| 538 | |||
| 539 | <para>The <structfield>audio</structfield> "channel number" | ||
| 540 | field counting audio inputs was renamed to | ||
| 541 | <structfield>index</structfield>.</para> | ||
| 542 | |||
| 543 | <para>On <constant>VIDIOCSAUDIO</constant> the | ||
| 544 | <structfield>mode</structfield> field selects <emphasis>one</emphasis> | ||
| 545 | of the <constant>VIDEO_SOUND_MONO</constant>, | ||
| 546 | <constant>VIDEO_SOUND_STEREO</constant>, | ||
| 547 | <constant>VIDEO_SOUND_LANG1</constant> or | ||
| 548 | <constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When | ||
| 549 | the current audio standard is BTSC | ||
| 550 | <constant>VIDEO_SOUND_LANG2</constant> refers to SAP and | ||
| 551 | <constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also | ||
| 552 | undocumented in the V4L specification, there is no way to query the | ||
| 553 | selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns | ||
| 554 | the <emphasis>actually received</emphasis> audio programmes in this | ||
| 555 | field. In the V4L2 API this information is stored in the &v4l2-tuner; | ||
| 556 | <structfield>rxsubchans</structfield> and | ||
| 557 | <structfield>audmode</structfield> fields, respectively. See <xref | ||
| 558 | linkend="tuner" /> for more information on tuners. Related to audio | ||
| 559 | modes &v4l2-audio; also reports if this is a mono or stereo | ||
| 560 | input, regardless if the source is a tuner.</para> | ||
| 561 | |||
| 562 | <para>The following fields where replaced by V4L2 controls | ||
| 563 | accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and | ||
| 564 | &VIDIOC-S-CTRL; ioctls:<informaltable> | ||
| 565 | <tgroup cols="2"> | ||
| 566 | <thead> | ||
| 567 | <row> | ||
| 568 | <entry>struct | ||
| 569 | <structname>video_audio</structname></entry> | ||
| 570 | <entry>V4L2 Control ID</entry> | ||
| 571 | </row> | ||
| 572 | </thead> | ||
| 573 | <tbody valign="top"> | ||
| 574 | <row> | ||
| 575 | <entry><structfield>volume</structfield></entry> | ||
| 576 | <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> | ||
| 577 | </row> | ||
| 578 | <row> | ||
| 579 | <entry><structfield>bass</structfield></entry> | ||
| 580 | <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> | ||
| 581 | </row> | ||
| 582 | <row> | ||
| 583 | <entry><structfield>treble</structfield></entry> | ||
| 584 | <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> | ||
| 585 | </row> | ||
| 586 | <row> | ||
| 587 | <entry><structfield>balance</structfield></entry> | ||
| 588 | <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> | ||
| 589 | </row> | ||
| 590 | </tbody> | ||
| 591 | </tgroup> | ||
| 592 | </informaltable></para> | ||
| 593 | |||
| 594 | <para>To determine which of these controls are supported by a | ||
| 595 | driver V4L provides the <structfield>flags</structfield> | ||
| 596 | <constant>VIDEO_AUDIO_VOLUME</constant>, | ||
| 597 | <constant>VIDEO_AUDIO_BASS</constant>, | ||
| 598 | <constant>VIDEO_AUDIO_TREBLE</constant> and | ||
| 599 | <constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the | ||
| 600 | &VIDIOC-QUERYCTRL; ioctl reports if the respective control is | ||
| 601 | supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant> | ||
| 602 | and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the | ||
| 603 | boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para> | ||
| 604 | |||
| 605 | <para>All V4L2 controls have a <structfield>step</structfield> | ||
| 606 | attribute replacing the struct <structname>video_audio</structname> | ||
| 607 | <structfield>step</structfield> field. The V4L audio controls are | ||
| 608 | assumed to range from 0 to 65535 with no particular reset value. The | ||
| 609 | V4L2 API permits arbitrary limits and defaults which can be queried | ||
| 610 | with the &VIDIOC-QUERYCTRL; ioctl. For general information about | ||
| 611 | controls see <xref linkend="control" />.</para> | ||
| 612 | </section> | ||
| 613 | |||
| 614 | <section> | ||
| 615 | <title>Frame Buffer Overlay</title> | ||
| 616 | |||
| 617 | <para>The V4L2 ioctls equivalent to | ||
| 618 | <constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant> | ||
| 619 | are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The | ||
| 620 | <structfield>base</structfield> field of struct | ||
| 621 | <structname>video_buffer</structname> remained unchanged, except V4L2 | ||
| 622 | defines a flag to indicate non-destructive overlays instead of a | ||
| 623 | <constant>NULL</constant> pointer. All other fields moved into the | ||
| 624 | &v4l2-pix-format; <structfield>fmt</structfield> substructure of | ||
| 625 | &v4l2-framebuffer;. The <structfield>depth</structfield> field was | ||
| 626 | replaced by <structfield>pixelformat</structfield>. See <xref | ||
| 627 | linkend="pixfmt-rgb" /> for a list of RGB formats and their | ||
| 628 | respective color depths.</para> | ||
| 629 | |||
| 630 | <para>Instead of the special ioctls | ||
| 631 | <constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant> | ||
| 632 | V4L2 uses the general-purpose data format negotiation ioctls | ||
| 633 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a | ||
| 634 | &v4l2-format; as argument. Here the <structfield>win</structfield> | ||
| 635 | member of the <structfield>fmt</structfield> union is used, a | ||
| 636 | &v4l2-window;.</para> | ||
| 637 | |||
| 638 | <para>The <structfield>x</structfield>, | ||
| 639 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 640 | <structfield>height</structfield> fields of struct | ||
| 641 | <structname>video_window</structname> moved into &v4l2-rect; | ||
| 642 | substructure <structfield>w</structfield> of struct | ||
| 643 | <structname>v4l2_window</structname>. The | ||
| 644 | <structfield>chromakey</structfield>, | ||
| 645 | <structfield>clips</structfield>, and | ||
| 646 | <structfield>clipcount</structfield> fields remained unchanged. Struct | ||
| 647 | <structname>video_clip</structname> was renamed to &v4l2-clip;, also | ||
| 648 | containing a struct <structname>v4l2_rect</structname>, but the | ||
| 649 | semantics are still the same.</para> | ||
| 650 | |||
| 651 | <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was | ||
| 652 | dropped. Instead applications must set the | ||
| 653 | <structfield>field</structfield> field to | ||
| 654 | <constant>V4L2_FIELD_ANY</constant> or | ||
| 655 | <constant>V4L2_FIELD_INTERLACED</constant>. The | ||
| 656 | <constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into | ||
| 657 | &v4l2-framebuffer;, under the new name | ||
| 658 | <constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para> | ||
| 659 | |||
| 660 | <para>In V4L, storing a bitmap pointer in | ||
| 661 | <structfield>clips</structfield> and setting | ||
| 662 | <structfield>clipcount</structfield> to | ||
| 663 | <constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap | ||
| 664 | clipping, using a fixed size bitmap of 1024 × 625 bits. Struct | ||
| 665 | <structname>v4l2_window</structname> has a separate | ||
| 666 | <structfield>bitmap</structfield> pointer field for this purpose and | ||
| 667 | the bitmap size is determined by <structfield>w.width</structfield> and | ||
| 668 | <structfield>w.height</structfield>.</para> | ||
| 669 | |||
| 670 | <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or | ||
| 671 | disable overlay was renamed to &VIDIOC-OVERLAY;.</para> | ||
| 672 | </section> | ||
| 673 | |||
| 674 | <section> | ||
| 675 | <title>Cropping</title> | ||
| 676 | |||
| 677 | <para>To capture only a subsection of the full picture V4L | ||
| 678 | defines the <constant>VIDIOCGCAPTURE</constant> and | ||
| 679 | <constant>VIDIOCSCAPTURE</constant> ioctls using struct | ||
| 680 | <structname>video_capture</structname>. The equivalent V4L2 ioctls are | ||
| 681 | &VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related | ||
| 682 | &VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see | ||
| 683 | <xref linkend="crop" /> for details.</para> | ||
| 684 | |||
| 685 | <para>The <structfield>x</structfield>, | ||
| 686 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 687 | <structfield>height</structfield> fields moved into &v4l2-rect; | ||
| 688 | substructure <structfield>c</structfield> of struct | ||
| 689 | <structname>v4l2_crop</structname>. The | ||
| 690 | <structfield>decimation</structfield> field was dropped. In the V4L2 | ||
| 691 | API the scaling factor is implied by the size of the cropping | ||
| 692 | rectangle and the size of the captured or overlaid image.</para> | ||
| 693 | |||
| 694 | <para>The <constant>VIDEO_CAPTURE_ODD</constant> | ||
| 695 | and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the | ||
| 696 | odd or even field, respectively, were replaced by | ||
| 697 | <constant>V4L2_FIELD_TOP</constant> and | ||
| 698 | <constant>V4L2_FIELD_BOTTOM</constant> in the field named | ||
| 699 | <structfield>field</structfield> of &v4l2-pix-format; and | ||
| 700 | &v4l2-window;. These structures are used to select a capture or | ||
| 701 | overlay format with the &VIDIOC-S-FMT; ioctl.</para> | ||
| 702 | </section> | ||
| 703 | |||
| 704 | <section> | ||
| 705 | <title>Reading Images, Memory Mapping</title> | ||
| 706 | |||
| 707 | <section> | ||
| 708 | <title>Capturing using the read method</title> | ||
| 709 | |||
| 710 | <para>There is no essential difference between reading images | ||
| 711 | from a V4L or V4L2 device using the &func-read; function, however V4L2 | ||
| 712 | drivers are not required to support this I/O method. Applications can | ||
| 713 | determine if the function is available with the &VIDIOC-QUERYCAP; | ||
| 714 | ioctl. All V4L2 devices exchanging data with applications must support | ||
| 715 | the &func-select; and &func-poll; functions.</para> | ||
| 716 | |||
| 717 | <para>To select an image format and size, V4L provides the | ||
| 718 | <constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant> | ||
| 719 | ioctls. V4L2 uses the general-purpose data format negotiation ioctls | ||
| 720 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a | ||
| 721 | &v4l2-format; as argument, here the &v4l2-pix-format; named | ||
| 722 | <structfield>pix</structfield> of its <structfield>fmt</structfield> | ||
| 723 | union is used.</para> | ||
| 724 | |||
| 725 | <para>For more information about the V4L2 read interface see | ||
| 726 | <xref linkend="rw" />.</para> | ||
| 727 | </section> | ||
| 728 | <section> | ||
| 729 | <title>Capturing using memory mapping</title> | ||
| 730 | |||
| 731 | <para>Applications can read from V4L devices by mapping | ||
| 732 | buffers in device memory, or more often just buffers allocated in | ||
| 733 | DMA-able system memory, into their address space. This avoids the data | ||
| 734 | copying overhead of the read method. V4L2 supports memory mapping as | ||
| 735 | well, with a few differences.</para> | ||
| 736 | |||
| 737 | <informaltable> | ||
| 738 | <tgroup cols="2"> | ||
| 739 | <thead> | ||
| 740 | <row> | ||
| 741 | <entry>V4L</entry> | ||
| 742 | <entry>V4L2</entry> | ||
| 743 | </row> | ||
| 744 | </thead> | ||
| 745 | <tbody valign="top"> | ||
| 746 | <row> | ||
| 747 | <entry></entry> | ||
| 748 | <entry>The image format must be selected before | ||
| 749 | buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format | ||
| 750 | is selected the driver may use the last, possibly by another | ||
| 751 | application requested format.</entry> | ||
| 752 | </row> | ||
| 753 | <row> | ||
| 754 | <entry><para>Applications cannot change the number of | ||
| 755 | buffers. The it is built into the driver, unless it has a module | ||
| 756 | option to change the number when the driver module is | ||
| 757 | loaded.</para></entry> | ||
| 758 | <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the | ||
| 759 | desired number of buffers, this is a required step in the initialization | ||
| 760 | sequence.</para></entry> | ||
| 761 | </row> | ||
| 762 | <row> | ||
| 763 | <entry><para>Drivers map all buffers as one contiguous | ||
| 764 | range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is | ||
| 765 | available to query the number of buffers, the offset of each buffer | ||
| 766 | from the start of the virtual file, and the overall amount of memory | ||
| 767 | used, which can be used as arguments for the &func-mmap; | ||
| 768 | function.</para></entry> | ||
| 769 | <entry><para>Buffers are individually mapped. The | ||
| 770 | offset and size of each buffer can be determined with the | ||
| 771 | &VIDIOC-QUERYBUF; ioctl.</para></entry> | ||
| 772 | </row> | ||
| 773 | <row> | ||
| 774 | <entry><para>The <constant>VIDIOCMCAPTURE</constant> | ||
| 775 | ioctl prepares a buffer for capturing. It also determines the image | ||
| 776 | format for this buffer. The ioctl returns immediately, eventually with | ||
| 777 | an &EAGAIN; if no video signal had been detected. When the driver | ||
| 778 | supports more than one buffer applications can call the ioctl multiple | ||
| 779 | times and thus have multiple outstanding capture | ||
| 780 | requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl | ||
| 781 | suspends execution until a particular buffer has been | ||
| 782 | filled.</para></entry> | ||
| 783 | <entry><para>Drivers maintain an incoming and outgoing | ||
| 784 | queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming | ||
| 785 | queue. Filled buffers are dequeued from the outgoing queue with the | ||
| 786 | &VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this | ||
| 787 | function, &func-select; or &func-poll; can be used. The | ||
| 788 | &VIDIOC-STREAMON; ioctl must be called once after enqueuing one or | ||
| 789 | more buffers to start capturing. Its counterpart | ||
| 790 | &VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both | ||
| 791 | queues. Applications can query the signal status, if known, with the | ||
| 792 | &VIDIOC-ENUMINPUT; ioctl.</para></entry> | ||
| 793 | </row> | ||
| 794 | </tbody> | ||
| 795 | </tgroup> | ||
| 796 | </informaltable> | ||
| 797 | |||
| 798 | <para>For a more in-depth discussion of memory mapping and | ||
| 799 | examples, see <xref linkend="mmap" />.</para> | ||
| 800 | </section> | ||
| 801 | </section> | ||
| 802 | |||
| 803 | <section> | ||
| 804 | <title>Reading Raw VBI Data</title> | ||
| 805 | |||
| 806 | <para>Originally the V4L API did not specify a raw VBI capture | ||
| 807 | interface, only the device file <filename>/dev/vbi</filename> was | ||
| 808 | reserved for this purpose. The only driver supporting this interface | ||
| 809 | was the BTTV driver, de-facto defining the V4L VBI interface. Reading | ||
| 810 | from the device yields a raw VBI image with the following | ||
| 811 | parameters:<informaltable> | ||
| 812 | <tgroup cols="2"> | ||
| 813 | <thead> | ||
| 814 | <row> | ||
| 815 | <entry>&v4l2-vbi-format;</entry> | ||
| 816 | <entry>V4L, BTTV driver</entry> | ||
| 817 | </row> | ||
| 818 | </thead> | ||
| 819 | <tbody valign="top"> | ||
| 820 | <row> | ||
| 821 | <entry>sampling_rate</entry> | ||
| 822 | <entry>28636363 Hz NTSC (or any other 525-line | ||
| 823 | standard); 35468950 Hz PAL and SECAM (625-line standards)</entry> | ||
| 824 | </row> | ||
| 825 | <row> | ||
| 826 | <entry>offset</entry> | ||
| 827 | <entry>?</entry> | ||
| 828 | </row> | ||
| 829 | <row> | ||
| 830 | <entry>samples_per_line</entry> | ||
| 831 | <entry>2048</entry> | ||
| 832 | </row> | ||
| 833 | <row> | ||
| 834 | <entry>sample_format</entry> | ||
| 835 | <entry>V4L2_PIX_FMT_GREY. The last four bytes (a | ||
| 836 | machine endianess integer) contain a frame counter.</entry> | ||
| 837 | </row> | ||
| 838 | <row> | ||
| 839 | <entry>start[]</entry> | ||
| 840 | <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry> | ||
| 841 | </row> | ||
| 842 | <row> | ||
| 843 | <entry>count[]</entry> | ||
| 844 | <entry><para>16, 16<footnote><para>Old driver | ||
| 845 | versions used different values, eventually the custom | ||
| 846 | <constant>BTTV_VBISIZE</constant> ioctl was added to query the | ||
| 847 | correct values.</para></footnote></para></entry> | ||
| 848 | </row> | ||
| 849 | <row> | ||
| 850 | <entry>flags</entry> | ||
| 851 | <entry>0</entry> | ||
| 852 | </row> | ||
| 853 | </tbody> | ||
| 854 | </tgroup> | ||
| 855 | </informaltable></para> | ||
| 856 | |||
| 857 | <para>Undocumented in the V4L specification, in Linux 2.3 the | ||
| 858 | <constant>VIDIOCGVBIFMT</constant> and | ||
| 859 | <constant>VIDIOCSVBIFMT</constant> ioctls using struct | ||
| 860 | <structname>vbi_format</structname> were added to determine the VBI | ||
| 861 | image parameters. These ioctls are only partially compatible with the | ||
| 862 | V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para> | ||
| 863 | |||
| 864 | <para>An <structfield>offset</structfield> field does not | ||
| 865 | exist, <structfield>sample_format</structfield> is supposed to be | ||
| 866 | <constant>VIDEO_PALETTE_RAW</constant>, equivalent to | ||
| 867 | <constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are | ||
| 868 | probably equivalent to &v4l2-vbi-format;.</para> | ||
| 869 | |||
| 870 | <para>Apparently only the Zoran (ZR 36120) driver implements | ||
| 871 | these ioctls. The semantics differ from those specified for V4L2 in two | ||
| 872 | ways. The parameters are reset on &func-open; and | ||
| 873 | <constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the | ||
| 874 | parameters are invalid.</para> | ||
| 875 | </section> | ||
| 876 | |||
| 877 | <section> | ||
| 878 | <title>Miscellaneous</title> | ||
| 879 | |||
| 880 | <para>V4L2 has no equivalent of the | ||
| 881 | <constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI | ||
| 882 | device associated with a video capture device (or vice versa) by | ||
| 883 | reopening the device and requesting VBI data. For details see | ||
| 884 | <xref linkend="open" />.</para> | ||
| 885 | |||
| 886 | <para>No replacement exists for <constant>VIDIOCKEY</constant>, | ||
| 887 | and the V4L functions for microcode programming. A new interface for | ||
| 888 | MPEG compression and playback devices is documented in <xref | ||
| 889 | linkend="extended-controls" />.</para> | ||
| 890 | </section> | ||
| 891 | |||
| 892 | </section> | ||
| 893 | |||
| 894 | <section id="hist-v4l2"> | ||
| 895 | <title>Changes of the V4L2 API</title> | ||
| 896 | |||
| 897 | <para>Soon after the V4L API was added to the kernel it was | ||
| 898 | criticised as too inflexible. In August 1998 Bill Dirks proposed a | ||
| 899 | number of improvements and began to work on documentation, example | ||
| 900 | drivers and applications. With the help of other volunteers this | ||
| 901 | eventually became the V4L2 API, not just an extension but a | ||
| 902 | replacement for the V4L API. However it took another four years and | ||
| 903 | two stable kernel releases until the new API was finally accepted for | ||
| 904 | inclusion into the kernel in its present form.</para> | ||
| 905 | |||
| 906 | <section> | ||
| 907 | <title>Early Versions</title> | ||
| 908 | <para>1998-08-20: First version.</para> | ||
| 909 | |||
| 910 | <para>1998-08-27: The &func-select; function was introduced.</para> | ||
| 911 | |||
| 912 | <para>1998-09-10: New video standard interface.</para> | ||
| 913 | |||
| 914 | <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl | ||
| 915 | was replaced by the otherwise meaningless <constant>O_TRUNC</constant> | ||
| 916 | &func-open; flag, and the aliases <constant>O_NONCAP</constant> and | ||
| 917 | <constant>O_NOIO</constant> were defined. Applications can set this | ||
| 918 | flag if they intend to access controls only, as opposed to capture | ||
| 919 | applications which need exclusive access. The | ||
| 920 | <constant>VIDEO_STD_XXX</constant> identifiers are now ordinals | ||
| 921 | instead of flags, and the <function>video_std_construct()</function> | ||
| 922 | helper function takes id and transmission arguments.</para> | ||
| 923 | |||
| 924 | <para>1998-09-28: Revamped video standard. Made video controls | ||
| 925 | individually enumerable.</para> | ||
| 926 | |||
| 927 | <para>1998-10-02: The <structfield>id</structfield> field was | ||
| 928 | removed from struct <structname>video_standard</structname> and the | ||
| 929 | color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was | ||
| 930 | renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A | ||
| 931 | first draft of the Codec API was released.</para> | ||
| 932 | |||
| 933 | <para>1998-11-08: Many minor changes. Most symbols have been | ||
| 934 | renamed. Some material changes to &v4l2-capability;.</para> | ||
| 935 | |||
| 936 | <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para> | ||
| 937 | |||
| 938 | <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant> | ||
| 939 | changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and | ||
| 940 | <constant>V4L2_PIX_FMT_RGB32</constant> changed to | ||
| 941 | <constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now | ||
| 942 | accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under | ||
| 943 | names starting with <constant>V4L2_CID_AUDIO</constant>. The | ||
| 944 | <constant>V4L2_MAJOR</constant> define was removed from | ||
| 945 | <filename>videodev.h</filename> since it was only used once in the | ||
| 946 | <filename>videodev</filename> kernel module. The | ||
| 947 | <constant>YUV422</constant> and <constant>YUV411</constant> planar | ||
| 948 | image formats were added.</para> | ||
| 949 | |||
| 950 | <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and | ||
| 951 | video output devices were added.</para> | ||
| 952 | |||
| 953 | <para>1999-01-14: A raw VBI capture interface was added.</para> | ||
| 954 | |||
| 955 | <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl | ||
| 956 | was removed.</para> | ||
| 957 | </section> | ||
| 958 | |||
| 959 | <section> | ||
| 960 | <title>V4L2 Version 0.16 1999-01-31</title> | ||
| 961 | <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF | ||
| 962 | are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added | ||
| 963 | digital zoom (cropping) controls.</para> | ||
| 964 | </section> | ||
| 965 | |||
| 966 | <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill | ||
| 967 | forgot to bump the version number or never released it. --> | ||
| 968 | |||
| 969 | <section> | ||
| 970 | <title>V4L2 Version 0.18 1999-03-16</title> | ||
| 971 | <para>Added a v4l to V4L2 ioctl compatibility layer to | ||
| 972 | videodev.c. Driver writers, this changes how you implement your ioctl | ||
| 973 | handler. See the Driver Writer's Guide. Added some more control id | ||
| 974 | codes.</para> | ||
| 975 | </section> | ||
| 976 | |||
| 977 | <section> | ||
| 978 | <title>V4L2 Version 0.19 1999-06-05</title> | ||
| 979 | <para>1999-03-18: Fill in the category and catname fields of | ||
| 980 | v4l2_queryctrl objects before passing them to the driver. Required a | ||
| 981 | minor change to the VIDIOC_QUERYCTRL handlers in the sample | ||
| 982 | drivers.</para> | ||
| 983 | <para>1999-03-31: Better compatibility for v4l memory capture | ||
| 984 | ioctls. Requires changes to drivers to fully support new compatibility | ||
| 985 | features, see Driver Writer's Guide and v4l2cap.c. Added new control | ||
| 986 | IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, | ||
| 987 | and _YUV411P to _YUV411P.</para> | ||
| 988 | <para>1999-04-04: Added a few more control IDs.</para> | ||
| 989 | <para>1999-04-07: Added the button control type.</para> | ||
| 990 | <para>1999-05-02: Fixed a typo in videodev.h, and added the | ||
| 991 | V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para> | ||
| 992 | <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing | ||
| 993 | a malfunction of this ioctl.</para> | ||
| 994 | <para>1999-06-05: Changed the value of | ||
| 995 | V4L2_CID_WHITENESS.</para> | ||
| 996 | </section> | ||
| 997 | |||
| 998 | <section> | ||
| 999 | <title>V4L2 Version 0.20 (1999-09-10)</title> | ||
| 1000 | |||
| 1001 | <para>Version 0.20 introduced a number of changes which were | ||
| 1002 | <emphasis>not backward compatible</emphasis> with 0.19 and earlier | ||
| 1003 | versions. Purpose of these changes was to simplify the API, while | ||
| 1004 | making it more extensible and following common Linux driver API | ||
| 1005 | conventions.</para> | ||
| 1006 | |||
| 1007 | <orderedlist> | ||
| 1008 | <listitem> | ||
| 1009 | <para>Some typos in <constant>V4L2_FMT_FLAG</constant> | ||
| 1010 | symbols were fixed. &v4l2-clip; was changed for compatibility with | ||
| 1011 | v4l. (1999-08-30)</para> | ||
| 1012 | </listitem> | ||
| 1013 | |||
| 1014 | <listitem> | ||
| 1015 | <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added. | ||
| 1016 | (1999-09-05)</para> | ||
| 1017 | </listitem> | ||
| 1018 | |||
| 1019 | <listitem> | ||
| 1020 | <para>All ioctl() commands that used an integer argument now | ||
| 1021 | take a pointer to an integer. Where it makes sense, ioctls will return | ||
| 1022 | the actual new value in the integer pointed to by the argument, a | ||
| 1023 | common convention in the V4L2 API. The affected ioctls are: | ||
| 1024 | VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, | ||
| 1025 | VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example | ||
| 1026 | <programlisting> | ||
| 1027 | err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); | ||
| 1028 | </programlisting> becomes <programlisting> | ||
| 1029 | int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); | ||
| 1030 | </programlisting> | ||
| 1031 | </para> | ||
| 1032 | </listitem> | ||
| 1033 | |||
| 1034 | <listitem> | ||
| 1035 | <para>All the different get- and set-format commands were | ||
| 1036 | swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union | ||
| 1037 | and a type field selecting the union member as parameter. Purpose is to | ||
| 1038 | simplify the API by eliminating several ioctls and to allow new and | ||
| 1039 | driver private data streams without adding new ioctls.</para> | ||
| 1040 | |||
| 1041 | <para>This change obsoletes the following ioctls: | ||
| 1042 | <constant>VIDIOC_S_INFMT</constant>, | ||
| 1043 | <constant>VIDIOC_G_INFMT</constant>, | ||
| 1044 | <constant>VIDIOC_S_OUTFMT</constant>, | ||
| 1045 | <constant>VIDIOC_G_OUTFMT</constant>, | ||
| 1046 | <constant>VIDIOC_S_VBIFMT</constant> and | ||
| 1047 | <constant>VIDIOC_G_VBIFMT</constant>. The image format structure | ||
| 1048 | <structname>v4l2_format</structname> was renamed to &v4l2-pix-format;, | ||
| 1049 | while &v4l2-format; is now the envelopping structure for all format | ||
| 1050 | negotiations.</para> | ||
| 1051 | </listitem> | ||
| 1052 | |||
| 1053 | <listitem> | ||
| 1054 | <para>Similar to the changes above, the | ||
| 1055 | <constant>VIDIOC_G_PARM</constant> and | ||
| 1056 | <constant>VIDIOC_S_PARM</constant> ioctls were merged with | ||
| 1057 | <constant>VIDIOC_G_OUTPARM</constant> and | ||
| 1058 | <constant>VIDIOC_S_OUTPARM</constant>. A | ||
| 1059 | <structfield>type</structfield> field in the new &v4l2-streamparm; | ||
| 1060 | selects the respective union member.</para> | ||
| 1061 | |||
| 1062 | <para>This change obsoletes the | ||
| 1063 | <constant>VIDIOC_G_OUTPARM</constant> and | ||
| 1064 | <constant>VIDIOC_S_OUTPARM</constant> ioctls.</para> | ||
| 1065 | </listitem> | ||
| 1066 | |||
| 1067 | <listitem> | ||
| 1068 | <para>Control enumeration was simplified, and two new | ||
| 1069 | control flags were introduced and one dropped. The | ||
| 1070 | <structfield>catname</structfield> field was replaced by a | ||
| 1071 | <structfield>group</structfield> field.</para> | ||
| 1072 | |||
| 1073 | <para>Drivers can now flag unsupported and temporarily | ||
| 1074 | unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant> | ||
| 1075 | and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The | ||
| 1076 | <structfield>group</structfield> name indicates a possibly narrower | ||
| 1077 | classification than the <structfield>category</structfield>. In other | ||
| 1078 | words, there may be multiple groups within a category. Controls within | ||
| 1079 | a group would typically be drawn within a group box. Controls in | ||
| 1080 | different categories might have a greater separation, or may even | ||
| 1081 | appear in separate windows.</para> | ||
| 1082 | </listitem> | ||
| 1083 | |||
| 1084 | <listitem> | ||
| 1085 | <para>The &v4l2-buffer; <structfield>timestamp</structfield> | ||
| 1086 | was changed to a 64 bit integer, containing the sampling or output | ||
| 1087 | time of the frame in nanoseconds. Additionally timestamps will be in | ||
| 1088 | absolute system time, not starting from zero at the beginning of a | ||
| 1089 | stream. The data type name for timestamps is stamp_t, defined as a | ||
| 1090 | signed 64-bit integer. Output devices should not send a buffer out | ||
| 1091 | until the time in the timestamp field has arrived. I would like to | ||
| 1092 | follow SGI's lead, and adopt a multimedia timestamping system like | ||
| 1093 | their UST (Unadjusted System Time). See | ||
| 1094 | http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is | ||
| 1095 | no longer valid.] UST uses timestamps that are 64-bit signed integers | ||
| 1096 | (not struct timeval's) and given in nanosecond units. The UST clock | ||
| 1097 | starts at zero when the system is booted and runs continuously and | ||
| 1098 | uniformly. It takes a little over 292 years for UST to overflow. There | ||
| 1099 | is no way to set the UST clock. The regular Linux time-of-day clock | ||
| 1100 | can be changed periodically, which would cause errors if it were being | ||
| 1101 | used for timestamping a multimedia stream. A real UST style clock will | ||
| 1102 | require some support in the kernel that is not there yet. But in | ||
| 1103 | anticipation, I will change the timestamp field to a 64-bit integer, | ||
| 1104 | and I will change the v4l2_masterclock_gettime() function (used only | ||
| 1105 | by drivers) to return a 64-bit integer.</para> | ||
| 1106 | </listitem> | ||
| 1107 | |||
| 1108 | <listitem> | ||
| 1109 | <para>A <structfield>sequence</structfield> field was added | ||
| 1110 | to &v4l2-buffer;. The <structfield>sequence</structfield> field counts | ||
| 1111 | captured frames, it is ignored by output devices. When a capture | ||
| 1112 | driver drops a frame, the sequence number of that frame is | ||
| 1113 | skipped.</para> | ||
| 1114 | </listitem> | ||
| 1115 | </orderedlist> | ||
| 1116 | </section> | ||
| 1117 | |||
| 1118 | <section> | ||
| 1119 | <title>V4L2 Version 0.20 incremental changes</title> | ||
| 1120 | <!-- Version number didn't change anymore, reason unknown. --> | ||
| 1121 | |||
| 1122 | <para>1999-12-23: In &v4l2-vbi-format; the | ||
| 1123 | <structfield>reserved1</structfield> field became | ||
| 1124 | <structfield>offset</structfield>. Previously drivers were required to | ||
| 1125 | clear the <structfield>reserved1</structfield> field.</para> | ||
| 1126 | |||
| 1127 | <para>2000-01-13: The | ||
| 1128 | <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para> | ||
| 1129 | |||
| 1130 | <para>2000-07-31: The <filename>linux/poll.h</filename> header | ||
| 1131 | is now included by <filename>videodev.h</filename> for compatibility | ||
| 1132 | with the original <filename>videodev.h</filename> file.</para> | ||
| 1133 | |||
| 1134 | <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and | ||
| 1135 | <constant>V4L2_PIX_FMT_Y41P</constant> were added.</para> | ||
| 1136 | |||
| 1137 | <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was | ||
| 1138 | added.</para> | ||
| 1139 | |||
| 1140 | <para>2000-12-04: A couple typos in symbol names were fixed.</para> | ||
| 1141 | |||
| 1142 | <para>2001-01-18: To avoid namespace conflicts the | ||
| 1143 | <constant>fourcc</constant> macro defined in the | ||
| 1144 | <filename>videodev.h</filename> header file was renamed to | ||
| 1145 | <constant>v4l2_fourcc</constant>.</para> | ||
| 1146 | |||
| 1147 | <para>2001-01-25: A possible driver-level compatibility problem | ||
| 1148 | between the <filename>videodev.h</filename> file in Linux 2.4.0 and | ||
| 1149 | the <filename>videodev.h</filename> file included in the | ||
| 1150 | <filename>videodevX</filename> patch was fixed. Users of an earlier | ||
| 1151 | version of <filename>videodevX</filename> on Linux 2.4.0 should | ||
| 1152 | recompile their V4L and V4L2 drivers.</para> | ||
| 1153 | |||
| 1154 | <para>2001-01-26: A possible kernel-level incompatibility | ||
| 1155 | between the <filename>videodev.h</filename> file in the | ||
| 1156 | <filename>videodevX</filename> patch and the | ||
| 1157 | <filename>videodev.h</filename> file in Linux 2.2.x with devfs patches | ||
| 1158 | applied was fixed.</para> | ||
| 1159 | |||
| 1160 | <para>2001-03-02: Certain V4L ioctls which pass data in both | ||
| 1161 | direction although they are defined with read-only parameter, did not | ||
| 1162 | work correctly through the backward compatibility layer. | ||
| 1163 | [Solution?]</para> | ||
| 1164 | |||
| 1165 | <para>2001-04-13: Big endian 16-bit RGB formats were added.</para> | ||
| 1166 | |||
| 1167 | <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and | ||
| 1168 | &VIDIOC-S-FREQUENCY; ioctls were added. (The old | ||
| 1169 | <constant>VIDIOC_G_FREQ</constant> and | ||
| 1170 | <constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners | ||
| 1171 | into account.)</para> | ||
| 1172 | |||
| 1173 | <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was | ||
| 1174 | added. This may <emphasis>break compatibility</emphasis> as the | ||
| 1175 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct | ||
| 1176 | <structname>v4l2_fmt</structname> <structfield>type</structfield> | ||
| 1177 | field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the | ||
| 1178 | documentation of the &v4l2-vbi-format; | ||
| 1179 | <structfield>offset</structfield> field the ambiguous phrase "rising | ||
| 1180 | edge" was changed to "leading edge".</para> | ||
| 1181 | </section> | ||
| 1182 | |||
| 1183 | <section> | ||
| 1184 | <title>V4L2 Version 0.20 2000-11-23</title> | ||
| 1185 | |||
| 1186 | <para>A number of changes were made to the raw VBI | ||
| 1187 | interface.</para> | ||
| 1188 | |||
| 1189 | <orderedlist> | ||
| 1190 | <listitem> | ||
| 1191 | <para>Figures clarifying the line numbering scheme were | ||
| 1192 | added to the V4L2 API specification. The | ||
| 1193 | <structfield>start</structfield>[0] and | ||
| 1194 | <structfield>start</structfield>[1] fields no longer count line | ||
| 1195 | numbers beginning at zero. Rationale: a) The previous definition was | ||
| 1196 | unclear. b) The <structfield>start</structfield>[] values are ordinal | ||
| 1197 | numbers. c) There is no point in inventing a new line numbering | ||
| 1198 | scheme. We now use line number as defined by ITU-R, period. | ||
| 1199 | Compatibility: Add one to the start values. Applications depending on | ||
| 1200 | the previous semantics may not function correctly.</para> | ||
| 1201 | </listitem> | ||
| 1202 | |||
| 1203 | <listitem> | ||
| 1204 | <para>The restriction "count[0] > 0 and count[1] > 0" | ||
| 1205 | has been relaxed to "(count[0] + count[1]) > 0". Rationale: | ||
| 1206 | Drivers may allocate resources at scan line granularity and some data | ||
| 1207 | services are transmitted only on the first field. The comment that | ||
| 1208 | both <structfield>count</structfield> values will usually be equal is | ||
| 1209 | misleading and pointless and has been removed. This change | ||
| 1210 | <emphasis>breaks compatibility</emphasis> with earlier versions: | ||
| 1211 | Drivers may return EINVAL, applications may not function | ||
| 1212 | correctly.</para> | ||
| 1213 | </listitem> | ||
| 1214 | |||
| 1215 | <listitem> | ||
| 1216 | <para>Drivers are again permitted to return negative | ||
| 1217 | (unknown) start values as proposed earlier. Why this feature was | ||
| 1218 | dropped is unclear. This change may <emphasis>break | ||
| 1219 | compatibility</emphasis> with applications depending on the start | ||
| 1220 | values being positive. The use of <constant>EBUSY</constant> and | ||
| 1221 | <constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl | ||
| 1222 | was clarified. The &EBUSY; was finally documented, and the | ||
| 1223 | <structfield>reserved2</structfield> field which was previously | ||
| 1224 | mentioned only in the <filename>videodev.h</filename> header | ||
| 1225 | file.</para> | ||
| 1226 | </listitem> | ||
| 1227 | |||
| 1228 | <listitem> | ||
| 1229 | <para>New buffer types | ||
| 1230 | <constant>V4L2_TYPE_VBI_INPUT</constant> and | ||
| 1231 | <constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an | ||
| 1232 | alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was | ||
| 1233 | missing in the <filename>videodev.h</filename> file.</para> | ||
| 1234 | </listitem> | ||
| 1235 | </orderedlist> | ||
| 1236 | </section> | ||
| 1237 | |||
| 1238 | <section> | ||
| 1239 | <title>V4L2 Version 0.20 2002-07-25</title> | ||
| 1240 | <para>Added sliced VBI interface proposal.</para> | ||
| 1241 | </section> | ||
| 1242 | |||
| 1243 | <section> | ||
| 1244 | <title>V4L2 in Linux 2.5.46, 2002-10</title> | ||
| 1245 | |||
| 1246 | <para>Around October-November 2002, prior to an announced | ||
| 1247 | feature freeze of Linux 2.5, the API was revised, drawing from | ||
| 1248 | experience with V4L2 0.20. This unnamed version was finally merged | ||
| 1249 | into Linux 2.5.46.</para> | ||
| 1250 | |||
| 1251 | <orderedlist> | ||
| 1252 | <listitem> | ||
| 1253 | <para>As specified in <xref linkend="related" />, drivers | ||
| 1254 | must make related device functions available under all minor device | ||
| 1255 | numbers.</para> | ||
| 1256 | </listitem> | ||
| 1257 | |||
| 1258 | <listitem> | ||
| 1259 | <para>The &func-open; function requires access mode | ||
| 1260 | <constant>O_RDWR</constant> regardless of the device type. All V4L2 | ||
| 1261 | drivers exchanging data with applications must support the | ||
| 1262 | <constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant> | ||
| 1263 | flag, a V4L2 symbol which aliased the meaningless | ||
| 1264 | <constant>O_TRUNC</constant> to indicate accesses without data | ||
| 1265 | exchange (panel applications) was dropped. Drivers must stay in "panel | ||
| 1266 | mode" until the application attempts to initiate a data exchange, see | ||
| 1267 | <xref linkend="open" />.</para> | ||
| 1268 | </listitem> | ||
| 1269 | |||
| 1270 | <listitem> | ||
| 1271 | <para>The &v4l2-capability; changed dramatically. Note that | ||
| 1272 | also the size of the structure changed, which is encoded in the ioctl | ||
| 1273 | request code, thus older V4L2 devices will respond with an &EINVAL; to | ||
| 1274 | the new &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 1275 | |||
| 1276 | <para>There are new fields to identify the driver, a new RDS | ||
| 1277 | device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the | ||
| 1278 | <constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has | ||
| 1279 | any audio connectors, another I/O capability | ||
| 1280 | <constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to | ||
| 1281 | these changes the <structfield>type</structfield> field became a bit | ||
| 1282 | set and was merged into the <structfield>flags</structfield> field. | ||
| 1283 | <constant>V4L2_FLAG_TUNER</constant> was renamed to | ||
| 1284 | <constant>V4L2_CAP_TUNER</constant>, | ||
| 1285 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced | ||
| 1286 | <constant>V4L2_FLAG_PREVIEW</constant> and | ||
| 1287 | <constant>V4L2_CAP_VBI_CAPTURE</constant> and | ||
| 1288 | <constant>V4L2_CAP_VBI_OUTPUT</constant> replaced | ||
| 1289 | <constant>V4L2_FLAG_DATA_SERVICE</constant>. | ||
| 1290 | <constant>V4L2_FLAG_READ</constant> and | ||
| 1291 | <constant>V4L2_FLAG_WRITE</constant> were merged into | ||
| 1292 | <constant>V4L2_CAP_READWRITE</constant>.</para> | ||
| 1293 | |||
| 1294 | <para>The redundant fields | ||
| 1295 | <structfield>inputs</structfield>, <structfield>outputs</structfield> | ||
| 1296 | and <structfield>audios</structfield> were removed. These properties | ||
| 1297 | can be determined as described in <xref linkend="video" /> and <xref | ||
| 1298 | linkend="audio" />.</para> | ||
| 1299 | |||
| 1300 | <para>The somewhat volatile and therefore barely useful | ||
| 1301 | fields <structfield>maxwidth</structfield>, | ||
| 1302 | <structfield>maxheight</structfield>, | ||
| 1303 | <structfield>minwidth</structfield>, | ||
| 1304 | <structfield>minheight</structfield>, | ||
| 1305 | <structfield>maxframerate</structfield> were removed. This information | ||
| 1306 | is available as described in <xref linkend="format" /> and | ||
| 1307 | <xref linkend="standard" />.</para> | ||
| 1308 | |||
| 1309 | <para><constant>V4L2_FLAG_SELECT</constant> was removed. We | ||
| 1310 | believe the select() function is important enough to require support | ||
| 1311 | of it in all V4L2 drivers exchanging data with applications. The | ||
| 1312 | redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed, | ||
| 1313 | this information is available as described in <xref | ||
| 1314 | linkend="format" />.</para> | ||
| 1315 | </listitem> | ||
| 1316 | |||
| 1317 | <listitem> | ||
| 1318 | <para>In &v4l2-input; the | ||
| 1319 | <structfield>assoc_audio</structfield> field and the | ||
| 1320 | <structfield>capability</structfield> field and its only flag | ||
| 1321 | <constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new | ||
| 1322 | <structfield>audioset</structfield> field. Instead of linking one | ||
| 1323 | video input to one audio input this field reports all audio inputs | ||
| 1324 | this video input combines with.</para> | ||
| 1325 | |||
| 1326 | <para>New fields are <structfield>tuner</structfield> | ||
| 1327 | (reversing the former link from tuners to video inputs), | ||
| 1328 | <structfield>std</structfield> and | ||
| 1329 | <structfield>status</structfield>.</para> | ||
| 1330 | |||
| 1331 | <para>Accordingly &v4l2-output; lost its | ||
| 1332 | <structfield>capability</structfield> and | ||
| 1333 | <structfield>assoc_audio</structfield> fields. | ||
| 1334 | <structfield>audioset</structfield>, | ||
| 1335 | <structfield>modulator</structfield> and | ||
| 1336 | <structfield>std</structfield> where added instead.</para> | ||
| 1337 | </listitem> | ||
| 1338 | |||
| 1339 | <listitem> | ||
| 1340 | <para>The &v4l2-audio; field | ||
| 1341 | <structfield>audio</structfield> was renamed to | ||
| 1342 | <structfield>index</structfield>, for consistency with other | ||
| 1343 | structures. A new capability flag | ||
| 1344 | <constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the | ||
| 1345 | audio input in question supports stereo sound. | ||
| 1346 | <constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding | ||
| 1347 | <constant>V4L2_AUDMODE</constant> flags where removed. This can be | ||
| 1348 | easily implemented using controls. (However the same applies to AVL | ||
| 1349 | which is still there.)</para> | ||
| 1350 | |||
| 1351 | <para>Again for consistency the &v4l2-audioout; field | ||
| 1352 | <structfield>audio</structfield> was renamed to | ||
| 1353 | <structfield>index</structfield>.</para> | ||
| 1354 | </listitem> | ||
| 1355 | |||
| 1356 | <listitem> | ||
| 1357 | <para>The &v4l2-tuner; | ||
| 1358 | <structfield>input</structfield> field was replaced by an | ||
| 1359 | <structfield>index</structfield> field, permitting devices with | ||
| 1360 | multiple tuners. The link between video inputs and tuners is now | ||
| 1361 | reversed, inputs point to their tuner. The | ||
| 1362 | <structfield>std</structfield> substructure became a | ||
| 1363 | simple set (more about this below) and moved into &v4l2-input;. A | ||
| 1364 | <structfield>type</structfield> field was added.</para> | ||
| 1365 | |||
| 1366 | <para>Accordingly in &v4l2-modulator; the | ||
| 1367 | <structfield>output</structfield> was replaced by an | ||
| 1368 | <structfield>index</structfield> field.</para> | ||
| 1369 | |||
| 1370 | <para>In &v4l2-frequency; the | ||
| 1371 | <structfield>port</structfield> field was replaced by a | ||
| 1372 | <structfield>tuner</structfield> field containing the respective tuner | ||
| 1373 | or modulator index number. A tuner <structfield>type</structfield> | ||
| 1374 | field was added and the <structfield>reserved</structfield> field | ||
| 1375 | became larger for future extensions (satellite tuners in | ||
| 1376 | particular).</para> | ||
| 1377 | </listitem> | ||
| 1378 | |||
| 1379 | <listitem> | ||
| 1380 | <para>The idea of completely transparent video standards was | ||
| 1381 | dropped. Experience showed that applications must be able to work with | ||
| 1382 | video standards beyond presenting the user a menu. Instead of | ||
| 1383 | enumerating supported standards with an ioctl applications can now | ||
| 1384 | refer to standards by &v4l2-std-id; and symbols defined in the | ||
| 1385 | <filename>videodev2.h</filename> header file. For details see <xref | ||
| 1386 | linkend="standard" />. The &VIDIOC-G-STD; and | ||
| 1387 | &VIDIOC-S-STD; now take a pointer to this type as argument. | ||
| 1388 | &VIDIOC-QUERYSTD; was added to autodetect the received standard, if | ||
| 1389 | the hardware has this capability. In &v4l2-standard; an | ||
| 1390 | <structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;. | ||
| 1391 | A &v4l2-std-id; field named <structfield>id</structfield> was added as | ||
| 1392 | machine readable identifier, also replacing the | ||
| 1393 | <structfield>transmission</structfield> field. The misleading | ||
| 1394 | <structfield>framerate</structfield> field was renamed | ||
| 1395 | to <structfield>frameperiod</structfield>. The now obsolete | ||
| 1396 | <structfield>colorstandard</structfield> information, originally | ||
| 1397 | needed to distguish between variations of standards, were | ||
| 1398 | removed.</para> | ||
| 1399 | |||
| 1400 | <para>Struct <structname>v4l2_enumstd</structname> ceased to | ||
| 1401 | be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard; | ||
| 1402 | directly. The information which standards are supported by a | ||
| 1403 | particular video input or output moved into &v4l2-input; and | ||
| 1404 | &v4l2-output; fields named <structfield>std</structfield>, | ||
| 1405 | respectively.</para> | ||
| 1406 | </listitem> | ||
| 1407 | |||
| 1408 | <listitem> | ||
| 1409 | <para>The &v4l2-queryctrl; fields | ||
| 1410 | <structfield>category</structfield> and | ||
| 1411 | <structfield>group</structfield> did not catch on and/or were not | ||
| 1412 | implemented as expected and therefore removed.</para> | ||
| 1413 | </listitem> | ||
| 1414 | |||
| 1415 | <listitem> | ||
| 1416 | <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data | ||
| 1417 | formats as with &VIDIOC-S-FMT;, but without the overhead of | ||
| 1418 | programming the hardware and regardless of I/O in progress.</para> | ||
| 1419 | |||
| 1420 | <para>In &v4l2-format; the <structfield>fmt</structfield> | ||
| 1421 | union was extended to contain &v4l2-window;. All image format | ||
| 1422 | negotiations are now possible with <constant>VIDIOC_G_FMT</constant>, | ||
| 1423 | <constant>VIDIOC_S_FMT</constant> and | ||
| 1424 | <constant>VIDIOC_TRY_FMT</constant>; ioctl. The | ||
| 1425 | <constant>VIDIOC_G_WIN</constant> and | ||
| 1426 | <constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video | ||
| 1427 | overlay were removed. The <structfield>type</structfield> field | ||
| 1428 | changed to type &v4l2-buf-type; and the buffer type names changed as | ||
| 1429 | follows.<informaltable> | ||
| 1430 | <tgroup cols="2"> | ||
| 1431 | <thead> | ||
| 1432 | <row> | ||
| 1433 | <entry>Old defines</entry> | ||
| 1434 | <entry>&v4l2-buf-type;</entry> | ||
| 1435 | </row> | ||
| 1436 | </thead> | ||
| 1437 | <tbody valign="top"> | ||
| 1438 | <row> | ||
| 1439 | <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry> | ||
| 1440 | <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> | ||
| 1441 | </row> | ||
| 1442 | <row> | ||
| 1443 | <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry> | ||
| 1444 | <entry>Omitted for now</entry> | ||
| 1445 | </row> | ||
| 1446 | <row> | ||
| 1447 | <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry> | ||
| 1448 | <entry>Omitted for now</entry> | ||
| 1449 | </row> | ||
| 1450 | <row> | ||
| 1451 | <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry> | ||
| 1452 | <entry>Omitted for now</entry> | ||
| 1453 | </row> | ||
| 1454 | <row> | ||
| 1455 | <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry> | ||
| 1456 | <entry>Omitted for now</entry> | ||
| 1457 | </row> | ||
| 1458 | <row> | ||
| 1459 | <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry> | ||
| 1460 | <entry>Omitted for now</entry> | ||
| 1461 | </row> | ||
| 1462 | <row> | ||
| 1463 | <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry> | ||
| 1464 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> | ||
| 1465 | </row> | ||
| 1466 | <row> | ||
| 1467 | <entry><constant>-</constant></entry> | ||
| 1468 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> | ||
| 1469 | </row> | ||
| 1470 | <row> | ||
| 1471 | <entry><constant>-</constant></entry> | ||
| 1472 | <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> | ||
| 1473 | </row> | ||
| 1474 | <row> | ||
| 1475 | <entry><constant>-</constant></entry> | ||
| 1476 | <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> | ||
| 1477 | </row> | ||
| 1478 | <row> | ||
| 1479 | <entry><constant>-</constant></entry> | ||
| 1480 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> | ||
| 1481 | </row> | ||
| 1482 | <row> | ||
| 1483 | <entry><constant>-</constant></entry> | ||
| 1484 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> | ||
| 1485 | </row> | ||
| 1486 | <row> | ||
| 1487 | <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry> | ||
| 1488 | <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> | ||
| 1489 | </row> | ||
| 1490 | </tbody> | ||
| 1491 | </tgroup> | ||
| 1492 | </informaltable></para> | ||
| 1493 | </listitem> | ||
| 1494 | |||
| 1495 | <listitem> | ||
| 1496 | <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named | ||
| 1497 | <structfield>type</structfield> was added as in &v4l2-format;. The | ||
| 1498 | <constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and | ||
| 1499 | was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with | ||
| 1500 | type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> | ||
| 1501 | </listitem> | ||
| 1502 | |||
| 1503 | <listitem> | ||
| 1504 | <para>In &v4l2-pix-format; the | ||
| 1505 | <structfield>depth</structfield> field was removed, assuming | ||
| 1506 | applications which recognize the format by its four-character-code | ||
| 1507 | already know the color depth, and others do not care about it. The | ||
| 1508 | same rationale lead to the removal of the | ||
| 1509 | <constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The | ||
| 1510 | <constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed | ||
| 1511 | because drivers are not supposed to convert images in kernel space. A | ||
| 1512 | user library of conversion functions should be provided instead. The | ||
| 1513 | <constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant. | ||
| 1514 | Applications can set the <structfield>bytesperline</structfield> field | ||
| 1515 | to zero to get a reasonable default. Since the remaining flags were | ||
| 1516 | replaced as well, the <structfield>flags</structfield> field itself | ||
| 1517 | was removed.</para> | ||
| 1518 | <para>The interlace flags were replaced by a &v4l2-field; | ||
| 1519 | value in a newly added <structfield>field</structfield> | ||
| 1520 | field.<informaltable> | ||
| 1521 | <tgroup cols="2"> | ||
| 1522 | <thead> | ||
| 1523 | <row> | ||
| 1524 | <entry>Old flag</entry> | ||
| 1525 | <entry>&v4l2-field;</entry> | ||
| 1526 | </row> | ||
| 1527 | </thead> | ||
| 1528 | <tbody valign="top"> | ||
| 1529 | <row> | ||
| 1530 | <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry> | ||
| 1531 | <entry>?</entry> | ||
| 1532 | </row> | ||
| 1533 | <row> | ||
| 1534 | <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant> | ||
| 1535 | = <constant>V4L2_FMT_FLAG_COMBINED</constant></entry> | ||
| 1536 | <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> | ||
| 1537 | </row> | ||
| 1538 | <row> | ||
| 1539 | <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant> | ||
| 1540 | = <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry> | ||
| 1541 | <entry><constant>V4L2_FIELD_TOP</constant></entry> | ||
| 1542 | </row> | ||
| 1543 | <row> | ||
| 1544 | <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant> | ||
| 1545 | = <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry> | ||
| 1546 | <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> | ||
| 1547 | </row> | ||
| 1548 | <row> | ||
| 1549 | <entry><constant>-</constant></entry> | ||
| 1550 | <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> | ||
| 1551 | </row> | ||
| 1552 | <row> | ||
| 1553 | <entry><constant>-</constant></entry> | ||
| 1554 | <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> | ||
| 1555 | </row> | ||
| 1556 | <row> | ||
| 1557 | <entry><constant>-</constant></entry> | ||
| 1558 | <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> | ||
| 1559 | </row> | ||
| 1560 | </tbody> | ||
| 1561 | </tgroup> | ||
| 1562 | </informaltable></para> | ||
| 1563 | |||
| 1564 | <para>The color space flags were replaced by a | ||
| 1565 | &v4l2-colorspace; value in a newly added | ||
| 1566 | <structfield>colorspace</structfield> field, where one of | ||
| 1567 | <constant>V4L2_COLORSPACE_SMPTE170M</constant>, | ||
| 1568 | <constant>V4L2_COLORSPACE_BT878</constant>, | ||
| 1569 | <constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or | ||
| 1570 | <constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces | ||
| 1571 | <constant>V4L2_FMT_CS_601YUV</constant>.</para> | ||
| 1572 | </listitem> | ||
| 1573 | |||
| 1574 | <listitem> | ||
| 1575 | <para>In &v4l2-requestbuffers; the | ||
| 1576 | <structfield>type</structfield> field was properly defined as | ||
| 1577 | &v4l2-buf-type;. Buffer types changed as mentioned above. A new | ||
| 1578 | <structfield>memory</structfield> field of type &v4l2-memory; was | ||
| 1579 | added to distinguish between I/O methods using buffers allocated | ||
| 1580 | by the driver or the application. See <xref linkend="io" /> for | ||
| 1581 | details.</para> | ||
| 1582 | </listitem> | ||
| 1583 | |||
| 1584 | <listitem> | ||
| 1585 | <para>In &v4l2-buffer; the <structfield>type</structfield> | ||
| 1586 | field was properly defined as &v4l2-buf-type;. Buffer types changed as | ||
| 1587 | mentioned above. A <structfield>field</structfield> field of type | ||
| 1588 | &v4l2-field; was added to indicate if a buffer contains a top or | ||
| 1589 | bottom field. The old field flags were removed. Since no unadjusted | ||
| 1590 | system time clock was added to the kernel as planned, the | ||
| 1591 | <structfield>timestamp</structfield> field changed back from type | ||
| 1592 | stamp_t, an unsigned 64 bit integer expressing the sample time in | ||
| 1593 | nanoseconds, to struct <structname>timeval</structname>. With the | ||
| 1594 | addition of a second memory mapping method the | ||
| 1595 | <structfield>offset</structfield> field moved into union | ||
| 1596 | <structfield>m</structfield>, and a new | ||
| 1597 | <structfield>memory</structfield> field of type &v4l2-memory; was | ||
| 1598 | added to distinguish between I/O methods. See <xref linkend="io" /> | ||
| 1599 | for details.</para> | ||
| 1600 | |||
| 1601 | <para>The <constant>V4L2_BUF_REQ_CONTIG</constant> | ||
| 1602 | flag was used by the V4L compatibility layer, after changes to this | ||
| 1603 | code it was no longer needed. The | ||
| 1604 | <constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if | ||
| 1605 | the buffer was indeed allocated in device memory rather than DMA-able | ||
| 1606 | system memory. It was barely useful and so was removed.</para> | ||
| 1607 | </listitem> | ||
| 1608 | |||
| 1609 | <listitem> | ||
| 1610 | <para>In &v4l2-framebuffer; the | ||
| 1611 | <structfield>base[3]</structfield> array anticipating double- and | ||
| 1612 | triple-buffering in off-screen video memory, however without defining | ||
| 1613 | a synchronization mechanism, was replaced by a single pointer. The | ||
| 1614 | <constant>V4L2_FBUF_CAP_SCALEUP</constant> and | ||
| 1615 | <constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed. | ||
| 1616 | Applications can determine this capability more accurately using the | ||
| 1617 | new cropping and scaling interface. The | ||
| 1618 | <constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by | ||
| 1619 | <constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and | ||
| 1620 | <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para> | ||
| 1621 | </listitem> | ||
| 1622 | |||
| 1623 | <listitem> | ||
| 1624 | <para>In &v4l2-clip; the <structfield>x</structfield>, | ||
| 1625 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 1626 | <structfield>height</structfield> field moved into a | ||
| 1627 | <structfield>c</structfield> substructure of type &v4l2-rect;. The | ||
| 1628 | <structfield>x</structfield> and <structfield>y</structfield> fields | ||
| 1629 | were renamed to <structfield>left</structfield> and | ||
| 1630 | <structfield>top</structfield>, &ie; offsets to a context dependent | ||
| 1631 | origin.</para> | ||
| 1632 | </listitem> | ||
| 1633 | |||
| 1634 | <listitem> | ||
| 1635 | <para>In &v4l2-window; the <structfield>x</structfield>, | ||
| 1636 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 1637 | <structfield>height</structfield> field moved into a | ||
| 1638 | <structfield>w</structfield> substructure as above. A | ||
| 1639 | <structfield>field</structfield> field of type %v4l2-field; was added | ||
| 1640 | to distinguish between field and frame (interlaced) overlay.</para> | ||
| 1641 | </listitem> | ||
| 1642 | |||
| 1643 | <listitem> | ||
| 1644 | <para>The digital zoom interface, including struct | ||
| 1645 | <structname>v4l2_zoomcap</structname>, struct | ||
| 1646 | <structname>v4l2_zoom</structname>, | ||
| 1647 | <constant>V4L2_ZOOM_NONCAP</constant> and | ||
| 1648 | <constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new | ||
| 1649 | cropping and scaling interface. The previously unused struct | ||
| 1650 | <structname>v4l2_cropcap</structname> and | ||
| 1651 | <structname>v4l2_crop</structname> where redefined for this purpose. | ||
| 1652 | See <xref linkend="crop" /> for details.</para> | ||
| 1653 | </listitem> | ||
| 1654 | |||
| 1655 | <listitem> | ||
| 1656 | <para>In &v4l2-vbi-format; the | ||
| 1657 | <structfield>SAMPLE_FORMAT</structfield> field now contains a | ||
| 1658 | four-character-code as used to identify video image formats and | ||
| 1659 | <constant>V4L2_PIX_FMT_GREY</constant> replaces the | ||
| 1660 | <constant>V4L2_VBI_SF_UBYTE</constant> define. The | ||
| 1661 | <structfield>reserved</structfield> field was extended.</para> | ||
| 1662 | </listitem> | ||
| 1663 | |||
| 1664 | <listitem> | ||
| 1665 | <para>In &v4l2-captureparm; the type of the | ||
| 1666 | <structfield>timeperframe</structfield> field changed from unsigned | ||
| 1667 | long to &v4l2-fract;. This allows the accurate expression of multiples | ||
| 1668 | of the NTSC-M frame rate 30000 / 1001. A new field | ||
| 1669 | <structfield>readbuffers</structfield> was added to control the driver | ||
| 1670 | behaviour in read I/O mode.</para> | ||
| 1671 | |||
| 1672 | <para>Similar changes were made to &v4l2-outputparm;.</para> | ||
| 1673 | </listitem> | ||
| 1674 | |||
| 1675 | <listitem> | ||
| 1676 | <para>The struct <structname>v4l2_performance</structname> | ||
| 1677 | and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when | ||
| 1678 | using the <link linkend="rw">read/write I/O method</link>, which is | ||
| 1679 | limited anyway, this information is already available to | ||
| 1680 | applications.</para> | ||
| 1681 | </listitem> | ||
| 1682 | |||
| 1683 | <listitem> | ||
| 1684 | <para>The example transformation from RGB to YCbCr color | ||
| 1685 | space in the old V4L2 documentation was inaccurate, this has been | ||
| 1686 | corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be | ||
| 1687 | 0.587, and 127/112 != 255/224 --></para> | ||
| 1688 | </listitem> | ||
| 1689 | </orderedlist> | ||
| 1690 | </section> | ||
| 1691 | |||
| 1692 | <section> | ||
| 1693 | <title>V4L2 2003-06-19</title> | ||
| 1694 | |||
| 1695 | <orderedlist> | ||
| 1696 | <listitem> | ||
| 1697 | <para>A new capability flag | ||
| 1698 | <constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior | ||
| 1699 | to this change radio devices would identify solely by having exactly one | ||
| 1700 | tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para> | ||
| 1701 | </listitem> | ||
| 1702 | |||
| 1703 | <listitem> | ||
| 1704 | <para>An optional driver access priority mechanism was | ||
| 1705 | added, see <xref linkend="app-pri" /> for details.</para> | ||
| 1706 | </listitem> | ||
| 1707 | |||
| 1708 | <listitem> | ||
| 1709 | <para>The audio input and output interface was found to be | ||
| 1710 | incomplete.</para> | ||
| 1711 | <para>Previously the &VIDIOC-G-AUDIO; | ||
| 1712 | ioctl would enumerate the available audio inputs. An ioctl to | ||
| 1713 | determine the current audio input, if more than one combines with the | ||
| 1714 | current video input, did not exist. So | ||
| 1715 | <constant>VIDIOC_G_AUDIO</constant> was renamed to | ||
| 1716 | <constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in | ||
| 1717 | the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate | ||
| 1718 | audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio | ||
| 1719 | input.</para> | ||
| 1720 | <para>The same changes were made to &VIDIOC-G-AUDOUT; and | ||
| 1721 | &VIDIOC-ENUMAUDOUT;.</para> | ||
| 1722 | <para>Until further the "videodev" module will automatically | ||
| 1723 | translate between the old and new ioctls, but drivers and applications | ||
| 1724 | must be updated to successfully compile again.</para> | ||
| 1725 | </listitem> | ||
| 1726 | |||
| 1727 | <listitem> | ||
| 1728 | <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with | ||
| 1729 | write-read parameter. It was changed to write-only, while the write-read | ||
| 1730 | version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old | ||
| 1731 | ioctl will be removed in the future. Until further the "videodev" | ||
| 1732 | kernel module will automatically translate to the new version, so drivers | ||
| 1733 | must be recompiled, but not applications.</para> | ||
| 1734 | </listitem> | ||
| 1735 | |||
| 1736 | <listitem> | ||
| 1737 | <para><xref linkend="overlay" /> incorrectly stated that | ||
| 1738 | clipping rectangles define regions where the video can be seen. | ||
| 1739 | Correct is that clipping rectangles define regions where | ||
| 1740 | <emphasis>no</emphasis> video shall be displayed and so the graphics | ||
| 1741 | surface can be seen.</para> | ||
| 1742 | </listitem> | ||
| 1743 | |||
| 1744 | <listitem> | ||
| 1745 | <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were | ||
| 1746 | defined with write-only parameter, inconsistent with other ioctls | ||
| 1747 | modifying their argument. They were changed to write-read, while a | ||
| 1748 | <constant>_OLD</constant> suffix was added to the write-only versions. | ||
| 1749 | The old ioctls will be removed in the future. Drivers and | ||
| 1750 | applications assuming a constant parameter need an update.</para> | ||
| 1751 | </listitem> | ||
| 1752 | </orderedlist> | ||
| 1753 | </section> | ||
| 1754 | |||
| 1755 | <section> | ||
| 1756 | <title>V4L2 2003-11-05</title> | ||
| 1757 | <orderedlist> | ||
| 1758 | <listitem> | ||
| 1759 | <para>In <xref linkend="pixfmt-rgb" /> the following pixel | ||
| 1760 | formats were incorrectly transferred from Bill Dirks' V4L2 | ||
| 1761 | specification. Descriptions below refer to bytes in memory, in | ||
| 1762 | ascending address order.<informaltable> | ||
| 1763 | <tgroup cols="3"> | ||
| 1764 | <thead> | ||
| 1765 | <row> | ||
| 1766 | <entry>Symbol</entry> | ||
| 1767 | <entry>In this document prior to revision | ||
| 1768 | 0.5</entry> | ||
| 1769 | <entry>Corrected</entry> | ||
| 1770 | </row> | ||
| 1771 | </thead> | ||
| 1772 | <tbody valign="top"> | ||
| 1773 | <row> | ||
| 1774 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 1775 | <entry>B, G, R</entry> | ||
| 1776 | <entry>R, G, B</entry> | ||
| 1777 | </row> | ||
| 1778 | <row> | ||
| 1779 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 1780 | <entry>R, G, B</entry> | ||
| 1781 | <entry>B, G, R</entry> | ||
| 1782 | </row> | ||
| 1783 | <row> | ||
| 1784 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 1785 | <entry>B, G, R, X</entry> | ||
| 1786 | <entry>R, G, B, X</entry> | ||
| 1787 | </row> | ||
| 1788 | <row> | ||
| 1789 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 1790 | <entry>R, G, B, X</entry> | ||
| 1791 | <entry>B, G, R, X</entry> | ||
| 1792 | </row> | ||
| 1793 | </tbody> | ||
| 1794 | </tgroup> | ||
| 1795 | </informaltable> The | ||
| 1796 | <constant>V4L2_PIX_FMT_BGR24</constant> example was always | ||
| 1797 | correct.</para> | ||
| 1798 | <para>In <xref linkend="v4l-image-properties" /> the mapping | ||
| 1799 | of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and | ||
| 1800 | <constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats | ||
| 1801 | was accordingly corrected.</para> | ||
| 1802 | </listitem> | ||
| 1803 | |||
| 1804 | <listitem> | ||
| 1805 | <para>Unrelated to the fixes above, drivers may still | ||
| 1806 | interpret some V4L2 RGB pixel formats differently. These issues have | ||
| 1807 | yet to be addressed, for details see <xref | ||
| 1808 | linkend="pixfmt-rgb" />.</para> | ||
| 1809 | </listitem> | ||
| 1810 | </orderedlist> | ||
| 1811 | </section> | ||
| 1812 | |||
| 1813 | <section> | ||
| 1814 | <title>V4L2 in Linux 2.6.6, 2004-05-09</title> | ||
| 1815 | <orderedlist> | ||
| 1816 | <listitem> | ||
| 1817 | <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined | ||
| 1818 | with read-only parameter. It is now defined as write-read ioctl, while | ||
| 1819 | the read-only version was renamed to | ||
| 1820 | <constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed | ||
| 1821 | in the future.</para> | ||
| 1822 | </listitem> | ||
| 1823 | </orderedlist> | ||
| 1824 | </section> | ||
| 1825 | |||
| 1826 | <section> | ||
| 1827 | <title>V4L2 in Linux 2.6.8</title> | ||
| 1828 | <orderedlist> | ||
| 1829 | <listitem> | ||
| 1830 | <para>A new field <structfield>input</structfield> (former | ||
| 1831 | <structfield>reserved[0]</structfield>) was added to the &v4l2-buffer; | ||
| 1832 | structure. Purpose of this field is to alternate between video inputs | ||
| 1833 | (⪚ cameras) in step with the video capturing process. This function | ||
| 1834 | must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant> | ||
| 1835 | flag. The <structfield>flags</structfield> field is no longer | ||
| 1836 | read-only.</para> | ||
| 1837 | </listitem> | ||
| 1838 | </orderedlist> | ||
| 1839 | </section> | ||
| 1840 | |||
| 1841 | <section> | ||
| 1842 | <title>V4L2 spec erratum 2004-08-01</title> | ||
| 1843 | |||
| 1844 | <orderedlist> | ||
| 1845 | <listitem> | ||
| 1846 | <para>The return value of the | ||
| 1847 | <xref linkend="func-open" /> function was incorrectly documented.</para> | ||
| 1848 | </listitem> | ||
| 1849 | |||
| 1850 | <listitem> | ||
| 1851 | <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para> | ||
| 1852 | </listitem> | ||
| 1853 | |||
| 1854 | <listitem> | ||
| 1855 | <para>In the Current Audio Input example the | ||
| 1856 | <constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong | ||
| 1857 | argument.</para> | ||
| 1858 | </listitem> | ||
| 1859 | |||
| 1860 | <listitem> | ||
| 1861 | <para>The documentation of the &VIDIOC-QBUF; and | ||
| 1862 | &VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer; | ||
| 1863 | <structfield>memory</structfield> field. It was also missing from | ||
| 1864 | examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO; | ||
| 1865 | was not documented.</para> | ||
| 1866 | </listitem> | ||
| 1867 | </orderedlist> | ||
| 1868 | </section> | ||
| 1869 | |||
| 1870 | <section> | ||
| 1871 | <title>V4L2 in Linux 2.6.14</title> | ||
| 1872 | <orderedlist> | ||
| 1873 | <listitem> | ||
| 1874 | <para>A new sliced VBI interface was added. It is documented | ||
| 1875 | in <xref linkend="sliced" /> and replaces the interface first | ||
| 1876 | proposed in V4L2 specification 0.8.</para> | ||
| 1877 | </listitem> | ||
| 1878 | </orderedlist> | ||
| 1879 | </section> | ||
| 1880 | |||
| 1881 | <section> | ||
| 1882 | <title>V4L2 in Linux 2.6.15</title> | ||
| 1883 | <orderedlist> | ||
| 1884 | <listitem> | ||
| 1885 | <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para> | ||
| 1886 | </listitem> | ||
| 1887 | |||
| 1888 | <listitem> | ||
| 1889 | <para>New video standards | ||
| 1890 | <constant>V4L2_STD_NTSC_443</constant>, | ||
| 1891 | <constant>V4L2_STD_SECAM_LC</constant>, | ||
| 1892 | <constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1), | ||
| 1893 | and <constant>V4L2_STD_ATSC</constant> (a set of | ||
| 1894 | <constant>V4L2_STD_ATSC_8_VSB</constant> and | ||
| 1895 | <constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the | ||
| 1896 | <constant>V4L2_STD_525_60</constant> set now includes | ||
| 1897 | <constant>V4L2_STD_NTSC_443</constant>. See also <xref | ||
| 1898 | linkend="v4l2-std-id" />.</para> | ||
| 1899 | </listitem> | ||
| 1900 | |||
| 1901 | <listitem> | ||
| 1902 | <para>The <constant>VIDIOC_G_COMP</constant> and | ||
| 1903 | <constant>VIDIOC_S_COMP</constant> ioctl were renamed to | ||
| 1904 | <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 1905 | <constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument | ||
| 1906 | was replaced by a struct | ||
| 1907 | <structname>v4l2_mpeg_compression</structname> pointer. (The | ||
| 1908 | <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 1909 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux | ||
| 1910 | 2.6.25.)</para> | ||
| 1911 | </listitem> | ||
| 1912 | </orderedlist> | ||
| 1913 | </section> | ||
| 1914 | |||
| 1915 | <section> | ||
| 1916 | <title>V4L2 spec erratum 2005-11-27</title> | ||
| 1917 | <para>The capture example in <xref linkend="capture-example" /> | ||
| 1918 | called the &VIDIOC-S-CROP; ioctl without checking if cropping is | ||
| 1919 | supported. In the video standard selection example in | ||
| 1920 | <xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong | ||
| 1921 | argument type.</para> | ||
| 1922 | </section> | ||
| 1923 | |||
| 1924 | <section> | ||
| 1925 | <title>V4L2 spec erratum 2006-01-10</title> | ||
| 1926 | <orderedlist> | ||
| 1927 | <listitem> | ||
| 1928 | <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in | ||
| 1929 | &v4l2-input; not only indicates if the color killer is enabled, but | ||
| 1930 | also if it is active. (The color killer disables color decoding when | ||
| 1931 | it detects no color in the video signal to improve the image | ||
| 1932 | quality.)</para> | ||
| 1933 | </listitem> | ||
| 1934 | |||
| 1935 | <listitem> | ||
| 1936 | <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as | ||
| 1937 | stated on its reference page. The ioctl changed in 2003 as noted above.</para> | ||
| 1938 | </listitem> | ||
| 1939 | </orderedlist> | ||
| 1940 | </section> | ||
| 1941 | |||
| 1942 | <section> | ||
| 1943 | <title>V4L2 spec erratum 2006-02-03</title> | ||
| 1944 | <orderedlist> | ||
| 1945 | <listitem> | ||
| 1946 | <para>In &v4l2-captureparm; and &v4l2-outputparm; the | ||
| 1947 | <structfield>timeperframe</structfield> field gives the time in | ||
| 1948 | seconds, not microseconds.</para> | ||
| 1949 | </listitem> | ||
| 1950 | </orderedlist> | ||
| 1951 | </section> | ||
| 1952 | |||
| 1953 | <section> | ||
| 1954 | <title>V4L2 spec erratum 2006-02-04</title> | ||
| 1955 | <orderedlist> | ||
| 1956 | <listitem> | ||
| 1957 | <para>The <structfield>clips</structfield> field in | ||
| 1958 | &v4l2-window; must point to an array of &v4l2-clip;, not a linked | ||
| 1959 | list, because drivers ignore the struct | ||
| 1960 | <structname>v4l2_clip</structname>.<structfield>next</structfield> | ||
| 1961 | pointer.</para> | ||
| 1962 | </listitem> | ||
| 1963 | </orderedlist> | ||
| 1964 | </section> | ||
| 1965 | |||
| 1966 | <section> | ||
| 1967 | <title>V4L2 in Linux 2.6.17</title> | ||
| 1968 | <orderedlist> | ||
| 1969 | <listitem> | ||
| 1970 | <para>New video standard macros were added: | ||
| 1971 | <constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the | ||
| 1972 | sets <constant>V4L2_STD_MN</constant>, | ||
| 1973 | <constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and | ||
| 1974 | <constant>V4L2_STD_DK</constant>. The | ||
| 1975 | <constant>V4L2_STD_NTSC</constant> and | ||
| 1976 | <constant>V4L2_STD_SECAM</constant> sets now include | ||
| 1977 | <constant>V4L2_STD_NTSC_M_KR</constant> and | ||
| 1978 | <constant>V4L2_STD_SECAM_LC</constant> respectively.</para> | ||
| 1979 | </listitem> | ||
| 1980 | |||
| 1981 | <listitem> | ||
| 1982 | <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant> | ||
| 1983 | was defined to record both languages of a bilingual program. The | ||
| 1984 | use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose | ||
| 1985 | is deprecated now. See the &VIDIOC-G-TUNER; section for | ||
| 1986 | details.</para> | ||
| 1987 | </listitem> | ||
| 1988 | </orderedlist> | ||
| 1989 | </section> | ||
| 1990 | |||
| 1991 | <section> | ||
| 1992 | <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title> | ||
| 1993 | <orderedlist> | ||
| 1994 | <listitem> | ||
| 1995 | <para>In various places | ||
| 1996 | <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and | ||
| 1997 | <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI | ||
| 1998 | interface were not mentioned along with other buffer types.</para> | ||
| 1999 | </listitem> | ||
| 2000 | |||
| 2001 | <listitem> | ||
| 2002 | <para>In <xref linkend="vidioc-g-audio" /> it was clarified | ||
| 2003 | that the &v4l2-audio; <structfield>mode</structfield> field is a flags | ||
| 2004 | field.</para> | ||
| 2005 | </listitem> | ||
| 2006 | |||
| 2007 | <listitem> | ||
| 2008 | <para><xref linkend="vidioc-querycap" /> did not mention the | ||
| 2009 | sliced VBI and radio capability flags.</para> | ||
| 2010 | </listitem> | ||
| 2011 | |||
| 2012 | <listitem> | ||
| 2013 | <para>In <xref linkend="vidioc-g-frequency" /> it was | ||
| 2014 | clarified that applications must initialize the tuner | ||
| 2015 | <structfield>type</structfield> field of &v4l2-frequency; before | ||
| 2016 | calling &VIDIOC-S-FREQUENCY;.</para> | ||
| 2017 | </listitem> | ||
| 2018 | |||
| 2019 | <listitem> | ||
| 2020 | <para>The <structfield>reserved</structfield> array | ||
| 2021 | in &v4l2-requestbuffers; has 2 elements, not 32.</para> | ||
| 2022 | </listitem> | ||
| 2023 | |||
| 2024 | <listitem> | ||
| 2025 | <para>In <xref linkend="output" /> and <xref | ||
| 2026 | linkend="raw-vbi" /> the device file names | ||
| 2027 | <filename>/dev/vout</filename> which never caught on were replaced | ||
| 2028 | by <filename>/dev/video</filename>.</para> | ||
| 2029 | </listitem> | ||
| 2030 | |||
| 2031 | <listitem> | ||
| 2032 | <para>With Linux 2.6.15 the possible range for VBI device minor | ||
| 2033 | numbers was extended from 224-239 to 224-255. Accordingly device file names | ||
| 2034 | <filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are | ||
| 2035 | possible now.</para> | ||
| 2036 | </listitem> | ||
| 2037 | </orderedlist> | ||
| 2038 | </section> | ||
| 2039 | |||
| 2040 | <section> | ||
| 2041 | <title>V4L2 in Linux 2.6.18</title> | ||
| 2042 | <orderedlist> | ||
| 2043 | <listitem> | ||
| 2044 | <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; | ||
| 2045 | and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported | ||
| 2046 | controls with &VIDIOC-QUERYCTRL;, new control types | ||
| 2047 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and | ||
| 2048 | <constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref | ||
| 2049 | linkend="v4l2-ctrl-type" />), and new control flags | ||
| 2050 | <constant>V4L2_CTRL_FLAG_READ_ONLY</constant>, | ||
| 2051 | <constant>V4L2_CTRL_FLAG_UPDATE</constant>, | ||
| 2052 | <constant>V4L2_CTRL_FLAG_INACTIVE</constant> and | ||
| 2053 | <constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref | ||
| 2054 | linkend="control-flags" />). See <xref | ||
| 2055 | linkend="extended-controls" /> for details.</para> | ||
| 2056 | </listitem> | ||
| 2057 | </orderedlist> | ||
| 2058 | </section> | ||
| 2059 | |||
| 2060 | <section> | ||
| 2061 | <title>V4L2 in Linux 2.6.19</title> | ||
| 2062 | <orderedlist> | ||
| 2063 | <listitem> | ||
| 2064 | <para>In &v4l2-sliced-vbi-cap; a buffer type field was added | ||
| 2065 | replacing a reserved field. Note on architectures where the size of | ||
| 2066 | enum types differs from int types the size of the structure changed. | ||
| 2067 | The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only | ||
| 2068 | to write-read. Applications must initialize the type field and clear | ||
| 2069 | the reserved fields now. These changes may <emphasis>break the | ||
| 2070 | compatibility</emphasis> with older drivers and applications.</para> | ||
| 2071 | </listitem> | ||
| 2072 | |||
| 2073 | <listitem> | ||
| 2074 | <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and | ||
| 2075 | &VIDIOC-ENUM-FRAMEINTERVALS; were added.</para> | ||
| 2076 | </listitem> | ||
| 2077 | |||
| 2078 | <listitem> | ||
| 2079 | <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref | ||
| 2080 | linkend="rgb-formats" />) was added.</para> | ||
| 2081 | </listitem> | ||
| 2082 | </orderedlist> | ||
| 2083 | </section> | ||
| 2084 | |||
| 2085 | <section> | ||
| 2086 | <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title> | ||
| 2087 | <orderedlist> | ||
| 2088 | <listitem> | ||
| 2089 | <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref | ||
| 2090 | linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para> | ||
| 2091 | </listitem> | ||
| 2092 | </orderedlist> | ||
| 2093 | </section> | ||
| 2094 | |||
| 2095 | <section> | ||
| 2096 | <title>V4L2 in Linux 2.6.21</title> | ||
| 2097 | <orderedlist> | ||
| 2098 | <listitem> | ||
| 2099 | <para>The <filename>videodev2.h</filename> header file is | ||
| 2100 | now dual licensed under GNU General Public License version two or | ||
| 2101 | later, and under a 3-clause BSD-style license.</para> | ||
| 2102 | </listitem> | ||
| 2103 | </orderedlist> | ||
| 2104 | </section> | ||
| 2105 | |||
| 2106 | <section> | ||
| 2107 | <title>V4L2 in Linux 2.6.22</title> | ||
| 2108 | <orderedlist> | ||
| 2109 | <listitem> | ||
| 2110 | <para>Two new field orders | ||
| 2111 | <constant>V4L2_FIELD_INTERLACED_TB</constant> and | ||
| 2112 | <constant>V4L2_FIELD_INTERLACED_BT</constant> were | ||
| 2113 | added. See <xref linkend="v4l2-field" /> for details.</para> | ||
| 2114 | </listitem> | ||
| 2115 | |||
| 2116 | <listitem> | ||
| 2117 | <para>Three new clipping/blending methods with a global or | ||
| 2118 | straight or inverted local alpha value were added to the video overlay | ||
| 2119 | interface. See the description of the &VIDIOC-G-FBUF; and | ||
| 2120 | &VIDIOC-S-FBUF; ioctls for details.</para> | ||
| 2121 | <para>A new <structfield>global_alpha</structfield> field | ||
| 2122 | was added to <link | ||
| 2123 | linkend="v4l2-window"><structname>v4l2_window</structname></link>, | ||
| 2124 | extending the structure. This may <emphasis>break | ||
| 2125 | compatibility</emphasis> with applications using a struct | ||
| 2126 | <structname>v4l2_window</structname> directly. However the <link | ||
| 2127 | linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a | ||
| 2128 | pointer to a <link linkend="v4l2-format">v4l2_format</link> parent | ||
| 2129 | structure with padding bytes at the end, are not affected.</para> | ||
| 2130 | </listitem> | ||
| 2131 | |||
| 2132 | <listitem> | ||
| 2133 | <para>The format of the <structfield>chromakey</structfield> | ||
| 2134 | field in &v4l2-window; changed from "host order RGB32" to a pixel | ||
| 2135 | value in the same format as the framebuffer. This may <emphasis>break | ||
| 2136 | compatibility</emphasis> with existing applications. Drivers | ||
| 2137 | supporting the "host order RGB32" format are not known.</para> | ||
| 2138 | </listitem> | ||
| 2139 | |||
| 2140 | </orderedlist> | ||
| 2141 | </section> | ||
| 2142 | |||
| 2143 | <section> | ||
| 2144 | <title>V4L2 in Linux 2.6.24</title> | ||
| 2145 | <orderedlist> | ||
| 2146 | <listitem> | ||
| 2147 | <para>The pixel formats | ||
| 2148 | <constant>V4L2_PIX_FMT_PAL8</constant>, | ||
| 2149 | <constant>V4L2_PIX_FMT_YUV444</constant>, | ||
| 2150 | <constant>V4L2_PIX_FMT_YUV555</constant>, | ||
| 2151 | <constant>V4L2_PIX_FMT_YUV565</constant> and | ||
| 2152 | <constant>V4L2_PIX_FMT_YUV32</constant> were added.</para> | ||
| 2153 | </listitem> | ||
| 2154 | </orderedlist> | ||
| 2155 | </section> | ||
| 2156 | |||
| 2157 | <section> | ||
| 2158 | <title>V4L2 in Linux 2.6.25</title> | ||
| 2159 | <orderedlist> | ||
| 2160 | <listitem> | ||
| 2161 | <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16"> | ||
| 2162 | <constant>V4L2_PIX_FMT_Y16</constant></link> and <link | ||
| 2163 | linkend="V4L2-PIX-FMT-SBGGR16"> | ||
| 2164 | <constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para> | ||
| 2165 | </listitem> | ||
| 2166 | <listitem> | ||
| 2167 | <para>New <link linkend="control">controls</link> | ||
| 2168 | <constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>, | ||
| 2169 | <constant>V4L2_CID_HUE_AUTO</constant>, | ||
| 2170 | <constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>, | ||
| 2171 | <constant>V4L2_CID_SHARPNESS</constant> and | ||
| 2172 | <constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The | ||
| 2173 | controls <constant>V4L2_CID_BLACK_LEVEL</constant>, | ||
| 2174 | <constant>V4L2_CID_WHITENESS</constant>, | ||
| 2175 | <constant>V4L2_CID_HCENTER</constant> and | ||
| 2176 | <constant>V4L2_CID_VCENTER</constant> were deprecated. | ||
| 2177 | </para> | ||
| 2178 | </listitem> | ||
| 2179 | <listitem> | ||
| 2180 | <para>A <link linkend="camera-controls">Camera controls | ||
| 2181 | class</link> was added, with the new controls | ||
| 2182 | <constant>V4L2_CID_EXPOSURE_AUTO</constant>, | ||
| 2183 | <constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>, | ||
| 2184 | <constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>, | ||
| 2185 | <constant>V4L2_CID_PAN_RELATIVE</constant>, | ||
| 2186 | <constant>V4L2_CID_TILT_RELATIVE</constant>, | ||
| 2187 | <constant>V4L2_CID_PAN_RESET</constant>, | ||
| 2188 | <constant>V4L2_CID_TILT_RESET</constant>, | ||
| 2189 | <constant>V4L2_CID_PAN_ABSOLUTE</constant>, | ||
| 2190 | <constant>V4L2_CID_TILT_ABSOLUTE</constant>, | ||
| 2191 | <constant>V4L2_CID_FOCUS_ABSOLUTE</constant>, | ||
| 2192 | <constant>V4L2_CID_FOCUS_RELATIVE</constant> and | ||
| 2193 | <constant>V4L2_CID_FOCUS_AUTO</constant>.</para> | ||
| 2194 | </listitem> | ||
| 2195 | <listitem> | ||
| 2196 | <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 2197 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded | ||
| 2198 | by the <link linkend="extended-controls">extended controls</link> | ||
| 2199 | interface in Linux 2.6.18, where finally removed from the | ||
| 2200 | <filename>videodev2.h</filename> header file.</para> | ||
| 2201 | </listitem> | ||
| 2202 | </orderedlist> | ||
| 2203 | </section> | ||
| 2204 | |||
| 2205 | <section> | ||
| 2206 | <title>V4L2 in Linux 2.6.26</title> | ||
| 2207 | <orderedlist> | ||
| 2208 | <listitem> | ||
| 2209 | <para>The pixel formats | ||
| 2210 | <constant>V4L2_PIX_FMT_Y16</constant> and | ||
| 2211 | <constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para> | ||
| 2212 | </listitem> | ||
| 2213 | <listitem> | ||
| 2214 | <para>Added user controls | ||
| 2215 | <constant>V4L2_CID_CHROMA_AGC</constant> and | ||
| 2216 | <constant>V4L2_CID_COLOR_KILLER</constant>.</para> | ||
| 2217 | </listitem> | ||
| 2218 | </orderedlist> | ||
| 2219 | </section> | ||
| 2220 | |||
| 2221 | <section> | ||
| 2222 | <title>V4L2 in Linux 2.6.27</title> | ||
| 2223 | <orderedlist> | ||
| 2224 | <listitem> | ||
| 2225 | <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the | ||
| 2226 | <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para> | ||
| 2227 | </listitem> | ||
| 2228 | <listitem> | ||
| 2229 | <para>The pixel formats | ||
| 2230 | <constant>V4L2_PIX_FMT_YVYU</constant>, | ||
| 2231 | <constant>V4L2_PIX_FMT_PCA501</constant>, | ||
| 2232 | <constant>V4L2_PIX_FMT_PCA505</constant>, | ||
| 2233 | <constant>V4L2_PIX_FMT_PCA508</constant>, | ||
| 2234 | <constant>V4L2_PIX_FMT_PCA561</constant>, | ||
| 2235 | <constant>V4L2_PIX_FMT_SGBRG8</constant>, | ||
| 2236 | <constant>V4L2_PIX_FMT_PAC207</constant> and | ||
| 2237 | <constant>V4L2_PIX_FMT_PJPG</constant> were added.</para> | ||
| 2238 | </listitem> | ||
| 2239 | </orderedlist> | ||
| 2240 | </section> | ||
| 2241 | |||
| 2242 | <section> | ||
| 2243 | <title>V4L2 in Linux 2.6.28</title> | ||
| 2244 | <orderedlist> | ||
| 2245 | <listitem> | ||
| 2246 | <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and | ||
| 2247 | <constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para> | ||
| 2248 | </listitem> | ||
| 2249 | <listitem> | ||
| 2250 | <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG | ||
| 2251 | video encoding.</para> | ||
| 2252 | </listitem> | ||
| 2253 | <listitem> | ||
| 2254 | <para>The pixel formats | ||
| 2255 | <constant>V4L2_PIX_FMT_SGRBG10</constant> and | ||
| 2256 | <constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para> | ||
| 2257 | </listitem> | ||
| 2258 | </orderedlist> | ||
| 2259 | </section> | ||
| 2260 | |||
| 2261 | <section> | ||
| 2262 | <title>V4L2 in Linux 2.6.29</title> | ||
| 2263 | <orderedlist> | ||
| 2264 | <listitem> | ||
| 2265 | <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed | ||
| 2266 | to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT; | ||
| 2267 | was introduced in its place. The old struct <structname>v4l2_chip_ident</structname> | ||
| 2268 | was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para> | ||
| 2269 | </listitem> | ||
| 2270 | <listitem> | ||
| 2271 | <para>The pixel formats | ||
| 2272 | <constant>V4L2_PIX_FMT_VYUY</constant>, | ||
| 2273 | <constant>V4L2_PIX_FMT_NV16</constant> and | ||
| 2274 | <constant>V4L2_PIX_FMT_NV61</constant> were added.</para> | ||
| 2275 | </listitem> | ||
| 2276 | <listitem> | ||
| 2277 | <para>Added camera controls | ||
| 2278 | <constant>V4L2_CID_ZOOM_ABSOLUTE</constant>, | ||
| 2279 | <constant>V4L2_CID_ZOOM_RELATIVE</constant>, | ||
| 2280 | <constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and | ||
| 2281 | <constant>V4L2_CID_PRIVACY</constant>.</para> | ||
| 2282 | </listitem> | ||
| 2283 | </orderedlist> | ||
| 2284 | </section> | ||
| 2285 | <section> | ||
| 2286 | <title>V4L2 in Linux 2.6.30</title> | ||
| 2287 | <orderedlist> | ||
| 2288 | <listitem> | ||
| 2289 | <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para> | ||
| 2290 | </listitem> | ||
| 2291 | <listitem> | ||
| 2292 | <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para> | ||
| 2293 | </listitem> | ||
| 2294 | </orderedlist> | ||
| 2295 | </section> | ||
| 2296 | <section> | ||
| 2297 | <title>V4L2 in Linux 2.6.32</title> | ||
| 2298 | <orderedlist> | ||
| 2299 | <listitem> | ||
| 2300 | <para>In order to be easier to compare a V4L2 API and a kernel | ||
| 2301 | version, now V4L2 API is numbered using the Linux Kernel version numeration.</para> | ||
| 2302 | </listitem> | ||
| 2303 | <listitem> | ||
| 2304 | <para>Finalized the RDS capture API. See <xref linkend="rds" /> for | ||
| 2305 | more information.</para> | ||
| 2306 | </listitem> | ||
| 2307 | <listitem> | ||
| 2308 | <para>Added new capabilities for modulators and RDS encoders.</para> | ||
| 2309 | </listitem> | ||
| 2310 | <listitem> | ||
| 2311 | <para>Add description for libv4l API.</para> | ||
| 2312 | </listitem> | ||
| 2313 | <listitem> | ||
| 2314 | <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para> | ||
| 2315 | </listitem> | ||
| 2316 | <listitem> | ||
| 2317 | <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para> | ||
| 2318 | </listitem> | ||
| 2319 | <listitem> | ||
| 2320 | <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para> | ||
| 2321 | </listitem> | ||
| 2322 | <listitem> | ||
| 2323 | <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para> | ||
| 2324 | </listitem> | ||
| 2325 | </orderedlist> | ||
| 2326 | </section> | ||
| 2327 | </section> | ||
| 2328 | |||
| 2329 | <section id="other"> | ||
| 2330 | <title>Relation of V4L2 to other Linux multimedia APIs</title> | ||
| 2331 | |||
| 2332 | <section id="xvideo"> | ||
| 2333 | <title>X Video Extension</title> | ||
| 2334 | |||
| 2335 | <para>The X Video Extension (abbreviated XVideo or just Xv) is | ||
| 2336 | an extension of the X Window system, implemented for example by the | ||
| 2337 | XFree86 project. Its scope is similar to V4L2, an API to video capture | ||
| 2338 | and output devices for X clients. Xv allows applications to display | ||
| 2339 | live video in a window, send window contents to a TV output, and | ||
| 2340 | capture or output still images in XPixmaps<footnote> | ||
| 2341 | <para>This is not implemented in XFree86.</para> | ||
| 2342 | </footnote>. With their implementation XFree86 makes the | ||
| 2343 | extension available across many operating systems and | ||
| 2344 | architectures.</para> | ||
| 2345 | |||
| 2346 | <para>Because the driver is embedded into the X server Xv has a | ||
| 2347 | number of advantages over the V4L2 <link linkend="overlay">video | ||
| 2348 | overlay interface</link>. The driver can easily determine the overlay | ||
| 2349 | target, &ie; visible graphics memory or off-screen buffers for a | ||
| 2350 | destructive overlay. It can program the RAMDAC for a non-destructive | ||
| 2351 | overlay, scaling or color-keying, or the clipping functions of the | ||
| 2352 | video capture hardware, always in sync with drawing operations or | ||
| 2353 | windows moving or changing their stacking order.</para> | ||
| 2354 | |||
| 2355 | <para>To combine the advantages of Xv and V4L a special Xv | ||
| 2356 | driver exists in XFree86 and XOrg, just programming any overlay capable | ||
| 2357 | Video4Linux device it finds. To enable it | ||
| 2358 | <filename>/etc/X11/XF86Config</filename> must contain these lines:</para> | ||
| 2359 | <para><screen> | ||
| 2360 | Section "Module" | ||
| 2361 | Load "v4l" | ||
| 2362 | EndSection</screen></para> | ||
| 2363 | |||
| 2364 | <para>As of XFree86 4.2 this driver still supports only V4L | ||
| 2365 | ioctls, however it should work just fine with all V4L2 devices through | ||
| 2366 | the V4L2 backward-compatibility layer. Since V4L2 permits multiple | ||
| 2367 | opens it is possible (if supported by the V4L2 driver) to capture | ||
| 2368 | video while an X client requested video overlay. Restrictions of | ||
| 2369 | simultaneous capturing and overlay are discussed in <xref | ||
| 2370 | linkend="overlay" /> apply.</para> | ||
| 2371 | |||
| 2372 | <para>Only marginally related to V4L2, XFree86 extended Xv to | ||
| 2373 | support hardware YUV to RGB conversion and scaling for faster video | ||
| 2374 | playback, and added an interface to MPEG-2 decoding hardware. This API | ||
| 2375 | is useful to display images captured with V4L2 devices.</para> | ||
| 2376 | </section> | ||
| 2377 | |||
| 2378 | <section> | ||
| 2379 | <title>Digital Video</title> | ||
| 2380 | |||
| 2381 | <para>V4L2 does not support digital terrestrial, cable or | ||
| 2382 | satellite broadcast. A separate project aiming at digital receivers | ||
| 2383 | exists. You can find its homepage at <ulink | ||
| 2384 | url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API | ||
| 2385 | has no connection to the V4L2 API except that drivers for hybrid | ||
| 2386 | hardware may support both.</para> | ||
| 2387 | </section> | ||
| 2388 | |||
| 2389 | <section> | ||
| 2390 | <title>Audio Interfaces</title> | ||
| 2391 | |||
| 2392 | <para>[to do - OSS/ALSA]</para> | ||
| 2393 | </section> | ||
| 2394 | </section> | ||
| 2395 | |||
| 2396 | <section id="experimental"> | ||
| 2397 | <title>Experimental API Elements</title> | ||
| 2398 | |||
| 2399 | <para>The following V4L2 API elements are currently experimental | ||
| 2400 | and may change in the future.</para> | ||
| 2401 | |||
| 2402 | <itemizedlist> | ||
| 2403 | <listitem> | ||
| 2404 | <para>Video Output Overlay (OSD) Interface, <xref | ||
| 2405 | linkend="osd" />.</para> | ||
| 2406 | </listitem> | ||
| 2407 | <listitem> | ||
| 2408 | <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, | ||
| 2409 | &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para> | ||
| 2410 | </listitem> | ||
| 2411 | <listitem> | ||
| 2412 | <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, | ||
| 2413 | &VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> | ||
| 2414 | </listitem> | ||
| 2415 | <listitem> | ||
| 2416 | <para>&VIDIOC-ENUM-FRAMESIZES; and | ||
| 2417 | &VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para> | ||
| 2418 | </listitem> | ||
| 2419 | <listitem> | ||
| 2420 | <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> | ||
| 2421 | </listitem> | ||
| 2422 | <listitem> | ||
| 2423 | <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; | ||
| 2424 | ioctls.</para> | ||
| 2425 | </listitem> | ||
| 2426 | <listitem> | ||
| 2427 | <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; | ||
| 2428 | ioctls.</para> | ||
| 2429 | </listitem> | ||
| 2430 | <listitem> | ||
| 2431 | <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> | ||
| 2432 | </listitem> | ||
| 2433 | </itemizedlist> | ||
| 2434 | </section> | ||
| 2435 | |||
| 2436 | <section id="obsolete"> | ||
| 2437 | <title>Obsolete API Elements</title> | ||
| 2438 | |||
| 2439 | <para>The following V4L2 API elements were superseded by new | ||
| 2440 | interfaces and should not be implemented in new drivers.</para> | ||
| 2441 | |||
| 2442 | <itemizedlist> | ||
| 2443 | <listitem> | ||
| 2444 | <para><constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 2445 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, | ||
| 2446 | <xref linkend="extended-controls" />.</para> | ||
| 2447 | </listitem> | ||
| 2448 | </itemizedlist> | ||
| 2449 | </section> | ||
| 2450 | |||
| 2451 | <!-- | ||
| 2452 | Local Variables: | ||
| 2453 | mode: sgml | ||
| 2454 | sgml-parent-document: "v4l2.sgml" | ||
| 2455 | indent-tabs-mode: nil | ||
| 2456 | End: | ||
| 2457 | --> | ||
diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml new file mode 100644 index 000000000000..f492accb691d --- /dev/null +++ b/Documentation/DocBook/v4l/controls.xml | |||
| @@ -0,0 +1,2049 @@ | |||
| 1 | <section id="control"> | ||
| 2 | <title>User Controls</title> | ||
| 3 | |||
| 4 | <para>Devices typically have a number of user-settable controls | ||
| 5 | such as brightness, saturation and so on, which would be presented to | ||
| 6 | the user on a graphical user interface. But, different devices | ||
| 7 | will have different controls available, and furthermore, the range of | ||
| 8 | possible values, and the default value will vary from device to | ||
| 9 | device. The control ioctls provide the information and a mechanism to | ||
| 10 | create a nice user interface for these controls that will work | ||
| 11 | correctly with any device.</para> | ||
| 12 | |||
| 13 | <para>All controls are accessed using an ID value. V4L2 defines | ||
| 14 | several IDs for specific purposes. Drivers can also implement their | ||
| 15 | own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant> | ||
| 16 | and higher values. The pre-defined control IDs have the prefix | ||
| 17 | <constant>V4L2_CID_</constant>, and are listed in <xref | ||
| 18 | linkend="control-id" />. The ID is used when querying the attributes of | ||
| 19 | a control, and when getting or setting the current value.</para> | ||
| 20 | |||
| 21 | <para>Generally applications should present controls to the user | ||
| 22 | without assumptions about their purpose. Each control comes with a | ||
| 23 | name string the user is supposed to understand. When the purpose is | ||
| 24 | non-intuitive the driver writer should provide a user manual, a user | ||
| 25 | interface plug-in or a driver specific panel application. Predefined | ||
| 26 | IDs were introduced to change a few controls programmatically, for | ||
| 27 | example to mute a device during a channel switch.</para> | ||
| 28 | |||
| 29 | <para>Drivers may enumerate different controls after switching | ||
| 30 | the current video input or output, tuner or modulator, or audio input | ||
| 31 | or output. Different in the sense of other bounds, another default and | ||
| 32 | current value, step size or other menu items. A control with a certain | ||
| 33 | <emphasis>custom</emphasis> ID can also change name and | ||
| 34 | type.<footnote> | ||
| 35 | <para>It will be more convenient for applications if drivers | ||
| 36 | make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but | ||
| 37 | that was never required.</para> | ||
| 38 | </footnote> Control values are stored globally, they do not | ||
| 39 | change when switching except to stay within the reported bounds. They | ||
| 40 | also do not change ⪚ when the device is opened or closed, when the | ||
| 41 | tuner radio frequency is changed or generally never without | ||
| 42 | application request. Since V4L2 specifies no event mechanism, panel | ||
| 43 | applications intended to cooperate with other panel applications (be | ||
| 44 | they built into a larger application, as a TV viewer) may need to | ||
| 45 | regularly poll control values to update their user | ||
| 46 | interface.<footnote> | ||
| 47 | <para>Applications could call an ioctl to request events. | ||
| 48 | After another process called &VIDIOC-S-CTRL; or another ioctl changing | ||
| 49 | shared properties the &func-select; function would indicate | ||
| 50 | readability until any ioctl (querying the properties) is | ||
| 51 | called.</para> | ||
| 52 | </footnote></para> | ||
| 53 | |||
| 54 | <table pgwide="1" frame="none" id="control-id"> | ||
| 55 | <title>Control IDs</title> | ||
| 56 | <tgroup cols="3"> | ||
| 57 | &cs-def; | ||
| 58 | <thead> | ||
| 59 | <row> | ||
| 60 | <entry>ID</entry> | ||
| 61 | <entry>Type</entry> | ||
| 62 | <entry>Description</entry> | ||
| 63 | </row> | ||
| 64 | </thead> | ||
| 65 | <tbody valign="top"> | ||
| 66 | <row> | ||
| 67 | <entry><constant>V4L2_CID_BASE</constant></entry> | ||
| 68 | <entry></entry> | ||
| 69 | <entry>First predefined ID, equal to | ||
| 70 | <constant>V4L2_CID_BRIGHTNESS</constant>.</entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry><constant>V4L2_CID_USER_BASE</constant></entry> | ||
| 74 | <entry></entry> | ||
| 75 | <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> | ||
| 79 | <entry>integer</entry> | ||
| 80 | <entry>Picture brightness, or more precisely, the black | ||
| 81 | level.</entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry><constant>V4L2_CID_CONTRAST</constant></entry> | ||
| 85 | <entry>integer</entry> | ||
| 86 | <entry>Picture contrast or luma gain.</entry> | ||
| 87 | </row> | ||
| 88 | <row> | ||
| 89 | <entry><constant>V4L2_CID_SATURATION</constant></entry> | ||
| 90 | <entry>integer</entry> | ||
| 91 | <entry>Picture color saturation or chroma gain.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry><constant>V4L2_CID_HUE</constant></entry> | ||
| 95 | <entry>integer</entry> | ||
| 96 | <entry>Hue or color balance.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> | ||
| 100 | <entry>integer</entry> | ||
| 101 | <entry>Overall audio volume. Note some drivers also | ||
| 102 | provide an OSS or ALSA mixer interface.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> | ||
| 106 | <entry>integer</entry> | ||
| 107 | <entry>Audio stereo balance. Minimum corresponds to all | ||
| 108 | the way left, maximum to right.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> | ||
| 112 | <entry>integer</entry> | ||
| 113 | <entry>Audio bass adjustment.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> | ||
| 117 | <entry>integer</entry> | ||
| 118 | <entry>Audio treble adjustment.</entry> | ||
| 119 | </row> | ||
| 120 | <row> | ||
| 121 | <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry> | ||
| 122 | <entry>boolean</entry> | ||
| 123 | <entry>Mute audio, &ie; set the volume to zero, however | ||
| 124 | without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like | ||
| 125 | ALSA drivers, V4L2 drivers must mute at load time to avoid excessive | ||
| 126 | noise. Actually the entire device should be reset to a low power | ||
| 127 | consumption state.</entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry> | ||
| 131 | <entry>boolean</entry> | ||
| 132 | <entry>Loudness mode (bass boost).</entry> | ||
| 133 | </row> | ||
| 134 | <row> | ||
| 135 | <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry> | ||
| 136 | <entry>integer</entry> | ||
| 137 | <entry>Another name for brightness (not a synonym of | ||
| 138 | <constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated | ||
| 139 | and should not be used in new drivers and applications.</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry> | ||
| 143 | <entry>boolean</entry> | ||
| 144 | <entry>Automatic white balance (cameras).</entry> | ||
| 145 | </row> | ||
| 146 | <row> | ||
| 147 | <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry> | ||
| 148 | <entry>button</entry> | ||
| 149 | <entry>This is an action control. When set (the value is | ||
| 150 | ignored), the device will do a white balance and then hold the current | ||
| 151 | setting. Contrast this with the boolean | ||
| 152 | <constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when | ||
| 153 | activated, keeps adjusting the white balance.</entry> | ||
| 154 | </row> | ||
| 155 | <row> | ||
| 156 | <entry><constant>V4L2_CID_RED_BALANCE</constant></entry> | ||
| 157 | <entry>integer</entry> | ||
| 158 | <entry>Red chroma balance.</entry> | ||
| 159 | </row> | ||
| 160 | <row> | ||
| 161 | <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry> | ||
| 162 | <entry>integer</entry> | ||
| 163 | <entry>Blue chroma balance.</entry> | ||
| 164 | </row> | ||
| 165 | <row> | ||
| 166 | <entry><constant>V4L2_CID_GAMMA</constant></entry> | ||
| 167 | <entry>integer</entry> | ||
| 168 | <entry>Gamma adjust.</entry> | ||
| 169 | </row> | ||
| 170 | <row> | ||
| 171 | <entry><constant>V4L2_CID_WHITENESS</constant></entry> | ||
| 172 | <entry>integer</entry> | ||
| 173 | <entry>Whiteness for grey-scale devices. This is a synonym | ||
| 174 | for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated | ||
| 175 | and should not be used in new drivers and applications.</entry> | ||
| 176 | </row> | ||
| 177 | <row> | ||
| 178 | <entry><constant>V4L2_CID_EXPOSURE</constant></entry> | ||
| 179 | <entry>integer</entry> | ||
| 180 | <entry>Exposure (cameras). [Unit?]</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry><constant>V4L2_CID_AUTOGAIN</constant></entry> | ||
| 184 | <entry>boolean</entry> | ||
| 185 | <entry>Automatic gain/exposure control.</entry> | ||
| 186 | </row> | ||
| 187 | <row> | ||
| 188 | <entry><constant>V4L2_CID_GAIN</constant></entry> | ||
| 189 | <entry>integer</entry> | ||
| 190 | <entry>Gain control.</entry> | ||
| 191 | </row> | ||
| 192 | <row> | ||
| 193 | <entry><constant>V4L2_CID_HFLIP</constant></entry> | ||
| 194 | <entry>boolean</entry> | ||
| 195 | <entry>Mirror the picture horizontally.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry><constant>V4L2_CID_VFLIP</constant></entry> | ||
| 199 | <entry>boolean</entry> | ||
| 200 | <entry>Mirror the picture vertically.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry> | ||
| 204 | <entry>integer</entry> | ||
| 205 | <entry>Horizontal image centering. This control is | ||
| 206 | deprecated. New drivers and applications should use the <link | ||
| 207 | linkend="camera-controls">Camera class controls</link> | ||
| 208 | <constant>V4L2_CID_PAN_ABSOLUTE</constant>, | ||
| 209 | <constant>V4L2_CID_PAN_RELATIVE</constant> and | ||
| 210 | <constant>V4L2_CID_PAN_RESET</constant> instead.</entry> | ||
| 211 | </row> | ||
| 212 | <row> | ||
| 213 | <entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant> | ||
| 214 | (formerly <constant>V4L2_CID_VCENTER</constant>)</entry> | ||
| 215 | <entry>integer</entry> | ||
| 216 | <entry>Vertical image centering. Centering is intended to | ||
| 217 | <emphasis>physically</emphasis> adjust cameras. For image cropping see | ||
| 218 | <xref linkend="crop" />, for clipping <xref linkend="overlay" />. This | ||
| 219 | control is deprecated. New drivers and applications should use the | ||
| 220 | <link linkend="camera-controls">Camera class controls</link> | ||
| 221 | <constant>V4L2_CID_TILT_ABSOLUTE</constant>, | ||
| 222 | <constant>V4L2_CID_TILT_RELATIVE</constant> and | ||
| 223 | <constant>V4L2_CID_TILT_RESET</constant> instead.</entry> | ||
| 224 | </row> | ||
| 225 | <row id="v4l2-power-line-frequency"> | ||
| 226 | <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry> | ||
| 227 | <entry>enum</entry> | ||
| 228 | <entry>Enables a power line frequency filter to avoid | ||
| 229 | flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are: | ||
| 230 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0), | ||
| 231 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1) and | ||
| 232 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2).</entry> | ||
| 233 | </row> | ||
| 234 | <row> | ||
| 235 | <entry><constant>V4L2_CID_HUE_AUTO</constant></entry> | ||
| 236 | <entry>boolean</entry> | ||
| 237 | <entry>Enables automatic hue control by the device. The | ||
| 238 | effect of setting <constant>V4L2_CID_HUE</constant> while automatic | ||
| 239 | hue control is enabled is undefined, drivers should ignore such | ||
| 240 | request.</entry> | ||
| 241 | </row> | ||
| 242 | <row> | ||
| 243 | <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry> | ||
| 244 | <entry>integer</entry> | ||
| 245 | <entry>This control specifies the white balance settings | ||
| 246 | as a color temperature in Kelvin. A driver should have a minimum of | ||
| 247 | 2800 (incandescent) to 6500 (daylight). For more information about | ||
| 248 | color temperature see <ulink | ||
| 249 | url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_CID_SHARPNESS</constant></entry> | ||
| 253 | <entry>integer</entry> | ||
| 254 | <entry>Adjusts the sharpness filters in a camera. The | ||
| 255 | minimum value disables the filters, higher values give a sharper | ||
| 256 | picture.</entry> | ||
| 257 | </row> | ||
| 258 | <row> | ||
| 259 | <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry> | ||
| 260 | <entry>integer</entry> | ||
| 261 | <entry>Adjusts the backlight compensation in a camera. The | ||
| 262 | minimum value disables backlight compensation.</entry> | ||
| 263 | </row> | ||
| 264 | <row> | ||
| 265 | <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry> | ||
| 266 | <entry>boolean</entry> | ||
| 267 | <entry>Chroma automatic gain control.</entry> | ||
| 268 | </row> | ||
| 269 | <row> | ||
| 270 | <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry> | ||
| 271 | <entry>boolean</entry> | ||
| 272 | <entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry> | ||
| 273 | </row> | ||
| 274 | <row id="v4l2-colorfx"> | ||
| 275 | <entry><constant>V4L2_CID_COLORFX</constant></entry> | ||
| 276 | <entry>enum</entry> | ||
| 277 | <entry>Selects a color effect. Possible values for | ||
| 278 | <constant>enum v4l2_colorfx</constant> are: | ||
| 279 | <constant>V4L2_COLORFX_NONE</constant> (0), | ||
| 280 | <constant>V4L2_COLORFX_BW</constant> (1) and | ||
| 281 | <constant>V4L2_COLORFX_SEPIA</constant> (2).</entry> | ||
| 282 | </row> | ||
| 283 | <row> | ||
| 284 | <entry><constant>V4L2_CID_LASTP1</constant></entry> | ||
| 285 | <entry></entry> | ||
| 286 | <entry>End of the predefined control IDs (currently | ||
| 287 | <constant>V4L2_CID_COLORFX</constant> + 1).</entry> | ||
| 288 | </row> | ||
| 289 | <row> | ||
| 290 | <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> | ||
| 291 | <entry></entry> | ||
| 292 | <entry>ID of the first custom (driver specific) control. | ||
| 293 | Applications depending on particular custom controls should check the | ||
| 294 | driver name and version, see <xref linkend="querycap" />.</entry> | ||
| 295 | </row> | ||
| 296 | </tbody> | ||
| 297 | </tgroup> | ||
| 298 | </table> | ||
| 299 | |||
| 300 | <para>Applications can enumerate the available controls with the | ||
| 301 | &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a | ||
| 302 | control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls. | ||
| 303 | Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>, | ||
| 304 | <constant>VIDIOC_G_CTRL</constant> and | ||
| 305 | <constant>VIDIOC_S_CTRL</constant> when the device has one or more | ||
| 306 | controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or | ||
| 307 | more menu type controls.</para> | ||
| 308 | |||
| 309 | <example> | ||
| 310 | <title>Enumerating all controls</title> | ||
| 311 | |||
| 312 | <programlisting> | ||
| 313 | &v4l2-queryctrl; queryctrl; | ||
| 314 | &v4l2-querymenu; querymenu; | ||
| 315 | |||
| 316 | static void | ||
| 317 | enumerate_menu (void) | ||
| 318 | { | ||
| 319 | printf (" Menu items:\n"); | ||
| 320 | |||
| 321 | memset (&querymenu, 0, sizeof (querymenu)); | ||
| 322 | querymenu.id = queryctrl.id; | ||
| 323 | |||
| 324 | for (querymenu.index = queryctrl.minimum; | ||
| 325 | querymenu.index <= queryctrl.maximum; | ||
| 326 | querymenu.index++) { | ||
| 327 | if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) { | ||
| 328 | printf (" %s\n", querymenu.name); | ||
| 329 | } else { | ||
| 330 | perror ("VIDIOC_QUERYMENU"); | ||
| 331 | exit (EXIT_FAILURE); | ||
| 332 | } | ||
| 333 | } | ||
| 334 | } | ||
| 335 | |||
| 336 | memset (&queryctrl, 0, sizeof (queryctrl)); | ||
| 337 | |||
| 338 | for (queryctrl.id = V4L2_CID_BASE; | ||
| 339 | queryctrl.id < V4L2_CID_LASTP1; | ||
| 340 | queryctrl.id++) { | ||
| 341 | if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 342 | if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) | ||
| 343 | continue; | ||
| 344 | |||
| 345 | printf ("Control %s\n", queryctrl.name); | ||
| 346 | |||
| 347 | if (queryctrl.type == V4L2_CTRL_TYPE_MENU) | ||
| 348 | enumerate_menu (); | ||
| 349 | } else { | ||
| 350 | if (errno == EINVAL) | ||
| 351 | continue; | ||
| 352 | |||
| 353 | perror ("VIDIOC_QUERYCTRL"); | ||
| 354 | exit (EXIT_FAILURE); | ||
| 355 | } | ||
| 356 | } | ||
| 357 | |||
| 358 | for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; | ||
| 359 | queryctrl.id++) { | ||
| 360 | if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 361 | if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) | ||
| 362 | continue; | ||
| 363 | |||
| 364 | printf ("Control %s\n", queryctrl.name); | ||
| 365 | |||
| 366 | if (queryctrl.type == V4L2_CTRL_TYPE_MENU) | ||
| 367 | enumerate_menu (); | ||
| 368 | } else { | ||
| 369 | if (errno == EINVAL) | ||
| 370 | break; | ||
| 371 | |||
| 372 | perror ("VIDIOC_QUERYCTRL"); | ||
| 373 | exit (EXIT_FAILURE); | ||
| 374 | } | ||
| 375 | } | ||
| 376 | </programlisting> | ||
| 377 | </example> | ||
| 378 | |||
| 379 | <example> | ||
| 380 | <title>Changing controls</title> | ||
| 381 | |||
| 382 | <programlisting> | ||
| 383 | &v4l2-queryctrl; queryctrl; | ||
| 384 | &v4l2-control; control; | ||
| 385 | |||
| 386 | memset (&queryctrl, 0, sizeof (queryctrl)); | ||
| 387 | queryctrl.id = V4L2_CID_BRIGHTNESS; | ||
| 388 | |||
| 389 | if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 390 | if (errno != EINVAL) { | ||
| 391 | perror ("VIDIOC_QUERYCTRL"); | ||
| 392 | exit (EXIT_FAILURE); | ||
| 393 | } else { | ||
| 394 | printf ("V4L2_CID_BRIGHTNESS is not supported\n"); | ||
| 395 | } | ||
| 396 | } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { | ||
| 397 | printf ("V4L2_CID_BRIGHTNESS is not supported\n"); | ||
| 398 | } else { | ||
| 399 | memset (&control, 0, sizeof (control)); | ||
| 400 | control.id = V4L2_CID_BRIGHTNESS; | ||
| 401 | control.value = queryctrl.default_value; | ||
| 402 | |||
| 403 | if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) { | ||
| 404 | perror ("VIDIOC_S_CTRL"); | ||
| 405 | exit (EXIT_FAILURE); | ||
| 406 | } | ||
| 407 | } | ||
| 408 | |||
| 409 | memset (&control, 0, sizeof (control)); | ||
| 410 | control.id = V4L2_CID_CONTRAST; | ||
| 411 | |||
| 412 | if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) { | ||
| 413 | control.value += 1; | ||
| 414 | |||
| 415 | /* The driver may clamp the value or return ERANGE, ignored here */ | ||
| 416 | |||
| 417 | if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control) | ||
| 418 | && errno != ERANGE) { | ||
| 419 | perror ("VIDIOC_S_CTRL"); | ||
| 420 | exit (EXIT_FAILURE); | ||
| 421 | } | ||
| 422 | /* Ignore if V4L2_CID_CONTRAST is unsupported */ | ||
| 423 | } else if (errno != EINVAL) { | ||
| 424 | perror ("VIDIOC_G_CTRL"); | ||
| 425 | exit (EXIT_FAILURE); | ||
| 426 | } | ||
| 427 | |||
| 428 | control.id = V4L2_CID_AUDIO_MUTE; | ||
| 429 | control.value = TRUE; /* silence */ | ||
| 430 | |||
| 431 | /* Errors ignored */ | ||
| 432 | ioctl (fd, VIDIOC_S_CTRL, &control); | ||
| 433 | </programlisting> | ||
| 434 | </example> | ||
| 435 | </section> | ||
| 436 | |||
| 437 | <section id="extended-controls"> | ||
| 438 | <title>Extended Controls</title> | ||
| 439 | |||
| 440 | <section> | ||
| 441 | <title>Introduction</title> | ||
| 442 | |||
| 443 | <para>The control mechanism as originally designed was meant | ||
| 444 | to be used for user settings (brightness, saturation, etc). However, | ||
| 445 | it turned out to be a very useful model for implementing more | ||
| 446 | complicated driver APIs where each driver implements only a subset of | ||
| 447 | a larger API.</para> | ||
| 448 | |||
| 449 | <para>The MPEG encoding API was the driving force behind | ||
| 450 | designing and implementing this extended control mechanism: the MPEG | ||
| 451 | standard is quite large and the currently supported hardware MPEG | ||
| 452 | encoders each only implement a subset of this standard. Further more, | ||
| 453 | many parameters relating to how the video is encoded into an MPEG | ||
| 454 | stream are specific to the MPEG encoding chip since the MPEG standard | ||
| 455 | only defines the format of the resulting MPEG stream, not how the | ||
| 456 | video is actually encoded into that format.</para> | ||
| 457 | |||
| 458 | <para>Unfortunately, the original control API lacked some | ||
| 459 | features needed for these new uses and so it was extended into the | ||
| 460 | (not terribly originally named) extended control API.</para> | ||
| 461 | |||
| 462 | <para>Even though the MPEG encoding API was the first effort | ||
| 463 | to use the Extended Control API, nowadays there are also other classes | ||
| 464 | of Extended Controls, such as Camera Controls and FM Transmitter Controls. | ||
| 465 | The Extended Controls API as well as all Extended Controls classes are | ||
| 466 | described in the following text.</para> | ||
| 467 | </section> | ||
| 468 | |||
| 469 | <section> | ||
| 470 | <title>The Extended Control API</title> | ||
| 471 | |||
| 472 | <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;, | ||
| 473 | &VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on | ||
| 474 | arrays of controls (as opposed to the &VIDIOC-G-CTRL; and | ||
| 475 | &VIDIOC-S-CTRL; ioctls that act on a single control). This is needed | ||
| 476 | since it is often required to atomically change several controls at | ||
| 477 | once.</para> | ||
| 478 | |||
| 479 | <para>Each of the new ioctls expects a pointer to a | ||
| 480 | &v4l2-ext-controls;. This structure contains a pointer to the control | ||
| 481 | array, a count of the number of controls in that array and a control | ||
| 482 | class. Control classes are used to group similar controls into a | ||
| 483 | single class. For example, control class | ||
| 484 | <constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls | ||
| 485 | (&ie; all controls that can also be set using the old | ||
| 486 | <constant>VIDIOC_S_CTRL</constant> ioctl). Control class | ||
| 487 | <constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls | ||
| 488 | relating to MPEG encoding, etc.</para> | ||
| 489 | |||
| 490 | <para>All controls in the control array must belong to the | ||
| 491 | specified control class. An error is returned if this is not the | ||
| 492 | case.</para> | ||
| 493 | |||
| 494 | <para>It is also possible to use an empty control array (count | ||
| 495 | == 0) to check whether the specified control class is | ||
| 496 | supported.</para> | ||
| 497 | |||
| 498 | <para>The control array is a &v4l2-ext-control; array. The | ||
| 499 | <structname>v4l2_ext_control</structname> structure is very similar to | ||
| 500 | &v4l2-control;, except for the fact that it also allows for 64-bit | ||
| 501 | values and pointers to be passed.</para> | ||
| 502 | |||
| 503 | <para>It is important to realize that due to the flexibility of | ||
| 504 | controls it is necessary to check whether the control you want to set | ||
| 505 | actually is supported in the driver and what the valid range of values | ||
| 506 | is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to | ||
| 507 | check this. Also note that it is possible that some of the menu | ||
| 508 | indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant> | ||
| 509 | may not be supported (<constant>VIDIOC_QUERYMENU</constant> will | ||
| 510 | return an error). A good example is the list of supported MPEG audio | ||
| 511 | bitrates. Some drivers only support one or two bitrates, others | ||
| 512 | support a wider range.</para> | ||
| 513 | </section> | ||
| 514 | |||
| 515 | <section> | ||
| 516 | <title>Enumerating Extended Controls</title> | ||
| 517 | |||
| 518 | <para>The recommended way to enumerate over the extended | ||
| 519 | controls is by using &VIDIOC-QUERYCTRL; in combination with the | ||
| 520 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para> | ||
| 521 | |||
| 522 | <informalexample> | ||
| 523 | <programlisting> | ||
| 524 | &v4l2-queryctrl; qctrl; | ||
| 525 | |||
| 526 | qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 527 | while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { | ||
| 528 | /* ... */ | ||
| 529 | qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 530 | } | ||
| 531 | </programlisting> | ||
| 532 | </informalexample> | ||
| 533 | |||
| 534 | <para>The initial control ID is set to 0 ORed with the | ||
| 535 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The | ||
| 536 | <constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first | ||
| 537 | control with a higher ID than the specified one. When no such controls | ||
| 538 | are found an error is returned.</para> | ||
| 539 | |||
| 540 | <para>If you want to get all controls within a specific control | ||
| 541 | class, then you can set the initial | ||
| 542 | <structfield>qctrl.id</structfield> value to the control class and add | ||
| 543 | an extra check to break out of the loop when a control of another | ||
| 544 | control class is found:</para> | ||
| 545 | |||
| 546 | <informalexample> | ||
| 547 | <programlisting> | ||
| 548 | qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 549 | while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { | ||
| 550 | if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) | ||
| 551 | break; | ||
| 552 | /* ... */ | ||
| 553 | qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 554 | } | ||
| 555 | </programlisting> | ||
| 556 | </informalexample> | ||
| 557 | |||
| 558 | <para>The 32-bit <structfield>qctrl.id</structfield> value is | ||
| 559 | subdivided into three bit ranges: the top 4 bits are reserved for | ||
| 560 | flags (⪚ <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not | ||
| 561 | actually part of the ID. The remaining 28 bits form the control ID, of | ||
| 562 | which the most significant 12 bits define the control class and the | ||
| 563 | least significant 16 bits identify the control within the control | ||
| 564 | class. It is guaranteed that these last 16 bits are always non-zero | ||
| 565 | for controls. The range of 0x1000 and up are reserved for | ||
| 566 | driver-specific controls. The macro | ||
| 567 | <constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class | ||
| 568 | ID based on a control ID.</para> | ||
| 569 | |||
| 570 | <para>If the driver does not support extended controls, then | ||
| 571 | <constant>VIDIOC_QUERYCTRL</constant> will fail when used in | ||
| 572 | combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In | ||
| 573 | that case the old method of enumerating control should be used (see | ||
| 574 | 1.8). But if it is supported, then it is guaranteed to enumerate over | ||
| 575 | all controls, including driver-private controls.</para> | ||
| 576 | </section> | ||
| 577 | |||
| 578 | <section> | ||
| 579 | <title>Creating Control Panels</title> | ||
| 580 | |||
| 581 | <para>It is possible to create control panels for a graphical | ||
| 582 | user interface where the user can select the various controls. | ||
| 583 | Basically you will have to iterate over all controls using the method | ||
| 584 | described above. Each control class starts with a control of type | ||
| 585 | <constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>. | ||
| 586 | <constant>VIDIOC_QUERYCTRL</constant> will return the name of this | ||
| 587 | control class which can be used as the title of a tab page within a | ||
| 588 | control panel.</para> | ||
| 589 | |||
| 590 | <para>The flags field of &v4l2-queryctrl; also contains hints on | ||
| 591 | the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation | ||
| 592 | for more details.</para> | ||
| 593 | </section> | ||
| 594 | |||
| 595 | <section id="mpeg-controls"> | ||
| 596 | <title>MPEG Control Reference</title> | ||
| 597 | |||
| 598 | <para>Below all controls within the MPEG control class are | ||
| 599 | described. First the generic controls, then controls specific for | ||
| 600 | certain hardware.</para> | ||
| 601 | |||
| 602 | <section> | ||
| 603 | <title>Generic MPEG Controls</title> | ||
| 604 | |||
| 605 | <table pgwide="1" frame="none" id="mpeg-control-id"> | ||
| 606 | <title>MPEG Control IDs</title> | ||
| 607 | <tgroup cols="4"> | ||
| 608 | <colspec colname="c1" colwidth="1*" /> | ||
| 609 | <colspec colname="c2" colwidth="6*" /> | ||
| 610 | <colspec colname="c3" colwidth="2*" /> | ||
| 611 | <colspec colname="c4" colwidth="6*" /> | ||
| 612 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 613 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 614 | <thead> | ||
| 615 | <row> | ||
| 616 | <entry spanname="id" align="left">ID</entry> | ||
| 617 | <entry align="left">Type</entry> | ||
| 618 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 619 | </row> | ||
| 620 | </thead> | ||
| 621 | <tbody valign="top"> | ||
| 622 | <row><entry></entry></row> | ||
| 623 | <row> | ||
| 624 | <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry> | ||
| 625 | <entry>class</entry> | ||
| 626 | </row><row><entry spanname="descr">The MPEG class | ||
| 627 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 628 | description of this control class. This description can be used as the | ||
| 629 | caption of a Tab page in a GUI, for example.</entry> | ||
| 630 | </row> | ||
| 631 | <row><entry></entry></row> | ||
| 632 | <row id="v4l2-mpeg-stream-type"> | ||
| 633 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant> </entry> | ||
| 634 | <entry>enum v4l2_mpeg_stream_type</entry> | ||
| 635 | </row><row><entry spanname="descr">The MPEG-1, -2 or -4 | ||
| 636 | output stream type. One cannot assume anything here. Each hardware | ||
| 637 | MPEG encoder tends to support different subsets of the available MPEG | ||
| 638 | stream types. The currently defined stream types are:</entry> | ||
| 639 | </row> | ||
| 640 | <row> | ||
| 641 | <entrytbl spanname="descr" cols="2"> | ||
| 642 | <tbody valign="top"> | ||
| 643 | <row> | ||
| 644 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant> </entry> | ||
| 645 | <entry>MPEG-2 program stream</entry> | ||
| 646 | </row> | ||
| 647 | <row> | ||
| 648 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant> </entry> | ||
| 649 | <entry>MPEG-2 transport stream</entry> | ||
| 650 | </row> | ||
| 651 | <row> | ||
| 652 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant> </entry> | ||
| 653 | <entry>MPEG-1 system stream</entry> | ||
| 654 | </row> | ||
| 655 | <row> | ||
| 656 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant> </entry> | ||
| 657 | <entry>MPEG-2 DVD-compatible stream</entry> | ||
| 658 | </row> | ||
| 659 | <row> | ||
| 660 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant> </entry> | ||
| 661 | <entry>MPEG-1 VCD-compatible stream</entry> | ||
| 662 | </row> | ||
| 663 | <row> | ||
| 664 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant> </entry> | ||
| 665 | <entry>MPEG-2 SVCD-compatible stream</entry> | ||
| 666 | </row> | ||
| 667 | </tbody> | ||
| 668 | </entrytbl> | ||
| 669 | </row> | ||
| 670 | <row><entry></entry></row> | ||
| 671 | <row> | ||
| 672 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant> </entry> | ||
| 673 | <entry>integer</entry> | ||
| 674 | </row><row><entry spanname="descr">Program Map Table | ||
| 675 | Packet ID for the MPEG transport stream (default 16)</entry> | ||
| 676 | </row> | ||
| 677 | <row><entry></entry></row> | ||
| 678 | <row> | ||
| 679 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant> </entry> | ||
| 680 | <entry>integer</entry> | ||
| 681 | </row><row><entry spanname="descr">Audio Packet ID for | ||
| 682 | the MPEG transport stream (default 256)</entry> | ||
| 683 | </row> | ||
| 684 | <row><entry></entry></row> | ||
| 685 | <row> | ||
| 686 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant> </entry> | ||
| 687 | <entry>integer</entry> | ||
| 688 | </row><row><entry spanname="descr">Video Packet ID for | ||
| 689 | the MPEG transport stream (default 260)</entry> | ||
| 690 | </row> | ||
| 691 | <row><entry></entry></row> | ||
| 692 | <row> | ||
| 693 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant> </entry> | ||
| 694 | <entry>integer</entry> | ||
| 695 | </row><row><entry spanname="descr">Packet ID for the | ||
| 696 | MPEG transport stream carrying PCR fields (default 259)</entry> | ||
| 697 | </row> | ||
| 698 | <row><entry></entry></row> | ||
| 699 | <row> | ||
| 700 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant> </entry> | ||
| 701 | <entry>integer</entry> | ||
| 702 | </row><row><entry spanname="descr">Audio ID for MPEG | ||
| 703 | PES</entry> | ||
| 704 | </row> | ||
| 705 | <row><entry></entry></row> | ||
| 706 | <row> | ||
| 707 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant> </entry> | ||
| 708 | <entry>integer</entry> | ||
| 709 | </row><row><entry spanname="descr">Video ID for MPEG | ||
| 710 | PES</entry> | ||
| 711 | </row> | ||
| 712 | <row><entry></entry></row> | ||
| 713 | <row id="v4l2-mpeg-stream-vbi-fmt"> | ||
| 714 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant> </entry> | ||
| 715 | <entry>enum v4l2_mpeg_stream_vbi_fmt</entry> | ||
| 716 | </row><row><entry spanname="descr">Some cards can embed | ||
| 717 | VBI data (⪚ Closed Caption, Teletext) into the MPEG stream. This | ||
| 718 | control selects whether VBI data should be embedded, and if so, what | ||
| 719 | embedding method should be used. The list of possible VBI formats | ||
| 720 | depends on the driver. The currently defined VBI format types | ||
| 721 | are:</entry> | ||
| 722 | </row> | ||
| 723 | <row> | ||
| 724 | <entrytbl spanname="descr" cols="2"> | ||
| 725 | <tbody valign="top"> | ||
| 726 | <row> | ||
| 727 | <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant> </entry> | ||
| 728 | <entry>No VBI in the MPEG stream</entry> | ||
| 729 | </row> | ||
| 730 | <row> | ||
| 731 | <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant> </entry> | ||
| 732 | <entry>VBI in private packets, IVTV format (documented | ||
| 733 | in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry> | ||
| 734 | </row> | ||
| 735 | </tbody> | ||
| 736 | </entrytbl> | ||
| 737 | </row> | ||
| 738 | <row><entry></entry></row> | ||
| 739 | <row id="v4l2-mpeg-audio-sampling-freq"> | ||
| 740 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant> </entry> | ||
| 741 | <entry>enum v4l2_mpeg_audio_sampling_freq</entry> | ||
| 742 | </row><row><entry spanname="descr">MPEG Audio sampling | ||
| 743 | frequency. Possible values are:</entry> | ||
| 744 | </row> | ||
| 745 | <row> | ||
| 746 | <entrytbl spanname="descr" cols="2"> | ||
| 747 | <tbody valign="top"> | ||
| 748 | <row> | ||
| 749 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant> </entry> | ||
| 750 | <entry>44.1 kHz</entry> | ||
| 751 | </row> | ||
| 752 | <row> | ||
| 753 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant> </entry> | ||
| 754 | <entry>48 kHz</entry> | ||
| 755 | </row> | ||
| 756 | <row> | ||
| 757 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant> </entry> | ||
| 758 | <entry>32 kHz</entry> | ||
| 759 | </row> | ||
| 760 | </tbody> | ||
| 761 | </entrytbl> | ||
| 762 | </row> | ||
| 763 | <row><entry></entry></row> | ||
| 764 | <row id="v4l2-mpeg-audio-encoding"> | ||
| 765 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant> </entry> | ||
| 766 | <entry>enum v4l2_mpeg_audio_encoding</entry> | ||
| 767 | </row><row><entry spanname="descr">MPEG Audio encoding. | ||
| 768 | Possible values are:</entry> | ||
| 769 | </row> | ||
| 770 | <row> | ||
| 771 | <entrytbl spanname="descr" cols="2"> | ||
| 772 | <tbody valign="top"> | ||
| 773 | <row> | ||
| 774 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant> </entry> | ||
| 775 | <entry>MPEG-1/2 Layer I encoding</entry> | ||
| 776 | </row> | ||
| 777 | <row> | ||
| 778 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant> </entry> | ||
| 779 | <entry>MPEG-1/2 Layer II encoding</entry> | ||
| 780 | </row> | ||
| 781 | <row> | ||
| 782 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant> </entry> | ||
| 783 | <entry>MPEG-1/2 Layer III encoding</entry> | ||
| 784 | </row> | ||
| 785 | <row> | ||
| 786 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> </entry> | ||
| 787 | <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry> | ||
| 788 | </row> | ||
| 789 | <row> | ||
| 790 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> </entry> | ||
| 791 | <entry>AC-3 aka ATSC A/52 encoding</entry> | ||
| 792 | </row> | ||
| 793 | </tbody> | ||
| 794 | </entrytbl> | ||
| 795 | </row> | ||
| 796 | <row><entry></entry></row> | ||
| 797 | <row id="v4l2-mpeg-audio-l1-bitrate"> | ||
| 798 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant> </entry> | ||
| 799 | <entry>enum v4l2_mpeg_audio_l1_bitrate</entry> | ||
| 800 | </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate. | ||
| 801 | Possible values are:</entry> | ||
| 802 | </row> | ||
| 803 | <row> | ||
| 804 | <entrytbl spanname="descr" cols="2"> | ||
| 805 | <tbody valign="top"> | ||
| 806 | <row> | ||
| 807 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant> </entry> | ||
| 808 | <entry>32 kbit/s</entry></row> | ||
| 809 | <row> | ||
| 810 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant> </entry> | ||
| 811 | <entry>64 kbit/s</entry> | ||
| 812 | </row> | ||
| 813 | <row> | ||
| 814 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant> </entry> | ||
| 815 | <entry>96 kbit/s</entry> | ||
| 816 | </row> | ||
| 817 | <row> | ||
| 818 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant> </entry> | ||
| 819 | <entry>128 kbit/s</entry> | ||
| 820 | </row> | ||
| 821 | <row> | ||
| 822 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant> </entry> | ||
| 823 | <entry>160 kbit/s</entry> | ||
| 824 | </row> | ||
| 825 | <row> | ||
| 826 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant> </entry> | ||
| 827 | <entry>192 kbit/s</entry> | ||
| 828 | </row> | ||
| 829 | <row> | ||
| 830 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant> </entry> | ||
| 831 | <entry>224 kbit/s</entry> | ||
| 832 | </row> | ||
| 833 | <row> | ||
| 834 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant> </entry> | ||
| 835 | <entry>256 kbit/s</entry> | ||
| 836 | </row> | ||
| 837 | <row> | ||
| 838 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant> </entry> | ||
| 839 | <entry>288 kbit/s</entry> | ||
| 840 | </row> | ||
| 841 | <row> | ||
| 842 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant> </entry> | ||
| 843 | <entry>320 kbit/s</entry> | ||
| 844 | </row> | ||
| 845 | <row> | ||
| 846 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant> </entry> | ||
| 847 | <entry>352 kbit/s</entry> | ||
| 848 | </row> | ||
| 849 | <row> | ||
| 850 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant> </entry> | ||
| 851 | <entry>384 kbit/s</entry> | ||
| 852 | </row> | ||
| 853 | <row> | ||
| 854 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant> </entry> | ||
| 855 | <entry>416 kbit/s</entry> | ||
| 856 | </row> | ||
| 857 | <row> | ||
| 858 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant> </entry> | ||
| 859 | <entry>448 kbit/s</entry> | ||
| 860 | </row> | ||
| 861 | </tbody> | ||
| 862 | </entrytbl> | ||
| 863 | </row> | ||
| 864 | <row><entry></entry></row> | ||
| 865 | <row id="v4l2-mpeg-audio-l2-bitrate"> | ||
| 866 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant> </entry> | ||
| 867 | <entry>enum v4l2_mpeg_audio_l2_bitrate</entry> | ||
| 868 | </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate. | ||
| 869 | Possible values are:</entry> | ||
| 870 | </row> | ||
| 871 | <row> | ||
| 872 | <entrytbl spanname="descr" cols="2"> | ||
| 873 | <tbody valign="top"> | ||
| 874 | <row> | ||
| 875 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant> </entry> | ||
| 876 | <entry>32 kbit/s</entry> | ||
| 877 | </row> | ||
| 878 | <row> | ||
| 879 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant> </entry> | ||
| 880 | <entry>48 kbit/s</entry> | ||
| 881 | </row> | ||
| 882 | <row> | ||
| 883 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant> </entry> | ||
| 884 | <entry>56 kbit/s</entry> | ||
| 885 | </row> | ||
| 886 | <row> | ||
| 887 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant> </entry> | ||
| 888 | <entry>64 kbit/s</entry> | ||
| 889 | </row> | ||
| 890 | <row> | ||
| 891 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant> </entry> | ||
| 892 | <entry>80 kbit/s</entry> | ||
| 893 | </row> | ||
| 894 | <row> | ||
| 895 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant> </entry> | ||
| 896 | <entry>96 kbit/s</entry> | ||
| 897 | </row> | ||
| 898 | <row> | ||
| 899 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant> </entry> | ||
| 900 | <entry>112 kbit/s</entry> | ||
| 901 | </row> | ||
| 902 | <row> | ||
| 903 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant> </entry> | ||
| 904 | <entry>128 kbit/s</entry> | ||
| 905 | </row> | ||
| 906 | <row> | ||
| 907 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant> </entry> | ||
| 908 | <entry>160 kbit/s</entry> | ||
| 909 | </row> | ||
| 910 | <row> | ||
| 911 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant> </entry> | ||
| 912 | <entry>192 kbit/s</entry> | ||
| 913 | </row> | ||
| 914 | <row> | ||
| 915 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant> </entry> | ||
| 916 | <entry>224 kbit/s</entry> | ||
| 917 | </row> | ||
| 918 | <row> | ||
| 919 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant> </entry> | ||
| 920 | <entry>256 kbit/s</entry> | ||
| 921 | </row> | ||
| 922 | <row> | ||
| 923 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant> </entry> | ||
| 924 | <entry>320 kbit/s</entry> | ||
| 925 | </row> | ||
| 926 | <row> | ||
| 927 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant> </entry> | ||
| 928 | <entry>384 kbit/s</entry> | ||
| 929 | </row> | ||
| 930 | </tbody> | ||
| 931 | </entrytbl> | ||
| 932 | </row> | ||
| 933 | <row><entry></entry></row> | ||
| 934 | <row id="v4l2-mpeg-audio-l3-bitrate"> | ||
| 935 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant> </entry> | ||
| 936 | <entry>enum v4l2_mpeg_audio_l3_bitrate</entry> | ||
| 937 | </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate. | ||
| 938 | Possible values are:</entry> | ||
| 939 | </row> | ||
| 940 | <row> | ||
| 941 | <entrytbl spanname="descr" cols="2"> | ||
| 942 | <tbody valign="top"> | ||
| 943 | <row> | ||
| 944 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant> </entry> | ||
| 945 | <entry>32 kbit/s</entry> | ||
| 946 | </row> | ||
| 947 | <row> | ||
| 948 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant> </entry> | ||
| 949 | <entry>40 kbit/s</entry> | ||
| 950 | </row> | ||
| 951 | <row> | ||
| 952 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant> </entry> | ||
| 953 | <entry>48 kbit/s</entry> | ||
| 954 | </row> | ||
| 955 | <row> | ||
| 956 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant> </entry> | ||
| 957 | <entry>56 kbit/s</entry> | ||
| 958 | </row> | ||
| 959 | <row> | ||
| 960 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant> </entry> | ||
| 961 | <entry>64 kbit/s</entry> | ||
| 962 | </row> | ||
| 963 | <row> | ||
| 964 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant> </entry> | ||
| 965 | <entry>80 kbit/s</entry> | ||
| 966 | </row> | ||
| 967 | <row> | ||
| 968 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant> </entry> | ||
| 969 | <entry>96 kbit/s</entry> | ||
| 970 | </row> | ||
| 971 | <row> | ||
| 972 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant> </entry> | ||
| 973 | <entry>112 kbit/s</entry> | ||
| 974 | </row> | ||
| 975 | <row> | ||
| 976 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant> </entry> | ||
| 977 | <entry>128 kbit/s</entry> | ||
| 978 | </row> | ||
| 979 | <row> | ||
| 980 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant> </entry> | ||
| 981 | <entry>160 kbit/s</entry> | ||
| 982 | </row> | ||
| 983 | <row> | ||
| 984 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant> </entry> | ||
| 985 | <entry>192 kbit/s</entry> | ||
| 986 | </row> | ||
| 987 | <row> | ||
| 988 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant> </entry> | ||
| 989 | <entry>224 kbit/s</entry> | ||
| 990 | </row> | ||
| 991 | <row> | ||
| 992 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant> </entry> | ||
| 993 | <entry>256 kbit/s</entry> | ||
| 994 | </row> | ||
| 995 | <row> | ||
| 996 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant> </entry> | ||
| 997 | <entry>320 kbit/s</entry> | ||
| 998 | </row> | ||
| 999 | </tbody> | ||
| 1000 | </entrytbl> | ||
| 1001 | </row> | ||
| 1002 | <row><entry></entry></row> | ||
| 1003 | <row> | ||
| 1004 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant> </entry> | ||
| 1005 | <entry>integer</entry> | ||
| 1006 | </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry> | ||
| 1007 | </row> | ||
| 1008 | <row><entry></entry></row> | ||
| 1009 | <row id="v4l2-mpeg-audio-ac3-bitrate"> | ||
| 1010 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant> </entry> | ||
| 1011 | <entry>enum v4l2_mpeg_audio_ac3_bitrate</entry> | ||
| 1012 | </row><row><entry spanname="descr">AC-3 bitrate. | ||
| 1013 | Possible values are:</entry> | ||
| 1014 | </row> | ||
| 1015 | <row> | ||
| 1016 | <entrytbl spanname="descr" cols="2"> | ||
| 1017 | <tbody valign="top"> | ||
| 1018 | <row> | ||
| 1019 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant> </entry> | ||
| 1020 | <entry>32 kbit/s</entry> | ||
| 1021 | </row> | ||
| 1022 | <row> | ||
| 1023 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant> </entry> | ||
| 1024 | <entry>40 kbit/s</entry> | ||
| 1025 | </row> | ||
| 1026 | <row> | ||
| 1027 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant> </entry> | ||
| 1028 | <entry>48 kbit/s</entry> | ||
| 1029 | </row> | ||
| 1030 | <row> | ||
| 1031 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant> </entry> | ||
| 1032 | <entry>56 kbit/s</entry> | ||
| 1033 | </row> | ||
| 1034 | <row> | ||
| 1035 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant> </entry> | ||
| 1036 | <entry>64 kbit/s</entry> | ||
| 1037 | </row> | ||
| 1038 | <row> | ||
| 1039 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant> </entry> | ||
| 1040 | <entry>80 kbit/s</entry> | ||
| 1041 | </row> | ||
| 1042 | <row> | ||
| 1043 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant> </entry> | ||
| 1044 | <entry>96 kbit/s</entry> | ||
| 1045 | </row> | ||
| 1046 | <row> | ||
| 1047 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant> </entry> | ||
| 1048 | <entry>112 kbit/s</entry> | ||
| 1049 | </row> | ||
| 1050 | <row> | ||
| 1051 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant> </entry> | ||
| 1052 | <entry>128 kbit/s</entry> | ||
| 1053 | </row> | ||
| 1054 | <row> | ||
| 1055 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant> </entry> | ||
| 1056 | <entry>160 kbit/s</entry> | ||
| 1057 | </row> | ||
| 1058 | <row> | ||
| 1059 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant> </entry> | ||
| 1060 | <entry>192 kbit/s</entry> | ||
| 1061 | </row> | ||
| 1062 | <row> | ||
| 1063 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant> </entry> | ||
| 1064 | <entry>224 kbit/s</entry> | ||
| 1065 | </row> | ||
| 1066 | <row> | ||
| 1067 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant> </entry> | ||
| 1068 | <entry>256 kbit/s</entry> | ||
| 1069 | </row> | ||
| 1070 | <row> | ||
| 1071 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant> </entry> | ||
| 1072 | <entry>320 kbit/s</entry> | ||
| 1073 | </row> | ||
| 1074 | <row> | ||
| 1075 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant> </entry> | ||
| 1076 | <entry>384 kbit/s</entry> | ||
| 1077 | </row> | ||
| 1078 | <row> | ||
| 1079 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant> </entry> | ||
| 1080 | <entry>448 kbit/s</entry> | ||
| 1081 | </row> | ||
| 1082 | <row> | ||
| 1083 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant> </entry> | ||
| 1084 | <entry>512 kbit/s</entry> | ||
| 1085 | </row> | ||
| 1086 | <row> | ||
| 1087 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant> </entry> | ||
| 1088 | <entry>576 kbit/s</entry> | ||
| 1089 | </row> | ||
| 1090 | <row> | ||
| 1091 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant> </entry> | ||
| 1092 | <entry>640 kbit/s</entry> | ||
| 1093 | </row> | ||
| 1094 | </tbody> | ||
| 1095 | </entrytbl> | ||
| 1096 | </row> | ||
| 1097 | <row><entry></entry></row> | ||
| 1098 | <row id="v4l2-mpeg-audio-mode"> | ||
| 1099 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant> </entry> | ||
| 1100 | <entry>enum v4l2_mpeg_audio_mode</entry> | ||
| 1101 | </row><row><entry spanname="descr">MPEG Audio mode. | ||
| 1102 | Possible values are:</entry> | ||
| 1103 | </row> | ||
| 1104 | <row> | ||
| 1105 | <entrytbl spanname="descr" cols="2"> | ||
| 1106 | <tbody valign="top"> | ||
| 1107 | <row> | ||
| 1108 | <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant> </entry> | ||
| 1109 | <entry>Stereo</entry> | ||
| 1110 | </row> | ||
| 1111 | <row> | ||
| 1112 | <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant> </entry> | ||
| 1113 | <entry>Joint Stereo</entry> | ||
| 1114 | </row> | ||
| 1115 | <row> | ||
| 1116 | <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant> </entry> | ||
| 1117 | <entry>Bilingual</entry> | ||
| 1118 | </row> | ||
| 1119 | <row> | ||
| 1120 | <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant> </entry> | ||
| 1121 | <entry>Mono</entry> | ||
| 1122 | </row> | ||
| 1123 | </tbody> | ||
| 1124 | </entrytbl> | ||
| 1125 | </row> | ||
| 1126 | <row><entry></entry></row> | ||
| 1127 | <row id="v4l2-mpeg-audio-mode-extension"> | ||
| 1128 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant> </entry> | ||
| 1129 | <entry>enum v4l2_mpeg_audio_mode_extension</entry> | ||
| 1130 | </row><row><entry spanname="descr">Joint Stereo | ||
| 1131 | audio mode extension. In Layer I and II they indicate which subbands | ||
| 1132 | are in intensity stereo. All other subbands are coded in stereo. Layer | ||
| 1133 | III is not (yet) supported. Possible values | ||
| 1134 | are:</entry> | ||
| 1135 | </row> | ||
| 1136 | <row> | ||
| 1137 | <entrytbl spanname="descr" cols="2"> | ||
| 1138 | <tbody valign="top"> | ||
| 1139 | <row> | ||
| 1140 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant> </entry> | ||
| 1141 | <entry>Subbands 4-31 in intensity stereo</entry> | ||
| 1142 | </row> | ||
| 1143 | <row> | ||
| 1144 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant> </entry> | ||
| 1145 | <entry>Subbands 8-31 in intensity stereo</entry> | ||
| 1146 | </row> | ||
| 1147 | <row> | ||
| 1148 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant> </entry> | ||
| 1149 | <entry>Subbands 12-31 in intensity stereo</entry> | ||
| 1150 | </row> | ||
| 1151 | <row> | ||
| 1152 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant> </entry> | ||
| 1153 | <entry>Subbands 16-31 in intensity stereo</entry> | ||
| 1154 | </row> | ||
| 1155 | </tbody> | ||
| 1156 | </entrytbl> | ||
| 1157 | </row> | ||
| 1158 | <row><entry></entry></row> | ||
| 1159 | <row id="v4l2-mpeg-audio-emphasis"> | ||
| 1160 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant> </entry> | ||
| 1161 | <entry>enum v4l2_mpeg_audio_emphasis</entry> | ||
| 1162 | </row><row><entry spanname="descr">Audio Emphasis. | ||
| 1163 | Possible values are:</entry> | ||
| 1164 | </row> | ||
| 1165 | <row> | ||
| 1166 | <entrytbl spanname="descr" cols="2"> | ||
| 1167 | <tbody valign="top"> | ||
| 1168 | <row> | ||
| 1169 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant> </entry> | ||
| 1170 | <entry>None</entry> | ||
| 1171 | </row> | ||
| 1172 | <row> | ||
| 1173 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant> </entry> | ||
| 1174 | <entry>50/15 microsecond emphasis</entry> | ||
| 1175 | </row> | ||
| 1176 | <row> | ||
| 1177 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant> </entry> | ||
| 1178 | <entry>CCITT J.17</entry> | ||
| 1179 | </row> | ||
| 1180 | </tbody> | ||
| 1181 | </entrytbl> | ||
| 1182 | </row> | ||
| 1183 | <row><entry></entry></row> | ||
| 1184 | <row id="v4l2-mpeg-audio-crc"> | ||
| 1185 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant> </entry> | ||
| 1186 | <entry>enum v4l2_mpeg_audio_crc</entry> | ||
| 1187 | </row><row><entry spanname="descr">CRC method. Possible | ||
| 1188 | values are:</entry> | ||
| 1189 | </row> | ||
| 1190 | <row> | ||
| 1191 | <entrytbl spanname="descr" cols="2"> | ||
| 1192 | <tbody valign="top"> | ||
| 1193 | <row> | ||
| 1194 | <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant> </entry> | ||
| 1195 | <entry>None</entry> | ||
| 1196 | </row> | ||
| 1197 | <row> | ||
| 1198 | <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant> </entry> | ||
| 1199 | <entry>16 bit parity check</entry> | ||
| 1200 | </row> | ||
| 1201 | </tbody> | ||
| 1202 | </entrytbl> | ||
| 1203 | </row> | ||
| 1204 | <row><entry></entry></row> | ||
| 1205 | <row> | ||
| 1206 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant> </entry> | ||
| 1207 | <entry>boolean</entry> | ||
| 1208 | </row><row><entry spanname="descr">Mutes the audio when | ||
| 1209 | capturing. This is not done by muting audio hardware, which can still | ||
| 1210 | produce a slight hiss, but in the encoder itself, guaranteeing a fixed | ||
| 1211 | and reproducable audio bitstream. 0 = unmuted, 1 = muted.</entry> | ||
| 1212 | </row> | ||
| 1213 | <row><entry></entry></row> | ||
| 1214 | <row id="v4l2-mpeg-video-encoding"> | ||
| 1215 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry> | ||
| 1216 | <entry>enum v4l2_mpeg_video_encoding</entry> | ||
| 1217 | </row><row><entry spanname="descr">MPEG Video encoding | ||
| 1218 | method. Possible values are:</entry> | ||
| 1219 | </row> | ||
| 1220 | <row> | ||
| 1221 | <entrytbl spanname="descr" cols="2"> | ||
| 1222 | <tbody valign="top"> | ||
| 1223 | <row> | ||
| 1224 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant> </entry> | ||
| 1225 | <entry>MPEG-1 Video encoding</entry> | ||
| 1226 | </row> | ||
| 1227 | <row> | ||
| 1228 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant> </entry> | ||
| 1229 | <entry>MPEG-2 Video encoding</entry> | ||
| 1230 | </row> | ||
| 1231 | <row> | ||
| 1232 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> </entry> | ||
| 1233 | <entry>MPEG-4 AVC (H.264) Video encoding</entry> | ||
| 1234 | </row> | ||
| 1235 | </tbody> | ||
| 1236 | </entrytbl> | ||
| 1237 | </row> | ||
| 1238 | <row><entry></entry></row> | ||
| 1239 | <row id="v4l2-mpeg-video-aspect"> | ||
| 1240 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant> </entry> | ||
| 1241 | <entry>enum v4l2_mpeg_video_aspect</entry> | ||
| 1242 | </row><row><entry spanname="descr">Video aspect. | ||
| 1243 | Possible values are:</entry> | ||
| 1244 | </row> | ||
| 1245 | <row> | ||
| 1246 | <entrytbl spanname="descr" cols="2"> | ||
| 1247 | <tbody valign="top"> | ||
| 1248 | <row> | ||
| 1249 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant> </entry> | ||
| 1250 | </row> | ||
| 1251 | <row> | ||
| 1252 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant> </entry> | ||
| 1253 | </row> | ||
| 1254 | <row> | ||
| 1255 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant> </entry> | ||
| 1256 | </row> | ||
| 1257 | <row> | ||
| 1258 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant> </entry> | ||
| 1259 | </row> | ||
| 1260 | </tbody> | ||
| 1261 | </entrytbl> | ||
| 1262 | </row> | ||
| 1263 | <row><entry></entry></row> | ||
| 1264 | <row> | ||
| 1265 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant> </entry> | ||
| 1266 | <entry>integer</entry> | ||
| 1267 | </row><row><entry spanname="descr">Number of B-Frames | ||
| 1268 | (default 2)</entry> | ||
| 1269 | </row> | ||
| 1270 | <row><entry></entry></row> | ||
| 1271 | <row> | ||
| 1272 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant> </entry> | ||
| 1273 | <entry>integer</entry> | ||
| 1274 | </row><row><entry spanname="descr">GOP size (default | ||
| 1275 | 12)</entry> | ||
| 1276 | </row> | ||
| 1277 | <row><entry></entry></row> | ||
| 1278 | <row> | ||
| 1279 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant> </entry> | ||
| 1280 | <entry>boolean</entry> | ||
| 1281 | </row><row><entry spanname="descr">GOP closure (default | ||
| 1282 | 1)</entry> | ||
| 1283 | </row> | ||
| 1284 | <row><entry></entry></row> | ||
| 1285 | <row> | ||
| 1286 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant> </entry> | ||
| 1287 | <entry>boolean</entry> | ||
| 1288 | </row><row><entry spanname="descr">Enable 3:2 pulldown | ||
| 1289 | (default 0)</entry> | ||
| 1290 | </row> | ||
| 1291 | <row><entry></entry></row> | ||
| 1292 | <row id="v4l2-mpeg-video-bitrate-mode"> | ||
| 1293 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant> </entry> | ||
| 1294 | <entry>enum v4l2_mpeg_video_bitrate_mode</entry> | ||
| 1295 | </row><row><entry spanname="descr">Video bitrate mode. | ||
| 1296 | Possible values are:</entry> | ||
| 1297 | </row> | ||
| 1298 | <row> | ||
| 1299 | <entrytbl spanname="descr" cols="2"> | ||
| 1300 | <tbody valign="top"> | ||
| 1301 | <row> | ||
| 1302 | <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant> </entry> | ||
| 1303 | <entry>Variable bitrate</entry> | ||
| 1304 | </row> | ||
| 1305 | <row> | ||
| 1306 | <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant> </entry> | ||
| 1307 | <entry>Constant bitrate</entry> | ||
| 1308 | </row> | ||
| 1309 | </tbody> | ||
| 1310 | </entrytbl> | ||
| 1311 | </row> | ||
| 1312 | <row><entry></entry></row> | ||
| 1313 | <row> | ||
| 1314 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant> </entry> | ||
| 1315 | <entry>integer</entry> | ||
| 1316 | </row><row><entry spanname="descr">Video bitrate in bits | ||
| 1317 | per second.</entry> | ||
| 1318 | </row> | ||
| 1319 | <row><entry></entry></row> | ||
| 1320 | <row> | ||
| 1321 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant> </entry> | ||
| 1322 | <entry>integer</entry> | ||
| 1323 | </row><row><entry spanname="descr">Peak video bitrate in | ||
| 1324 | bits per second. Must be larger or equal to the average video bitrate. | ||
| 1325 | It is ignored if the video bitrate mode is set to constant | ||
| 1326 | bitrate.</entry> | ||
| 1327 | </row> | ||
| 1328 | <row><entry></entry></row> | ||
| 1329 | <row> | ||
| 1330 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant> </entry> | ||
| 1331 | <entry>integer</entry> | ||
| 1332 | </row><row><entry spanname="descr">For every captured | ||
| 1333 | frame, skip this many subsequent frames (default 0).</entry> | ||
| 1334 | </row> | ||
| 1335 | <row><entry></entry></row> | ||
| 1336 | <row> | ||
| 1337 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant> </entry> | ||
| 1338 | <entry>boolean</entry> | ||
| 1339 | </row> | ||
| 1340 | <row><entry spanname="descr">"Mutes" the video to a | ||
| 1341 | fixed color when capturing. This is useful for testing, to produce a | ||
| 1342 | fixed video bitstream. 0 = unmuted, 1 = muted.</entry> | ||
| 1343 | </row> | ||
| 1344 | <row><entry></entry></row> | ||
| 1345 | <row> | ||
| 1346 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant> </entry> | ||
| 1347 | <entry>integer</entry> | ||
| 1348 | </row><row><entry spanname="descr">Sets the "mute" color | ||
| 1349 | of the video. The supplied 32-bit integer is interpreted as follows (bit | ||
| 1350 | 0 = least significant bit):</entry> | ||
| 1351 | </row> | ||
| 1352 | <row> | ||
| 1353 | <entrytbl spanname="descr" cols="2"> | ||
| 1354 | <tbody valign="top"> | ||
| 1355 | <row> | ||
| 1356 | <entry>Bit 0:7</entry> | ||
| 1357 | <entry>V chrominance information</entry> | ||
| 1358 | </row> | ||
| 1359 | <row> | ||
| 1360 | <entry>Bit 8:15</entry> | ||
| 1361 | <entry>U chrominance information</entry> | ||
| 1362 | </row> | ||
| 1363 | <row> | ||
| 1364 | <entry>Bit 16:23</entry> | ||
| 1365 | <entry>Y luminance information</entry> | ||
| 1366 | </row> | ||
| 1367 | <row> | ||
| 1368 | <entry>Bit 24:31</entry> | ||
| 1369 | <entry>Must be zero.</entry> | ||
| 1370 | </row> | ||
| 1371 | </tbody> | ||
| 1372 | </entrytbl> | ||
| 1373 | </row> | ||
| 1374 | </tbody> | ||
| 1375 | </tgroup> | ||
| 1376 | </table> | ||
| 1377 | </section> | ||
| 1378 | |||
| 1379 | <section> | ||
| 1380 | <title>CX2341x MPEG Controls</title> | ||
| 1381 | |||
| 1382 | <para>The following MPEG class controls deal with MPEG | ||
| 1383 | encoding settings that are specific to the Conexant CX23415 and | ||
| 1384 | CX23416 MPEG encoding chips.</para> | ||
| 1385 | |||
| 1386 | <table pgwide="1" frame="none" id="cx2341x-control-id"> | ||
| 1387 | <title>CX2341x Control IDs</title> | ||
| 1388 | <tgroup cols="4"> | ||
| 1389 | <colspec colname="c1" colwidth="1*" /> | ||
| 1390 | <colspec colname="c2" colwidth="6*" /> | ||
| 1391 | <colspec colname="c3" colwidth="2*" /> | ||
| 1392 | <colspec colname="c4" colwidth="6*" /> | ||
| 1393 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1394 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1395 | <thead> | ||
| 1396 | <row> | ||
| 1397 | <entry spanname="id" align="left">ID</entry> | ||
| 1398 | <entry align="left">Type</entry> | ||
| 1399 | </row><row><entry spanname="descr" align="left">Description</entry> | ||
| 1400 | </row> | ||
| 1401 | </thead> | ||
| 1402 | <tbody valign="top"> | ||
| 1403 | <row><entry></entry></row> | ||
| 1404 | <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode"> | ||
| 1405 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant> </entry> | ||
| 1406 | <entry>enum v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry> | ||
| 1407 | </row><row><entry spanname="descr">Sets the Spatial | ||
| 1408 | Filter mode (default <constant>MANUAL</constant>). Possible values | ||
| 1409 | are:</entry> | ||
| 1410 | </row> | ||
| 1411 | <row> | ||
| 1412 | <entrytbl spanname="descr" cols="2"> | ||
| 1413 | <tbody valign="top"> | ||
| 1414 | <row> | ||
| 1415 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant> </entry> | ||
| 1416 | <entry>Choose the filter manually</entry> | ||
| 1417 | </row> | ||
| 1418 | <row> | ||
| 1419 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant> </entry> | ||
| 1420 | <entry>Choose the filter automatically</entry> | ||
| 1421 | </row> | ||
| 1422 | </tbody> | ||
| 1423 | </entrytbl> | ||
| 1424 | </row> | ||
| 1425 | <row><entry></entry></row> | ||
| 1426 | <row> | ||
| 1427 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant> </entry> | ||
| 1428 | <entry>integer (0-15)</entry> | ||
| 1429 | </row><row><entry spanname="descr">The setting for the | ||
| 1430 | Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry> | ||
| 1431 | </row> | ||
| 1432 | <row><entry></entry></row> | ||
| 1433 | <row id="luma-spatial-filter-type"> | ||
| 1434 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant> </entry> | ||
| 1435 | <entry>enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry> | ||
| 1436 | </row><row><entry spanname="descr">Select the algorithm | ||
| 1437 | to use for the Luma Spatial Filter (default | ||
| 1438 | <constant>1D_HOR</constant>). Possible values:</entry> | ||
| 1439 | </row> | ||
| 1440 | <row> | ||
| 1441 | <entrytbl spanname="descr" cols="2"> | ||
| 1442 | <tbody valign="top"> | ||
| 1443 | <row> | ||
| 1444 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> | ||
| 1445 | <entry>No filter</entry> | ||
| 1446 | </row> | ||
| 1447 | <row> | ||
| 1448 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> | ||
| 1449 | <entry>One-dimensional horizontal</entry> | ||
| 1450 | </row> | ||
| 1451 | <row> | ||
| 1452 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant> </entry> | ||
| 1453 | <entry>One-dimensional vertical</entry> | ||
| 1454 | </row> | ||
| 1455 | <row> | ||
| 1456 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant> </entry> | ||
| 1457 | <entry>Two-dimensional separable</entry> | ||
| 1458 | </row> | ||
| 1459 | <row> | ||
| 1460 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant> </entry> | ||
| 1461 | <entry>Two-dimensional symmetrical | ||
| 1462 | non-separable</entry> | ||
| 1463 | </row> | ||
| 1464 | </tbody> | ||
| 1465 | </entrytbl> | ||
| 1466 | </row> | ||
| 1467 | <row><entry></entry></row> | ||
| 1468 | <row id="chroma-spatial-filter-type"> | ||
| 1469 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant> </entry> | ||
| 1470 | <entry>enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry> | ||
| 1471 | </row><row><entry spanname="descr">Select the algorithm | ||
| 1472 | for the Chroma Spatial Filter (default <constant>1D_HOR</constant>). | ||
| 1473 | Possible values are:</entry> | ||
| 1474 | </row> | ||
| 1475 | <row> | ||
| 1476 | <entrytbl spanname="descr" cols="2"> | ||
| 1477 | <tbody valign="top"> | ||
| 1478 | <row> | ||
| 1479 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> | ||
| 1480 | <entry>No filter</entry> | ||
| 1481 | </row> | ||
| 1482 | <row> | ||
| 1483 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> | ||
| 1484 | <entry>One-dimensional horizontal</entry> | ||
| 1485 | </row> | ||
| 1486 | </tbody> | ||
| 1487 | </entrytbl> | ||
| 1488 | </row> | ||
| 1489 | <row><entry></entry></row> | ||
| 1490 | <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode"> | ||
| 1491 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant> </entry> | ||
| 1492 | <entry>enum v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry> | ||
| 1493 | </row><row><entry spanname="descr">Sets the Temporal | ||
| 1494 | Filter mode (default <constant>MANUAL</constant>). Possible values | ||
| 1495 | are:</entry> | ||
| 1496 | </row> | ||
| 1497 | <row> | ||
| 1498 | <entrytbl spanname="descr" cols="2"> | ||
| 1499 | <tbody valign="top"> | ||
| 1500 | <row> | ||
| 1501 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant> </entry> | ||
| 1502 | <entry>Choose the filter manually</entry> | ||
| 1503 | </row> | ||
| 1504 | <row> | ||
| 1505 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant> </entry> | ||
| 1506 | <entry>Choose the filter automatically</entry> | ||
| 1507 | </row> | ||
| 1508 | </tbody> | ||
| 1509 | </entrytbl> | ||
| 1510 | </row> | ||
| 1511 | <row><entry></entry></row> | ||
| 1512 | <row> | ||
| 1513 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant> </entry> | ||
| 1514 | <entry>integer (0-31)</entry> | ||
| 1515 | </row><row><entry spanname="descr">The setting for the | ||
| 1516 | Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale | ||
| 1517 | capturing and 0 for scaled capturing.)</entry> | ||
| 1518 | </row> | ||
| 1519 | <row><entry></entry></row> | ||
| 1520 | <row id="v4l2-mpeg-cx2341x-video-median-filter-type"> | ||
| 1521 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant> </entry> | ||
| 1522 | <entry>enum v4l2_mpeg_cx2341x_video_median_filter_type</entry> | ||
| 1523 | </row><row><entry spanname="descr">Median Filter Type | ||
| 1524 | (default <constant>OFF</constant>). Possible values are:</entry> | ||
| 1525 | </row> | ||
| 1526 | <row> | ||
| 1527 | <entrytbl spanname="descr" cols="2"> | ||
| 1528 | <tbody valign="top"> | ||
| 1529 | <row> | ||
| 1530 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant> </entry> | ||
| 1531 | <entry>No filter</entry> | ||
| 1532 | </row> | ||
| 1533 | <row> | ||
| 1534 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant> </entry> | ||
| 1535 | <entry>Horizontal filter</entry> | ||
| 1536 | </row> | ||
| 1537 | <row> | ||
| 1538 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant> </entry> | ||
| 1539 | <entry>Vertical filter</entry> | ||
| 1540 | </row> | ||
| 1541 | <row> | ||
| 1542 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant> </entry> | ||
| 1543 | <entry>Horizontal and vertical filter</entry> | ||
| 1544 | </row> | ||
| 1545 | <row> | ||
| 1546 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant> </entry> | ||
| 1547 | <entry>Diagonal filter</entry> | ||
| 1548 | </row> | ||
| 1549 | </tbody> | ||
| 1550 | </entrytbl> | ||
| 1551 | </row> | ||
| 1552 | <row><entry></entry></row> | ||
| 1553 | <row> | ||
| 1554 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant> </entry> | ||
| 1555 | <entry>integer (0-255)</entry> | ||
| 1556 | </row><row><entry spanname="descr">Threshold above which | ||
| 1557 | the luminance median filter is enabled (default 0)</entry> | ||
| 1558 | </row> | ||
| 1559 | <row><entry></entry></row> | ||
| 1560 | <row> | ||
| 1561 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant> </entry> | ||
| 1562 | <entry>integer (0-255)</entry> | ||
| 1563 | </row><row><entry spanname="descr">Threshold below which | ||
| 1564 | the luminance median filter is enabled (default 255)</entry> | ||
| 1565 | </row> | ||
| 1566 | <row><entry></entry></row> | ||
| 1567 | <row> | ||
| 1568 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant> </entry> | ||
| 1569 | <entry>integer (0-255)</entry> | ||
| 1570 | </row><row><entry spanname="descr">Threshold above which | ||
| 1571 | the chroma median filter is enabled (default 0)</entry> | ||
| 1572 | </row> | ||
| 1573 | <row><entry></entry></row> | ||
| 1574 | <row> | ||
| 1575 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant> </entry> | ||
| 1576 | <entry>integer (0-255)</entry> | ||
| 1577 | </row><row><entry spanname="descr">Threshold below which | ||
| 1578 | the chroma median filter is enabled (default 255)</entry> | ||
| 1579 | </row> | ||
| 1580 | <row><entry></entry></row> | ||
| 1581 | <row> | ||
| 1582 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant> </entry> | ||
| 1583 | <entry>boolean</entry> | ||
| 1584 | </row> | ||
| 1585 | <row><entry spanname="descr">The CX2341X MPEG encoder | ||
| 1586 | can insert one empty MPEG-2 PES packet into the stream between every | ||
| 1587 | four video frames. The packet size is 2048 bytes, including the | ||
| 1588 | packet_start_code_prefix and stream_id fields. The stream_id is 0xBF | ||
| 1589 | (private stream 2). The payload consists of 0x00 bytes, to be filled | ||
| 1590 | in by the application. 0 = do not insert, 1 = insert packets.</entry> | ||
| 1591 | </row> | ||
| 1592 | </tbody> | ||
| 1593 | </tgroup> | ||
| 1594 | </table> | ||
| 1595 | </section> | ||
| 1596 | </section> | ||
| 1597 | |||
| 1598 | <section id="camera-controls"> | ||
| 1599 | <title>Camera Control Reference</title> | ||
| 1600 | |||
| 1601 | <para>The Camera class includes controls for mechanical (or | ||
| 1602 | equivalent digital) features of a device such as controllable lenses | ||
| 1603 | or sensors.</para> | ||
| 1604 | |||
| 1605 | <table pgwide="1" frame="none" id="camera-control-id"> | ||
| 1606 | <title>Camera Control IDs</title> | ||
| 1607 | <tgroup cols="4"> | ||
| 1608 | <colspec colname="c1" colwidth="1*" /> | ||
| 1609 | <colspec colname="c2" colwidth="6*" /> | ||
| 1610 | <colspec colname="c3" colwidth="2*" /> | ||
| 1611 | <colspec colname="c4" colwidth="6*" /> | ||
| 1612 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1613 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1614 | <thead> | ||
| 1615 | <row> | ||
| 1616 | <entry spanname="id" align="left">ID</entry> | ||
| 1617 | <entry align="left">Type</entry> | ||
| 1618 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 1619 | </row> | ||
| 1620 | </thead> | ||
| 1621 | <tbody valign="top"> | ||
| 1622 | <row><entry></entry></row> | ||
| 1623 | <row> | ||
| 1624 | <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant> </entry> | ||
| 1625 | <entry>class</entry> | ||
| 1626 | </row><row><entry spanname="descr">The Camera class | ||
| 1627 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 1628 | description of this control class.</entry> | ||
| 1629 | </row> | ||
| 1630 | <row><entry></entry></row> | ||
| 1631 | |||
| 1632 | <row id="v4l2-exposure-auto-type"> | ||
| 1633 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant> </entry> | ||
| 1634 | <entry>enum v4l2_exposure_auto_type</entry> | ||
| 1635 | </row><row><entry spanname="descr">Enables automatic | ||
| 1636 | adjustments of the exposure time and/or iris aperture. The effect of | ||
| 1637 | manual changes of the exposure time or iris aperture while these | ||
| 1638 | features are enabled is undefined, drivers should ignore such | ||
| 1639 | requests. Possible values are:</entry> | ||
| 1640 | </row> | ||
| 1641 | <row> | ||
| 1642 | <entrytbl spanname="descr" cols="2"> | ||
| 1643 | <tbody valign="top"> | ||
| 1644 | <row> | ||
| 1645 | <entry><constant>V4L2_EXPOSURE_AUTO</constant> </entry> | ||
| 1646 | <entry>Automatic exposure time, automatic iris | ||
| 1647 | aperture.</entry> | ||
| 1648 | </row> | ||
| 1649 | <row> | ||
| 1650 | <entry><constant>V4L2_EXPOSURE_MANUAL</constant> </entry> | ||
| 1651 | <entry>Manual exposure time, manual iris.</entry> | ||
| 1652 | </row> | ||
| 1653 | <row> | ||
| 1654 | <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant> </entry> | ||
| 1655 | <entry>Manual exposure time, auto iris.</entry> | ||
| 1656 | </row> | ||
| 1657 | <row> | ||
| 1658 | <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant> </entry> | ||
| 1659 | <entry>Auto exposure time, manual iris.</entry> | ||
| 1660 | </row> | ||
| 1661 | </tbody> | ||
| 1662 | </entrytbl> | ||
| 1663 | </row> | ||
| 1664 | <row><entry></entry></row> | ||
| 1665 | |||
| 1666 | <row> | ||
| 1667 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant> </entry> | ||
| 1668 | <entry>integer</entry> | ||
| 1669 | </row><row><entry spanname="descr">Determines the exposure | ||
| 1670 | time of the camera sensor. The exposure time is limited by the frame | ||
| 1671 | interval. Drivers should interpret the values as 100 µs units, | ||
| 1672 | where the value 1 stands for 1/10000th of a second, 10000 for 1 second | ||
| 1673 | and 100000 for 10 seconds.</entry> | ||
| 1674 | </row> | ||
| 1675 | <row><entry></entry></row> | ||
| 1676 | |||
| 1677 | <row> | ||
| 1678 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant> </entry> | ||
| 1679 | <entry>boolean</entry> | ||
| 1680 | </row><row><entry spanname="descr">When | ||
| 1681 | <constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to | ||
| 1682 | <constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>, | ||
| 1683 | this control determines if the device may dynamically vary the frame | ||
| 1684 | rate. By default this feature is disabled (0) and the frame rate must | ||
| 1685 | remain constant.</entry> | ||
| 1686 | </row> | ||
| 1687 | <row><entry></entry></row> | ||
| 1688 | |||
| 1689 | <row> | ||
| 1690 | <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry> | ||
| 1691 | <entry>integer</entry> | ||
| 1692 | </row><row><entry spanname="descr">This control turns the | ||
| 1693 | camera horizontally by the specified amount. The unit is undefined. A | ||
| 1694 | positive value moves the camera to the right (clockwise when viewed | ||
| 1695 | from above), a negative value to the left. A value of zero does not | ||
| 1696 | cause motion. This is a write-only control.</entry> | ||
| 1697 | </row> | ||
| 1698 | <row><entry></entry></row> | ||
| 1699 | |||
| 1700 | <row> | ||
| 1701 | <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant> </entry> | ||
| 1702 | <entry>integer</entry> | ||
| 1703 | </row><row><entry spanname="descr">This control turns the | ||
| 1704 | camera vertically by the specified amount. The unit is undefined. A | ||
| 1705 | positive value moves the camera up, a negative value down. A value of | ||
| 1706 | zero does not cause motion. This is a write-only control.</entry> | ||
| 1707 | </row> | ||
| 1708 | <row><entry></entry></row> | ||
| 1709 | |||
| 1710 | <row> | ||
| 1711 | <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant> </entry> | ||
| 1712 | <entry>button</entry> | ||
| 1713 | </row><row><entry spanname="descr">When this control is set, | ||
| 1714 | the camera moves horizontally to the default position.</entry> | ||
| 1715 | </row> | ||
| 1716 | <row><entry></entry></row> | ||
| 1717 | |||
| 1718 | <row> | ||
| 1719 | <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant> </entry> | ||
| 1720 | <entry>button</entry> | ||
| 1721 | </row><row><entry spanname="descr">When this control is set, | ||
| 1722 | the camera moves vertically to the default position.</entry> | ||
| 1723 | </row> | ||
| 1724 | <row><entry></entry></row> | ||
| 1725 | |||
| 1726 | <row> | ||
| 1727 | <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant> </entry> | ||
| 1728 | <entry>integer</entry> | ||
| 1729 | </row><row><entry spanname="descr">This control | ||
| 1730 | turns the camera horizontally to the specified position. Positive | ||
| 1731 | values move the camera to the right (clockwise when viewed from above), | ||
| 1732 | negative values to the left. Drivers should interpret the values as arc | ||
| 1733 | seconds, with valid values between -180 * 3600 and +180 * 3600 | ||
| 1734 | inclusive.</entry> | ||
| 1735 | </row> | ||
| 1736 | <row><entry></entry></row> | ||
| 1737 | |||
| 1738 | <row> | ||
| 1739 | <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant> </entry> | ||
| 1740 | <entry>integer</entry> | ||
| 1741 | </row><row><entry spanname="descr">This control | ||
| 1742 | turns the camera vertically to the specified position. Positive values | ||
| 1743 | move the camera up, negative values down. Drivers should interpret the | ||
| 1744 | values as arc seconds, with valid values between -180 * 3600 and +180 | ||
| 1745 | * 3600 inclusive.</entry> | ||
| 1746 | </row> | ||
| 1747 | <row><entry></entry></row> | ||
| 1748 | |||
| 1749 | <row> | ||
| 1750 | <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant> </entry> | ||
| 1751 | <entry>integer</entry> | ||
| 1752 | </row><row><entry spanname="descr">This control sets the | ||
| 1753 | focal point of the camera to the specified position. The unit is | ||
| 1754 | undefined. Positive values set the focus closer to the camera, | ||
| 1755 | negative values towards infinity.</entry> | ||
| 1756 | </row> | ||
| 1757 | <row><entry></entry></row> | ||
| 1758 | |||
| 1759 | <row> | ||
| 1760 | <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant> </entry> | ||
| 1761 | <entry>integer</entry> | ||
| 1762 | </row><row><entry spanname="descr">This control moves the | ||
| 1763 | focal point of the camera by the specified amount. The unit is | ||
| 1764 | undefined. Positive values move the focus closer to the camera, | ||
| 1765 | negative values towards infinity. This is a write-only control.</entry> | ||
| 1766 | </row> | ||
| 1767 | <row><entry></entry></row> | ||
| 1768 | |||
| 1769 | <row> | ||
| 1770 | <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry> | ||
| 1771 | <entry>boolean</entry> | ||
| 1772 | </row><row><entry spanname="descr">Enables automatic focus | ||
| 1773 | adjustments. The effect of manual focus adjustments while this feature | ||
| 1774 | is enabled is undefined, drivers should ignore such requests.</entry> | ||
| 1775 | </row> | ||
| 1776 | <row><entry></entry></row> | ||
| 1777 | |||
| 1778 | <row> | ||
| 1779 | <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry> | ||
| 1780 | <entry>integer</entry> | ||
| 1781 | </row><row><entry spanname="descr">Specify the objective lens | ||
| 1782 | focal length as an absolute value. The zoom unit is driver-specific and its | ||
| 1783 | value should be a positive integer.</entry> | ||
| 1784 | </row> | ||
| 1785 | <row><entry></entry></row> | ||
| 1786 | |||
| 1787 | <row> | ||
| 1788 | <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant> </entry> | ||
| 1789 | <entry>integer</entry> | ||
| 1790 | </row><row><entry spanname="descr">Specify the objective lens | ||
| 1791 | focal length relatively to the current value. Positive values move the zoom | ||
| 1792 | lens group towards the telephoto direction, negative values towards the | ||
| 1793 | wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry> | ||
| 1794 | </row> | ||
| 1795 | <row><entry></entry></row> | ||
| 1796 | |||
| 1797 | <row> | ||
| 1798 | <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant> </entry> | ||
| 1799 | <entry>integer</entry> | ||
| 1800 | </row><row><entry spanname="descr">Move the objective lens group | ||
| 1801 | at the specified speed until it reaches physical device limits or until an | ||
| 1802 | explicit request to stop the movement. A positive value moves the zoom lens | ||
| 1803 | group towards the telephoto direction. A value of zero stops the zoom lens | ||
| 1804 | group movement. A negative value moves the zoom lens group towards the | ||
| 1805 | wide-angle direction. The zoom speed unit is driver-specific.</entry> | ||
| 1806 | </row> | ||
| 1807 | <row><entry></entry></row> | ||
| 1808 | |||
| 1809 | <row> | ||
| 1810 | <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry> | ||
| 1811 | <entry>boolean</entry> | ||
| 1812 | </row><row><entry spanname="descr">Prevent video from being acquired | ||
| 1813 | by the camera. When this control is set to <constant>TRUE</constant> (1), no | ||
| 1814 | image can be captured by the camera. Common means to enforce privacy are | ||
| 1815 | mechanical obturation of the sensor and firmware image processing, but the | ||
| 1816 | device is not restricted to these methods. Devices that implement the privacy | ||
| 1817 | control must support read access and may support write access.</entry> | ||
| 1818 | </row> | ||
| 1819 | |||
| 1820 | <row> | ||
| 1821 | <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry> | ||
| 1822 | <entry>integer</entry> | ||
| 1823 | </row><row><entry spanname="descr">Switch the band-stop filter of a | ||
| 1824 | camera sensor on or off, or specify its strength. Such band-stop filters can | ||
| 1825 | be used, for example, to filter out the fluorescent light component.</entry> | ||
| 1826 | </row> | ||
| 1827 | <row><entry></entry></row> | ||
| 1828 | </tbody> | ||
| 1829 | </tgroup> | ||
| 1830 | </table> | ||
| 1831 | </section> | ||
| 1832 | |||
| 1833 | <section id="fm-tx-controls"> | ||
| 1834 | <title>FM Transmitter Control Reference</title> | ||
| 1835 | |||
| 1836 | <para>The FM Transmitter (FM_TX) class includes controls for common features of | ||
| 1837 | FM transmissions capable devices. Currently this class includes parameters for audio | ||
| 1838 | compression, pilot tone generation, audio deviation limiter, RDS transmission and | ||
| 1839 | tuning power features.</para> | ||
| 1840 | |||
| 1841 | <table pgwide="1" frame="none" id="fm-tx-control-id"> | ||
| 1842 | <title>FM_TX Control IDs</title> | ||
| 1843 | |||
| 1844 | <tgroup cols="4"> | ||
| 1845 | <colspec colname="c1" colwidth="1*" /> | ||
| 1846 | <colspec colname="c2" colwidth="6*" /> | ||
| 1847 | <colspec colname="c3" colwidth="2*" /> | ||
| 1848 | <colspec colname="c4" colwidth="6*" /> | ||
| 1849 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1850 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1851 | <thead> | ||
| 1852 | <row> | ||
| 1853 | <entry spanname="id" align="left">ID</entry> | ||
| 1854 | <entry align="left">Type</entry> | ||
| 1855 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 1856 | </row> | ||
| 1857 | </thead> | ||
| 1858 | <tbody valign="top"> | ||
| 1859 | <row><entry></entry></row> | ||
| 1860 | <row> | ||
| 1861 | <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry> | ||
| 1862 | <entry>class</entry> | ||
| 1863 | </row><row><entry spanname="descr">The FM_TX class | ||
| 1864 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 1865 | description of this control class.</entry> | ||
| 1866 | </row> | ||
| 1867 | <row> | ||
| 1868 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry> | ||
| 1869 | <entry>integer</entry> | ||
| 1870 | </row> | ||
| 1871 | <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz. | ||
| 1872 | The range and step are driver-specific.</entry> | ||
| 1873 | </row> | ||
| 1874 | <row> | ||
| 1875 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry> | ||
| 1876 | <entry>integer</entry> | ||
| 1877 | </row> | ||
| 1878 | <row><entry spanname="descr">Sets the RDS Programme Identification field | ||
| 1879 | for transmission.</entry> | ||
| 1880 | </row> | ||
| 1881 | <row> | ||
| 1882 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry> | ||
| 1883 | <entry>integer</entry> | ||
| 1884 | </row> | ||
| 1885 | <row><entry spanname="descr">Sets the RDS Programme Type field for transmission. | ||
| 1886 | This encodes up to 31 pre-defined programme types.</entry> | ||
| 1887 | </row> | ||
| 1888 | <row> | ||
| 1889 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry> | ||
| 1890 | <entry>string</entry> | ||
| 1891 | </row> | ||
| 1892 | <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission. | ||
| 1893 | It is intended for static display on a receiver. It is the primary aid to listeners in programme service | ||
| 1894 | identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification, | ||
| 1895 | there is a full description of the correct character encoding for Programme Service name strings. | ||
| 1896 | Also from RDS specification, PS is usually a single eight character text. However, it is also possible | ||
| 1897 | to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured | ||
| 1898 | with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry> | ||
| 1899 | </row> | ||
| 1900 | <row> | ||
| 1901 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry> | ||
| 1902 | <entry>string</entry> | ||
| 1903 | </row> | ||
| 1904 | <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of | ||
| 1905 | what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, | ||
| 1906 | programme-related information or any other text. In these cases, RadioText should be used in addition to | ||
| 1907 | <constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described | ||
| 1908 | in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being | ||
| 1909 | used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible | ||
| 1910 | to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured | ||
| 1911 | with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> | ||
| 1912 | </row> | ||
| 1913 | <row> | ||
| 1914 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry> | ||
| 1915 | <entry>boolean</entry> | ||
| 1916 | </row> | ||
| 1917 | <row><entry spanname="descr">Enables or disables the audio deviation limiter feature. | ||
| 1918 | The limiter is useful when trying to maximize the audio volume, minimize receiver-generated | ||
| 1919 | distortion and prevent overmodulation. | ||
| 1920 | </entry> | ||
| 1921 | </row> | ||
| 1922 | <row> | ||
| 1923 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry> | ||
| 1924 | <entry>integer</entry> | ||
| 1925 | </row> | ||
| 1926 | <row><entry spanname="descr">Sets the audio deviation limiter feature release time. | ||
| 1927 | Unit is in useconds. Step and range are driver-specific.</entry> | ||
| 1928 | </row> | ||
| 1929 | <row> | ||
| 1930 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry> | ||
| 1931 | <entry>integer</entry> | ||
| 1932 | </row> | ||
| 1933 | <row><entry spanname="descr">Configures audio frequency deviation level in Hz. | ||
| 1934 | The range and step are driver-specific.</entry> | ||
| 1935 | </row> | ||
| 1936 | <row> | ||
| 1937 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry> | ||
| 1938 | <entry>boolean</entry> | ||
| 1939 | </row> | ||
| 1940 | <row><entry spanname="descr">Enables or disables the audio compression feature. | ||
| 1941 | This feature amplifies signals below the threshold by a fixed gain and compresses audio | ||
| 1942 | signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry> | ||
| 1943 | </row> | ||
| 1944 | <row> | ||
| 1945 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry> | ||
| 1946 | <entry>integer</entry> | ||
| 1947 | </row> | ||
| 1948 | <row><entry spanname="descr">Sets the gain for audio compression feature. It is | ||
| 1949 | a dB value. The range and step are driver-specific.</entry> | ||
| 1950 | </row> | ||
| 1951 | <row> | ||
| 1952 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry> | ||
| 1953 | <entry>integer</entry> | ||
| 1954 | </row> | ||
| 1955 | <row><entry spanname="descr">Sets the threshold level for audio compression freature. | ||
| 1956 | It is a dB value. The range and step are driver-specific.</entry> | ||
| 1957 | </row> | ||
| 1958 | <row> | ||
| 1959 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry> | ||
| 1960 | <entry>integer</entry> | ||
| 1961 | </row> | ||
| 1962 | <row><entry spanname="descr">Sets the attack time for audio compression feature. | ||
| 1963 | It is a useconds value. The range and step are driver-specific.</entry> | ||
| 1964 | </row> | ||
| 1965 | <row> | ||
| 1966 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry> | ||
| 1967 | <entry>integer</entry> | ||
| 1968 | </row> | ||
| 1969 | <row><entry spanname="descr">Sets the release time for audio compression feature. | ||
| 1970 | It is a useconds value. The range and step are driver-specific.</entry> | ||
| 1971 | </row> | ||
| 1972 | <row> | ||
| 1973 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry> | ||
| 1974 | <entry>boolean</entry> | ||
| 1975 | </row> | ||
| 1976 | <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry> | ||
| 1977 | </row> | ||
| 1978 | <row> | ||
| 1979 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry> | ||
| 1980 | <entry>integer</entry> | ||
| 1981 | </row> | ||
| 1982 | <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is | ||
| 1983 | in Hz. The range and step are driver-specific.</entry> | ||
| 1984 | </row> | ||
| 1985 | <row> | ||
| 1986 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry> | ||
| 1987 | <entry>integer</entry> | ||
| 1988 | </row> | ||
| 1989 | <row><entry spanname="descr">Configures pilot tone frequency value. Unit is | ||
| 1990 | in Hz. The range and step are driver-specific.</entry> | ||
| 1991 | </row> | ||
| 1992 | <row> | ||
| 1993 | <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry> | ||
| 1994 | <entry>integer</entry> | ||
| 1995 | </row> | ||
| 1996 | <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting. | ||
| 1997 | A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. | ||
| 1998 | Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis | ||
| 1999 | defines possible values for pre-emphasis. Here they are:</entry> | ||
| 2000 | </row><row> | ||
| 2001 | <entrytbl spanname="descr" cols="2"> | ||
| 2002 | <tbody valign="top"> | ||
| 2003 | <row> | ||
| 2004 | <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry> | ||
| 2005 | <entry>No pre-emphasis is applied.</entry> | ||
| 2006 | </row> | ||
| 2007 | <row> | ||
| 2008 | <entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry> | ||
| 2009 | <entry>A pre-emphasis of 50 uS is used.</entry> | ||
| 2010 | </row> | ||
| 2011 | <row> | ||
| 2012 | <entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry> | ||
| 2013 | <entry>A pre-emphasis of 75 uS is used.</entry> | ||
| 2014 | </row> | ||
| 2015 | </tbody> | ||
| 2016 | </entrytbl> | ||
| 2017 | |||
| 2018 | </row> | ||
| 2019 | <row> | ||
| 2020 | <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry> | ||
| 2021 | <entry>integer</entry> | ||
| 2022 | </row> | ||
| 2023 | <row><entry spanname="descr">Sets the output power level for signal transmission. | ||
| 2024 | Unit is in dBuV. Range and step are driver-specific.</entry> | ||
| 2025 | </row> | ||
| 2026 | <row> | ||
| 2027 | <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry> | ||
| 2028 | <entry>integer</entry> | ||
| 2029 | </row> | ||
| 2030 | <row><entry spanname="descr">This selects the value of antenna tuning capacitor | ||
| 2031 | manually or automatically if set to zero. Unit, range and step are driver-specific.</entry> | ||
| 2032 | </row> | ||
| 2033 | <row><entry></entry></row> | ||
| 2034 | </tbody> | ||
| 2035 | </tgroup> | ||
| 2036 | </table> | ||
| 2037 | |||
| 2038 | <para>For more details about RDS specification, refer to | ||
| 2039 | <xref linkend="en50067" /> document, from CENELEC.</para> | ||
| 2040 | </section> | ||
| 2041 | </section> | ||
| 2042 | |||
| 2043 | <!-- | ||
| 2044 | Local Variables: | ||
| 2045 | mode: sgml | ||
| 2046 | sgml-parent-document: "common.sgml" | ||
| 2047 | indent-tabs-mode: nil | ||
| 2048 | End: | ||
| 2049 | --> | ||
diff --git a/Documentation/DocBook/v4l/crop.gif b/Documentation/DocBook/v4l/crop.gif new file mode 100644 index 000000000000..3b9e7d836d4b --- /dev/null +++ b/Documentation/DocBook/v4l/crop.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/crop.pdf b/Documentation/DocBook/v4l/crop.pdf new file mode 100644 index 000000000000..c9fb81cd32f3 --- /dev/null +++ b/Documentation/DocBook/v4l/crop.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml new file mode 100644 index 000000000000..32807e43f170 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-capture.xml | |||
| @@ -0,0 +1,115 @@ | |||
| 1 | <title>Video Capture Interface</title> | ||
| 2 | |||
| 3 | <para>Video capture devices sample an analog video signal and store | ||
| 4 | the digitized images in memory. Today nearly all devices can capture | ||
| 5 | at full 25 or 30 frames/second. With this interface applications can | ||
| 6 | control the capture process and move images from the driver into user | ||
| 7 | space.</para> | ||
| 8 | |||
| 9 | <para>Conventionally V4L2 video capture devices are accessed through | ||
| 10 | character device special files named <filename>/dev/video</filename> | ||
| 11 | and <filename>/dev/video0</filename> to | ||
| 12 | <filename>/dev/video63</filename> with major number 81 and minor | ||
| 13 | numbers 0 to 63. <filename>/dev/video</filename> is typically a | ||
| 14 | symbolic link to the preferred video device. Note the same device | ||
| 15 | files are used for video output devices.</para> | ||
| 16 | |||
| 17 | <section> | ||
| 18 | <title>Querying Capabilities</title> | ||
| 19 | |||
| 20 | <para>Devices supporting the video capture interface set the | ||
| 21 | <constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the | ||
| 22 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 23 | returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions | ||
| 24 | they may also support the <link linkend="overlay">video overlay</link> | ||
| 25 | (<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link | ||
| 26 | linkend="raw-vbi">raw VBI capture</link> | ||
| 27 | (<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of | ||
| 28 | the read/write or streaming I/O methods must be supported. Tuners and | ||
| 29 | audio inputs are optional.</para> | ||
| 30 | </section> | ||
| 31 | |||
| 32 | <section> | ||
| 33 | <title>Supplemental Functions</title> | ||
| 34 | |||
| 35 | <para>Video capture devices shall support <link | ||
| 36 | linkend="audio">audio input</link>, <link | ||
| 37 | linkend="tuner">tuner</link>, <link linkend="control">controls</link>, | ||
| 38 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 39 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 40 | The <link linkend="video">video input</link> and <link | ||
| 41 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 42 | all video capture devices.</para> | ||
| 43 | </section> | ||
| 44 | |||
| 45 | <section> | ||
| 46 | <title>Image Format Negotiation</title> | ||
| 47 | |||
| 48 | <para>The result of a capture operation is determined by | ||
| 49 | cropping and image format parameters. The former select an area of the | ||
| 50 | video picture to capture, the latter how images are stored in memory, | ||
| 51 | &ie; in RGB or YUV format, the number of bits per pixel or width and | ||
| 52 | height. Together they also define how images are scaled in the | ||
| 53 | process.</para> | ||
| 54 | |||
| 55 | <para>As usual these parameters are <emphasis>not</emphasis> reset | ||
| 56 | at &func-open; time to permit Unix tool chains, programming a device | ||
| 57 | and then reading from it as if it was a plain file. Well written V4L2 | ||
| 58 | applications ensure they really get what they want, including cropping | ||
| 59 | and scaling.</para> | ||
| 60 | |||
| 61 | <para>Cropping initialization at minimum requires to reset the | ||
| 62 | parameters to defaults. An example is given in <xref | ||
| 63 | linkend="crop" />.</para> | ||
| 64 | |||
| 65 | <para>To query the current image format applications set the | ||
| 66 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 67 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the | ||
| 68 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 69 | the &v4l2-pix-format; <structfield>pix</structfield> member of the | ||
| 70 | <structfield>fmt</structfield> union.</para> | ||
| 71 | |||
| 72 | <para>To request different parameters applications set the | ||
| 73 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 74 | initialize all fields of the &v4l2-pix-format; | ||
| 75 | <structfield>vbi</structfield> member of the | ||
| 76 | <structfield>fmt</structfield> union, or better just modify the | ||
| 77 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 78 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may | ||
| 79 | adjust the parameters and finally return the actual parameters as | ||
| 80 | <constant>VIDIOC_G_FMT</constant> does.</para> | ||
| 81 | |||
| 82 | <para>Like <constant>VIDIOC_S_FMT</constant> the | ||
| 83 | &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations | ||
| 84 | without disabling I/O or possibly time consuming hardware | ||
| 85 | preparations.</para> | ||
| 86 | |||
| 87 | <para>The contents of &v4l2-pix-format; are discussed in <xref | ||
| 88 | linkend="pixfmt" />. See also the specification of the | ||
| 89 | <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> | ||
| 90 | and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video | ||
| 91 | capture devices must implement both the | ||
| 92 | <constant>VIDIOC_G_FMT</constant> and | ||
| 93 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 94 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 95 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 96 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 97 | </section> | ||
| 98 | |||
| 99 | <section> | ||
| 100 | <title>Reading Images</title> | ||
| 101 | |||
| 102 | <para>A video capture device may support the <link | ||
| 103 | linkend="rw">read() function</link> and/or streaming (<link | ||
| 104 | linkend="mmap">memory mapping</link> or <link | ||
| 105 | linkend="userp">user pointer</link>) I/O. See <xref | ||
| 106 | linkend="io" /> for details.</para> | ||
| 107 | </section> | ||
| 108 | |||
| 109 | <!-- | ||
| 110 | Local Variables: | ||
| 111 | mode: sgml | ||
| 112 | sgml-parent-document: "v4l2.sgml" | ||
| 113 | indent-tabs-mode: nil | ||
| 114 | End: | ||
| 115 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-codec.xml b/Documentation/DocBook/v4l/dev-codec.xml new file mode 100644 index 000000000000..6e156dc45b94 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-codec.xml | |||
| @@ -0,0 +1,26 @@ | |||
| 1 | <title>Codec Interface</title> | ||
| 2 | |||
| 3 | <note> | ||
| 4 | <title>Suspended</title> | ||
| 5 | |||
| 6 | <para>This interface has been be suspended from the V4L2 API | ||
| 7 | implemented in Linux 2.6 until we have more experience with codec | ||
| 8 | device interfaces.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>A V4L2 codec can compress, decompress, transform, or otherwise | ||
| 12 | convert video data from one format into another format, in memory. | ||
| 13 | Applications send data to be converted to the driver through a | ||
| 14 | &func-write; call, and receive the converted data through a | ||
| 15 | &func-read; call. For efficiency a driver may also support streaming | ||
| 16 | I/O.</para> | ||
| 17 | |||
| 18 | <para>[to do]</para> | ||
| 19 | |||
| 20 | <!-- | ||
| 21 | Local Variables: | ||
| 22 | mode: sgml | ||
| 23 | sgml-parent-document: "v4l2.sgml" | ||
| 24 | indent-tabs-mode: nil | ||
| 25 | End: | ||
| 26 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-effect.xml b/Documentation/DocBook/v4l/dev-effect.xml new file mode 100644 index 000000000000..9c243beba0e6 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-effect.xml | |||
| @@ -0,0 +1,25 @@ | |||
| 1 | <title>Effect Devices Interface</title> | ||
| 2 | |||
| 3 | <note> | ||
| 4 | <title>Suspended</title> | ||
| 5 | |||
| 6 | <para>This interface has been be suspended from the V4L2 API | ||
| 7 | implemented in Linux 2.6 until we have more experience with effect | ||
| 8 | device interfaces.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>A V4L2 video effect device can do image effects, filtering, or | ||
| 12 | combine two or more images or image streams. For example video | ||
| 13 | transitions or wipes. Applications send data to be processed and | ||
| 14 | receive the result data either with &func-read; and &func-write; | ||
| 15 | functions, or through the streaming I/O mechanism.</para> | ||
| 16 | |||
| 17 | <para>[to do]</para> | ||
| 18 | |||
| 19 | <!-- | ||
| 20 | Local Variables: | ||
| 21 | mode: sgml | ||
| 22 | sgml-parent-document: "v4l2.sgml" | ||
| 23 | indent-tabs-mode: nil | ||
| 24 | End: | ||
| 25 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-osd.xml b/Documentation/DocBook/v4l/dev-osd.xml new file mode 100644 index 000000000000..c9a68a2ccd33 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-osd.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <title>Video Output Overlay Interface</title> | ||
| 2 | <subtitle>Also known as On-Screen Display (OSD)</subtitle> | ||
| 3 | |||
| 4 | <note> | ||
| 5 | <title>Experimental</title> | ||
| 6 | |||
| 7 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 8 | interface and may change in the future.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>Some video output devices can overlay a framebuffer image onto | ||
| 12 | the outgoing video signal. Applications can set up such an overlay | ||
| 13 | using this interface, which borrows structures and ioctls of the <link | ||
| 14 | linkend="overlay">Video Overlay</link> interface.</para> | ||
| 15 | |||
| 16 | <para>The OSD function is accessible through the same character | ||
| 17 | special file as the <link linkend="capture">Video Output</link> function. | ||
| 18 | Note the default function of such a <filename>/dev/video</filename> device | ||
| 19 | is video capturing or output. The OSD function is only available after | ||
| 20 | calling the &VIDIOC-S-FMT; ioctl.</para> | ||
| 21 | |||
| 22 | <section> | ||
| 23 | <title>Querying Capabilities</title> | ||
| 24 | |||
| 25 | <para>Devices supporting the <wordasword>Video Output | ||
| 26 | Overlay</wordasword> interface set the | ||
| 27 | <constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the | ||
| 28 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 29 | returned by the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 30 | </section> | ||
| 31 | |||
| 32 | <section> | ||
| 33 | <title>Framebuffer</title> | ||
| 34 | |||
| 35 | <para>Contrary to the <wordasword>Video Overlay</wordasword> | ||
| 36 | interface the framebuffer is normally implemented on the TV card and | ||
| 37 | not the graphics card. On Linux it is accessible as a framebuffer | ||
| 38 | device (<filename>/dev/fbN</filename>). Given a V4L2 device, | ||
| 39 | applications can find the corresponding framebuffer device by calling | ||
| 40 | the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the | ||
| 41 | physical address of the framebuffer in the | ||
| 42 | <structfield>base</structfield> field of &v4l2-framebuffer;. The | ||
| 43 | framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant> | ||
| 44 | returns the same address in the <structfield>smem_start</structfield> | ||
| 45 | field of struct <structname>fb_fix_screeninfo</structname>. The | ||
| 46 | <constant>FBIOGET_FSCREENINFO</constant> ioctl and struct | ||
| 47 | <structname>fb_fix_screeninfo</structname> are defined in the | ||
| 48 | <filename>linux/fb.h</filename> header file.</para> | ||
| 49 | |||
| 50 | <para>The width and height of the framebuffer depends on the | ||
| 51 | current video standard. A V4L2 driver may reject attempts to change | ||
| 52 | the video standard (or any other ioctl which would imply a framebuffer | ||
| 53 | size change) with an &EBUSY; until all applications closed the | ||
| 54 | framebuffer device.</para> | ||
| 55 | |||
| 56 | <example> | ||
| 57 | <title>Finding a framebuffer device for OSD</title> | ||
| 58 | |||
| 59 | <programlisting> | ||
| 60 | #include <linux/fb.h> | ||
| 61 | |||
| 62 | &v4l2-framebuffer; fbuf; | ||
| 63 | unsigned int i; | ||
| 64 | int fb_fd; | ||
| 65 | |||
| 66 | if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { | ||
| 67 | perror ("VIDIOC_G_FBUF"); | ||
| 68 | exit (EXIT_FAILURE); | ||
| 69 | } | ||
| 70 | |||
| 71 | for (i = 0; i > 30; ++i) { | ||
| 72 | char dev_name[16]; | ||
| 73 | struct fb_fix_screeninfo si; | ||
| 74 | |||
| 75 | snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i); | ||
| 76 | |||
| 77 | fb_fd = open (dev_name, O_RDWR); | ||
| 78 | if (-1 == fb_fd) { | ||
| 79 | switch (errno) { | ||
| 80 | case ENOENT: /* no such file */ | ||
| 81 | case ENXIO: /* no driver */ | ||
| 82 | continue; | ||
| 83 | |||
| 84 | default: | ||
| 85 | perror ("open"); | ||
| 86 | exit (EXIT_FAILURE); | ||
| 87 | } | ||
| 88 | } | ||
| 89 | |||
| 90 | if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) { | ||
| 91 | if (si.smem_start == (unsigned long) fbuf.base) | ||
| 92 | break; | ||
| 93 | } else { | ||
| 94 | /* Apparently not a framebuffer device. */ | ||
| 95 | } | ||
| 96 | |||
| 97 | close (fb_fd); | ||
| 98 | fb_fd = -1; | ||
| 99 | } | ||
| 100 | |||
| 101 | /* fb_fd is the file descriptor of the framebuffer device | ||
| 102 | for the video output overlay, or -1 if no device was found. */ | ||
| 103 | </programlisting> | ||
| 104 | </example> | ||
| 105 | </section> | ||
| 106 | |||
| 107 | <section> | ||
| 108 | <title>Overlay Window and Scaling</title> | ||
| 109 | |||
| 110 | <para>The overlay is controlled by source and target rectangles. | ||
| 111 | The source rectangle selects a subsection of the framebuffer image to | ||
| 112 | be overlaid, the target rectangle an area in the outgoing video signal | ||
| 113 | where the image will appear. Drivers may or may not support scaling, | ||
| 114 | and arbitrary sizes and positions of these rectangles. Further drivers | ||
| 115 | may support any (or none) of the clipping/blending methods defined for | ||
| 116 | the <link linkend="overlay">Video Overlay</link> interface.</para> | ||
| 117 | |||
| 118 | <para>A &v4l2-window; defines the size of the source rectangle, | ||
| 119 | its position in the framebuffer and the clipping/blending method to be | ||
| 120 | used for the overlay. To get the current parameters applications set | ||
| 121 | the <structfield>type</structfield> field of a &v4l2-format; to | ||
| 122 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the | ||
| 123 | &VIDIOC-G-FMT; ioctl. The driver fills the | ||
| 124 | <structname>v4l2_window</structname> substructure named | ||
| 125 | <structfield>win</structfield>. It is not possible to retrieve a | ||
| 126 | previously programmed clipping list or bitmap.</para> | ||
| 127 | |||
| 128 | <para>To program the source rectangle applications set the | ||
| 129 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 130 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize | ||
| 131 | the <structfield>win</structfield> substructure and call the | ||
| 132 | &VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against | ||
| 133 | hardware limits and returns the actual parameters as | ||
| 134 | <constant>VIDIOC_G_FMT</constant> does. Like | ||
| 135 | <constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be | ||
| 136 | used to learn about driver capabilities without actually changing | ||
| 137 | driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works | ||
| 138 | after the overlay has been enabled.</para> | ||
| 139 | |||
| 140 | <para>A &v4l2-crop; defines the size and position of the target | ||
| 141 | rectangle. The scaling factor of the overlay is implied by the width | ||
| 142 | and height given in &v4l2-window; and &v4l2-crop;. The cropping API | ||
| 143 | applies to <wordasword>Video Output</wordasword> and <wordasword>Video | ||
| 144 | Output Overlay</wordasword> devices in the same way as to | ||
| 145 | <wordasword>Video Capture</wordasword> and <wordasword>Video | ||
| 146 | Overlay</wordasword> devices, merely reversing the direction of the | ||
| 147 | data flow. For more information see <xref linkend="crop" />.</para> | ||
| 148 | </section> | ||
| 149 | |||
| 150 | <section> | ||
| 151 | <title>Enabling Overlay</title> | ||
| 152 | |||
| 153 | <para>There is no V4L2 ioctl to enable or disable the overlay, | ||
| 154 | however the framebuffer interface of the driver may support the | ||
| 155 | <constant>FBIOBLANK</constant> ioctl.</para> | ||
| 156 | </section> | ||
| 157 | |||
| 158 | <!-- | ||
| 159 | Local Variables: | ||
| 160 | mode: sgml | ||
| 161 | sgml-parent-document: "v4l2.sgml" | ||
| 162 | indent-tabs-mode: nil | ||
| 163 | End: | ||
| 164 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml new file mode 100644 index 000000000000..63c3c20e5a72 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-output.xml | |||
| @@ -0,0 +1,111 @@ | |||
| 1 | <title>Video Output Interface</title> | ||
| 2 | |||
| 3 | <para>Video output devices encode stills or image sequences as | ||
| 4 | analog video signal. With this interface applications can | ||
| 5 | control the encoding process and move images from user space to | ||
| 6 | the driver.</para> | ||
| 7 | |||
| 8 | <para>Conventionally V4L2 video output devices are accessed through | ||
| 9 | character device special files named <filename>/dev/video</filename> | ||
| 10 | and <filename>/dev/video0</filename> to | ||
| 11 | <filename>/dev/video63</filename> with major number 81 and minor | ||
| 12 | numbers 0 to 63. <filename>/dev/video</filename> is typically a | ||
| 13 | symbolic link to the preferred video device. Note the same device | ||
| 14 | files are used for video capture devices.</para> | ||
| 15 | |||
| 16 | <section> | ||
| 17 | <title>Querying Capabilities</title> | ||
| 18 | |||
| 19 | <para>Devices supporting the video output interface set the | ||
| 20 | <constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the | ||
| 21 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 22 | returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions | ||
| 23 | they may also support the <link linkend="raw-vbi">raw VBI | ||
| 24 | output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At | ||
| 25 | least one of the read/write or streaming I/O methods must be | ||
| 26 | supported. Modulators and audio outputs are optional.</para> | ||
| 27 | </section> | ||
| 28 | |||
| 29 | <section> | ||
| 30 | <title>Supplemental Functions</title> | ||
| 31 | |||
| 32 | <para>Video output devices shall support <link | ||
| 33 | linkend="audio">audio output</link>, <link | ||
| 34 | linkend="tuner">modulator</link>, <link linkend="control">controls</link>, | ||
| 35 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 36 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 37 | The <link linkend="video">video output</link> and <link | ||
| 38 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 39 | all video output devices.</para> | ||
| 40 | </section> | ||
| 41 | |||
| 42 | <section> | ||
| 43 | <title>Image Format Negotiation</title> | ||
| 44 | |||
| 45 | <para>The output is determined by cropping and image format | ||
| 46 | parameters. The former select an area of the video picture where the | ||
| 47 | image will appear, the latter how images are stored in memory, &ie; in | ||
| 48 | RGB or YUV format, the number of bits per pixel or width and height. | ||
| 49 | Together they also define how images are scaled in the process.</para> | ||
| 50 | |||
| 51 | <para>As usual these parameters are <emphasis>not</emphasis> reset | ||
| 52 | at &func-open; time to permit Unix tool chains, programming a device | ||
| 53 | and then writing to it as if it was a plain file. Well written V4L2 | ||
| 54 | applications ensure they really get what they want, including cropping | ||
| 55 | and scaling.</para> | ||
| 56 | |||
| 57 | <para>Cropping initialization at minimum requires to reset the | ||
| 58 | parameters to defaults. An example is given in <xref | ||
| 59 | linkend="crop" />.</para> | ||
| 60 | |||
| 61 | <para>To query the current image format applications set the | ||
| 62 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 63 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the | ||
| 64 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 65 | the &v4l2-pix-format; <structfield>pix</structfield> member of the | ||
| 66 | <structfield>fmt</structfield> union.</para> | ||
| 67 | |||
| 68 | <para>To request different parameters applications set the | ||
| 69 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 70 | initialize all fields of the &v4l2-pix-format; | ||
| 71 | <structfield>vbi</structfield> member of the | ||
| 72 | <structfield>fmt</structfield> union, or better just modify the | ||
| 73 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 74 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may | ||
| 75 | adjust the parameters and finally return the actual parameters as | ||
| 76 | <constant>VIDIOC_G_FMT</constant> does.</para> | ||
| 77 | |||
| 78 | <para>Like <constant>VIDIOC_S_FMT</constant> the | ||
| 79 | &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations | ||
| 80 | without disabling I/O or possibly time consuming hardware | ||
| 81 | preparations.</para> | ||
| 82 | |||
| 83 | <para>The contents of &v4l2-pix-format; are discussed in <xref | ||
| 84 | linkend="pixfmt" />. See also the specification of the | ||
| 85 | <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> | ||
| 86 | and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video | ||
| 87 | output devices must implement both the | ||
| 88 | <constant>VIDIOC_G_FMT</constant> and | ||
| 89 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 90 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 91 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 92 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 93 | </section> | ||
| 94 | |||
| 95 | <section> | ||
| 96 | <title>Writing Images</title> | ||
| 97 | |||
| 98 | <para>A video output device may support the <link | ||
| 99 | linkend="rw">write() function</link> and/or streaming (<link | ||
| 100 | linkend="mmap">memory mapping</link> or <link | ||
| 101 | linkend="userp">user pointer</link>) I/O. See <xref | ||
| 102 | linkend="io" /> for details.</para> | ||
| 103 | </section> | ||
| 104 | |||
| 105 | <!-- | ||
| 106 | Local Variables: | ||
| 107 | mode: sgml | ||
| 108 | sgml-parent-document: "v4l2.sgml" | ||
| 109 | indent-tabs-mode: nil | ||
| 110 | End: | ||
| 111 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-overlay.xml b/Documentation/DocBook/v4l/dev-overlay.xml new file mode 100644 index 000000000000..92513cf79150 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-overlay.xml | |||
| @@ -0,0 +1,379 @@ | |||
| 1 | <title>Video Overlay Interface</title> | ||
| 2 | <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle> | ||
| 3 | |||
| 4 | <para>Video overlay devices have the ability to genlock (TV-)video | ||
| 5 | into the (VGA-)video signal of a graphics card, or to store captured | ||
| 6 | images directly in video memory of a graphics card, typically with | ||
| 7 | clipping. This can be considerable more efficient than capturing | ||
| 8 | images and displaying them by other means. In the old days when only | ||
| 9 | nuclear power plants needed cooling towers this used to be the only | ||
| 10 | way to put live video into a window.</para> | ||
| 11 | |||
| 12 | <para>Video overlay devices are accessed through the same character | ||
| 13 | special files as <link linkend="capture">video capture</link> devices. | ||
| 14 | Note the default function of a <filename>/dev/video</filename> device | ||
| 15 | is video capturing. The overlay function is only available after | ||
| 16 | calling the &VIDIOC-S-FMT; ioctl.</para> | ||
| 17 | |||
| 18 | <para>The driver may support simultaneous overlay and capturing | ||
| 19 | using the read/write and streaming I/O methods. If so, operation at | ||
| 20 | the nominal frame rate of the video standard is not guaranteed. Frames | ||
| 21 | may be directed away from overlay to capture, or one field may be used | ||
| 22 | for overlay and the other for capture if the capture parameters permit | ||
| 23 | this.</para> | ||
| 24 | |||
| 25 | <para>Applications should use different file descriptors for | ||
| 26 | capturing and overlay. This must be supported by all drivers capable | ||
| 27 | of simultaneous capturing and overlay. Optionally these drivers may | ||
| 28 | also permit capturing and overlay with a single file descriptor for | ||
| 29 | compatibility with V4L and earlier versions of V4L2.<footnote> | ||
| 30 | <para>A common application of two file descriptors is the | ||
| 31 | XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and | ||
| 32 | a V4L2 application. While the X server controls video overlay, the | ||
| 33 | application can take advantage of memory mapping and DMA.</para> | ||
| 34 | <para>In the opinion of the designers of this API, no driver | ||
| 35 | writer taking the efforts to support simultaneous capturing and | ||
| 36 | overlay will restrict this ability by requiring a single file | ||
| 37 | descriptor, as in V4L and earlier versions of V4L2. Making this | ||
| 38 | optional means applications depending on two file descriptors need | ||
| 39 | backup routines to be compatible with all drivers, which is | ||
| 40 | considerable more work than using two fds in applications which do | ||
| 41 | not. Also two fd's fit the general concept of one file descriptor for | ||
| 42 | each logical stream. Hence as a complexity trade-off drivers | ||
| 43 | <emphasis>must</emphasis> support two file descriptors and | ||
| 44 | <emphasis>may</emphasis> support single fd operation.</para> | ||
| 45 | </footnote></para> | ||
| 46 | |||
| 47 | <section> | ||
| 48 | <title>Querying Capabilities</title> | ||
| 49 | |||
| 50 | <para>Devices supporting the video overlay interface set the | ||
| 51 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the | ||
| 52 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 53 | returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified | ||
| 54 | below must be supported. Tuners and audio inputs are optional.</para> | ||
| 55 | </section> | ||
| 56 | |||
| 57 | <section> | ||
| 58 | <title>Supplemental Functions</title> | ||
| 59 | |||
| 60 | <para>Video overlay devices shall support <link | ||
| 61 | linkend="audio">audio input</link>, <link | ||
| 62 | linkend="tuner">tuner</link>, <link linkend="control">controls</link>, | ||
| 63 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 64 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 65 | The <link linkend="video">video input</link> and <link | ||
| 66 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 67 | all video overlay devices.</para> | ||
| 68 | </section> | ||
| 69 | |||
| 70 | <section> | ||
| 71 | <title>Setup</title> | ||
| 72 | |||
| 73 | <para>Before overlay can commence applications must program the | ||
| 74 | driver with frame buffer parameters, namely the address and size of | ||
| 75 | the frame buffer and the image format, for example RGB 5:6:5. The | ||
| 76 | &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get | ||
| 77 | and set these parameters, respectively. The | ||
| 78 | <constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it | ||
| 79 | allows to set up DMA into physical memory, bypassing the memory | ||
| 80 | protection mechanisms of the kernel. Only the superuser can change the | ||
| 81 | frame buffer address and size. Users are not supposed to run TV | ||
| 82 | applications as root or with SUID bit set. A small helper application | ||
| 83 | with suitable privileges should query the graphics system and program | ||
| 84 | the V4L2 driver at the appropriate time.</para> | ||
| 85 | |||
| 86 | <para>Some devices add the video overlay to the output signal | ||
| 87 | of the graphics card. In this case the frame buffer is not modified by | ||
| 88 | the video device, and the frame buffer address and pixel format are | ||
| 89 | not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl | ||
| 90 | is not privileged. An application can check for this type of device by | ||
| 91 | calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para> | ||
| 92 | |||
| 93 | <para>A driver may support any (or none) of five clipping/blending | ||
| 94 | methods:<orderedlist> | ||
| 95 | <listitem> | ||
| 96 | <para>Chroma-keying displays the overlaid image only where | ||
| 97 | pixels in the primary graphics surface assume a certain color.</para> | ||
| 98 | </listitem> | ||
| 99 | <listitem> | ||
| 100 | <para>A bitmap can be specified where each bit corresponds | ||
| 101 | to a pixel in the overlaid image. When the bit is set, the | ||
| 102 | corresponding video pixel is displayed, otherwise a pixel of the | ||
| 103 | graphics surface.</para> | ||
| 104 | </listitem> | ||
| 105 | <listitem> | ||
| 106 | <para>A list of clipping rectangles can be specified. In | ||
| 107 | these regions <emphasis>no</emphasis> video is displayed, so the | ||
| 108 | graphics surface can be seen here.</para> | ||
| 109 | </listitem> | ||
| 110 | <listitem> | ||
| 111 | <para>The framebuffer has an alpha channel that can be used | ||
| 112 | to clip or blend the framebuffer with the video.</para> | ||
| 113 | </listitem> | ||
| 114 | <listitem> | ||
| 115 | <para>A global alpha value can be specified to blend the | ||
| 116 | framebuffer contents with video images.</para> | ||
| 117 | </listitem> | ||
| 118 | </orderedlist></para> | ||
| 119 | |||
| 120 | <para>When simultaneous capturing and overlay is supported and | ||
| 121 | the hardware prohibits different image and frame buffer formats, the | ||
| 122 | format requested first takes precedence. The attempt to capture | ||
| 123 | (&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an | ||
| 124 | &EBUSY; or return accordingly modified parameters..</para> | ||
| 125 | </section> | ||
| 126 | |||
| 127 | <section> | ||
| 128 | <title>Overlay Window</title> | ||
| 129 | |||
| 130 | <para>The overlaid image is determined by cropping and overlay | ||
| 131 | window parameters. The former select an area of the video picture to | ||
| 132 | capture, the latter how images are overlaid and clipped. Cropping | ||
| 133 | initialization at minimum requires to reset the parameters to | ||
| 134 | defaults. An example is given in <xref linkend="crop" />.</para> | ||
| 135 | |||
| 136 | <para>The overlay window is described by a &v4l2-window;. It | ||
| 137 | defines the size of the image, its position over the graphics surface | ||
| 138 | and the clipping to be applied. To get the current parameters | ||
| 139 | applications set the <structfield>type</structfield> field of a | ||
| 140 | &v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and | ||
| 141 | call the &VIDIOC-G-FMT; ioctl. The driver fills the | ||
| 142 | <structname>v4l2_window</structname> substructure named | ||
| 143 | <structfield>win</structfield>. It is not possible to retrieve a | ||
| 144 | previously programmed clipping list or bitmap.</para> | ||
| 145 | |||
| 146 | <para>To program the overlay window applications set the | ||
| 147 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 148 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the | ||
| 149 | <structfield>win</structfield> substructure and call the | ||
| 150 | &VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against | ||
| 151 | hardware limits and returns the actual parameters as | ||
| 152 | <constant>VIDIOC_G_FMT</constant> does. Like | ||
| 153 | <constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be | ||
| 154 | used to learn about driver capabilities without actually changing | ||
| 155 | driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works | ||
| 156 | after the overlay has been enabled.</para> | ||
| 157 | |||
| 158 | <para>The scaling factor of the overlaid image is implied by the | ||
| 159 | width and height given in &v4l2-window; and the size of the cropping | ||
| 160 | rectangle. For more information see <xref linkend="crop" />.</para> | ||
| 161 | |||
| 162 | <para>When simultaneous capturing and overlay is supported and | ||
| 163 | the hardware prohibits different image and window sizes, the size | ||
| 164 | requested first takes precedence. The attempt to capture or overlay as | ||
| 165 | well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly | ||
| 166 | modified parameters.</para> | ||
| 167 | |||
| 168 | <table pgwide="1" frame="none" id="v4l2-window"> | ||
| 169 | <title>struct <structname>v4l2_window</structname></title> | ||
| 170 | <tgroup cols="3"> | ||
| 171 | &cs-str; | ||
| 172 | <tbody valign="top"> | ||
| 173 | <row> | ||
| 174 | <entry>&v4l2-rect;</entry> | ||
| 175 | <entry><structfield>w</structfield></entry> | ||
| 176 | <entry>Size and position of the window relative to the | ||
| 177 | top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The | ||
| 178 | window can extend the frame buffer width and height, the | ||
| 179 | <structfield>x</structfield> and <structfield>y</structfield> | ||
| 180 | coordinates can be negative, and it can lie completely outside the | ||
| 181 | frame buffer. The driver clips the window accordingly, or if that is | ||
| 182 | not possible, modifies its size and/or position.</entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry>&v4l2-field;</entry> | ||
| 186 | <entry><structfield>field</structfield></entry> | ||
| 187 | <entry>Applications set this field to determine which | ||
| 188 | video field shall be overlaid, typically one of | ||
| 189 | <constant>V4L2_FIELD_ANY</constant> (0), | ||
| 190 | <constant>V4L2_FIELD_TOP</constant>, | ||
| 191 | <constant>V4L2_FIELD_BOTTOM</constant> or | ||
| 192 | <constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose | ||
| 193 | a different field order and return the actual setting here.</entry> | ||
| 194 | </row> | ||
| 195 | <row> | ||
| 196 | <entry>__u32</entry> | ||
| 197 | <entry><structfield>chromakey</structfield></entry> | ||
| 198 | <entry>When chroma-keying has been negotiated with | ||
| 199 | &VIDIOC-S-FBUF; applications set this field to the desired pixel value | ||
| 200 | for the chroma key. The format is the same as the pixel format of the | ||
| 201 | framebuffer (&v4l2-framebuffer; | ||
| 202 | <structfield>fmt.pixelformat</structfield> field), with bytes in host | ||
| 203 | order. E. g. for <link | ||
| 204 | linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link> | ||
| 205 | the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big | ||
| 206 | endian host.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry>&v4l2-clip; *</entry> | ||
| 210 | <entry><structfield>clips</structfield></entry> | ||
| 211 | <entry>When chroma-keying has <emphasis>not</emphasis> | ||
| 212 | been negotiated and &VIDIOC-G-FBUF; indicated this capability, | ||
| 213 | applications can set this field to point to an array of | ||
| 214 | clipping rectangles.</entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry></entry> | ||
| 218 | <entry></entry> | ||
| 219 | <entry>Like the window coordinates | ||
| 220 | <structfield>w</structfield>, clipping rectangles are defined relative | ||
| 221 | to the top, left corner of the frame buffer. However clipping | ||
| 222 | rectangles must not extend the frame buffer width and height, and they | ||
| 223 | must not overlap. If possible applications should merge adjacent | ||
| 224 | rectangles. Whether this must create x-y or y-x bands, or the order of | ||
| 225 | rectangles, is not defined. When clip lists are not supported the | ||
| 226 | driver ignores this field. Its contents after calling &VIDIOC-S-FMT; | ||
| 227 | are undefined.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u32</entry> | ||
| 231 | <entry><structfield>clipcount</structfield></entry> | ||
| 232 | <entry>When the application set the | ||
| 233 | <structfield>clips</structfield> field, this field must contain the | ||
| 234 | number of clipping rectangles in the list. When clip lists are not | ||
| 235 | supported the driver ignores this field, its contents after calling | ||
| 236 | <constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are | ||
| 237 | supported but no clipping is desired this field must be set to | ||
| 238 | zero.</entry> | ||
| 239 | </row> | ||
| 240 | <row> | ||
| 241 | <entry>void *</entry> | ||
| 242 | <entry><structfield>bitmap</structfield></entry> | ||
| 243 | <entry>When chroma-keying has | ||
| 244 | <emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated | ||
| 245 | this capability, applications can set this field to point to a | ||
| 246 | clipping bit mask.</entry> | ||
| 247 | </row> | ||
| 248 | <row> | ||
| 249 | <entry spanname="hspan"><para>It must be of the same size | ||
| 250 | as the window, <structfield>w.width</structfield> and | ||
| 251 | <structfield>w.height</structfield>. Each bit corresponds to a pixel | ||
| 252 | in the overlaid image, which is displayed only when the bit is | ||
| 253 | <emphasis>set</emphasis>. Pixel coordinates translate to bits like: | ||
| 254 | <programlisting> | ||
| 255 | ((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] & (1 << (x & 7))</programlisting></para><para>where <structfield>0</structfield> ≤ x < | ||
| 256 | <structfield>w.width</structfield> and <structfield>0</structfield> ≤ | ||
| 257 | y <<structfield>w.height</structfield>.<footnote> | ||
| 258 | <para>Should we require | ||
| 259 | <structfield>w.width</structfield> to be a multiple of | ||
| 260 | eight?</para> | ||
| 261 | </footnote></para><para>When a clipping | ||
| 262 | bit mask is not supported the driver ignores this field, its contents | ||
| 263 | after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported | ||
| 264 | but no clipping is desired this field must be set to | ||
| 265 | <constant>NULL</constant>.</para><para>Applications need not create a | ||
| 266 | clip list or bit mask. When they pass both, or despite negotiating | ||
| 267 | chroma-keying, the results are undefined. Regardless of the chosen | ||
| 268 | method, the clipping abilities of the hardware may be limited in | ||
| 269 | quantity or quality. The results when these limits are exceeded are | ||
| 270 | undefined.<footnote> | ||
| 271 | <para>When the image is written into frame buffer | ||
| 272 | memory it will be undesirable if the driver clips out less pixels | ||
| 273 | than expected, because the application and graphics system are not | ||
| 274 | aware these regions need to be refreshed. The driver should clip out | ||
| 275 | more pixels or not write the image at all.</para> | ||
| 276 | </footnote></para></entry> | ||
| 277 | </row> | ||
| 278 | <row> | ||
| 279 | <entry>__u8</entry> | ||
| 280 | <entry><structfield>global_alpha</structfield></entry> | ||
| 281 | <entry>The global alpha value used to blend the | ||
| 282 | framebuffer with video images, if global alpha blending has been | ||
| 283 | negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see | ||
| 284 | &VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry> | ||
| 285 | </row> | ||
| 286 | <row> | ||
| 287 | <entry></entry> | ||
| 288 | <entry></entry> | ||
| 289 | <entry>Note this field was added in Linux 2.6.23, extending the structure. However | ||
| 290 | the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, | ||
| 291 | which take a pointer to a <link | ||
| 292 | linkend="v4l2-format">v4l2_format</link> parent structure with padding | ||
| 293 | bytes at the end, are not affected.</entry> | ||
| 294 | </row> | ||
| 295 | </tbody> | ||
| 296 | </tgroup> | ||
| 297 | </table> | ||
| 298 | |||
| 299 | <table pgwide="1" frame="none" id="v4l2-clip"> | ||
| 300 | <title>struct <structname>v4l2_clip</structname><footnote> | ||
| 301 | <para>The X Window system defines "regions" which are | ||
| 302 | vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 - | ||
| 303 | x1 and height = y2 - y1, so one cannot pass X11 clip lists | ||
| 304 | directly.</para> | ||
| 305 | </footnote></title> | ||
| 306 | <tgroup cols="3"> | ||
| 307 | &cs-str; | ||
| 308 | <tbody valign="top"> | ||
| 309 | <row> | ||
| 310 | <entry>&v4l2-rect;</entry> | ||
| 311 | <entry><structfield>c</structfield></entry> | ||
| 312 | <entry>Coordinates of the clipping rectangle, relative to | ||
| 313 | the top, left corner of the frame buffer. Only window pixels | ||
| 314 | <emphasis>outside</emphasis> all clipping rectangles are | ||
| 315 | displayed.</entry> | ||
| 316 | </row> | ||
| 317 | <row> | ||
| 318 | <entry>&v4l2-clip; *</entry> | ||
| 319 | <entry><structfield>next</structfield></entry> | ||
| 320 | <entry>Pointer to the next clipping rectangle, NULL when | ||
| 321 | this is the last rectangle. Drivers ignore this field, it cannot be | ||
| 322 | used to pass a linked list of clipping rectangles.</entry> | ||
| 323 | </row> | ||
| 324 | </tbody> | ||
| 325 | </tgroup> | ||
| 326 | </table> | ||
| 327 | |||
| 328 | <!-- NB for easier reading this table is duplicated | ||
| 329 | in the vidioc-cropcap chapter.--> | ||
| 330 | |||
| 331 | <table pgwide="1" frame="none" id="v4l2-rect"> | ||
| 332 | <title>struct <structname>v4l2_rect</structname></title> | ||
| 333 | <tgroup cols="3"> | ||
| 334 | &cs-str; | ||
| 335 | <tbody valign="top"> | ||
| 336 | <row> | ||
| 337 | <entry>__s32</entry> | ||
| 338 | <entry><structfield>left</structfield></entry> | ||
| 339 | <entry>Horizontal offset of the top, left corner of the | ||
| 340 | rectangle, in pixels.</entry> | ||
| 341 | </row> | ||
| 342 | <row> | ||
| 343 | <entry>__s32</entry> | ||
| 344 | <entry><structfield>top</structfield></entry> | ||
| 345 | <entry>Vertical offset of the top, left corner of the | ||
| 346 | rectangle, in pixels. Offsets increase to the right and down.</entry> | ||
| 347 | </row> | ||
| 348 | <row> | ||
| 349 | <entry>__s32</entry> | ||
| 350 | <entry><structfield>width</structfield></entry> | ||
| 351 | <entry>Width of the rectangle, in pixels.</entry> | ||
| 352 | </row> | ||
| 353 | <row> | ||
| 354 | <entry>__s32</entry> | ||
| 355 | <entry><structfield>height</structfield></entry> | ||
| 356 | <entry>Height of the rectangle, in pixels. Width and | ||
| 357 | height cannot be negative, the fields are signed for hysterical | ||
| 358 | reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject | ||
| 359 | "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry> | ||
| 360 | </row> | ||
| 361 | </tbody> | ||
| 362 | </tgroup> | ||
| 363 | </table> | ||
| 364 | </section> | ||
| 365 | |||
| 366 | <section> | ||
| 367 | <title>Enabling Overlay</title> | ||
| 368 | |||
| 369 | <para>To start or stop the frame buffer overlay applications call | ||
| 370 | the &VIDIOC-OVERLAY; ioctl.</para> | ||
| 371 | </section> | ||
| 372 | |||
| 373 | <!-- | ||
| 374 | Local Variables: | ||
| 375 | mode: sgml | ||
| 376 | sgml-parent-document: "v4l2.sgml" | ||
| 377 | indent-tabs-mode: nil | ||
| 378 | End: | ||
| 379 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-radio.xml b/Documentation/DocBook/v4l/dev-radio.xml new file mode 100644 index 000000000000..73aa90b45b34 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-radio.xml | |||
| @@ -0,0 +1,57 @@ | |||
| 1 | <title>Radio Interface</title> | ||
| 2 | |||
| 3 | <para>This interface is intended for AM and FM (analog) radio | ||
| 4 | receivers and transmitters.</para> | ||
| 5 | |||
| 6 | <para>Conventionally V4L2 radio devices are accessed through | ||
| 7 | character device special files named <filename>/dev/radio</filename> | ||
| 8 | and <filename>/dev/radio0</filename> to | ||
| 9 | <filename>/dev/radio63</filename> with major number 81 and minor | ||
| 10 | numbers 64 to 127.</para> | ||
| 11 | |||
| 12 | <section> | ||
| 13 | <title>Querying Capabilities</title> | ||
| 14 | |||
| 15 | <para>Devices supporting the radio interface set the | ||
| 16 | <constant>V4L2_CAP_RADIO</constant> and | ||
| 17 | <constant>V4L2_CAP_TUNER</constant> or | ||
| 18 | <constant>V4L2_CAP_MODULATOR</constant> flag in the | ||
| 19 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 20 | returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of | ||
| 21 | capability flags are reserved for future extensions.</para> | ||
| 22 | </section> | ||
| 23 | |||
| 24 | <section> | ||
| 25 | <title>Supplemental Functions</title> | ||
| 26 | |||
| 27 | <para>Radio devices can support <link | ||
| 28 | linkend="control">controls</link>, and must support the <link | ||
| 29 | linkend="tuner">tuner or modulator</link> ioctls.</para> | ||
| 30 | |||
| 31 | <para>They do not support the video input or output, audio input | ||
| 32 | or output, video standard, cropping and scaling, compression and | ||
| 33 | streaming parameter, or overlay ioctls. All other ioctls and I/O | ||
| 34 | methods are reserved for future extensions.</para> | ||
| 35 | </section> | ||
| 36 | |||
| 37 | <section> | ||
| 38 | <title>Programming</title> | ||
| 39 | |||
| 40 | <para>Radio devices may have a couple audio controls (as discussed | ||
| 41 | in <xref linkend="control" />) such as a volume control, possibly custom | ||
| 42 | controls. Further all radio devices have one tuner or modulator (these are | ||
| 43 | discussed in <xref linkend="tuner" />) with index number zero to select | ||
| 44 | the radio frequency and to determine if a monaural or FM stereo | ||
| 45 | program is received/emitted. Drivers switch automatically between AM and FM | ||
| 46 | depending on the selected frequency. The &VIDIOC-G-TUNER; or | ||
| 47 | &VIDIOC-G-MODULATOR; ioctl | ||
| 48 | reports the supported frequency range.</para> | ||
| 49 | </section> | ||
| 50 | |||
| 51 | <!-- | ||
| 52 | Local Variables: | ||
| 53 | mode: sgml | ||
| 54 | sgml-parent-document: "v4l2.sgml" | ||
| 55 | indent-tabs-mode: nil | ||
| 56 | End: | ||
| 57 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-raw-vbi.xml b/Documentation/DocBook/v4l/dev-raw-vbi.xml new file mode 100644 index 000000000000..c5a70bdfaf27 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-raw-vbi.xml | |||
| @@ -0,0 +1,347 @@ | |||
| 1 | <title>Raw VBI Data Interface</title> | ||
| 2 | |||
| 3 | <para>VBI is an abbreviation of Vertical Blanking Interval, a gap | ||
| 4 | in the sequence of lines of an analog video signal. During VBI | ||
| 5 | no picture information is transmitted, allowing some time while the | ||
| 6 | electron beam of a cathode ray tube TV returns to the top of the | ||
| 7 | screen. Using an oscilloscope you will find here the vertical | ||
| 8 | synchronization pulses and short data packages ASK | ||
| 9 | modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal | ||
| 10 | level represents a '1' bit, a low level a '0' bit.</para></footnote> | ||
| 11 | onto the video signal. These are transmissions of services such as | ||
| 12 | Teletext or Closed Caption.</para> | ||
| 13 | |||
| 14 | <para>Subject of this interface type is raw VBI data, as sampled off | ||
| 15 | a video signal, or to be added to a signal for output. | ||
| 16 | The data format is similar to uncompressed video images, a number of | ||
| 17 | lines times a number of samples per line, we call this a VBI image.</para> | ||
| 18 | |||
| 19 | <para>Conventionally V4L2 VBI devices are accessed through character | ||
| 20 | device special files named <filename>/dev/vbi</filename> and | ||
| 21 | <filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with | ||
| 22 | major number 81 and minor numbers 224 to 255. | ||
| 23 | <filename>/dev/vbi</filename> is typically a symbolic link to the | ||
| 24 | preferred VBI device. This convention applies to both input and output | ||
| 25 | devices.</para> | ||
| 26 | |||
| 27 | <para>To address the problems of finding related video and VBI | ||
| 28 | devices VBI capturing and output is also available as device function | ||
| 29 | under <filename>/dev/video</filename>. To capture or output raw VBI | ||
| 30 | data with these devices applications must call the &VIDIOC-S-FMT; | ||
| 31 | ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing | ||
| 32 | or output is the default device function.</para> | ||
| 33 | |||
| 34 | <section> | ||
| 35 | <title>Querying Capabilities</title> | ||
| 36 | |||
| 37 | <para>Devices supporting the raw VBI capturing or output API set | ||
| 38 | the <constant>V4L2_CAP_VBI_CAPTURE</constant> or | ||
| 39 | <constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the | ||
| 40 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 41 | returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the | ||
| 42 | read/write, streaming or asynchronous I/O methods must be | ||
| 43 | supported. VBI devices may or may not have a tuner or modulator.</para> | ||
| 44 | </section> | ||
| 45 | |||
| 46 | <section> | ||
| 47 | <title>Supplemental Functions</title> | ||
| 48 | |||
| 49 | <para>VBI devices shall support <link linkend="video">video | ||
| 50 | input or output</link>, <link linkend="tuner">tuner or | ||
| 51 | modulator</link>, and <link linkend="control">controls</link> ioctls | ||
| 52 | as needed. The <link linkend="standard">video standard</link> ioctls provide | ||
| 53 | information vital to program a VBI device, therefore must be | ||
| 54 | supported.</para> | ||
| 55 | </section> | ||
| 56 | |||
| 57 | <section> | ||
| 58 | <title>Raw VBI Format Negotiation</title> | ||
| 59 | |||
| 60 | <para>Raw VBI sampling abilities can vary, in particular the | ||
| 61 | sampling frequency. To properly interpret the data V4L2 specifies an | ||
| 62 | ioctl to query the sampling parameters. Moreover, to allow for some | ||
| 63 | flexibility applications can also suggest different parameters.</para> | ||
| 64 | |||
| 65 | <para>As usual these parameters are <emphasis>not</emphasis> | ||
| 66 | reset at &func-open; time to permit Unix tool chains, programming a | ||
| 67 | device and then reading from it as if it was a plain file. Well | ||
| 68 | written V4L2 applications should always ensure they really get what | ||
| 69 | they want, requesting reasonable parameters and then checking if the | ||
| 70 | actual parameters are suitable.</para> | ||
| 71 | |||
| 72 | <para>To query the current raw VBI capture parameters | ||
| 73 | applications set the <structfield>type</structfield> field of a | ||
| 74 | &v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or | ||
| 75 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the | ||
| 76 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 77 | the &v4l2-vbi-format; <structfield>vbi</structfield> member of the | ||
| 78 | <structfield>fmt</structfield> union.</para> | ||
| 79 | |||
| 80 | <para>To request different parameters applications set the | ||
| 81 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 82 | initialize all fields of the &v4l2-vbi-format; | ||
| 83 | <structfield>vbi</structfield> member of the | ||
| 84 | <structfield>fmt</structfield> union, or better just modify the | ||
| 85 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 86 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return | ||
| 87 | an &EINVAL; only when the given parameters are ambiguous, otherwise | ||
| 88 | they modify the parameters according to the hardware capabilites and | ||
| 89 | return the actual parameters. When the driver allocates resources at | ||
| 90 | this point, it may return an &EBUSY; to indicate the returned | ||
| 91 | parameters are valid but the required resources are currently not | ||
| 92 | available. That may happen for instance when the video and VBI areas | ||
| 93 | to capture would overlap, or when the driver supports multiple opens | ||
| 94 | and another process already requested VBI capturing or output. Anyway, | ||
| 95 | applications must expect other resource allocation points which may | ||
| 96 | return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl | ||
| 97 | and the first read(), write() and select() call.</para> | ||
| 98 | |||
| 99 | <para>VBI devices must implement both the | ||
| 100 | <constant>VIDIOC_G_FMT</constant> and | ||
| 101 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 102 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 103 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 104 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 105 | |||
| 106 | <table pgwide="1" frame="none" id="v4l2-vbi-format"> | ||
| 107 | <title>struct <structname>v4l2_vbi_format</structname></title> | ||
| 108 | <tgroup cols="3"> | ||
| 109 | &cs-str; | ||
| 110 | <tbody valign="top"> | ||
| 111 | <row> | ||
| 112 | <entry>__u32</entry> | ||
| 113 | <entry><structfield>sampling_rate</structfield></entry> | ||
| 114 | <entry>Samples per second, i. e. unit 1 Hz.</entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>offset</structfield></entry> | ||
| 119 | <entry><para>Horizontal offset of the VBI image, | ||
| 120 | relative to the leading edge of the line synchronization pulse and | ||
| 121 | counted in samples: The first sample in the VBI image will be located | ||
| 122 | <structfield>offset</structfield> / | ||
| 123 | <structfield>sampling_rate</structfield> seconds following the leading | ||
| 124 | edge. See also <xref linkend="vbi-hsync" />.</para></entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>__u32</entry> | ||
| 128 | <entry><structfield>samples_per_line</structfield></entry> | ||
| 129 | <entry></entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>__u32</entry> | ||
| 133 | <entry><structfield>sample_format</structfield></entry> | ||
| 134 | <entry><para>Defines the sample format as in <xref | ||
| 135 | linkend="pixfmt" />, a four-character-code.<footnote> | ||
| 136 | <para>A few devices may be unable to | ||
| 137 | sample VBI data at all but can extend the video capture window to the | ||
| 138 | VBI region.</para> | ||
| 139 | </footnote> Usually this is | ||
| 140 | <constant>V4L2_PIX_FMT_GREY</constant>, i. e. each sample | ||
| 141 | consists of 8 bits with lower values oriented towards the black level. | ||
| 142 | Do not assume any other correlation of values with the signal level. | ||
| 143 | For example, the MSB does not necessarily indicate if the signal is | ||
| 144 | 'high' or 'low' because 128 may not be the mean value of the | ||
| 145 | signal. Drivers shall not convert the sample format by software.</para></entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>__u32</entry> | ||
| 149 | <entry><structfield>start</structfield>[2]</entry> | ||
| 150 | <entry>This is the scanning system line number | ||
| 151 | associated with the first line of the VBI image, of the first and the | ||
| 152 | second field respectively. See <xref linkend="vbi-525" /> and | ||
| 153 | <xref linkend="vbi-625" /> for valid values. VBI input drivers can | ||
| 154 | return start values 0 if the hardware cannot reliable identify | ||
| 155 | scanning lines, VBI acquisition may not require this | ||
| 156 | information.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>count</structfield>[2]</entry> | ||
| 161 | <entry>The number of lines in the first and second | ||
| 162 | field image, respectively.</entry> | ||
| 163 | </row> | ||
| 164 | <row> | ||
| 165 | <entry spanname="hspan"><para>Drivers should be as | ||
| 166 | flexibility as possible. For example, it may be possible to extend or | ||
| 167 | move the VBI capture window down to the picture area, implementing a | ||
| 168 | 'full field mode' to capture data service transmissions embedded in | ||
| 169 | the picture.</para><para>An application can set the first or second | ||
| 170 | <structfield>count</structfield> value to zero if no data is required | ||
| 171 | from the respective field; <structfield>count</structfield>[1] if the | ||
| 172 | scanning system is progressive, &ie; not interlaced. The | ||
| 173 | corresponding start value shall be ignored by the application and | ||
| 174 | driver. Anyway, drivers may not support single field capturing and | ||
| 175 | return both count values non-zero.</para><para>Both | ||
| 176 | <structfield>count</structfield> values set to zero, or line numbers | ||
| 177 | outside the bounds depicted in <xref linkend="vbi-525" /> and <xref | ||
| 178 | linkend="vbi-625" />, or a field image covering | ||
| 179 | lines of two fields, are invalid and shall not be returned by the | ||
| 180 | driver.</para><para>To initialize the <structfield>start</structfield> | ||
| 181 | and <structfield>count</structfield> fields, applications must first | ||
| 182 | determine the current video standard selection. The &v4l2-std-id; or | ||
| 183 | the <structfield>framelines</structfield> field of &v4l2-standard; can | ||
| 184 | be evaluated for this purpose.</para></entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry>__u32</entry> | ||
| 188 | <entry><structfield>flags</structfield></entry> | ||
| 189 | <entry>See <xref linkend="vbifmt-flags" /> below. Currently | ||
| 190 | only drivers set flags, applications must set this field to | ||
| 191 | zero.</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry>__u32</entry> | ||
| 195 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 196 | <entry>This array is reserved for future extensions. | ||
| 197 | Drivers and applications must set it to zero.</entry> | ||
| 198 | </row> | ||
| 199 | </tbody> | ||
| 200 | </tgroup> | ||
| 201 | </table> | ||
| 202 | |||
| 203 | <table pgwide="1" frame="none" id="vbifmt-flags"> | ||
| 204 | <title>Raw VBI Format Flags</title> | ||
| 205 | <tgroup cols="3"> | ||
| 206 | &cs-def; | ||
| 207 | <tbody valign="top"> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_VBI_UNSYNC</constant></entry> | ||
| 210 | <entry>0x0001</entry> | ||
| 211 | <entry><para>This flag indicates hardware which does not | ||
| 212 | properly distinguish between fields. Normally the VBI image stores the | ||
| 213 | first field (lower scanning line numbers) first in memory. This may be | ||
| 214 | a top or bottom field depending on the video standard. When this flag | ||
| 215 | is set the first or second field may be stored first, however the | ||
| 216 | fields are still in correct temporal order with the older field first | ||
| 217 | in memory.<footnote> | ||
| 218 | <para>Most VBI services transmit on both fields, but | ||
| 219 | some have different semantics depending on the field number. These | ||
| 220 | cannot be reliable decoded or encoded when | ||
| 221 | <constant>V4L2_VBI_UNSYNC</constant> is set.</para> | ||
| 222 | </footnote></para></entry> | ||
| 223 | </row> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_VBI_INTERLACED</constant></entry> | ||
| 226 | <entry>0x0002</entry> | ||
| 227 | <entry>By default the two field images will be passed | ||
| 228 | sequentially; all lines of the first field followed by all lines of | ||
| 229 | the second field (compare <xref linkend="field-order" /> | ||
| 230 | <constant>V4L2_FIELD_SEQ_TB</constant> and | ||
| 231 | <constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom | ||
| 232 | field is first in memory depends on the video standard). When this | ||
| 233 | flag is set, the two fields are interlaced (cf. | ||
| 234 | <constant>V4L2_FIELD_INTERLACED</constant>). The first line of the | ||
| 235 | first field followed by the first line of the second field, then the | ||
| 236 | two second lines, and so on. Such a layout may be necessary when the | ||
| 237 | hardware has been programmed to capture or output interlaced video | ||
| 238 | images and is unable to separate the fields for VBI capturing at | ||
| 239 | the same time. For simplicity setting this flag implies that both | ||
| 240 | <structfield>count</structfield> values are equal and non-zero.</entry> | ||
| 241 | </row> | ||
| 242 | </tbody> | ||
| 243 | </tgroup> | ||
| 244 | </table> | ||
| 245 | |||
| 246 | <figure id="vbi-hsync"> | ||
| 247 | <title>Line synchronization</title> | ||
| 248 | <mediaobject> | ||
| 249 | <imageobject> | ||
| 250 | <imagedata fileref="vbi_hsync.pdf" format="PS" /> | ||
| 251 | </imageobject> | ||
| 252 | <imageobject> | ||
| 253 | <imagedata fileref="vbi_hsync.gif" format="GIF" /> | ||
| 254 | </imageobject> | ||
| 255 | <textobject> | ||
| 256 | <phrase>Line synchronization diagram</phrase> | ||
| 257 | </textobject> | ||
| 258 | </mediaobject> | ||
| 259 | </figure> | ||
| 260 | |||
| 261 | <figure id="vbi-525"> | ||
| 262 | <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title> | ||
| 263 | <mediaobject> | ||
| 264 | <imageobject> | ||
| 265 | <imagedata fileref="vbi_525.pdf" format="PS" /> | ||
| 266 | </imageobject> | ||
| 267 | <imageobject> | ||
| 268 | <imagedata fileref="vbi_525.gif" format="GIF" /> | ||
| 269 | </imageobject> | ||
| 270 | <textobject> | ||
| 271 | <phrase>NTSC field synchronization diagram</phrase> | ||
| 272 | </textobject> | ||
| 273 | <caption> | ||
| 274 | <para>(1) For the purpose of this specification field 2 | ||
| 275 | starts in line 264 and not 263.5 because half line capturing is not | ||
| 276 | supported.</para> | ||
| 277 | </caption> | ||
| 278 | </mediaobject> | ||
| 279 | </figure> | ||
| 280 | |||
| 281 | <figure id="vbi-625"> | ||
| 282 | <title>ITU-R 625 line numbering</title> | ||
| 283 | <mediaobject> | ||
| 284 | <imageobject> | ||
| 285 | <imagedata fileref="vbi_625.pdf" format="PS" /> | ||
| 286 | </imageobject> | ||
| 287 | <imageobject> | ||
| 288 | <imagedata fileref="vbi_625.gif" format="GIF" /> | ||
| 289 | </imageobject> | ||
| 290 | <textobject> | ||
| 291 | <phrase>PAL/SECAM field synchronization diagram</phrase> | ||
| 292 | </textobject> | ||
| 293 | <caption> | ||
| 294 | <para>(1) For the purpose of this specification field 2 | ||
| 295 | starts in line 314 and not 313.5 because half line capturing is not | ||
| 296 | supported.</para> | ||
| 297 | </caption> | ||
| 298 | </mediaobject> | ||
| 299 | </figure> | ||
| 300 | |||
| 301 | <para>Remember the VBI image format depends on the selected | ||
| 302 | video standard, therefore the application must choose a new standard or | ||
| 303 | query the current standard first. Attempts to read or write data ahead | ||
| 304 | of format negotiation, or after switching the video standard which may | ||
| 305 | invalidate the negotiated VBI parameters, should be refused by the | ||
| 306 | driver. A format change during active I/O is not permitted.</para> | ||
| 307 | </section> | ||
| 308 | |||
| 309 | <section> | ||
| 310 | <title>Reading and writing VBI images</title> | ||
| 311 | |||
| 312 | <para>To assure synchronization with the field number and easier | ||
| 313 | implementation, the smallest unit of data passed at a time is one | ||
| 314 | frame, consisting of two fields of VBI images immediately following in | ||
| 315 | memory.</para> | ||
| 316 | |||
| 317 | <para>The total size of a frame computes as follows:</para> | ||
| 318 | |||
| 319 | <programlisting> | ||
| 320 | (<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) * | ||
| 321 | <structfield>samples_per_line</structfield> * sample size in bytes</programlisting> | ||
| 322 | |||
| 323 | <para>The sample size is most likely always one byte, | ||
| 324 | applications must check the <structfield>sample_format</structfield> | ||
| 325 | field though, to function properly with other drivers.</para> | ||
| 326 | |||
| 327 | <para>A VBI device may support <link | ||
| 328 | linkend="rw">read/write</link> and/or streaming (<link | ||
| 329 | linkend="mmap">memory mapping</link> or <link | ||
| 330 | linkend="userp">user pointer</link>) I/O. The latter bears the | ||
| 331 | possibility of synchronizing video and | ||
| 332 | VBI data by using buffer timestamps.</para> | ||
| 333 | |||
| 334 | <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(), | ||
| 335 | write() and select() call can be resource allocation points returning | ||
| 336 | an &EBUSY; if the required hardware resources are temporarily | ||
| 337 | unavailable, for example the device is already in use by another | ||
| 338 | process.</para> | ||
| 339 | </section> | ||
| 340 | |||
| 341 | <!-- | ||
| 342 | Local Variables: | ||
| 343 | mode: sgml | ||
| 344 | sgml-parent-document: "v4l2.sgml" | ||
| 345 | indent-tabs-mode: nil | ||
| 346 | End: | ||
| 347 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-rds.xml b/Documentation/DocBook/v4l/dev-rds.xml new file mode 100644 index 000000000000..0869d701b1e5 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-rds.xml | |||
| @@ -0,0 +1,168 @@ | |||
| 1 | <title>RDS Interface</title> | ||
| 2 | |||
| 3 | <para>The Radio Data System transmits supplementary | ||
| 4 | information in binary format, for example the station name or travel | ||
| 5 | information, on an inaudible audio subcarrier of a radio program. This | ||
| 6 | interface is aimed at devices capable of receiving and decoding RDS | ||
| 7 | information.</para> | ||
| 8 | |||
| 9 | <para>For more information see the core RDS standard <xref linkend="en50067" /> | ||
| 10 | and the RBDS standard <xref linkend="nrsc4" />.</para> | ||
| 11 | |||
| 12 | <para>Note that the RBDS standard as is used in the USA is almost identical | ||
| 13 | to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields | ||
| 14 | have slightly different meanings. See the RBDS standard for more information.</para> | ||
| 15 | |||
| 16 | <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search). | ||
| 17 | This is a proprietary format which seems to be discontinued. The RDS interface does not | ||
| 18 | support this format. Should support for MMBS (or the so-called 'E blocks' in general) | ||
| 19 | be needed, then please contact the linux-media mailing list: &v4l-ml;.</para> | ||
| 20 | |||
| 21 | <section> | ||
| 22 | <title>Querying Capabilities</title> | ||
| 23 | |||
| 24 | <para>Devices supporting the RDS capturing API | ||
| 25 | set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in | ||
| 26 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 27 | returned by the &VIDIOC-QUERYCAP; ioctl. | ||
| 28 | Any tuner that supports RDS will set the | ||
| 29 | <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> | ||
| 30 | field of &v4l2-tuner;. | ||
| 31 | Whether an RDS signal is present can be detected by looking at | ||
| 32 | the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the | ||
| 33 | <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para> | ||
| 34 | |||
| 35 | <para>Devices supporting the RDS output API | ||
| 36 | set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in | ||
| 37 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 38 | returned by the &VIDIOC-QUERYCAP; ioctl. | ||
| 39 | Any modulator that supports RDS will set the | ||
| 40 | <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> | ||
| 41 | field of &v4l2-modulator;. | ||
| 42 | In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> | ||
| 43 | bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para> | ||
| 44 | |||
| 45 | </section> | ||
| 46 | |||
| 47 | <section> | ||
| 48 | <title>Reading RDS data</title> | ||
| 49 | |||
| 50 | <para>RDS data can be read from the radio device | ||
| 51 | with the &func-read; function. The data is packed in groups of three bytes, | ||
| 52 | as follows:</para> | ||
| 53 | <table frame="none" pgwide="1" id="v4l2-rds-data"> | ||
| 54 | <title>struct | ||
| 55 | <structname>v4l2_rds_data</structname></title> | ||
| 56 | <tgroup cols="3"> | ||
| 57 | <colspec colname="c1" colwidth="1*" /> | ||
| 58 | <colspec colname="c2" colwidth="1*" /> | ||
| 59 | <colspec colname="c3" colwidth="5*" /> | ||
| 60 | <tbody valign="top"> | ||
| 61 | <row> | ||
| 62 | <entry>__u8</entry> | ||
| 63 | <entry><structfield>lsb</structfield></entry> | ||
| 64 | <entry>Least Significant Byte of RDS Block</entry> | ||
| 65 | </row> | ||
| 66 | <row> | ||
| 67 | <entry>__u8</entry> | ||
| 68 | <entry><structfield>msb</structfield></entry> | ||
| 69 | <entry>Most Significant Byte of RDS Block</entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>__u8</entry> | ||
| 73 | <entry><structfield>block</structfield></entry> | ||
| 74 | <entry>Block description</entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </table> | ||
| 79 | <table frame="none" pgwide="1" id="v4l2-rds-block"> | ||
| 80 | <title>Block description</title> | ||
| 81 | <tgroup cols="2"> | ||
| 82 | <colspec colname="c1" colwidth="1*" /> | ||
| 83 | <colspec colname="c2" colwidth="5*" /> | ||
| 84 | <tbody valign="top"> | ||
| 85 | <row> | ||
| 86 | <entry>Bits 0-2</entry> | ||
| 87 | <entry>Block (aka offset) of the received data.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>Bits 3-5</entry> | ||
| 91 | <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>Bit 6</entry> | ||
| 95 | <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>Bit 7</entry> | ||
| 99 | <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry> | ||
| 100 | </row> | ||
| 101 | </tbody> | ||
| 102 | </tgroup> | ||
| 103 | </table> | ||
| 104 | |||
| 105 | <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> | ||
| 106 | <title>Block defines</title> | ||
| 107 | <tgroup cols="3"> | ||
| 108 | <colspec colname="c1" colwidth="1*" /> | ||
| 109 | <colspec colname="c2" colwidth="1*" /> | ||
| 110 | <colspec colname="c3" colwidth="5*" /> | ||
| 111 | <tbody valign="top"> | ||
| 112 | <row> | ||
| 113 | <entry>V4L2_RDS_BLOCK_MSK</entry> | ||
| 114 | <entry>7</entry> | ||
| 115 | <entry>Mask for bits 0-2 to get the block ID.</entry> | ||
| 116 | </row> | ||
| 117 | <row> | ||
| 118 | <entry>V4L2_RDS_BLOCK_A</entry> | ||
| 119 | <entry>0</entry> | ||
| 120 | <entry>Block A.</entry> | ||
| 121 | </row> | ||
| 122 | <row> | ||
| 123 | <entry>V4L2_RDS_BLOCK_B</entry> | ||
| 124 | <entry>1</entry> | ||
| 125 | <entry>Block B.</entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>V4L2_RDS_BLOCK_C</entry> | ||
| 129 | <entry>2</entry> | ||
| 130 | <entry>Block C.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>V4L2_RDS_BLOCK_D</entry> | ||
| 134 | <entry>3</entry> | ||
| 135 | <entry>Block D.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>V4L2_RDS_BLOCK_C_ALT</entry> | ||
| 139 | <entry>4</entry> | ||
| 140 | <entry>Block C'.</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry>V4L2_RDS_BLOCK_INVALID</entry> | ||
| 144 | <entry>7</entry> | ||
| 145 | <entry>An invalid block.</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>V4L2_RDS_BLOCK_CORRECTED</entry> | ||
| 149 | <entry>0x40</entry> | ||
| 150 | <entry>A bit error was detected but corrected.</entry> | ||
| 151 | </row> | ||
| 152 | <row> | ||
| 153 | <entry>V4L2_RDS_BLOCK_ERROR</entry> | ||
| 154 | <entry>0x80</entry> | ||
| 155 | <entry>An incorrectable error occurred.</entry> | ||
| 156 | </row> | ||
| 157 | </tbody> | ||
| 158 | </tgroup> | ||
| 159 | </table> | ||
| 160 | </section> | ||
| 161 | |||
| 162 | <!-- | ||
| 163 | Local Variables: | ||
| 164 | mode: sgml | ||
| 165 | sgml-parent-document: "v4l2.sgml" | ||
| 166 | indent-tabs-mode: nil | ||
| 167 | End: | ||
| 168 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/v4l/dev-sliced-vbi.xml new file mode 100644 index 000000000000..69e789fa7f7b --- /dev/null +++ b/Documentation/DocBook/v4l/dev-sliced-vbi.xml | |||
| @@ -0,0 +1,708 @@ | |||
| 1 | <title>Sliced VBI Data Interface</title> | ||
| 2 | |||
| 3 | <para>VBI stands for Vertical Blanking Interval, a gap in the | ||
| 4 | sequence of lines of an analog video signal. During VBI no picture | ||
| 5 | information is transmitted, allowing some time while the electron beam | ||
| 6 | of a cathode ray tube TV returns to the top of the screen.</para> | ||
| 7 | |||
| 8 | <para>Sliced VBI devices use hardware to demodulate data transmitted | ||
| 9 | in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by | ||
| 10 | software, see also the <link linkend="raw-vbi">raw VBI | ||
| 11 | interface</link>. The data is passed as short packets of fixed size, | ||
| 12 | covering one scan line each. The number of packets per video frame is | ||
| 13 | variable.</para> | ||
| 14 | |||
| 15 | <para>Sliced VBI capture and output devices are accessed through the | ||
| 16 | same character special files as raw VBI devices. When a driver | ||
| 17 | supports both interfaces, the default function of a | ||
| 18 | <filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI | ||
| 19 | capturing or output, and the sliced VBI function is only available | ||
| 20 | after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a | ||
| 21 | <filename>/dev/video</filename> device may support the sliced VBI API, | ||
| 22 | however the default function here is video capturing or output. | ||
| 23 | Different file descriptors must be used to pass raw and sliced VBI | ||
| 24 | data simultaneously, if this is supported by the driver.</para> | ||
| 25 | |||
| 26 | <section> | ||
| 27 | <title>Querying Capabilities</title> | ||
| 28 | |||
| 29 | <para>Devices supporting the sliced VBI capturing or output API | ||
| 30 | set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or | ||
| 31 | <constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in | ||
| 32 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 33 | returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the | ||
| 34 | read/write, streaming or asynchronous <link linkend="io">I/O | ||
| 35 | methods</link> must be supported. Sliced VBI devices may have a tuner | ||
| 36 | or modulator.</para> | ||
| 37 | </section> | ||
| 38 | |||
| 39 | <section> | ||
| 40 | <title>Supplemental Functions</title> | ||
| 41 | |||
| 42 | <para>Sliced VBI devices shall support <link linkend="video">video | ||
| 43 | input or output</link> and <link linkend="tuner">tuner or | ||
| 44 | modulator</link> ioctls if they have these capabilities, and they may | ||
| 45 | support <link linkend="control">control</link> ioctls. The <link | ||
| 46 | linkend="standard">video standard</link> ioctls provide information | ||
| 47 | vital to program a sliced VBI device, therefore must be | ||
| 48 | supported.</para> | ||
| 49 | </section> | ||
| 50 | |||
| 51 | <section id="sliced-vbi-format-negotitation"> | ||
| 52 | <title>Sliced VBI Format Negotiation</title> | ||
| 53 | |||
| 54 | <para>To find out which data services are supported by the | ||
| 55 | hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl. | ||
| 56 | All drivers implementing the sliced VBI interface must support this | ||
| 57 | ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl | ||
| 58 | when the number of VBI lines the hardware can capture or output per | ||
| 59 | frame, or the number of services it can identify on a given line are | ||
| 60 | limited. For example on PAL line 16 the hardware may be able to look | ||
| 61 | for a VPS or Teletext signal, but not both at the same time.</para> | ||
| 62 | |||
| 63 | <para>To determine the currently selected services applications | ||
| 64 | set the <structfield>type </structfield> field of &v4l2-format; to | ||
| 65 | <constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant> | ||
| 66 | V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT; | ||
| 67 | ioctl fills the <structfield>fmt.sliced</structfield> member, a | ||
| 68 | &v4l2-sliced-vbi-format;.</para> | ||
| 69 | |||
| 70 | <para>Applications can request different parameters by | ||
| 71 | initializing or modifying the <structfield>fmt.sliced</structfield> | ||
| 72 | member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the | ||
| 73 | <structname>v4l2_format</structname> structure.</para> | ||
| 74 | |||
| 75 | <para>The sliced VBI API is more complicated than the raw VBI API | ||
| 76 | because the hardware must be told which VBI service to expect on each | ||
| 77 | scan line. Not all services may be supported by the hardware on all | ||
| 78 | lines (this is especially true for VBI output where Teletext is often | ||
| 79 | unsupported and other services can only be inserted in one specific | ||
| 80 | line). In many cases, however, it is sufficient to just set the | ||
| 81 | <structfield>service_set</structfield> field to the required services | ||
| 82 | and let the driver fill the <structfield>service_lines</structfield> | ||
| 83 | array according to hardware capabilities. Only if more precise control | ||
| 84 | is needed should the programmer set the | ||
| 85 | <structfield>service_lines</structfield> array explicitly.</para> | ||
| 86 | |||
| 87 | <para>The &VIDIOC-S-FMT; ioctl modifies the parameters | ||
| 88 | according to hardware capabilities. When the driver allocates | ||
| 89 | resources at this point, it may return an &EBUSY; if the required | ||
| 90 | resources are temporarily unavailable. Other resource allocation | ||
| 91 | points which may return <errorcode>EBUSY</errorcode> can be the | ||
| 92 | &VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and | ||
| 93 | &func-select; call.</para> | ||
| 94 | |||
| 95 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format"> | ||
| 96 | <title>struct | ||
| 97 | <structname>v4l2_sliced_vbi_format</structname></title> | ||
| 98 | <tgroup cols="5"> | ||
| 99 | <colspec colname="c1" colwidth="3*" /> | ||
| 100 | <colspec colname="c2" colwidth="3*" /> | ||
| 101 | <colspec colname="c3" colwidth="2*" /> | ||
| 102 | <colspec colname="c4" colwidth="2*" /> | ||
| 103 | <colspec colname="c5" colwidth="2*" /> | ||
| 104 | <spanspec namest="c3" nameend="c5" spanname="hspan" /> | ||
| 105 | <tbody valign="top"> | ||
| 106 | <row> | ||
| 107 | <entry>__u32</entry> | ||
| 108 | <entry><structfield>service_set</structfield></entry> | ||
| 109 | <entry spanname="hspan"><para>If | ||
| 110 | <structfield>service_set</structfield> is non-zero when passed with | ||
| 111 | &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the | ||
| 112 | <structfield>service_lines</structfield> array will be filled by the | ||
| 113 | driver according to the services specified in this field. For example, | ||
| 114 | if <structfield>service_set</structfield> is initialized with | ||
| 115 | <constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a | ||
| 116 | driver for the cx25840 video decoder sets lines 7-22 of both | ||
| 117 | fields<footnote><para>According to <link | ||
| 118 | linkend="ets300706">ETS 300 706</link> lines 6-22 of the | ||
| 119 | first field and lines 5-22 of the second field may carry Teletext | ||
| 120 | data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant> | ||
| 121 | and line 23 of the first field to | ||
| 122 | <constant>V4L2_SLICED_WSS_625</constant>. If | ||
| 123 | <structfield>service_set</structfield> is set to zero, then the values | ||
| 124 | of <structfield>service_lines</structfield> will be used instead. | ||
| 125 | </para><para>On return the driver sets this field to the union of all | ||
| 126 | elements of the returned <structfield>service_lines</structfield> | ||
| 127 | array. It may contain less services than requested, perhaps just one, | ||
| 128 | if the hardware cannot handle more services simultaneously. It may be | ||
| 129 | empty (zero) if none of the requested services are supported by the | ||
| 130 | hardware.</para></entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>__u16</entry> | ||
| 134 | <entry><structfield>service_lines</structfield>[2][24]</entry> | ||
| 135 | <entry spanname="hspan"><para>Applications initialize this | ||
| 136 | array with sets of data services the driver shall look for or insert | ||
| 137 | on the respective scan line. Subject to hardware capabilities drivers | ||
| 138 | return the requested set, a subset, which may be just a single | ||
| 139 | service, or an empty set. When the hardware cannot handle multiple | ||
| 140 | services on the same line the driver shall choose one. No assumptions | ||
| 141 | can be made on which service the driver chooses.</para><para>Data | ||
| 142 | services are defined in <xref linkend="vbi-services2" />. Array indices | ||
| 143 | map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref | ||
| 144 | linkend="vbi-625" />) as follows: <!-- No nested | ||
| 145 | tables, sigh. --></para></entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry></entry> | ||
| 149 | <entry></entry> | ||
| 150 | <entry>Element</entry> | ||
| 151 | <entry>525 line systems</entry> | ||
| 152 | <entry>625 line systems</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry></entry> | ||
| 156 | <entry></entry> | ||
| 157 | <entry><structfield>service_lines</structfield>[0][1]</entry> | ||
| 158 | <entry align="center">1</entry> | ||
| 159 | <entry align="center">1</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry></entry> | ||
| 163 | <entry></entry> | ||
| 164 | <entry><structfield>service_lines</structfield>[0][23]</entry> | ||
| 165 | <entry align="center">23</entry> | ||
| 166 | <entry align="center">23</entry> | ||
| 167 | </row> | ||
| 168 | <row> | ||
| 169 | <entry></entry> | ||
| 170 | <entry></entry> | ||
| 171 | <entry><structfield>service_lines</structfield>[1][1]</entry> | ||
| 172 | <entry align="center">264</entry> | ||
| 173 | <entry align="center">314</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry></entry> | ||
| 177 | <entry></entry> | ||
| 178 | <entry><structfield>service_lines</structfield>[1][23]</entry> | ||
| 179 | <entry align="center">286</entry> | ||
| 180 | <entry align="center">336</entry> | ||
| 181 | </row> | ||
| 182 | <!-- End of line numbers table. --> | ||
| 183 | <row> | ||
| 184 | <entry></entry> | ||
| 185 | <entry></entry> | ||
| 186 | <entry spanname="hspan">Drivers must set | ||
| 187 | <structfield>service_lines</structfield>[0][0] and | ||
| 188 | <structfield>service_lines</structfield>[1][0] to zero.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry>__u32</entry> | ||
| 192 | <entry><structfield>io_size</structfield></entry> | ||
| 193 | <entry spanname="hspan">Maximum number of bytes passed by | ||
| 194 | one &func-read; or &func-write; call, and the buffer size in bytes for | ||
| 195 | the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to | ||
| 196 | the size of &v4l2-sliced-vbi-data; times the number of non-zero | ||
| 197 | elements in the returned <structfield>service_lines</structfield> | ||
| 198 | array (that is the number of lines potentially carrying data).</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry>__u32</entry> | ||
| 202 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 203 | <entry spanname="hspan">This array is reserved for future | ||
| 204 | extensions. Applications and drivers must set it to zero.</entry> | ||
| 205 | </row> | ||
| 206 | </tbody> | ||
| 207 | </tgroup> | ||
| 208 | </table> | ||
| 209 | |||
| 210 | <!-- See also vidioc-g-sliced-vbi-cap.sgml --> | ||
| 211 | <table frame="none" pgwide="1" id="vbi-services2"> | ||
| 212 | <title>Sliced VBI services</title> | ||
| 213 | <tgroup cols="5"> | ||
| 214 | <colspec colname="c1" colwidth="2*" /> | ||
| 215 | <colspec colname="c2" colwidth="1*" /> | ||
| 216 | <colspec colname="c3" colwidth="1*" /> | ||
| 217 | <colspec colname="c4" colwidth="2*" /> | ||
| 218 | <colspec colname="c5" colwidth="2*" /> | ||
| 219 | <spanspec namest="c3" nameend="c5" spanname="rlp" /> | ||
| 220 | <thead> | ||
| 221 | <row> | ||
| 222 | <entry>Symbol</entry> | ||
| 223 | <entry>Value</entry> | ||
| 224 | <entry>Reference</entry> | ||
| 225 | <entry>Lines, usually</entry> | ||
| 226 | <entry>Payload</entry> | ||
| 227 | </row> | ||
| 228 | </thead> | ||
| 229 | <tbody valign="top"> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_SLICED_TELETEXT_B</constant> | ||
| 232 | (Teletext System B)</entry> | ||
| 233 | <entry>0x0001</entry> | ||
| 234 | <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> | ||
| 235 | <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> | ||
| 236 | <entry>Last 42 of the 45 byte Teletext packet, that is | ||
| 237 | without clock run-in and framing code, lsb first transmitted.</entry> | ||
| 238 | </row> | ||
| 239 | <row> | ||
| 240 | <entry><constant>V4L2_SLICED_VPS</constant></entry> | ||
| 241 | <entry>0x0400</entry> | ||
| 242 | <entry><xref linkend="ets300231" /></entry> | ||
| 243 | <entry>PAL line 16</entry> | ||
| 244 | <entry>Byte number 3 to 15 according to Figure 9 of | ||
| 245 | ETS 300 231, lsb first transmitted.</entry> | ||
| 246 | </row> | ||
| 247 | <row> | ||
| 248 | <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> | ||
| 249 | <entry>0x1000</entry> | ||
| 250 | <entry><xref linkend="eia608" /></entry> | ||
| 251 | <entry>NTSC line 21, 284 (second field 21)</entry> | ||
| 252 | <entry>Two bytes in transmission order, including parity | ||
| 253 | bit, lsb first transmitted.</entry> | ||
| 254 | </row> | ||
| 255 | <row> | ||
| 256 | <entry><constant>V4L2_SLICED_WSS_625</constant></entry> | ||
| 257 | <entry>0x4000</entry> | ||
| 258 | <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> | ||
| 259 | <entry>PAL/SECAM line 23</entry> | ||
| 260 | <entry><screen> | ||
| 261 | Byte 0 1 | ||
| 262 | msb lsb msb lsb | ||
| 263 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | ||
| 264 | </screen></entry> | ||
| 265 | </row> | ||
| 266 | <row> | ||
| 267 | <entry><constant>V4L2_SLICED_VBI_525</constant></entry> | ||
| 268 | <entry>0x1000</entry> | ||
| 269 | <entry spanname="rlp">Set of services applicable to 525 | ||
| 270 | line systems.</entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>V4L2_SLICED_VBI_625</constant></entry> | ||
| 274 | <entry>0x4401</entry> | ||
| 275 | <entry spanname="rlp">Set of services applicable to 625 | ||
| 276 | line systems.</entry> | ||
| 277 | </row> | ||
| 278 | </tbody> | ||
| 279 | </tgroup> | ||
| 280 | </table> | ||
| 281 | |||
| 282 | <para>Drivers may return an &EINVAL; when applications attempt to | ||
| 283 | read or write data without prior format negotiation, after switching | ||
| 284 | the video standard (which may invalidate the negotiated VBI | ||
| 285 | parameters) and after switching the video input (which may change the | ||
| 286 | video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return | ||
| 287 | an &EBUSY; when applications attempt to change the format while i/o is | ||
| 288 | in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call, | ||
| 289 | and after the first &func-read; or &func-write; call).</para> | ||
| 290 | </section> | ||
| 291 | |||
| 292 | <section> | ||
| 293 | <title>Reading and writing sliced VBI data</title> | ||
| 294 | |||
| 295 | <para>A single &func-read; or &func-write; call must pass all data | ||
| 296 | belonging to one video frame. That is an array of | ||
| 297 | <structname>v4l2_sliced_vbi_data</structname> structures with one or | ||
| 298 | more elements and a total size not exceeding | ||
| 299 | <structfield>io_size</structfield> bytes. Likewise in streaming I/O | ||
| 300 | mode one buffer of <structfield>io_size</structfield> bytes must | ||
| 301 | contain data of one video frame. The <structfield>id</structfield> of | ||
| 302 | unused <structname>v4l2_sliced_vbi_data</structname> elements must be | ||
| 303 | zero.</para> | ||
| 304 | |||
| 305 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data"> | ||
| 306 | <title>struct | ||
| 307 | <structname>v4l2_sliced_vbi_data</structname></title> | ||
| 308 | <tgroup cols="3"> | ||
| 309 | &cs-def; | ||
| 310 | <tbody valign="top"> | ||
| 311 | <row> | ||
| 312 | <entry>__u32</entry> | ||
| 313 | <entry><structfield>id</structfield></entry> | ||
| 314 | <entry>A flag from <xref linkend="vbi-services" /> | ||
| 315 | identifying the type of data in this packet. Only a single bit must be | ||
| 316 | set. When the <structfield>id</structfield> of a captured packet is | ||
| 317 | zero, the packet is empty and the contents of other fields are | ||
| 318 | undefined. Applications shall ignore empty packets. When the | ||
| 319 | <structfield>id</structfield> of a packet for output is zero the | ||
| 320 | contents of the <structfield>data</structfield> field are undefined | ||
| 321 | and the driver must no longer insert data on the requested | ||
| 322 | <structfield>field</structfield> and | ||
| 323 | <structfield>line</structfield>.</entry> | ||
| 324 | </row> | ||
| 325 | <row> | ||
| 326 | <entry>__u32</entry> | ||
| 327 | <entry><structfield>field</structfield></entry> | ||
| 328 | <entry>The video field number this data has been captured | ||
| 329 | from, or shall be inserted at. <constant>0</constant> for the first | ||
| 330 | field, <constant>1</constant> for the second field.</entry> | ||
| 331 | </row> | ||
| 332 | <row> | ||
| 333 | <entry>__u32</entry> | ||
| 334 | <entry><structfield>line</structfield></entry> | ||
| 335 | <entry>The field (as opposed to frame) line number this | ||
| 336 | data has been captured from, or shall be inserted at. See <xref | ||
| 337 | linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid | ||
| 338 | values. Sliced VBI capture devices can set the line number of all | ||
| 339 | packets to <constant>0</constant> if the hardware cannot reliably | ||
| 340 | identify scan lines. The field number must always be valid.</entry> | ||
| 341 | </row> | ||
| 342 | <row> | ||
| 343 | <entry>__u32</entry> | ||
| 344 | <entry><structfield>reserved</structfield></entry> | ||
| 345 | <entry>This field is reserved for future extensions. | ||
| 346 | Applications and drivers must set it to zero.</entry> | ||
| 347 | </row> | ||
| 348 | <row> | ||
| 349 | <entry>__u8</entry> | ||
| 350 | <entry><structfield>data</structfield>[48]</entry> | ||
| 351 | <entry>The packet payload. See <xref | ||
| 352 | linkend="vbi-services" /> for the contents and number of | ||
| 353 | bytes passed for each data type. The contents of padding bytes at the | ||
| 354 | end of this array are undefined, drivers and applications shall ignore | ||
| 355 | them.</entry> | ||
| 356 | </row> | ||
| 357 | </tbody> | ||
| 358 | </tgroup> | ||
| 359 | </table> | ||
| 360 | |||
| 361 | <para>Packets are always passed in ascending line number order, | ||
| 362 | without duplicate line numbers. The &func-write; function and the | ||
| 363 | &VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate | ||
| 364 | this rule. They must also return an &EINVAL; when applications pass an | ||
| 365 | incorrect field or line number, or a combination of | ||
| 366 | <structfield>field</structfield>, <structfield>line</structfield> and | ||
| 367 | <structfield>id</structfield> which has not been negotiated with the | ||
| 368 | &VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are | ||
| 369 | unknown the driver must pass the packets in transmitted order. The | ||
| 370 | driver can insert empty packets with <structfield>id</structfield> set | ||
| 371 | to zero anywhere in the packet array.</para> | ||
| 372 | |||
| 373 | <para>To assure synchronization and to distinguish from frame | ||
| 374 | dropping, when a captured frame does not carry any of the requested | ||
| 375 | data services drivers must pass one or more empty packets. When an | ||
| 376 | application fails to pass VBI data in time for output, the driver | ||
| 377 | must output the last VPS and WSS packet again, and disable the output | ||
| 378 | of Closed Caption and Teletext data, or output data which is ignored | ||
| 379 | by Closed Caption and Teletext decoders.</para> | ||
| 380 | |||
| 381 | <para>A sliced VBI device may support <link | ||
| 382 | linkend="rw">read/write</link> and/or streaming (<link | ||
| 383 | linkend="mmap">memory mapping</link> and/or <link linkend="userp">user | ||
| 384 | pointer</link>) I/O. The latter bears the possibility of synchronizing | ||
| 385 | video and VBI data by using buffer timestamps.</para> | ||
| 386 | |||
| 387 | </section> | ||
| 388 | |||
| 389 | <section> | ||
| 390 | <title>Sliced VBI Data in MPEG Streams</title> | ||
| 391 | |||
| 392 | <para>If a device can produce an MPEG output stream, it may be | ||
| 393 | capable of providing <link | ||
| 394 | linkend="sliced-vbi-format-negotitation">negotiated sliced VBI | ||
| 395 | services</link> as data embedded in the MPEG stream. Users or | ||
| 396 | applications control this sliced VBI data insertion with the <link | ||
| 397 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | ||
| 398 | control.</para> | ||
| 399 | |||
| 400 | <para>If the driver does not provide the <link | ||
| 401 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | ||
| 402 | control, or only allows that control to be set to <link | ||
| 403 | linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 404 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device | ||
| 405 | cannot embed sliced VBI data in the MPEG stream.</para> | ||
| 406 | |||
| 407 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> | ||
| 408 | V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set | ||
| 409 | the device driver to capture nor cease capturing sliced VBI data. The | ||
| 410 | control only indicates to embed sliced VBI data in the MPEG stream, if | ||
| 411 | an application has negotiated sliced VBI service be captured.</para> | ||
| 412 | |||
| 413 | <para>It may also be the case that a device can embed sliced VBI | ||
| 414 | data in only certain types of MPEG streams: for example in an MPEG-2 | ||
| 415 | PS but not an MPEG-2 TS. In this situation, if sliced VBI data | ||
| 416 | insertion is requested, the sliced VBI data will be embedded in MPEG | ||
| 417 | stream types when supported, and silently omitted from MPEG stream | ||
| 418 | types where sliced VBI data insertion is not supported by the device. | ||
| 419 | </para> | ||
| 420 | |||
| 421 | <para>The following subsections specify the format of the | ||
| 422 | embedded sliced VBI data.</para> | ||
| 423 | |||
| 424 | <section> | ||
| 425 | <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> | ||
| 426 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 427 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI | ||
| 428 | format shall be interpreted by drivers as a control to cease | ||
| 429 | embedding sliced VBI data in MPEG streams. Neither the device nor | ||
| 430 | driver shall insert "empty" embedded sliced VBI data packets in the | ||
| 431 | MPEG stream when this format is set. No MPEG stream data structures | ||
| 432 | are specified for this format.</para> | ||
| 433 | </section> | ||
| 434 | |||
| 435 | <section> | ||
| 436 | <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> | ||
| 437 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 438 | V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI | ||
| 439 | format, when supported, indicates to the driver to embed up to 36 | ||
| 440 | lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private | ||
| 441 | Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> | ||
| 442 | Program Pack</emphasis> in the MPEG stream.</para> | ||
| 443 | |||
| 444 | <para><emphasis>Historical context</emphasis>: This format | ||
| 445 | specification originates from a custom, embedded, sliced VBI data | ||
| 446 | format used by the <filename>ivtv</filename> driver. This format | ||
| 447 | has already been informally specified in the kernel sources in the | ||
| 448 | file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> | ||
| 449 | . The maximum size of the payload and other aspects of this format | ||
| 450 | are driven by the CX23415 MPEG decoder's capabilities and limitations | ||
| 451 | with respect to extracting, decoding, and displaying sliced VBI data | ||
| 452 | embedded within an MPEG stream.</para> | ||
| 453 | |||
| 454 | <para>This format's use is <emphasis>not</emphasis> exclusive to | ||
| 455 | the <filename>ivtv</filename> driver <emphasis>nor</emphasis> | ||
| 456 | exclusive to CX2341x devices, as the sliced VBI data packet insertion | ||
| 457 | into the MPEG stream is implemented in driver software. At least the | ||
| 458 | <filename>cx18</filename> driver provides sliced VBI data insertion | ||
| 459 | into an MPEG-2 PS in this format as well.</para> | ||
| 460 | |||
| 461 | <para>The following definitions specify the payload of the | ||
| 462 | MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain | ||
| 463 | sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> | ||
| 464 | <constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. | ||
| 465 | (The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header | ||
| 466 | and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are | ||
| 467 | not detailed here. Please refer to the MPEG-2 specifications for | ||
| 468 | details on those packet headers.)</para> | ||
| 469 | |||
| 470 | <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES | ||
| 471 | </emphasis> packets that contain sliced VBI data is specified by | ||
| 472 | &v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable | ||
| 473 | length, depending on the actual number of lines of sliced VBI data | ||
| 474 | present in a video frame. The payload may be padded at the end with | ||
| 475 | unspecified fill bytes to align the end of the payload to a 4-byte | ||
| 476 | boundary. The payload shall never exceed 1552 bytes (2 fields with | ||
| 477 | 18 lines/field with 43 bytes of data/line and a 4 byte magic number). | ||
| 478 | </para> | ||
| 479 | |||
| 480 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> | ||
| 481 | <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> | ||
| 482 | </title> | ||
| 483 | <tgroup cols="4"> | ||
| 484 | &cs-ustr; | ||
| 485 | <tbody valign="top"> | ||
| 486 | <row> | ||
| 487 | <entry>__u8</entry> | ||
| 488 | <entry><structfield>magic</structfield>[4]</entry> | ||
| 489 | <entry></entry> | ||
| 490 | <entry>A "magic" constant from <xref | ||
| 491 | linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates | ||
| 492 | this is a valid sliced VBI data payload and also indicates which | ||
| 493 | member of the anonymous union, <structfield>itv0</structfield> or | ||
| 494 | <structfield>ITV0</structfield>, to use for the payload data.</entry> | ||
| 495 | </row> | ||
| 496 | <row> | ||
| 497 | <entry>union</entry> | ||
| 498 | <entry>(anonymous)</entry> | ||
| 499 | </row> | ||
| 500 | <row> | ||
| 501 | <entry></entry> | ||
| 502 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> | ||
| 503 | <structname>v4l2_mpeg_vbi_itv0</structname></link> | ||
| 504 | </entry> | ||
| 505 | <entry><structfield>itv0</structfield></entry> | ||
| 506 | <entry>The primary form of the sliced VBI data payload | ||
| 507 | that contains anywhere from 1 to 35 lines of sliced VBI data. | ||
| 508 | Line masks are provided in this form of the payload indicating | ||
| 509 | which VBI lines are provided.</entry> | ||
| 510 | </row> | ||
| 511 | <row> | ||
| 512 | <entry></entry> | ||
| 513 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1"> | ||
| 514 | <structname>v4l2_mpeg_vbi_ITV0</structname></link> | ||
| 515 | </entry> | ||
| 516 | <entry><structfield>ITV0</structfield></entry> | ||
| 517 | <entry>An alternate form of the sliced VBI data payload | ||
| 518 | used when 36 lines of sliced VBI data are present. No line masks are | ||
| 519 | provided in this form of the payload; all valid line mask bits are | ||
| 520 | implcitly set.</entry> | ||
| 521 | </row> | ||
| 522 | </tbody> | ||
| 523 | </tgroup> | ||
| 524 | </table> | ||
| 525 | |||
| 526 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> | ||
| 527 | <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; | ||
| 528 | <structfield>magic</structfield> field</title> | ||
| 529 | <tgroup cols="3"> | ||
| 530 | &cs-def; | ||
| 531 | <thead> | ||
| 532 | <row> | ||
| 533 | <entry align="left">Defined Symbol</entry> | ||
| 534 | <entry align="left">Value</entry> | ||
| 535 | <entry align="left">Description</entry> | ||
| 536 | </row> | ||
| 537 | </thead> | ||
| 538 | <tbody valign="top"> | ||
| 539 | <row> | ||
| 540 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> | ||
| 541 | </entry> | ||
| 542 | <entry>"itv0"</entry> | ||
| 543 | <entry>Indicates the <structfield>itv0</structfield> | ||
| 544 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> | ||
| 545 | </row> | ||
| 546 | <row> | ||
| 547 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> | ||
| 548 | </entry> | ||
| 549 | <entry>"ITV0"</entry> | ||
| 550 | <entry>Indicates the <structfield>ITV0</structfield> | ||
| 551 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and | ||
| 552 | that 36 lines of sliced VBI data are present.</entry> | ||
| 553 | </row> | ||
| 554 | </tbody> | ||
| 555 | </tgroup> | ||
| 556 | </table> | ||
| 557 | |||
| 558 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> | ||
| 559 | <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> | ||
| 560 | </title> | ||
| 561 | <tgroup cols="3"> | ||
| 562 | &cs-str; | ||
| 563 | <tbody valign="top"> | ||
| 564 | <row> | ||
| 565 | <entry>__le32</entry> | ||
| 566 | <entry><structfield>linemask</structfield>[2]</entry> | ||
| 567 | <entry><para>Bitmasks indicating the VBI service lines | ||
| 568 | present. These <structfield>linemask</structfield> values are stored | ||
| 569 | in little endian byte order in the MPEG stream. Some reference | ||
| 570 | <structfield>linemask</structfield> bit positions with their | ||
| 571 | corresponding VBI line number and video field are given below. | ||
| 572 | b<subscript>0</subscript> indicates the least significant bit of a | ||
| 573 | <structfield>linemask</structfield> value:<screen> | ||
| 574 | <structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field | ||
| 575 | <structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field | ||
| 576 | <structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field | ||
| 577 | <structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field | ||
| 578 | <structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field | ||
| 579 | <structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field | ||
| 580 | <structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> | ||
| 581 | </row> | ||
| 582 | <row> | ||
| 583 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | ||
| 584 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | ||
| 585 | </entry> | ||
| 586 | <entry><structfield>line</structfield>[35]</entry> | ||
| 587 | <entry>This is a variable length array that holds from 1 | ||
| 588 | to 35 lines of sliced VBI data. The sliced VBI data lines present | ||
| 589 | correspond to the bits set in the <structfield>linemask</structfield> | ||
| 590 | array, starting from b<subscript>0</subscript> of <structfield> | ||
| 591 | linemask</structfield>[0] up through b<subscript>31</subscript> of | ||
| 592 | <structfield>linemask</structfield>[0], and from b<subscript>0 | ||
| 593 | </subscript> of <structfield>linemask</structfield>[1] up through b | ||
| 594 | <subscript>3</subscript> of <structfield>linemask</structfield>[1]. | ||
| 595 | <structfield>line</structfield>[0] corresponds to the first bit | ||
| 596 | found set in the <structfield>linemask</structfield> array, | ||
| 597 | <structfield>line</structfield>[1] corresponds to the second bit | ||
| 598 | found set in the <structfield>linemask</structfield> array, etc. | ||
| 599 | If no <structfield>linemask</structfield> array bits are set, then | ||
| 600 | <structfield>line</structfield>[0] may contain one line of | ||
| 601 | unspecified data that should be ignored by applications.</entry> | ||
| 602 | </row> | ||
| 603 | </tbody> | ||
| 604 | </tgroup> | ||
| 605 | </table> | ||
| 606 | |||
| 607 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1"> | ||
| 608 | <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> | ||
| 609 | </title> | ||
| 610 | <tgroup cols="3"> | ||
| 611 | &cs-str; | ||
| 612 | <tbody valign="top"> | ||
| 613 | <row> | ||
| 614 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | ||
| 615 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | ||
| 616 | </entry> | ||
| 617 | <entry><structfield>line</structfield>[36]</entry> | ||
| 618 | <entry>A fixed length array of 36 lines of sliced VBI | ||
| 619 | data. <structfield>line</structfield>[0] through <structfield>line | ||
| 620 | </structfield>[17] correspond to lines 6 through 23 of the | ||
| 621 | first field. <structfield>line</structfield>[18] through | ||
| 622 | <structfield>line</structfield>[35] corresponds to lines 6 | ||
| 623 | through 23 of the second field.</entry> | ||
| 624 | </row> | ||
| 625 | </tbody> | ||
| 626 | </tgroup> | ||
| 627 | </table> | ||
| 628 | |||
| 629 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> | ||
| 630 | <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> | ||
| 631 | </title> | ||
| 632 | <tgroup cols="3"> | ||
| 633 | &cs-str; | ||
| 634 | <tbody valign="top"> | ||
| 635 | <row> | ||
| 636 | <entry>__u8</entry> | ||
| 637 | <entry><structfield>id</structfield></entry> | ||
| 638 | <entry>A line identifier value from | ||
| 639 | <xref linkend="ITV0-Line-Identifier-Constants" /> that indicates | ||
| 640 | the type of sliced VBI data stored on this line.</entry> | ||
| 641 | </row> | ||
| 642 | <row> | ||
| 643 | <entry>__u8</entry> | ||
| 644 | <entry><structfield>data</structfield>[42]</entry> | ||
| 645 | <entry>The sliced VBI data for the line.</entry> | ||
| 646 | </row> | ||
| 647 | </tbody> | ||
| 648 | </tgroup> | ||
| 649 | </table> | ||
| 650 | |||
| 651 | <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> | ||
| 652 | <title>Line Identifiers for struct <link | ||
| 653 | linkend="v4l2-mpeg-vbi-itv0-line"><structname> | ||
| 654 | v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id | ||
| 655 | </structfield> field</title> | ||
| 656 | <tgroup cols="3"> | ||
| 657 | &cs-def; | ||
| 658 | <thead> | ||
| 659 | <row> | ||
| 660 | <entry align="left">Defined Symbol</entry> | ||
| 661 | <entry align="left">Value</entry> | ||
| 662 | <entry align="left">Description</entry> | ||
| 663 | </row> | ||
| 664 | </thead> | ||
| 665 | <tbody valign="top"> | ||
| 666 | <row> | ||
| 667 | <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> | ||
| 668 | </entry> | ||
| 669 | <entry>1</entry> | ||
| 670 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 671 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 672 | </row> | ||
| 673 | <row> | ||
| 674 | <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> | ||
| 675 | </entry> | ||
| 676 | <entry>4</entry> | ||
| 677 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 678 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 679 | </row> | ||
| 680 | <row> | ||
| 681 | <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> | ||
| 682 | </entry> | ||
| 683 | <entry>5</entry> | ||
| 684 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 685 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 686 | </row> | ||
| 687 | <row> | ||
| 688 | <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> | ||
| 689 | </entry> | ||
| 690 | <entry>7</entry> | ||
| 691 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 692 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 693 | </row> | ||
| 694 | </tbody> | ||
| 695 | </tgroup> | ||
| 696 | </table> | ||
| 697 | |||
| 698 | </section> | ||
| 699 | </section> | ||
| 700 | |||
| 701 | |||
| 702 | <!-- | ||
| 703 | Local Variables: | ||
| 704 | mode: sgml | ||
| 705 | sgml-parent-document: "v4l2.sgml" | ||
| 706 | indent-tabs-mode: nil | ||
| 707 | End: | ||
| 708 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-teletext.xml b/Documentation/DocBook/v4l/dev-teletext.xml new file mode 100644 index 000000000000..76184e8ed618 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-teletext.xml | |||
| @@ -0,0 +1,40 @@ | |||
| 1 | <title>Teletext Interface</title> | ||
| 2 | |||
| 3 | <para>This interface aims at devices receiving and demodulating | ||
| 4 | Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the | ||
| 5 | Teletext packages and storing formatted pages in cache memory. Such | ||
| 6 | devices are usually implemented as microcontrollers with serial | ||
| 7 | interface (I<superscript>2</superscript>C) and can be found on older | ||
| 8 | TV cards, dedicated Teletext decoding cards and home-brew devices | ||
| 9 | connected to the PC parallel port.</para> | ||
| 10 | |||
| 11 | <para>The Teletext API was designed by Martin Buck. It is defined in | ||
| 12 | the kernel header file <filename>linux/videotext.h</filename>, the | ||
| 13 | specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/"> | ||
| 14 | ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of | ||
| 15 | the German public television Teletext service.) Conventional character | ||
| 16 | device file names are <filename>/dev/vtx</filename> and | ||
| 17 | <filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16 | ||
| 18 | respectively. A similar interface exists for the Philips SAA5249 | ||
| 19 | Teletext decoder [specification?] with character device file names | ||
| 20 | <filename>/dev/tlkN</filename>, device number 102, N.</para> | ||
| 21 | |||
| 22 | <para>Eventually the Teletext API was integrated into the V4L API | ||
| 23 | with character device file names <filename>/dev/vtx0</filename> to | ||
| 24 | <filename>/dev/vtx31</filename>, device major number 81, minor numbers | ||
| 25 | 192 to 223. For reference the V4L Teletext API specification is | ||
| 26 | reproduced here in full: "Teletext interfaces talk the existing VTX | ||
| 27 | API." Teletext devices with major number 83 and 102 will be removed in | ||
| 28 | Linux 2.6.</para> | ||
| 29 | |||
| 30 | <para>There are no plans to replace the Teletext API or to integrate | ||
| 31 | it into V4L2. Please write to the linux-media mailing list: &v4l-ml; | ||
| 32 | when the need arises.</para> | ||
| 33 | |||
| 34 | <!-- | ||
| 35 | Local Variables: | ||
| 36 | mode: sgml | ||
| 37 | sgml-parent-document: "v4l2.sgml" | ||
| 38 | indent-tabs-mode: nil | ||
| 39 | End: | ||
| 40 | --> | ||
diff --git a/Documentation/DocBook/v4l/driver.xml b/Documentation/DocBook/v4l/driver.xml new file mode 100644 index 000000000000..1f7eea5c4ec3 --- /dev/null +++ b/Documentation/DocBook/v4l/driver.xml | |||
| @@ -0,0 +1,208 @@ | |||
| 1 | <title>V4L2 Driver Programming</title> | ||
| 2 | |||
| 3 | <!-- This part defines the interface between the "videodev" | ||
| 4 | module and individual drivers. --> | ||
| 5 | |||
| 6 | <para>to do</para> | ||
| 7 | <!-- | ||
| 8 | <para>V4L2 is a two-layer driver system. The top layer is the "videodev" | ||
| 9 | kernel module. When videodev initializes it registers as character device | ||
| 10 | with major number 81, and it registers a set of file operations. All V4L2 | ||
| 11 | drivers are really clients of videodev, which calls V4L2 drivers through | ||
| 12 | driver method functions. V4L2 drivers are also written as kernel modules. | ||
| 13 | After probing the hardware they register one or more devices with | ||
| 14 | videodev.</para> | ||
| 15 | |||
| 16 | <section id="driver-modules"> | ||
| 17 | <title>Driver Modules</title> | ||
| 18 | |||
| 19 | <para>V4L2 driver modules must have an initialization function which is | ||
| 20 | called after the module was loaded into kernel, an exit function whis is | ||
| 21 | called before the module is removed. When the driver is compiled into the | ||
| 22 | kernel these functions called at system boot and shutdown time.</para> | ||
| 23 | |||
| 24 | <informalexample> | ||
| 25 | <programlisting> | ||
| 26 | #include <linux/module.h> | ||
| 27 | |||
| 28 | /* Export information about this module. For details and other useful | ||
| 29 | macros see <filename>linux/module.h</filename>. */ | ||
| 30 | MODULE_DESCRIPTION("my - driver for my hardware"); | ||
| 31 | MODULE_AUTHOR("Your name here"); | ||
| 32 | MODULE_LICENSE("GPL"); | ||
| 33 | |||
| 34 | static void | ||
| 35 | my_module_exit (void) | ||
| 36 | { | ||
| 37 | /* Free all resources allocated by my_module_init(). */ | ||
| 38 | } | ||
| 39 | |||
| 40 | static int | ||
| 41 | my_module_init (void) | ||
| 42 | { | ||
| 43 | /* Bind the driver to the supported hardware, see | ||
| 44 | <link linkend="driver-pci"> and | ||
| 45 | <link linkend="driver-usb"> for examples. */ | ||
| 46 | |||
| 47 | return 0; /* a negative value on error, 0 on success. */ | ||
| 48 | } | ||
| 49 | |||
| 50 | /* Export module functions. */ | ||
| 51 | module_init (my_module_init); | ||
| 52 | module_exit (my_module_exit); | ||
| 53 | </programlisting> | ||
| 54 | </informalexample> | ||
| 55 | |||
| 56 | <para>Users can add parameters when kernel modules are inserted:</para> | ||
| 57 | |||
| 58 | <informalexample> | ||
| 59 | <programlisting> | ||
| 60 | include <linux/moduleparam.h> | ||
| 61 | |||
| 62 | static int my_option = 123; | ||
| 63 | static int my_option_array[47]; | ||
| 64 | |||
| 65 | /* Export the symbol, an int, with access permissions 0664. | ||
| 66 | See <filename>linux/moduleparam.h</filename> for other types. */ | ||
| 67 | module_param (my_option, int, 0644); | ||
| 68 | module_param_array (my_option_array, int, NULL, 0644); | ||
| 69 | |||
| 70 | MODULE_PARM_DESC (my_option, "Does magic things, default 123"); | ||
| 71 | </programlisting> | ||
| 72 | </informalexample> | ||
| 73 | |||
| 74 | <para>One parameter should be supported by all V4L2 drivers, the minor | ||
| 75 | number of the device it will register. Purpose is to predictably link V4L2 | ||
| 76 | drivers to device nodes if more than one video device is installed. Use the | ||
| 77 | name of the device node followed by a "_nr" suffix, for example "video_nr" | ||
| 78 | for <filename>/dev/video</filename>.</para> | ||
| 79 | |||
| 80 | <informalexample> | ||
| 81 | <programlisting> | ||
| 82 | /* Minor number of the device, -1 to allocate the first unused. */ | ||
| 83 | static int video_nr = -1; | ||
| 84 | |||
| 85 | module_param (video_nr, int, 0444); | ||
| 86 | </programlisting> | ||
| 87 | </informalexample> | ||
| 88 | </section> | ||
| 89 | |||
| 90 | <section id="driver-pci"> | ||
| 91 | <title>PCI Devices</title> | ||
| 92 | |||
| 93 | <para>PCI devices are initialized like this:</para> | ||
| 94 | |||
| 95 | <informalexample> | ||
| 96 | <programlisting> | ||
| 97 | typedef struct { | ||
| 98 | /* State of one physical device. */ | ||
| 99 | } my_device; | ||
| 100 | |||
| 101 | static int | ||
| 102 | my_resume (struct pci_dev * pci_dev) | ||
| 103 | { | ||
| 104 | /* Restore the suspended device to working state. */ | ||
| 105 | } | ||
| 106 | |||
| 107 | static int | ||
| 108 | my_suspend (struct pci_dev * pci_dev, | ||
| 109 | pm_message_t state) | ||
| 110 | { | ||
| 111 | /* This function is called before the system goes to sleep. | ||
| 112 | Stop all DMAs and disable interrupts, then put the device | ||
| 113 | into a low power state. For details see the kernel | ||
| 114 | sources under <filename>Documentation/power</filename>. */ | ||
| 115 | |||
| 116 | return 0; /* a negative value on error, 0 on success. */ | ||
| 117 | } | ||
| 118 | |||
| 119 | static void __devexit | ||
| 120 | my_remove (struct pci_dev * pci_dev) | ||
| 121 | { | ||
| 122 | my_device *my = pci_get_drvdata (pci_dev); | ||
| 123 | |||
| 124 | /* Describe me. */ | ||
| 125 | } | ||
| 126 | |||
| 127 | static int __devinit | ||
| 128 | my_probe (struct pci_dev * pci_dev, | ||
| 129 | const struct pci_device_id * pci_id) | ||
| 130 | { | ||
| 131 | my_device *my; | ||
| 132 | |||
| 133 | /* Describe me. */ | ||
| 134 | |||
| 135 | /* You can allocate per-device data here and store a pointer | ||
| 136 | to it in the pci_dev structure. */ | ||
| 137 | my = ...; | ||
| 138 | pci_set_drvdata (pci_dev, my); | ||
| 139 | |||
| 140 | return 0; /* a negative value on error, 0 on success. */ | ||
| 141 | } | ||
| 142 | |||
| 143 | /* A list of supported PCI devices. */ | ||
| 144 | static struct pci_device_id | ||
| 145 | my_pci_device_ids [] = { | ||
| 146 | { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, | ||
| 147 | PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 }, | ||
| 148 | { 0 } /* end of list */ | ||
| 149 | }; | ||
| 150 | |||
| 151 | /* Load our module if supported PCI devices are installed. */ | ||
| 152 | MODULE_DEVICE_TABLE (pci, my_pci_device_ids); | ||
| 153 | |||
| 154 | static struct pci_driver | ||
| 155 | my_pci_driver = { | ||
| 156 | .name = "my", | ||
| 157 | .id_table = my_pci_device_ids, | ||
| 158 | |||
| 159 | .probe = my_probe, | ||
| 160 | .remove = __devexit_p (my_remove), | ||
| 161 | |||
| 162 | /* Power management functions. */ | ||
| 163 | .suspend = my_suspend, | ||
| 164 | .resume = my_resume, | ||
| 165 | }; | ||
| 166 | |||
| 167 | static void | ||
| 168 | my_module_exit (void) | ||
| 169 | { | ||
| 170 | pci_unregister_driver (&my_pci_driver); | ||
| 171 | } | ||
| 172 | |||
| 173 | static int | ||
| 174 | my_module_init (void) | ||
| 175 | { | ||
| 176 | return pci_register_driver (&my_pci_driver); | ||
| 177 | } | ||
| 178 | </programlisting> | ||
| 179 | </informalexample> | ||
| 180 | </section> | ||
| 181 | |||
| 182 | <section id="driver-usb"> | ||
| 183 | <title>USB Devices</title> | ||
| 184 | <para>to do</para> | ||
| 185 | </section> | ||
| 186 | <section id="driver-registering"> | ||
| 187 | <title>Registering V4L2 Drivers</title> | ||
| 188 | |||
| 189 | <para>After a V4L2 driver probed the hardware it registers one or more | ||
| 190 | devices with the videodev module.</para> | ||
| 191 | </section> | ||
| 192 | <section id="driver-file-ops"> | ||
| 193 | <title>File Operations</title> | ||
| 194 | <para>to do</para> | ||
| 195 | </section> | ||
| 196 | <section id="driver-internal-api"> | ||
| 197 | <title>Internal API</title> | ||
| 198 | <para>to do</para> | ||
| 199 | </section> | ||
| 200 | --> | ||
| 201 | |||
| 202 | <!-- | ||
| 203 | Local Variables: | ||
| 204 | mode: sgml | ||
| 205 | sgml-parent-document: "v4l2.sgml" | ||
| 206 | indent-tabs-mode: nil | ||
| 207 | End: | ||
| 208 | --> | ||
diff --git a/Documentation/DocBook/v4l/fdl-appendix.xml b/Documentation/DocBook/v4l/fdl-appendix.xml new file mode 100644 index 000000000000..b6ce50dbe492 --- /dev/null +++ b/Documentation/DocBook/v4l/fdl-appendix.xml | |||
| @@ -0,0 +1,671 @@ | |||
| 1 | <!-- | ||
| 2 | The GNU Free Documentation License 1.1 in DocBook | ||
| 3 | Markup by Eric Baudais <baudais@okstate.edu> | ||
| 4 | Maintained by the GNOME Documentation Project | ||
| 5 | http://developer.gnome.org/projects/gdp | ||
| 6 | Version: 1.0.1 | ||
| 7 | Last Modified: Nov 16, 2000 | ||
| 8 | --> | ||
| 9 | |||
| 10 | <appendix id="fdl"> | ||
| 11 | <appendixinfo> | ||
| 12 | <releaseinfo> | ||
| 13 | Version 1.1, March 2000 | ||
| 14 | </releaseinfo> | ||
| 15 | <copyright> | ||
| 16 | <year>2000</year><holder>Free Software Foundation, Inc.</holder> | ||
| 17 | </copyright> | ||
| 18 | <legalnotice id="fdl-legalnotice"> | ||
| 19 | <para> | ||
| 20 | <address>Free Software Foundation, Inc. <street>59 Temple Place, | ||
| 21 | Suite 330</street>, <city>Boston</city>, <state>MA</state> | ||
| 22 | <postcode>02111-1307</postcode> <country>USA</country></address> | ||
| 23 | Everyone is permitted to copy and distribute verbatim copies of this | ||
| 24 | license document, but changing it is not allowed. | ||
| 25 | </para> | ||
| 26 | </legalnotice> | ||
| 27 | </appendixinfo> | ||
| 28 | <title>GNU Free Documentation License</title> | ||
| 29 | |||
| 30 | <sect1 id="fdl-preamble"> | ||
| 31 | <title>0. PREAMBLE</title> | ||
| 32 | <para> | ||
| 33 | The purpose of this License is to make a manual, textbook, or | ||
| 34 | other written document <quote>free</quote> in the sense of | ||
| 35 | freedom: to assure everyone the effective freedom to copy and | ||
| 36 | redistribute it, with or without modifying it, either | ||
| 37 | commercially or noncommercially. Secondarily, this License | ||
| 38 | preserves for the author and publisher a way to get credit for | ||
| 39 | their work, while not being considered responsible for | ||
| 40 | modifications made by others. | ||
| 41 | </para> | ||
| 42 | |||
| 43 | <para> | ||
| 44 | This License is a kind of <quote>copyleft</quote>, which means | ||
| 45 | that derivative works of the document must themselves be free in | ||
| 46 | the same sense. It complements the GNU General Public License, | ||
| 47 | which is a copyleft license designed for free software. | ||
| 48 | </para> | ||
| 49 | |||
| 50 | <para> | ||
| 51 | We have designed this License in order to use it for manuals for | ||
| 52 | free software, because free software needs free documentation: a | ||
| 53 | free program should come with manuals providing the same | ||
| 54 | freedoms that the software does. But this License is not limited | ||
| 55 | to software manuals; it can be used for any textual work, | ||
| 56 | regardless of subject matter or whether it is published as a | ||
| 57 | printed book. We recommend this License principally for works | ||
| 58 | whose purpose is instruction or reference. | ||
| 59 | </para> | ||
| 60 | </sect1> | ||
| 61 | <sect1 id="fdl-section1"> | ||
| 62 | <title>1. APPLICABILITY AND DEFINITIONS</title> | ||
| 63 | <para id="fdl-document"> | ||
| 64 | This License applies to any manual or other work that contains a | ||
| 65 | notice placed by the copyright holder saying it can be | ||
| 66 | distributed under the terms of this License. The | ||
| 67 | <quote>Document</quote>, below, refers to any such manual or | ||
| 68 | work. Any member of the public is a licensee, and is addressed | ||
| 69 | as <quote>you</quote>. | ||
| 70 | </para> | ||
| 71 | |||
| 72 | <para id="fdl-modified"> | ||
| 73 | A <quote>Modified Version</quote> of the Document means any work | ||
| 74 | containing the Document or a portion of it, either copied | ||
| 75 | verbatim, or with modifications and/or translated into another | ||
| 76 | language. | ||
| 77 | </para> | ||
| 78 | |||
| 79 | <para id="fdl-secondary"> | ||
| 80 | A <quote>Secondary Section</quote> is a named appendix or a | ||
| 81 | front-matter section of the <link | ||
| 82 | linkend="fdl-document">Document</link> that deals exclusively | ||
| 83 | with the relationship of the publishers or authors of the | ||
| 84 | Document to the Document's overall subject (or to related | ||
| 85 | matters) and contains nothing that could fall directly within | ||
| 86 | that overall subject. (For example, if the Document is in part a | ||
| 87 | textbook of mathematics, a Secondary Section may not explain any | ||
| 88 | mathematics.) The relationship could be a matter of historical | ||
| 89 | connection with the subject or with related matters, or of | ||
| 90 | legal, commercial, philosophical, ethical or political position | ||
| 91 | regarding them. | ||
| 92 | </para> | ||
| 93 | |||
| 94 | <para id="fdl-invariant"> | ||
| 95 | The <quote>Invariant Sections</quote> are certain <link | ||
| 96 | linkend="fdl-secondary"> Secondary Sections</link> whose titles | ||
| 97 | are designated, as being those of Invariant Sections, in the | ||
| 98 | notice that says that the <link | ||
| 99 | linkend="fdl-document">Document</link> is released under this | ||
| 100 | License. | ||
| 101 | </para> | ||
| 102 | |||
| 103 | <para id="fdl-cover-texts"> | ||
| 104 | The <quote>Cover Texts</quote> are certain short passages of | ||
| 105 | text that are listed, as Front-Cover Texts or Back-Cover Texts, | ||
| 106 | in the notice that says that the <link | ||
| 107 | linkend="fdl-document">Document</link> is released under this | ||
| 108 | License. | ||
| 109 | </para> | ||
| 110 | |||
| 111 | <para id="fdl-transparent"> | ||
| 112 | A <quote>Transparent</quote> copy of the <link | ||
| 113 | linkend="fdl-document"> Document</link> means a machine-readable | ||
| 114 | copy, represented in a format whose specification is available | ||
| 115 | to the general public, whose contents can be viewed and edited | ||
| 116 | directly and straightforwardly with generic text editors or (for | ||
| 117 | images composed of pixels) generic paint programs or (for | ||
| 118 | drawings) some widely available drawing editor, and that is | ||
| 119 | suitable for input to text formatters or for automatic | ||
| 120 | translation to a variety of formats suitable for input to text | ||
| 121 | formatters. A copy made in an otherwise Transparent file format | ||
| 122 | whose markup has been designed to thwart or discourage | ||
| 123 | subsequent modification by readers is not Transparent. A copy | ||
| 124 | that is not <quote>Transparent</quote> is called | ||
| 125 | <quote>Opaque</quote>. | ||
| 126 | </para> | ||
| 127 | |||
| 128 | <para> | ||
| 129 | Examples of suitable formats for Transparent copies include | ||
| 130 | plain ASCII without markup, Texinfo input format, LaTeX input | ||
| 131 | format, SGML or XML using a publicly available DTD, and | ||
| 132 | standard-conforming simple HTML designed for human | ||
| 133 | modification. Opaque formats include PostScript, PDF, | ||
| 134 | proprietary formats that can be read and edited only by | ||
| 135 | proprietary word processors, SGML or XML for which the DTD | ||
| 136 | and/or processing tools are not generally available, and the | ||
| 137 | machine-generated HTML produced by some word processors for | ||
| 138 | output purposes only. | ||
| 139 | </para> | ||
| 140 | |||
| 141 | <para id="fdl-title-page"> | ||
| 142 | The <quote>Title Page</quote> means, for a printed book, the | ||
| 143 | title page itself, plus such following pages as are needed to | ||
| 144 | hold, legibly, the material this License requires to appear in | ||
| 145 | the title page. For works in formats which do not have any title | ||
| 146 | page as such, <quote>Title Page</quote> means the text near the | ||
| 147 | most prominent appearance of the work's title, preceding the | ||
| 148 | beginning of the body of the text. | ||
| 149 | </para> | ||
| 150 | </sect1> | ||
| 151 | |||
| 152 | <sect1 id="fdl-section2"> | ||
| 153 | <title>2. VERBATIM COPYING</title> | ||
| 154 | <para> | ||
| 155 | You may copy and distribute the <link | ||
| 156 | linkend="fdl-document">Document</link> in any medium, either | ||
| 157 | commercially or noncommercially, provided that this License, the | ||
| 158 | copyright notices, and the license notice saying this License | ||
| 159 | applies to the Document are reproduced in all copies, and that | ||
| 160 | you add no other conditions whatsoever to those of this | ||
| 161 | License. You may not use technical measures to obstruct or | ||
| 162 | control the reading or further copying of the copies you make or | ||
| 163 | distribute. However, you may accept compensation in exchange for | ||
| 164 | copies. If you distribute a large enough number of copies you | ||
| 165 | must also follow the conditions in <link | ||
| 166 | linkend="fdl-section3">section 3</link>. | ||
| 167 | </para> | ||
| 168 | |||
| 169 | <para> | ||
| 170 | You may also lend copies, under the same conditions stated | ||
| 171 | above, and you may publicly display copies. | ||
| 172 | </para> | ||
| 173 | </sect1> | ||
| 174 | |||
| 175 | <sect1 id="fdl-section3"> | ||
| 176 | <title>3. COPYING IN QUANTITY</title> | ||
| 177 | <para> | ||
| 178 | If you publish printed copies of the <link | ||
| 179 | linkend="fdl-document">Document</link> numbering more than 100, | ||
| 180 | and the Document's license notice requires <link | ||
| 181 | linkend="fdl-cover-texts">Cover Texts</link>, you must enclose | ||
| 182 | the copies in covers that carry, clearly and legibly, all these | ||
| 183 | Cover Texts: Front-Cover Texts on the front cover, and | ||
| 184 | Back-Cover Texts on the back cover. Both covers must also | ||
| 185 | clearly and legibly identify you as the publisher of these | ||
| 186 | copies. The front cover must present the full title with all | ||
| 187 | words of the title equally prominent and visible. You may add | ||
| 188 | other material on the covers in addition. Copying with changes | ||
| 189 | limited to the covers, as long as they preserve the title of the | ||
| 190 | <link linkend="fdl-document">Document</link> and satisfy these | ||
| 191 | conditions, can be treated as verbatim copying in other | ||
| 192 | respects. | ||
| 193 | </para> | ||
| 194 | |||
| 195 | <para> | ||
| 196 | If the required texts for either cover are too voluminous to fit | ||
| 197 | legibly, you should put the first ones listed (as many as fit | ||
| 198 | reasonably) on the actual cover, and continue the rest onto | ||
| 199 | adjacent pages. | ||
| 200 | </para> | ||
| 201 | |||
| 202 | <para> | ||
| 203 | If you publish or distribute <link | ||
| 204 | linkend="fdl-transparent">Opaque</link> copies of the <link | ||
| 205 | linkend="fdl-document">Document</link> numbering more than 100, | ||
| 206 | you must either include a machine-readable <link | ||
| 207 | linkend="fdl-transparent">Transparent</link> copy along with | ||
| 208 | each Opaque copy, or state in or with each Opaque copy a | ||
| 209 | publicly-accessible computer-network location containing a | ||
| 210 | complete Transparent copy of the Document, free of added | ||
| 211 | material, which the general network-using public has access to | ||
| 212 | download anonymously at no charge using public-standard network | ||
| 213 | protocols. If you use the latter option, you must take | ||
| 214 | reasonably prudent steps, when you begin distribution of Opaque | ||
| 215 | copies in quantity, to ensure that this Transparent copy will | ||
| 216 | remain thus accessible at the stated location until at least one | ||
| 217 | year after the last time you distribute an Opaque copy (directly | ||
| 218 | or through your agents or retailers) of that edition to the | ||
| 219 | public. | ||
| 220 | </para> | ||
| 221 | |||
| 222 | <para> | ||
| 223 | It is requested, but not required, that you contact the authors | ||
| 224 | of the <link linkend="fdl-document">Document</link> well before | ||
| 225 | redistributing any large number of copies, to give them a chance | ||
| 226 | to provide you with an updated version of the Document. | ||
| 227 | </para> | ||
| 228 | </sect1> | ||
| 229 | |||
| 230 | <sect1 id="fdl-section4"> | ||
| 231 | <title>4. MODIFICATIONS</title> | ||
| 232 | <para> | ||
| 233 | You may copy and distribute a <link | ||
| 234 | linkend="fdl-modified">Modified Version</link> of the <link | ||
| 235 | linkend="fdl-document">Document</link> under the conditions of | ||
| 236 | sections <link linkend="fdl-section2">2</link> and <link | ||
| 237 | linkend="fdl-section3">3</link> above, provided that you release | ||
| 238 | the Modified Version under precisely this License, with the | ||
| 239 | Modified Version filling the role of the Document, thus | ||
| 240 | licensing distribution and modification of the Modified Version | ||
| 241 | to whoever possesses a copy of it. In addition, you must do | ||
| 242 | these things in the Modified Version: | ||
| 243 | </para> | ||
| 244 | |||
| 245 | <itemizedlist mark="opencircle"> | ||
| 246 | <listitem> | ||
| 247 | <formalpara> | ||
| 248 | <title>A</title> | ||
| 249 | <para> | ||
| 250 | Use in the <link linkend="fdl-title-page">Title | ||
| 251 | Page</link> (and on the covers, if any) a title distinct | ||
| 252 | from that of the <link | ||
| 253 | linkend="fdl-document">Document</link>, and from those of | ||
| 254 | previous versions (which should, if there were any, be | ||
| 255 | listed in the History section of the Document). You may | ||
| 256 | use the same title as a previous version if the original | ||
| 257 | publisher of that version gives permission. | ||
| 258 | </para> | ||
| 259 | </formalpara> | ||
| 260 | </listitem> | ||
| 261 | |||
| 262 | <listitem> | ||
| 263 | <formalpara> | ||
| 264 | <title>B</title> | ||
| 265 | <para> | ||
| 266 | List on the <link linkend="fdl-title-page">Title | ||
| 267 | Page</link>, as authors, one or more persons or entities | ||
| 268 | responsible for authorship of the modifications in the | ||
| 269 | <link linkend="fdl-modified">Modified Version</link>, | ||
| 270 | together with at least five of the principal authors of | ||
| 271 | the <link linkend="fdl-document">Document</link> (all of | ||
| 272 | its principal authors, if it has less than five). | ||
| 273 | </para> | ||
| 274 | </formalpara> | ||
| 275 | </listitem> | ||
| 276 | |||
| 277 | <listitem> | ||
| 278 | <formalpara> | ||
| 279 | <title>C</title> | ||
| 280 | <para> | ||
| 281 | State on the <link linkend="fdl-title-page">Title | ||
| 282 | Page</link> the name of the publisher of the <link | ||
| 283 | linkend="fdl-modified">Modified Version</link>, as the | ||
| 284 | publisher. | ||
| 285 | </para> | ||
| 286 | </formalpara> | ||
| 287 | </listitem> | ||
| 288 | |||
| 289 | <listitem> | ||
| 290 | <formalpara> | ||
| 291 | <title>D</title> | ||
| 292 | <para> | ||
| 293 | Preserve all the copyright notices of the <link | ||
| 294 | linkend="fdl-document">Document</link>. | ||
| 295 | </para> | ||
| 296 | </formalpara> | ||
| 297 | </listitem> | ||
| 298 | |||
| 299 | <listitem> | ||
| 300 | <formalpara> | ||
| 301 | <title>E</title> | ||
| 302 | <para> | ||
| 303 | Add an appropriate copyright notice for your modifications | ||
| 304 | adjacent to the other copyright notices. | ||
| 305 | </para> | ||
| 306 | </formalpara> | ||
| 307 | </listitem> | ||
| 308 | |||
| 309 | <listitem> | ||
| 310 | <formalpara> | ||
| 311 | <title>F</title> | ||
| 312 | <para> | ||
| 313 | Include, immediately after the copyright notices, a | ||
| 314 | license notice giving the public permission to use the | ||
| 315 | <link linkend="fdl-modified">Modified Version</link> under | ||
| 316 | the terms of this License, in the form shown in the | ||
| 317 | Addendum below. | ||
| 318 | </para> | ||
| 319 | </formalpara> | ||
| 320 | </listitem> | ||
| 321 | |||
| 322 | <listitem> | ||
| 323 | <formalpara> | ||
| 324 | <title>G</title> | ||
| 325 | <para> | ||
| 326 | Preserve in that license notice the full lists of <link | ||
| 327 | linkend="fdl-invariant"> Invariant Sections</link> and | ||
| 328 | required <link linkend="fdl-cover-texts">Cover | ||
| 329 | Texts</link> given in the <link | ||
| 330 | linkend="fdl-document">Document's</link> license notice. | ||
| 331 | </para> | ||
| 332 | </formalpara> | ||
| 333 | </listitem> | ||
| 334 | |||
| 335 | <listitem> | ||
| 336 | <formalpara> | ||
| 337 | <title>H</title> | ||
| 338 | <para> | ||
| 339 | Include an unaltered copy of this License. | ||
| 340 | </para> | ||
| 341 | </formalpara> | ||
| 342 | </listitem> | ||
| 343 | |||
| 344 | <listitem> | ||
| 345 | <formalpara> | ||
| 346 | <title>I</title> | ||
| 347 | <para> | ||
| 348 | Preserve the section entitled <quote>History</quote>, and | ||
| 349 | its title, and add to it an item stating at least the | ||
| 350 | title, year, new authors, and publisher of the <link | ||
| 351 | linkend="fdl-modified">Modified Version </link>as given on | ||
| 352 | the <link linkend="fdl-title-page">Title Page</link>. If | ||
| 353 | there is no section entitled <quote>History</quote> in the | ||
| 354 | <link linkend="fdl-document">Document</link>, create one | ||
| 355 | stating the title, year, authors, and publisher of the | ||
| 356 | Document as given on its Title Page, then add an item | ||
| 357 | describing the Modified Version as stated in the previous | ||
| 358 | sentence. | ||
| 359 | </para> | ||
| 360 | </formalpara> | ||
| 361 | </listitem> | ||
| 362 | |||
| 363 | <listitem> | ||
| 364 | <formalpara> | ||
| 365 | <title>J</title> | ||
| 366 | <para> | ||
| 367 | Preserve the network location, if any, given in the <link | ||
| 368 | linkend="fdl-document">Document</link> for public access | ||
| 369 | to a <link linkend="fdl-transparent">Transparent</link> | ||
| 370 | copy of the Document, and likewise the network locations | ||
| 371 | given in the Document for previous versions it was based | ||
| 372 | on. These may be placed in the <quote>History</quote> | ||
| 373 | section. You may omit a network location for a work that | ||
| 374 | was published at least four years before the Document | ||
| 375 | itself, or if the original publisher of the version it | ||
| 376 | refers to gives permission. | ||
| 377 | </para> | ||
| 378 | </formalpara> | ||
| 379 | </listitem> | ||
| 380 | |||
| 381 | <listitem> | ||
| 382 | <formalpara> | ||
| 383 | <title>K</title> | ||
| 384 | <para> | ||
| 385 | In any section entitled <quote>Acknowledgements</quote> or | ||
| 386 | <quote>Dedications</quote>, preserve the section's title, | ||
| 387 | and preserve in the section all the substance and tone of | ||
| 388 | each of the contributor acknowledgements and/or | ||
| 389 | dedications given therein. | ||
| 390 | </para> | ||
| 391 | </formalpara> | ||
| 392 | </listitem> | ||
| 393 | |||
| 394 | <listitem> | ||
| 395 | <formalpara> | ||
| 396 | <title>L</title> | ||
| 397 | <para> | ||
| 398 | Preserve all the <link linkend="fdl-invariant">Invariant | ||
| 399 | Sections</link> of the <link | ||
| 400 | linkend="fdl-document">Document</link>, unaltered in their | ||
| 401 | text and in their titles. Section numbers or the | ||
| 402 | equivalent are not considered part of the section titles. | ||
| 403 | </para> | ||
| 404 | </formalpara> | ||
| 405 | </listitem> | ||
| 406 | |||
| 407 | <listitem> | ||
| 408 | <formalpara> | ||
| 409 | <title>M</title> | ||
| 410 | <para> | ||
| 411 | Delete any section entitled | ||
| 412 | <quote>Endorsements</quote>. Such a section may not be | ||
| 413 | included in the <link linkend="fdl-modified">Modified | ||
| 414 | Version</link>. | ||
| 415 | </para> | ||
| 416 | </formalpara> | ||
| 417 | </listitem> | ||
| 418 | |||
| 419 | <listitem> | ||
| 420 | <formalpara> | ||
| 421 | <title>N</title> | ||
| 422 | <para> | ||
| 423 | Do not retitle any existing section as | ||
| 424 | <quote>Endorsements</quote> or to conflict in title with | ||
| 425 | any <link linkend="fdl-invariant">Invariant | ||
| 426 | Section</link>. | ||
| 427 | </para> | ||
| 428 | </formalpara> | ||
| 429 | </listitem> | ||
| 430 | </itemizedlist> | ||
| 431 | |||
| 432 | <para> | ||
| 433 | If the <link linkend="fdl-modified">Modified Version</link> | ||
| 434 | includes new front-matter sections or appendices that qualify as | ||
| 435 | <link linkend="fdl-secondary">Secondary Sections</link> and | ||
| 436 | contain no material copied from the Document, you may at your | ||
| 437 | option designate some or all of these sections as invariant. To | ||
| 438 | do this, add their titles to the list of <link | ||
| 439 | linkend="fdl-invariant">Invariant Sections</link> in the | ||
| 440 | Modified Version's license notice. These titles must be | ||
| 441 | distinct from any other section titles. | ||
| 442 | </para> | ||
| 443 | |||
| 444 | <para> | ||
| 445 | You may add a section entitled <quote>Endorsements</quote>, | ||
| 446 | provided it contains nothing but endorsements of your <link | ||
| 447 | linkend="fdl-modified">Modified Version</link> by various | ||
| 448 | parties--for example, statements of peer review or that the text | ||
| 449 | has been approved by an organization as the authoritative | ||
| 450 | definition of a standard. | ||
| 451 | </para> | ||
| 452 | |||
| 453 | <para> | ||
| 454 | You may add a passage of up to five words as a <link | ||
| 455 | linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage | ||
| 456 | of up to 25 words as a <link | ||
| 457 | linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of | ||
| 458 | the list of <link linkend="fdl-cover-texts">Cover Texts</link> | ||
| 459 | in the <link linkend="fdl-modified">Modified Version</link>. | ||
| 460 | Only one passage of Front-Cover Text and one of Back-Cover Text | ||
| 461 | may be added by (or through arrangements made by) any one | ||
| 462 | entity. If the <link linkend="fdl-document">Document</link> | ||
| 463 | already includes a cover text for the same cover, previously | ||
| 464 | added by you or by arrangement made by the same entity you are | ||
| 465 | acting on behalf of, you may not add another; but you may | ||
| 466 | replace the old one, on explicit permission from the previous | ||
| 467 | publisher that added the old one. | ||
| 468 | </para> | ||
| 469 | |||
| 470 | <para> | ||
| 471 | The author(s) and publisher(s) of the <link | ||
| 472 | linkend="fdl-document">Document</link> do not by this License | ||
| 473 | give permission to use their names for publicity for or to | ||
| 474 | assert or imply endorsement of any <link | ||
| 475 | linkend="fdl-modified">Modified Version </link>. | ||
| 476 | </para> | ||
| 477 | </sect1> | ||
| 478 | |||
| 479 | <sect1 id="fdl-section5"> | ||
| 480 | <title>5. COMBINING DOCUMENTS</title> | ||
| 481 | <para> | ||
| 482 | You may combine the <link linkend="fdl-document">Document</link> | ||
| 483 | with other documents released under this License, under the | ||
| 484 | terms defined in <link linkend="fdl-section4">section 4</link> | ||
| 485 | above for modified versions, provided that you include in the | ||
| 486 | combination all of the <link linkend="fdl-invariant">Invariant | ||
| 487 | Sections</link> of all of the original documents, unmodified, | ||
| 488 | and list them all as Invariant Sections of your combined work in | ||
| 489 | its license notice. | ||
| 490 | </para> | ||
| 491 | |||
| 492 | <para> | ||
| 493 | The combined work need only contain one copy of this License, | ||
| 494 | and multiple identical <link linkend="fdl-invariant">Invariant | ||
| 495 | Sections</link> may be replaced with a single copy. If there are | ||
| 496 | multiple Invariant Sections with the same name but different | ||
| 497 | contents, make the title of each such section unique by adding | ||
| 498 | at the end of it, in parentheses, the name of the original | ||
| 499 | author or publisher of that section if known, or else a unique | ||
| 500 | number. Make the same adjustment to the section titles in the | ||
| 501 | list of Invariant Sections in the license notice of the combined | ||
| 502 | work. | ||
| 503 | </para> | ||
| 504 | |||
| 505 | <para> | ||
| 506 | In the combination, you must combine any sections entitled | ||
| 507 | <quote>History</quote> in the various original documents, | ||
| 508 | forming one section entitled <quote>History</quote>; likewise | ||
| 509 | combine any sections entitled <quote>Acknowledgements</quote>, | ||
| 510 | and any sections entitled <quote>Dedications</quote>. You must | ||
| 511 | delete all sections entitled <quote>Endorsements.</quote> | ||
| 512 | </para> | ||
| 513 | </sect1> | ||
| 514 | |||
| 515 | <sect1 id="fdl-section6"> | ||
| 516 | <title>6. COLLECTIONS OF DOCUMENTS</title> | ||
| 517 | <para> | ||
| 518 | You may make a collection consisting of the <link | ||
| 519 | linkend="fdl-document">Document</link> and other documents | ||
| 520 | released under this License, and replace the individual copies | ||
| 521 | of this License in the various documents with a single copy that | ||
| 522 | is included in the collection, provided that you follow the | ||
| 523 | rules of this License for verbatim copying of each of the | ||
| 524 | documents in all other respects. | ||
| 525 | </para> | ||
| 526 | |||
| 527 | <para> | ||
| 528 | You may extract a single document from such a collection, and | ||
| 529 | dispbibute it individually under this License, provided you | ||
| 530 | insert a copy of this License into the extracted document, and | ||
| 531 | follow this License in all other respects regarding verbatim | ||
| 532 | copying of that document. | ||
| 533 | </para> | ||
| 534 | </sect1> | ||
| 535 | |||
| 536 | <sect1 id="fdl-section7"> | ||
| 537 | <title>7. AGGREGATION WITH INDEPENDENT WORKS</title> | ||
| 538 | <para> | ||
| 539 | A compilation of the <link | ||
| 540 | linkend="fdl-document">Document</link> or its derivatives with | ||
| 541 | other separate and independent documents or works, in or on a | ||
| 542 | volume of a storage or distribution medium, does not as a whole | ||
| 543 | count as a <link linkend="fdl-modified">Modified Version</link> | ||
| 544 | of the Document, provided no compilation copyright is claimed | ||
| 545 | for the compilation. Such a compilation is called an | ||
| 546 | <quote>aggregate</quote>, and this License does not apply to the | ||
| 547 | other self-contained works thus compiled with the Document , on | ||
| 548 | account of their being thus compiled, if they are not themselves | ||
| 549 | derivative works of the Document. If the <link | ||
| 550 | linkend="fdl-cover-texts">Cover Text</link> requirement of <link | ||
| 551 | linkend="fdl-section3">section 3</link> is applicable to these | ||
| 552 | copies of the Document, then if the Document is less than one | ||
| 553 | quarter of the entire aggregate, the Document's Cover Texts may | ||
| 554 | be placed on covers that surround only the Document within the | ||
| 555 | aggregate. Otherwise they must appear on covers around the whole | ||
| 556 | aggregate. | ||
| 557 | </para> | ||
| 558 | </sect1> | ||
| 559 | |||
| 560 | <sect1 id="fdl-section8"> | ||
| 561 | <title>8. TRANSLATION</title> | ||
| 562 | <para> | ||
| 563 | Translation is considered a kind of modification, so you may | ||
| 564 | distribute translations of the <link | ||
| 565 | linkend="fdl-document">Document</link> under the terms of <link | ||
| 566 | linkend="fdl-section4">section 4</link>. Replacing <link | ||
| 567 | linkend="fdl-invariant"> Invariant Sections</link> with | ||
| 568 | translations requires special permission from their copyright | ||
| 569 | holders, but you may include translations of some or all | ||
| 570 | Invariant Sections in addition to the original versions of these | ||
| 571 | Invariant Sections. You may include a translation of this | ||
| 572 | License provided that you also include the original English | ||
| 573 | version of this License. In case of a disagreement between the | ||
| 574 | translation and the original English version of this License, | ||
| 575 | the original English version will prevail. | ||
| 576 | </para> | ||
| 577 | </sect1> | ||
| 578 | |||
| 579 | <sect1 id="fdl-section9"> | ||
| 580 | <title>9. TERMINATION</title> | ||
| 581 | <para> | ||
| 582 | You may not copy, modify, sublicense, or distribute the <link | ||
| 583 | linkend="fdl-document">Document</link> except as expressly | ||
| 584 | provided for under this License. Any other attempt to copy, | ||
| 585 | modify, sublicense or distribute the Document is void, and will | ||
| 586 | automatically terminate your rights under this License. However, | ||
| 587 | parties who have received copies, or rights, from you under this | ||
| 588 | License will not have their licenses terminated so long as such | ||
| 589 | parties remain in full compliance. | ||
| 590 | </para> | ||
| 591 | </sect1> | ||
| 592 | |||
| 593 | <sect1 id="fdl-section10"> | ||
| 594 | <title>10. FUTURE REVISIONS OF THIS LICENSE</title> | ||
| 595 | <para> | ||
| 596 | The <ulink type="http" | ||
| 597 | url="http://www.gnu.org/fsf/fsf.html">Free Software | ||
| 598 | Foundation</ulink> may publish new, revised versions of the GNU | ||
| 599 | Free Documentation License from time to time. Such new versions | ||
| 600 | will be similar in spirit to the present version, but may differ | ||
| 601 | in detail to address new problems or concerns. See <ulink | ||
| 602 | type="http" | ||
| 603 | url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>. | ||
| 604 | </para> | ||
| 605 | |||
| 606 | <para> | ||
| 607 | Each version of the License is given a distinguishing version | ||
| 608 | number. If the <link linkend="fdl-document">Document</link> | ||
| 609 | specifies that a particular numbered version of this License | ||
| 610 | <quote>or any later version</quote> applies to it, you have the | ||
| 611 | option of following the terms and conditions either of that | ||
| 612 | specified version or of any later version that has been | ||
| 613 | published (not as a draft) by the Free Software Foundation. If | ||
| 614 | the Document does not specify a version number of this License, | ||
| 615 | you may choose any version ever published (not as a draft) by | ||
| 616 | the Free Software Foundation. | ||
| 617 | </para> | ||
| 618 | </sect1> | ||
| 619 | |||
| 620 | <sect1 id="fdl-using"> | ||
| 621 | <title>Addendum</title> | ||
| 622 | <para> | ||
| 623 | To use this License in a document you have written, include a copy of | ||
| 624 | the License in the document and put the following copyright and | ||
| 625 | license notices just after the title page: | ||
| 626 | </para> | ||
| 627 | |||
| 628 | <blockquote> | ||
| 629 | <para> | ||
| 630 | Copyright © YEAR YOUR NAME. | ||
| 631 | </para> | ||
| 632 | <para> | ||
| 633 | Permission is granted to copy, distribute and/or modify this | ||
| 634 | document under the terms of the GNU Free Documentation | ||
| 635 | License, Version 1.1 or any later version published by the | ||
| 636 | Free Software Foundation; with the <link | ||
| 637 | linkend="fdl-invariant">Invariant Sections</link> being LIST | ||
| 638 | THEIR TITLES, with the <link | ||
| 639 | linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST, | ||
| 640 | and with the <link linkend="fdl-cover-texts">Back-Cover | ||
| 641 | Texts</link> being LIST. A copy of the license is included in | ||
| 642 | the section entitled <quote>GNU Free Documentation | ||
| 643 | License</quote>. | ||
| 644 | </para> | ||
| 645 | </blockquote> | ||
| 646 | |||
| 647 | <para> | ||
| 648 | If you have no <link linkend="fdl-invariant">Invariant | ||
| 649 | Sections</link>, write <quote>with no Invariant Sections</quote> | ||
| 650 | instead of saying which ones are invariant. If you have no | ||
| 651 | <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write | ||
| 652 | <quote>no Front-Cover Texts</quote> instead of | ||
| 653 | <quote>Front-Cover Texts being LIST</quote>; likewise for <link | ||
| 654 | linkend="fdl-cover-texts">Back-Cover Texts</link>. | ||
| 655 | </para> | ||
| 656 | |||
| 657 | <para> | ||
| 658 | If your document contains nontrivial examples of program code, | ||
| 659 | we recommend releasing these examples in parallel under your | ||
| 660 | choice of free software license, such as the <ulink type="http" | ||
| 661 | url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public | ||
| 662 | License</ulink>, to permit their use in free software. | ||
| 663 | </para> | ||
| 664 | </sect1> | ||
| 665 | </appendix> | ||
| 666 | |||
| 667 | |||
| 668 | |||
| 669 | |||
| 670 | |||
| 671 | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_bt.gif b/Documentation/DocBook/v4l/fieldseq_bt.gif new file mode 100644 index 000000000000..60e8569a76c9 --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_bt.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_bt.pdf b/Documentation/DocBook/v4l/fieldseq_bt.pdf new file mode 100644 index 000000000000..26598b23f80d --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_bt.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.gif b/Documentation/DocBook/v4l/fieldseq_tb.gif new file mode 100644 index 000000000000..718492f1cfc7 --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_tb.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.pdf b/Documentation/DocBook/v4l/fieldseq_tb.pdf new file mode 100644 index 000000000000..4965b22ddb3a --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_tb.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/func-close.xml b/Documentation/DocBook/v4l/func-close.xml new file mode 100644 index 000000000000..dfb41cbbbec3 --- /dev/null +++ b/Documentation/DocBook/v4l/func-close.xml | |||
| @@ -0,0 +1,70 @@ | |||
| 1 | <refentry id="func-close"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 close()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-close</refname> | ||
| 9 | <refpurpose>Close a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>close</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | </funcprototype> | ||
| 19 | </funcsynopsis> | ||
| 20 | </refsynopsisdiv> | ||
| 21 | |||
| 22 | <refsect1> | ||
| 23 | <title>Arguments</title> | ||
| 24 | |||
| 25 | <variablelist> | ||
| 26 | <varlistentry> | ||
| 27 | <term><parameter>fd</parameter></term> | ||
| 28 | <listitem> | ||
| 29 | <para>&fd;</para> | ||
| 30 | </listitem> | ||
| 31 | </varlistentry> | ||
| 32 | </variablelist> | ||
| 33 | </refsect1> | ||
| 34 | |||
| 35 | <refsect1> | ||
| 36 | <title>Description</title> | ||
| 37 | |||
| 38 | <para>Closes the device. Any I/O in progress is terminated and | ||
| 39 | resources associated with the file descriptor are freed. However data | ||
| 40 | format parameters, current input or output, control values or other | ||
| 41 | properties remain unchanged.</para> | ||
| 42 | </refsect1> | ||
| 43 | |||
| 44 | <refsect1> | ||
| 45 | <title>Return Value</title> | ||
| 46 | |||
| 47 | <para>The function returns <returnvalue>0</returnvalue> on | ||
| 48 | success, <returnvalue>-1</returnvalue> on failure and the | ||
| 49 | <varname>errno</varname> is set appropriately. Possible error | ||
| 50 | codes:</para> | ||
| 51 | |||
| 52 | <variablelist> | ||
| 53 | <varlistentry> | ||
| 54 | <term><errorcode>EBADF</errorcode></term> | ||
| 55 | <listitem> | ||
| 56 | <para><parameter>fd</parameter> is not a valid open file | ||
| 57 | descriptor.</para> | ||
| 58 | </listitem> | ||
| 59 | </varlistentry> | ||
| 60 | </variablelist> | ||
| 61 | </refsect1> | ||
| 62 | </refentry> | ||
| 63 | |||
| 64 | <!-- | ||
| 65 | Local Variables: | ||
| 66 | mode: sgml | ||
| 67 | sgml-parent-document: "v4l2.sgml" | ||
| 68 | indent-tabs-mode: nil | ||
| 69 | End: | ||
| 70 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-ioctl.xml b/Documentation/DocBook/v4l/func-ioctl.xml new file mode 100644 index 000000000000..00f9690e1c28 --- /dev/null +++ b/Documentation/DocBook/v4l/func-ioctl.xml | |||
| @@ -0,0 +1,146 @@ | |||
| 1 | <refentry id="func-ioctl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 ioctl()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-ioctl</refname> | ||
| 9 | <refpurpose>Program a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>void *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>V4L2 ioctl request code as defined in the <link | ||
| 38 | linkend="videodev">videodev.h</link> header file, for example | ||
| 39 | VIDIOC_QUERYCAP.</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>argp</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>Pointer to a function parameter, usually a structure.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | |||
| 51 | <refsect1> | ||
| 52 | <title>Description</title> | ||
| 53 | |||
| 54 | <para>The <function>ioctl()</function> function is used to program | ||
| 55 | V4L2 devices. The argument <parameter>fd</parameter> must be an open | ||
| 56 | file descriptor. An ioctl <parameter>request</parameter> has encoded | ||
| 57 | in it whether the argument is an input, output or read/write | ||
| 58 | parameter, and the size of the argument <parameter>argp</parameter> in | ||
| 59 | bytes. Macros and defines specifying V4L2 ioctl requests are located | ||
| 60 | in the <link linkend="videodev">videodev.h</link> header file. | ||
| 61 | Applications should use their own copy, not include the version in the | ||
| 62 | kernel sources on the system they compile on. All V4L2 ioctl requests, | ||
| 63 | their respective function and parameters are specified in <xref | ||
| 64 | linkend="user-func" />.</para> | ||
| 65 | </refsect1> | ||
| 66 | |||
| 67 | <refsect1> | ||
| 68 | <title>Return Value</title> | ||
| 69 | |||
| 70 | <para>On success the <function>ioctl()</function> function returns | ||
| 71 | <returnvalue>0</returnvalue> and does not reset the | ||
| 72 | <varname>errno</varname> variable. On failure | ||
| 73 | <returnvalue>-1</returnvalue> is returned, when the ioctl takes an | ||
| 74 | output or read/write parameter it remains unmodified, and the | ||
| 75 | <varname>errno</varname> variable is set appropriately. See below for | ||
| 76 | possible error codes. Generic errors like <errorcode>EBADF</errorcode> | ||
| 77 | or <errorcode>EFAULT</errorcode> are not listed in the sections | ||
| 78 | discussing individual ioctl requests.</para> | ||
| 79 | <para>Note ioctls may return undefined error codes. Since errors | ||
| 80 | may have side effects such as a driver reset applications should | ||
| 81 | abort on unexpected errors.</para> | ||
| 82 | |||
| 83 | <variablelist> | ||
| 84 | <varlistentry> | ||
| 85 | <term><errorcode>EBADF</errorcode></term> | ||
| 86 | <listitem> | ||
| 87 | <para><parameter>fd</parameter> is not a valid open file | ||
| 88 | descriptor.</para> | ||
| 89 | </listitem> | ||
| 90 | </varlistentry> | ||
| 91 | <varlistentry> | ||
| 92 | <term><errorcode>EBUSY</errorcode></term> | ||
| 93 | <listitem> | ||
| 94 | <para>The property cannot be changed right now. Typically | ||
| 95 | this error code is returned when I/O is in progress or the driver | ||
| 96 | supports multiple opens and another process locked the property.</para> | ||
| 97 | </listitem> | ||
| 98 | </varlistentry> | ||
| 99 | <varlistentry> | ||
| 100 | <term><errorcode>EFAULT</errorcode></term> | ||
| 101 | <listitem> | ||
| 102 | <para><parameter>argp</parameter> references an inaccessible | ||
| 103 | memory area.</para> | ||
| 104 | </listitem> | ||
| 105 | </varlistentry> | ||
| 106 | <varlistentry> | ||
| 107 | <term><errorcode>ENOTTY</errorcode></term> | ||
| 108 | <listitem> | ||
| 109 | <para><parameter>fd</parameter> is not associated with a | ||
| 110 | character special device.</para> | ||
| 111 | </listitem> | ||
| 112 | </varlistentry> | ||
| 113 | <varlistentry> | ||
| 114 | <term><errorcode>EINVAL</errorcode></term> | ||
| 115 | <listitem> | ||
| 116 | <para>The <parameter>request</parameter> or the data pointed | ||
| 117 | to by <parameter>argp</parameter> is not valid. This is a very common | ||
| 118 | error code, see the individual ioctl requests listed in <xref | ||
| 119 | linkend="user-func" /> for actual causes.</para> | ||
| 120 | </listitem> | ||
| 121 | </varlistentry> | ||
| 122 | <varlistentry> | ||
| 123 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 124 | <listitem> | ||
| 125 | <para>Not enough physical or virtual memory was available to | ||
| 126 | complete the request.</para> | ||
| 127 | </listitem> | ||
| 128 | </varlistentry> | ||
| 129 | <varlistentry> | ||
| 130 | <term><errorcode>ERANGE</errorcode></term> | ||
| 131 | <listitem> | ||
| 132 | <para>The application attempted to set a control with the | ||
| 133 | &VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para> | ||
| 134 | </listitem> | ||
| 135 | </varlistentry> | ||
| 136 | </variablelist> | ||
| 137 | </refsect1> | ||
| 138 | </refentry> | ||
| 139 | |||
| 140 | <!-- | ||
| 141 | Local Variables: | ||
| 142 | mode: sgml | ||
| 143 | sgml-parent-document: "v4l2.sgml" | ||
| 144 | indent-tabs-mode: nil | ||
| 145 | End: | ||
| 146 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml new file mode 100644 index 000000000000..2e2fc3933aea --- /dev/null +++ b/Documentation/DocBook/v4l/func-mmap.xml | |||
| @@ -0,0 +1,185 @@ | |||
| 1 | <refentry id="func-mmap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 mmap()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-mmap</refname> | ||
| 9 | <refpurpose>Map device memory into application address space</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <unistd.h> | ||
| 16 | #include <sys/mman.h></funcsynopsisinfo> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>void *<function>mmap</function></funcdef> | ||
| 19 | <paramdef>void *<parameter>start</parameter></paramdef> | ||
| 20 | <paramdef>size_t <parameter>length</parameter></paramdef> | ||
| 21 | <paramdef>int <parameter>prot</parameter></paramdef> | ||
| 22 | <paramdef>int <parameter>flags</parameter></paramdef> | ||
| 23 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 24 | <paramdef>off_t <parameter>offset</parameter></paramdef> | ||
| 25 | </funcprototype> | ||
| 26 | </funcsynopsis> | ||
| 27 | </refsynopsisdiv> | ||
| 28 | |||
| 29 | <refsect1> | ||
| 30 | <title>Arguments</title> | ||
| 31 | <variablelist> | ||
| 32 | <varlistentry> | ||
| 33 | <term><parameter>start</parameter></term> | ||
| 34 | <listitem> | ||
| 35 | <para>Map the buffer to this address in the | ||
| 36 | application's address space. When the <constant>MAP_FIXED</constant> | ||
| 37 | flag is specified, <parameter>start</parameter> must be a multiple of the | ||
| 38 | pagesize and mmap will fail when the specified address | ||
| 39 | cannot be used. Use of this option is discouraged; applications should | ||
| 40 | just specify a <constant>NULL</constant> pointer here.</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>length</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>Length of the memory area to map. This must be the | ||
| 47 | same value as returned by the driver in the &v4l2-buffer; | ||
| 48 | <structfield>length</structfield> field.</para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | <varlistentry> | ||
| 52 | <term><parameter>prot</parameter></term> | ||
| 53 | <listitem> | ||
| 54 | <para>The <parameter>prot</parameter> argument describes the | ||
| 55 | desired memory protection. Regardless of the device type and the | ||
| 56 | direction of data exchange it should be set to | ||
| 57 | <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>, | ||
| 58 | permitting read and write access to image buffers. Drivers should | ||
| 59 | support at least this combination of flags. Note the Linux | ||
| 60 | <filename>video-buf</filename> kernel module, which is used by the | ||
| 61 | bttv, saa7134, saa7146, cx88 and vivi driver supports only | ||
| 62 | <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When | ||
| 63 | the driver does not support the desired protection the | ||
| 64 | <function>mmap()</function> function fails.</para> | ||
| 65 | <para>Note device memory accesses (⪚ the memory on a | ||
| 66 | graphics card with video capturing hardware) may incur a performance | ||
| 67 | penalty compared to main memory accesses, or reads may be | ||
| 68 | significantly slower than writes or vice versa. Other I/O methods may | ||
| 69 | be more efficient in this case.</para> | ||
| 70 | </listitem> | ||
| 71 | </varlistentry> | ||
| 72 | <varlistentry> | ||
| 73 | <term><parameter>flags</parameter></term> | ||
| 74 | <listitem> | ||
| 75 | <para>The <parameter>flags</parameter> parameter | ||
| 76 | specifies the type of the mapped object, mapping options and whether | ||
| 77 | modifications made to the mapped copy of the page are private to the | ||
| 78 | process or are to be shared with other references.</para> | ||
| 79 | <para><constant>MAP_FIXED</constant> requests that the | ||
| 80 | driver selects no other address than the one specified. If the | ||
| 81 | specified address cannot be used, <function>mmap()</function> will fail. If | ||
| 82 | <constant>MAP_FIXED</constant> is specified, | ||
| 83 | <parameter>start</parameter> must be a multiple of the pagesize. Use | ||
| 84 | of this option is discouraged.</para> | ||
| 85 | <para>One of the <constant>MAP_SHARED</constant> or | ||
| 86 | <constant>MAP_PRIVATE</constant> flags must be set. | ||
| 87 | <constant>MAP_SHARED</constant> allows applications to share the | ||
| 88 | mapped memory with other (⪚ child-) processes. Note the Linux | ||
| 89 | <filename>video-buf</filename> module which is used by the bttv, | ||
| 90 | saa7134, saa7146, cx88 and vivi driver supports only | ||
| 91 | <constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant> | ||
| 92 | requests copy-on-write semantics. V4L2 applications should not set the | ||
| 93 | <constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>, | ||
| 94 | <constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant> | ||
| 95 | flag.</para> | ||
| 96 | </listitem> | ||
| 97 | </varlistentry> | ||
| 98 | <varlistentry> | ||
| 99 | <term><parameter>fd</parameter></term> | ||
| 100 | <listitem> | ||
| 101 | <para>&fd;</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><parameter>offset</parameter></term> | ||
| 106 | <listitem> | ||
| 107 | <para>Offset of the buffer in device memory. This must be the | ||
| 108 | same value as returned by the driver in the &v4l2-buffer; | ||
| 109 | <structfield>m</structfield> union <structfield>offset</structfield> field.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | </variablelist> | ||
| 113 | </refsect1> | ||
| 114 | |||
| 115 | <refsect1> | ||
| 116 | <title>Description</title> | ||
| 117 | |||
| 118 | <para>The <function>mmap()</function> function asks to map | ||
| 119 | <parameter>length</parameter> bytes starting at | ||
| 120 | <parameter>offset</parameter> in the memory of the device specified by | ||
| 121 | <parameter>fd</parameter> into the application address space, | ||
| 122 | preferably at address <parameter>start</parameter>. This latter | ||
| 123 | address is a hint only, and is usually specified as 0.</para> | ||
| 124 | |||
| 125 | <para>Suitable length and offset parameters are queried with the | ||
| 126 | &VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the | ||
| 127 | &VIDIOC-REQBUFS; ioctl before they can be queried.</para> | ||
| 128 | |||
| 129 | <para>To unmap buffers the &func-munmap; function is used.</para> | ||
| 130 | </refsect1> | ||
| 131 | |||
| 132 | <refsect1> | ||
| 133 | <title>Return Value</title> | ||
| 134 | |||
| 135 | <para>On success <function>mmap()</function> returns a pointer to | ||
| 136 | the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is | ||
| 137 | returned, and the <varname>errno</varname> variable is set | ||
| 138 | appropriately. Possible error codes are:</para> | ||
| 139 | |||
| 140 | <variablelist> | ||
| 141 | <varlistentry> | ||
| 142 | <term><errorcode>EBADF</errorcode></term> | ||
| 143 | <listitem> | ||
| 144 | <para><parameter>fd</parameter> is not a valid file | ||
| 145 | descriptor.</para> | ||
| 146 | </listitem> | ||
| 147 | </varlistentry> | ||
| 148 | <varlistentry> | ||
| 149 | <term><errorcode>EACCES</errorcode></term> | ||
| 150 | <listitem> | ||
| 151 | <para><parameter>fd</parameter> is | ||
| 152 | not open for reading and writing.</para> | ||
| 153 | </listitem> | ||
| 154 | </varlistentry> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The <parameter>start</parameter> or | ||
| 159 | <parameter>length</parameter> or <parameter>offset</parameter> are not | ||
| 160 | suitable. (E. g. they are too large, or not aligned on a | ||
| 161 | <constant>PAGESIZE</constant> boundary.)</para> | ||
| 162 | <para>The <parameter>flags</parameter> or | ||
| 163 | <parameter>prot</parameter> value is not supported.</para> | ||
| 164 | <para>No buffers have been allocated with the | ||
| 165 | &VIDIOC-REQBUFS; ioctl.</para> | ||
| 166 | </listitem> | ||
| 167 | </varlistentry> | ||
| 168 | <varlistentry> | ||
| 169 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 170 | <listitem> | ||
| 171 | <para>Not enough physical or virtual memory was available to | ||
| 172 | complete the request.</para> | ||
| 173 | </listitem> | ||
| 174 | </varlistentry> | ||
| 175 | </variablelist> | ||
| 176 | </refsect1> | ||
| 177 | </refentry> | ||
| 178 | |||
| 179 | <!-- | ||
| 180 | Local Variables: | ||
| 181 | mode: sgml | ||
| 182 | sgml-parent-document: "v4l2.sgml" | ||
| 183 | indent-tabs-mode: nil | ||
| 184 | End: | ||
| 185 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml new file mode 100644 index 000000000000..502ed49323b0 --- /dev/null +++ b/Documentation/DocBook/v4l/func-munmap.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="func-munmap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 munmap()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-munmap</refname> | ||
| 9 | <refpurpose>Unmap device memory</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <unistd.h> | ||
| 16 | #include <sys/mman.h></funcsynopsisinfo> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>int <function>munmap</function></funcdef> | ||
| 19 | <paramdef>void *<parameter>start</parameter></paramdef> | ||
| 20 | <paramdef>size_t <parameter>length</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | </refsynopsisdiv> | ||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>start</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>Address of the mapped buffer as returned by the | ||
| 31 | &func-mmap; function.</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>length</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>Length of the mapped buffer. This must be the same | ||
| 38 | value as given to <function>mmap()</function> and returned by the | ||
| 39 | driver in the &v4l2-buffer; <structfield>length</structfield> | ||
| 40 | field.</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | </variablelist> | ||
| 44 | </refsect1> | ||
| 45 | |||
| 46 | <refsect1> | ||
| 47 | <title>Description</title> | ||
| 48 | |||
| 49 | <para>Unmaps a previously with the &func-mmap; function mapped | ||
| 50 | buffer and frees it, if possible. <!-- ? This function (not freeing) | ||
| 51 | has no impact on I/O in progress, specifically it does not imply | ||
| 52 | &VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be | ||
| 53 | enqueued, dequeued or queried, they are just not accessible by the | ||
| 54 | application.--></para> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Return Value</title> | ||
| 59 | |||
| 60 | <para>On success <function>munmap()</function> returns 0, on | ||
| 61 | failure -1 and the <varname>errno</varname> variable is set | ||
| 62 | appropriately:</para> | ||
| 63 | |||
| 64 | <variablelist> | ||
| 65 | <varlistentry> | ||
| 66 | <term><errorcode>EINVAL</errorcode></term> | ||
| 67 | <listitem> | ||
| 68 | <para>The <parameter>start</parameter> or | ||
| 69 | <parameter>length</parameter> is incorrect, or no buffers have been | ||
| 70 | mapped yet.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-open.xml b/Documentation/DocBook/v4l/func-open.xml new file mode 100644 index 000000000000..7595d07a8c72 --- /dev/null +++ b/Documentation/DocBook/v4l/func-open.xml | |||
| @@ -0,0 +1,121 @@ | |||
| 1 | <refentry id="func-open"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 open()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-open</refname> | ||
| 9 | <refpurpose>Open a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>open</function></funcdef> | ||
| 17 | <paramdef>const char *<parameter>device_name</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>flags</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>device_name</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>Device to be opened.</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>flags</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>Open flags. Access mode must be | ||
| 37 | <constant>O_RDWR</constant>. This is just a technicality, input devices | ||
| 38 | still support only reading and output devices only writing.</para> | ||
| 39 | <para>When the <constant>O_NONBLOCK</constant> flag is | ||
| 40 | given, the read() function and the &VIDIOC-DQBUF; ioctl will return | ||
| 41 | the &EAGAIN; when no data is available or no buffer is in the driver | ||
| 42 | outgoing queue, otherwise these functions block until data becomes | ||
| 43 | available. All V4L2 drivers exchanging data with applications must | ||
| 44 | support the <constant>O_NONBLOCK</constant> flag.</para> | ||
| 45 | <para>Other flags have no effect.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>To open a V4L2 device applications call | ||
| 54 | <function>open()</function> with the desired device name. This | ||
| 55 | function has no side effects; all data format parameters, current | ||
| 56 | input or output, control values or other properties remain unchanged. | ||
| 57 | At the first <function>open()</function> call after loading the driver | ||
| 58 | they will be reset to default values, drivers are never in an | ||
| 59 | undefined state.</para> | ||
| 60 | </refsect1> | ||
| 61 | <refsect1> | ||
| 62 | <title>Return Value</title> | ||
| 63 | |||
| 64 | <para>On success <function>open</function> returns the new file | ||
| 65 | descriptor. On error -1 is returned, and the <varname>errno</varname> | ||
| 66 | variable is set appropriately. Possible error codes are:</para> | ||
| 67 | |||
| 68 | <variablelist> | ||
| 69 | <varlistentry> | ||
| 70 | <term><errorcode>EACCES</errorcode></term> | ||
| 71 | <listitem> | ||
| 72 | <para>The caller has no permission to access the | ||
| 73 | device.</para> | ||
| 74 | </listitem> | ||
| 75 | </varlistentry> | ||
| 76 | <varlistentry> | ||
| 77 | <term><errorcode>EBUSY</errorcode></term> | ||
| 78 | <listitem> | ||
| 79 | <para>The driver does not support multiple opens and the | ||
| 80 | device is already in use.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>ENXIO</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>No device corresponding to this device special file | ||
| 87 | exists.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | <varlistentry> | ||
| 91 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 92 | <listitem> | ||
| 93 | <para>Not enough kernel memory was available to complete the | ||
| 94 | request.</para> | ||
| 95 | </listitem> | ||
| 96 | </varlistentry> | ||
| 97 | <varlistentry> | ||
| 98 | <term><errorcode>EMFILE</errorcode></term> | ||
| 99 | <listitem> | ||
| 100 | <para>The process already has the maximum number of | ||
| 101 | files open.</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><errorcode>ENFILE</errorcode></term> | ||
| 106 | <listitem> | ||
| 107 | <para>The limit on the total number of files open on the | ||
| 108 | system has been reached.</para> | ||
| 109 | </listitem> | ||
| 110 | </varlistentry> | ||
| 111 | </variablelist> | ||
| 112 | </refsect1> | ||
| 113 | </refentry> | ||
| 114 | |||
| 115 | <!-- | ||
| 116 | Local Variables: | ||
| 117 | mode: sgml | ||
| 118 | sgml-parent-document: "v4l2.sgml" | ||
| 119 | indent-tabs-mode: nil | ||
| 120 | End: | ||
| 121 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-poll.xml b/Documentation/DocBook/v4l/func-poll.xml new file mode 100644 index 000000000000..ec3c718f5963 --- /dev/null +++ b/Documentation/DocBook/v4l/func-poll.xml | |||
| @@ -0,0 +1,127 @@ | |||
| 1 | <refentry id="func-poll"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 poll()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-poll</refname> | ||
| 9 | <refpurpose>Wait for some event on a file descriptor</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>poll</function></funcdef> | ||
| 17 | <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef> | ||
| 18 | <paramdef>unsigned int <parameter>nfds</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>timeout</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Description</title> | ||
| 26 | |||
| 27 | <para>With the <function>poll()</function> function applications | ||
| 28 | can suspend execution until the driver has captured data or is ready | ||
| 29 | to accept data for output.</para> | ||
| 30 | |||
| 31 | <para>When streaming I/O has been negotiated this function waits | ||
| 32 | until a buffer has been filled or displayed and can be dequeued with | ||
| 33 | the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing | ||
| 34 | queue of the driver the function returns immediately.</para> | ||
| 35 | |||
| 36 | <para>On success <function>poll()</function> returns the number of | ||
| 37 | file descriptors that have been selected (that is, file descriptors | ||
| 38 | for which the <structfield>revents</structfield> field of the | ||
| 39 | respective <structname>pollfd</structname> structure is non-zero). | ||
| 40 | Capture devices set the <constant>POLLIN</constant> and | ||
| 41 | <constant>POLLRDNORM</constant> flags in the | ||
| 42 | <structfield>revents</structfield> field, output devices the | ||
| 43 | <constant>POLLOUT</constant> and <constant>POLLWRNORM</constant> | ||
| 44 | flags. When the function timed out it returns a value of zero, on | ||
| 45 | failure it returns <returnvalue>-1</returnvalue> and the | ||
| 46 | <varname>errno</varname> variable is set appropriately. When the | ||
| 47 | application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the | ||
| 48 | <function>poll()</function> function succeeds, but sets the | ||
| 49 | <constant>POLLERR</constant> flag in the | ||
| 50 | <structfield>revents</structfield> field.</para> | ||
| 51 | |||
| 52 | <para>When use of the <function>read()</function> function has | ||
| 53 | been negotiated and the driver does not capture yet, the | ||
| 54 | <function>poll</function> function starts capturing. When that fails | ||
| 55 | it returns a <constant>POLLERR</constant> as above. Otherwise it waits | ||
| 56 | until data has been captured and can be read. When the driver captures | ||
| 57 | continuously (as opposed to, for example, still images) the function | ||
| 58 | may return immediately.</para> | ||
| 59 | |||
| 60 | <para>When use of the <function>write()</function> function has | ||
| 61 | been negotiated the <function>poll</function> function just waits | ||
| 62 | until the driver is ready for a non-blocking | ||
| 63 | <function>write()</function> call.</para> | ||
| 64 | |||
| 65 | <para>All drivers implementing the <function>read()</function> or | ||
| 66 | <function>write()</function> function or streaming I/O must also | ||
| 67 | support the <function>poll()</function> function.</para> | ||
| 68 | |||
| 69 | <para>For more details see the | ||
| 70 | <function>poll()</function> manual page.</para> | ||
| 71 | </refsect1> | ||
| 72 | |||
| 73 | <refsect1> | ||
| 74 | <title>Return Value</title> | ||
| 75 | |||
| 76 | <para>On success, <function>poll()</function> returns the number | ||
| 77 | structures which have non-zero <structfield>revents</structfield> | ||
| 78 | fields, or zero if the call timed out. On error | ||
| 79 | <returnvalue>-1</returnvalue> is returned, and the | ||
| 80 | <varname>errno</varname> variable is set appropriately:</para> | ||
| 81 | |||
| 82 | <variablelist> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBADF</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>One or more of the <parameter>ufds</parameter> members | ||
| 87 | specify an invalid file descriptor.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | <varlistentry> | ||
| 91 | <term><errorcode>EBUSY</errorcode></term> | ||
| 92 | <listitem> | ||
| 93 | <para>The driver does not support multiple read or write | ||
| 94 | streams and the device is already in use.</para> | ||
| 95 | </listitem> | ||
| 96 | </varlistentry> | ||
| 97 | <varlistentry> | ||
| 98 | <term><errorcode>EFAULT</errorcode></term> | ||
| 99 | <listitem> | ||
| 100 | <para><parameter>ufds</parameter> references an inaccessible | ||
| 101 | memory area.</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><errorcode>EINTR</errorcode></term> | ||
| 106 | <listitem> | ||
| 107 | <para>The call was interrupted by a signal.</para> | ||
| 108 | </listitem> | ||
| 109 | </varlistentry> | ||
| 110 | <varlistentry> | ||
| 111 | <term><errorcode>EINVAL</errorcode></term> | ||
| 112 | <listitem> | ||
| 113 | <para>The <parameter>nfds</parameter> argument is greater | ||
| 114 | than <constant>OPEN_MAX</constant>.</para> | ||
| 115 | </listitem> | ||
| 116 | </varlistentry> | ||
| 117 | </variablelist> | ||
| 118 | </refsect1> | ||
| 119 | </refentry> | ||
| 120 | |||
| 121 | <!-- | ||
| 122 | Local Variables: | ||
| 123 | mode: sgml | ||
| 124 | sgml-parent-document: "v4l2.sgml" | ||
| 125 | indent-tabs-mode: nil | ||
| 126 | End: | ||
| 127 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-read.xml b/Documentation/DocBook/v4l/func-read.xml new file mode 100644 index 000000000000..a5089bf8873d --- /dev/null +++ b/Documentation/DocBook/v4l/func-read.xml | |||
| @@ -0,0 +1,189 @@ | |||
| 1 | <refentry id="func-read"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 read()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-read</refname> | ||
| 9 | <refpurpose>Read from a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>ssize_t <function>read</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>void *<parameter>buf</parameter></paramdef> | ||
| 19 | <paramdef>size_t <parameter>count</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>buf</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para></para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>count</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para><function>read()</function> attempts to read up to | ||
| 53 | <parameter>count</parameter> bytes from file descriptor | ||
| 54 | <parameter>fd</parameter> into the buffer starting at | ||
| 55 | <parameter>buf</parameter>. The layout of the data in the buffer is | ||
| 56 | discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, | ||
| 57 | <function>read()</function> returns zero and has no other results. If | ||
| 58 | <parameter>count</parameter> is greater than | ||
| 59 | <constant>SSIZE_MAX</constant>, the result is unspecified. Regardless | ||
| 60 | of the <parameter>count</parameter> value each | ||
| 61 | <function>read()</function> call will provide at most one frame (two | ||
| 62 | fields) worth of data.</para> | ||
| 63 | |||
| 64 | <para>By default <function>read()</function> blocks until data | ||
| 65 | becomes available. When the <constant>O_NONBLOCK</constant> flag was | ||
| 66 | given to the &func-open; function it | ||
| 67 | returns immediately with an &EAGAIN; when no data is available. The | ||
| 68 | &func-select; or &func-poll; functions | ||
| 69 | can always be used to suspend execution until data becomes available. All | ||
| 70 | drivers supporting the <function>read()</function> function must also | ||
| 71 | support <function>select()</function> and | ||
| 72 | <function>poll()</function>.</para> | ||
| 73 | |||
| 74 | <para>Drivers can implement read functionality in different | ||
| 75 | ways, using a single or multiple buffers and discarding the oldest or | ||
| 76 | newest frames once the internal buffers are filled.</para> | ||
| 77 | |||
| 78 | <para><function>read()</function> never returns a "snapshot" of a | ||
| 79 | buffer being filled. Using a single buffer the driver will stop | ||
| 80 | capturing when the application starts reading the buffer until the | ||
| 81 | read is finished. Thus only the period of the vertical blanking | ||
| 82 | interval is available for reading, or the capture rate must fall below | ||
| 83 | the nominal frame rate of the video standard.</para> | ||
| 84 | |||
| 85 | <para>The behavior of | ||
| 86 | <function>read()</function> when called during the active picture | ||
| 87 | period or the vertical blanking separating the top and bottom field | ||
| 88 | depends on the discarding policy. A driver discarding the oldest | ||
| 89 | frames keeps capturing into an internal buffer, continuously | ||
| 90 | overwriting the previously, not read frame, and returns the frame | ||
| 91 | being received at the time of the <function>read()</function> call as | ||
| 92 | soon as it is complete.</para> | ||
| 93 | |||
| 94 | <para>A driver discarding the newest frames stops capturing until | ||
| 95 | the next <function>read()</function> call. The frame being received at | ||
| 96 | <function>read()</function> time is discarded, returning the following | ||
| 97 | frame instead. Again this implies a reduction of the capture rate to | ||
| 98 | one half or less of the nominal frame rate. An example of this model | ||
| 99 | is the video read mode of the bttv driver, initiating a DMA to user | ||
| 100 | memory when <function>read()</function> is called and returning when | ||
| 101 | the DMA finished.</para> | ||
| 102 | |||
| 103 | <para>In the multiple buffer model drivers maintain a ring of | ||
| 104 | internal buffers, automatically advancing to the next free buffer. | ||
| 105 | This allows continuous capturing when the application can empty the | ||
| 106 | buffers fast enough. Again, the behavior when the driver runs out of | ||
| 107 | free buffers depends on the discarding policy.</para> | ||
| 108 | |||
| 109 | <para>Applications can get and set the number of buffers used | ||
| 110 | internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; | ||
| 111 | ioctls. They are optional, however. The discarding policy is not | ||
| 112 | reported and cannot be changed. For minimum requirements see <xref | ||
| 113 | linkend="devices" />.</para> | ||
| 114 | </refsect1> | ||
| 115 | |||
| 116 | <refsect1> | ||
| 117 | <title>Return Value</title> | ||
| 118 | |||
| 119 | <para>On success, the number of bytes read is returned. It is not | ||
| 120 | an error if this number is smaller than the number of bytes requested, | ||
| 121 | or the amount of data required for one frame. This may happen for | ||
| 122 | example because <function>read()</function> was interrupted by a | ||
| 123 | signal. On error, -1 is returned, and the <varname>errno</varname> | ||
| 124 | variable is set appropriately. In this case the next read will start | ||
| 125 | at the beginning of a new frame. Possible error codes are:</para> | ||
| 126 | |||
| 127 | <variablelist> | ||
| 128 | <varlistentry> | ||
| 129 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 130 | <listitem> | ||
| 131 | <para>Non-blocking I/O has been selected using | ||
| 132 | O_NONBLOCK and no data was immediately available for reading.</para> | ||
| 133 | </listitem> | ||
| 134 | </varlistentry> | ||
| 135 | <varlistentry> | ||
| 136 | <term><errorcode>EBADF</errorcode></term> | ||
| 137 | <listitem> | ||
| 138 | <para><parameter>fd</parameter> is not a valid file | ||
| 139 | descriptor or is not open for reading, or the process already has the | ||
| 140 | maximum number of files open.</para> | ||
| 141 | </listitem> | ||
| 142 | </varlistentry> | ||
| 143 | <varlistentry> | ||
| 144 | <term><errorcode>EBUSY</errorcode></term> | ||
| 145 | <listitem> | ||
| 146 | <para>The driver does not support multiple read streams and the | ||
| 147 | device is already in use.</para> | ||
| 148 | </listitem> | ||
| 149 | </varlistentry> | ||
| 150 | <varlistentry> | ||
| 151 | <term><errorcode>EFAULT</errorcode></term> | ||
| 152 | <listitem> | ||
| 153 | <para><parameter>buf</parameter> references an inaccessible | ||
| 154 | memory area.</para> | ||
| 155 | </listitem> | ||
| 156 | </varlistentry> | ||
| 157 | <varlistentry> | ||
| 158 | <term><errorcode>EINTR</errorcode></term> | ||
| 159 | <listitem> | ||
| 160 | <para>The call was interrupted by a signal before any | ||
| 161 | data was read.</para> | ||
| 162 | </listitem> | ||
| 163 | </varlistentry> | ||
| 164 | <varlistentry> | ||
| 165 | <term><errorcode>EIO</errorcode></term> | ||
| 166 | <listitem> | ||
| 167 | <para>I/O error. This indicates some hardware problem or a | ||
| 168 | failure to communicate with a remote device (USB camera etc.).</para> | ||
| 169 | </listitem> | ||
| 170 | </varlistentry> | ||
| 171 | <varlistentry> | ||
| 172 | <term><errorcode>EINVAL</errorcode></term> | ||
| 173 | <listitem> | ||
| 174 | <para>The <function>read()</function> function is not | ||
| 175 | supported by this driver, not on this device, or generally not on this | ||
| 176 | type of device.</para> | ||
| 177 | </listitem> | ||
| 178 | </varlistentry> | ||
| 179 | </variablelist> | ||
| 180 | </refsect1> | ||
| 181 | </refentry> | ||
| 182 | |||
| 183 | <!-- | ||
| 184 | Local Variables: | ||
| 185 | mode: sgml | ||
| 186 | sgml-parent-document: "v4l2.sgml" | ||
| 187 | indent-tabs-mode: nil | ||
| 188 | End: | ||
| 189 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-select.xml b/Documentation/DocBook/v4l/func-select.xml new file mode 100644 index 000000000000..b6713623181f --- /dev/null +++ b/Documentation/DocBook/v4l/func-select.xml | |||
| @@ -0,0 +1,138 @@ | |||
| 1 | <refentry id="func-select"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 select()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-select</refname> | ||
| 9 | <refpurpose>Synchronous I/O multiplexing</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <sys/time.h> | ||
| 16 | #include <sys/types.h> | ||
| 17 | #include <unistd.h></funcsynopsisinfo> | ||
| 18 | <funcprototype> | ||
| 19 | <funcdef>int <function>select</function></funcdef> | ||
| 20 | <paramdef>int <parameter>nfds</parameter></paramdef> | ||
| 21 | <paramdef>fd_set *<parameter>readfds</parameter></paramdef> | ||
| 22 | <paramdef>fd_set *<parameter>writefds</parameter></paramdef> | ||
| 23 | <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef> | ||
| 24 | <paramdef>struct timeval *<parameter>timeout</parameter></paramdef> | ||
| 25 | </funcprototype> | ||
| 26 | </funcsynopsis> | ||
| 27 | </refsynopsisdiv> | ||
| 28 | |||
| 29 | <refsect1> | ||
| 30 | <title>Description</title> | ||
| 31 | |||
| 32 | <para>With the <function>select()</function> function applications | ||
| 33 | can suspend execution until the driver has captured data or is ready | ||
| 34 | to accept data for output.</para> | ||
| 35 | |||
| 36 | <para>When streaming I/O has been negotiated this function waits | ||
| 37 | until a buffer has been filled or displayed and can be dequeued with | ||
| 38 | the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing | ||
| 39 | queue of the driver the function returns immediately.</para> | ||
| 40 | |||
| 41 | <para>On success <function>select()</function> returns the total | ||
| 42 | number of bits set in the <structname>fd_set</structname>s. When the | ||
| 43 | function timed out it returns a value of zero. On failure it returns | ||
| 44 | <returnvalue>-1</returnvalue> and the <varname>errno</varname> | ||
| 45 | variable is set appropriately. When the application did not call | ||
| 46 | &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the | ||
| 47 | <function>select()</function> function succeeds, setting the bit of | ||
| 48 | the file descriptor in <parameter>readfds</parameter> or | ||
| 49 | <parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls | ||
| 50 | will fail.<footnote><para>The Linux kernel implements | ||
| 51 | <function>select()</function> like the &func-poll; function, but | ||
| 52 | <function>select()</function> cannot return a | ||
| 53 | <constant>POLLERR</constant>.</para> | ||
| 54 | </footnote></para> | ||
| 55 | |||
| 56 | <para>When use of the <function>read()</function> function has | ||
| 57 | been negotiated and the driver does not capture yet, the | ||
| 58 | <function>select()</function> function starts capturing. When that | ||
| 59 | fails, <function>select()</function> returns successful and a | ||
| 60 | subsequent <function>read()</function> call, which also attempts to | ||
| 61 | start capturing, will return an appropriate error code. When the | ||
| 62 | driver captures continuously (as opposed to, for example, still | ||
| 63 | images) and data is already available the | ||
| 64 | <function>select()</function> function returns immediately.</para> | ||
| 65 | |||
| 66 | <para>When use of the <function>write()</function> function has | ||
| 67 | been negotiated the <function>select()</function> function just waits | ||
| 68 | until the driver is ready for a non-blocking | ||
| 69 | <function>write()</function> call.</para> | ||
| 70 | |||
| 71 | <para>All drivers implementing the <function>read()</function> or | ||
| 72 | <function>write()</function> function or streaming I/O must also | ||
| 73 | support the <function>select()</function> function.</para> | ||
| 74 | |||
| 75 | <para>For more details see the <function>select()</function> | ||
| 76 | manual page.</para> | ||
| 77 | |||
| 78 | </refsect1> | ||
| 79 | |||
| 80 | <refsect1> | ||
| 81 | <title>Return Value</title> | ||
| 82 | |||
| 83 | <para>On success, <function>select()</function> returns the number | ||
| 84 | of descriptors contained in the three returned descriptor sets, which | ||
| 85 | will be zero if the timeout expired. On error | ||
| 86 | <returnvalue>-1</returnvalue> is returned, and the | ||
| 87 | <varname>errno</varname> variable is set appropriately; the sets and | ||
| 88 | <parameter>timeout</parameter> are undefined. Possible error codes | ||
| 89 | are:</para> | ||
| 90 | |||
| 91 | <variablelist> | ||
| 92 | <varlistentry> | ||
| 93 | <term><errorcode>EBADF</errorcode></term> | ||
| 94 | <listitem> | ||
| 95 | <para>One or more of the file descriptor sets specified a | ||
| 96 | file descriptor that is not open.</para> | ||
| 97 | </listitem> | ||
| 98 | </varlistentry> | ||
| 99 | <varlistentry> | ||
| 100 | <term><errorcode>EBUSY</errorcode></term> | ||
| 101 | <listitem> | ||
| 102 | <para>The driver does not support multiple read or write | ||
| 103 | streams and the device is already in use.</para> | ||
| 104 | </listitem> | ||
| 105 | </varlistentry> | ||
| 106 | <varlistentry> | ||
| 107 | <term><errorcode>EFAULT</errorcode></term> | ||
| 108 | <listitem> | ||
| 109 | <para>The <parameter>readfds</parameter>, | ||
| 110 | <parameter>writefds</parameter>, <parameter>exceptfds</parameter> or | ||
| 111 | <parameter>timeout</parameter> pointer references an inaccessible memory | ||
| 112 | area.</para> | ||
| 113 | </listitem> | ||
| 114 | </varlistentry> | ||
| 115 | <varlistentry> | ||
| 116 | <term><errorcode>EINTR</errorcode></term> | ||
| 117 | <listitem> | ||
| 118 | <para>The call was interrupted by a signal.</para> | ||
| 119 | </listitem> | ||
| 120 | </varlistentry> | ||
| 121 | <varlistentry> | ||
| 122 | <term><errorcode>EINVAL</errorcode></term> | ||
| 123 | <listitem> | ||
| 124 | <para>The <parameter>nfds</parameter> argument is less than | ||
| 125 | zero or greater than <constant>FD_SETSIZE</constant>.</para> | ||
| 126 | </listitem> | ||
| 127 | </varlistentry> | ||
| 128 | </variablelist> | ||
| 129 | </refsect1> | ||
| 130 | </refentry> | ||
| 131 | |||
| 132 | <!-- | ||
| 133 | Local Variables: | ||
| 134 | mode: sgml | ||
| 135 | sgml-parent-document: "v4l2.sgml" | ||
| 136 | indent-tabs-mode: nil | ||
| 137 | End: | ||
| 138 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-write.xml b/Documentation/DocBook/v4l/func-write.xml new file mode 100644 index 000000000000..2c09c09371c3 --- /dev/null +++ b/Documentation/DocBook/v4l/func-write.xml | |||
| @@ -0,0 +1,136 @@ | |||
| 1 | <refentry id="func-write"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 write()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-write</refname> | ||
| 9 | <refpurpose>Write to a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>ssize_t <function>write</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>void *<parameter>buf</parameter></paramdef> | ||
| 19 | <paramdef>size_t <parameter>count</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>buf</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para></para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>count</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para><function>write()</function> writes up to | ||
| 53 | <parameter>count</parameter> bytes to the device referenced by the | ||
| 54 | file descriptor <parameter>fd</parameter> from the buffer starting at | ||
| 55 | <parameter>buf</parameter>. When the hardware outputs are not active | ||
| 56 | yet, this function enables them. When <parameter>count</parameter> is | ||
| 57 | zero, <function>write()</function> returns | ||
| 58 | <returnvalue>0</returnvalue> without any other effect.</para> | ||
| 59 | |||
| 60 | <para>When the application does not provide more data in time, the | ||
| 61 | previous video frame, raw VBI image, sliced VPS or WSS data is | ||
| 62 | displayed again. Sliced Teletext or Closed Caption data is not | ||
| 63 | repeated, the driver inserts a blank line instead.</para> | ||
| 64 | </refsect1> | ||
| 65 | |||
| 66 | <refsect1> | ||
| 67 | <title>Return Value</title> | ||
| 68 | |||
| 69 | <para>On success, the number of bytes written are returned. Zero | ||
| 70 | indicates nothing was written. On error, <returnvalue>-1</returnvalue> | ||
| 71 | is returned, and the <varname>errno</varname> variable is set | ||
| 72 | appropriately. In this case the next write will start at the beginning | ||
| 73 | of a new frame. Possible error codes are:</para> | ||
| 74 | |||
| 75 | <variablelist> | ||
| 76 | <varlistentry> | ||
| 77 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 78 | <listitem> | ||
| 79 | <para>Non-blocking I/O has been selected using the <link | ||
| 80 | linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no | ||
| 81 | buffer space was available to write the data immediately.</para> | ||
| 82 | </listitem> | ||
| 83 | </varlistentry> | ||
| 84 | <varlistentry> | ||
| 85 | <term><errorcode>EBADF</errorcode></term> | ||
| 86 | <listitem> | ||
| 87 | <para><parameter>fd</parameter> is not a valid file | ||
| 88 | descriptor or is not open for writing.</para> | ||
| 89 | </listitem> | ||
| 90 | </varlistentry> | ||
| 91 | <varlistentry> | ||
| 92 | <term><errorcode>EBUSY</errorcode></term> | ||
| 93 | <listitem> | ||
| 94 | <para>The driver does not support multiple write streams and the | ||
| 95 | device is already in use.</para> | ||
| 96 | </listitem> | ||
| 97 | </varlistentry> | ||
| 98 | <varlistentry> | ||
| 99 | <term><errorcode>EFAULT</errorcode></term> | ||
| 100 | <listitem> | ||
| 101 | <para><parameter>buf</parameter> references an inaccessible | ||
| 102 | memory area.</para> | ||
| 103 | </listitem> | ||
| 104 | </varlistentry> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>EINTR</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The call was interrupted by a signal before any | ||
| 109 | data was written.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | <varlistentry> | ||
| 113 | <term><errorcode>EIO</errorcode></term> | ||
| 114 | <listitem> | ||
| 115 | <para>I/O error. This indicates some hardware problem.</para> | ||
| 116 | </listitem> | ||
| 117 | </varlistentry> | ||
| 118 | <varlistentry> | ||
| 119 | <term><errorcode>EINVAL</errorcode></term> | ||
| 120 | <listitem> | ||
| 121 | <para>The <function>write()</function> function is not | ||
| 122 | supported by this driver, not on this device, or generally not on this | ||
| 123 | type of device.</para> | ||
| 124 | </listitem> | ||
| 125 | </varlistentry> | ||
| 126 | </variablelist> | ||
| 127 | </refsect1> | ||
| 128 | </refentry> | ||
| 129 | |||
| 130 | <!-- | ||
| 131 | Local Variables: | ||
| 132 | mode: sgml | ||
| 133 | sgml-parent-document: "v4l2.sgml" | ||
| 134 | indent-tabs-mode: nil | ||
| 135 | End: | ||
| 136 | --> | ||
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml new file mode 100644 index 000000000000..f92f24323b2a --- /dev/null +++ b/Documentation/DocBook/v4l/io.xml | |||
| @@ -0,0 +1,1073 @@ | |||
| 1 | <title>Input/Output</title> | ||
| 2 | |||
| 3 | <para>The V4L2 API defines several different methods to read from or | ||
| 4 | write to a device. All drivers exchanging data with applications must | ||
| 5 | support at least one of them.</para> | ||
| 6 | |||
| 7 | <para>The classic I/O method using the <function>read()</function> | ||
| 8 | and <function>write()</function> function is automatically selected | ||
| 9 | after opening a V4L2 device. When the driver does not support this | ||
| 10 | method attempts to read or write will fail at any time.</para> | ||
| 11 | |||
| 12 | <para>Other methods must be negotiated. To select the streaming I/O | ||
| 13 | method with memory mapped or user buffers applications call the | ||
| 14 | &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined | ||
| 15 | yet.</para> | ||
| 16 | |||
| 17 | <para>Video overlay can be considered another I/O method, although | ||
| 18 | the application does not directly receive the image data. It is | ||
| 19 | selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. | ||
| 20 | For more information see <xref linkend="overlay" />.</para> | ||
| 21 | |||
| 22 | <para>Generally exactly one I/O method, including overlay, is | ||
| 23 | associated with each file descriptor. The only exceptions are | ||
| 24 | applications not exchanging data with a driver ("panel applications", | ||
| 25 | see <xref linkend="open" />) and drivers permitting simultaneous video capturing | ||
| 26 | and overlay using the same file descriptor, for compatibility with V4L | ||
| 27 | and earlier versions of V4L2.</para> | ||
| 28 | |||
| 29 | <para><constant>VIDIOC_S_FMT</constant> and | ||
| 30 | <constant>VIDIOC_REQBUFS</constant> would permit this to some degree, | ||
| 31 | but for simplicity drivers need not support switching the I/O method | ||
| 32 | (after first switching away from read/write) other than by closing | ||
| 33 | and reopening the device.</para> | ||
| 34 | |||
| 35 | <para>The following sections describe the various I/O methods in | ||
| 36 | more detail.</para> | ||
| 37 | |||
| 38 | <section id="rw"> | ||
| 39 | <title>Read/Write</title> | ||
| 40 | |||
| 41 | <para>Input and output devices support the | ||
| 42 | <function>read()</function> and <function>write()</function> function, | ||
| 43 | respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in | ||
| 44 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 45 | returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> | ||
| 46 | |||
| 47 | <para>Drivers may need the CPU to copy the data, but they may also | ||
| 48 | support DMA to or from user memory, so this I/O method is not | ||
| 49 | necessarily less efficient than other methods merely exchanging buffer | ||
| 50 | pointers. It is considered inferior though because no meta-information | ||
| 51 | like frame counters or timestamps are passed. This information is | ||
| 52 | necessary to recognize frame dropping and to synchronize with other | ||
| 53 | data streams. However this is also the simplest I/O method, requiring | ||
| 54 | little or no setup to exchange data. It permits command line stunts | ||
| 55 | like this (the <application>vidctrl</application> tool is | ||
| 56 | fictitious):</para> | ||
| 57 | |||
| 58 | <informalexample> | ||
| 59 | <screen> | ||
| 60 | > vidctrl /dev/video --input=0 --format=YUYV --size=352x288 | ||
| 61 | > dd if=/dev/video of=myimage.422 bs=202752 count=1 | ||
| 62 | </screen> | ||
| 63 | </informalexample> | ||
| 64 | |||
| 65 | <para>To read from the device applications use the | ||
| 66 | &func-read; function, to write the &func-write; function. | ||
| 67 | Drivers must implement one I/O method if they | ||
| 68 | exchange data with applications, but it need not be this.<footnote> | ||
| 69 | <para>It would be desirable if applications could depend on | ||
| 70 | drivers supporting all I/O interfaces, but as much as the complex | ||
| 71 | memory mapping I/O can be inadequate for some devices we have no | ||
| 72 | reason to require this interface, which is most useful for simple | ||
| 73 | applications capturing still images.</para> | ||
| 74 | </footnote> When reading or writing is supported, the driver | ||
| 75 | must also support the &func-select; and &func-poll; | ||
| 76 | function.<footnote> | ||
| 77 | <para>At the driver level <function>select()</function> and | ||
| 78 | <function>poll()</function> are the same, and | ||
| 79 | <function>select()</function> is too important to be optional.</para> | ||
| 80 | </footnote></para> | ||
| 81 | </section> | ||
| 82 | |||
| 83 | <section id="mmap"> | ||
| 84 | <title>Streaming I/O (Memory Mapping)</title> | ||
| 85 | |||
| 86 | <para>Input and output devices support this I/O method when the | ||
| 87 | <constant>V4L2_CAP_STREAMING</constant> flag in the | ||
| 88 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 89 | returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two | ||
| 90 | streaming methods, to determine if the memory mapping flavor is | ||
| 91 | supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> | ||
| 92 | |||
| 93 | <para>Streaming is an I/O method where only pointers to buffers | ||
| 94 | are exchanged between application and driver, the data itself is not | ||
| 95 | copied. Memory mapping is primarily intended to map buffers in device | ||
| 96 | memory into the application's address space. Device memory can be for | ||
| 97 | example the video memory on a graphics card with a video capture | ||
| 98 | add-on. However, being the most efficient I/O method available for a | ||
| 99 | long time, many other drivers support streaming as well, allocating | ||
| 100 | buffers in DMA-able main memory.</para> | ||
| 101 | |||
| 102 | <para>A driver can support many sets of buffers. Each set is | ||
| 103 | identified by a unique buffer type value. The sets are independent and | ||
| 104 | each set can hold a different type of data. To access different sets | ||
| 105 | at the same time different file descriptors must be used.<footnote> | ||
| 106 | <para>One could use one file descriptor and set the buffer | ||
| 107 | type field accordingly when calling &VIDIOC-QBUF; etc., but it makes | ||
| 108 | the <function>select()</function> function ambiguous. We also like the | ||
| 109 | clean approach of one file descriptor per logical stream. Video | ||
| 110 | overlay for example is also a logical stream, although the CPU is not | ||
| 111 | needed for continuous operation.</para> | ||
| 112 | </footnote></para> | ||
| 113 | |||
| 114 | <para>To allocate device buffers applications call the | ||
| 115 | &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer | ||
| 116 | type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. | ||
| 117 | This ioctl can also be used to change the number of buffers or to free | ||
| 118 | the allocated memory, provided none of the buffers are still | ||
| 119 | mapped.</para> | ||
| 120 | |||
| 121 | <para>Before applications can access the buffers they must map | ||
| 122 | them into their address space with the &func-mmap; function. The | ||
| 123 | location of the buffers in device memory can be determined with the | ||
| 124 | &VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and | ||
| 125 | <structfield>length</structfield> returned in a &v4l2-buffer; are | ||
| 126 | passed as sixth and second parameter to the | ||
| 127 | <function>mmap()</function> function. The offset and length values | ||
| 128 | must not be modified. Remember the buffers are allocated in physical | ||
| 129 | memory, as opposed to virtual memory which can be swapped out to disk. | ||
| 130 | Applications should free the buffers as soon as possible with the | ||
| 131 | &func-munmap; function.</para> | ||
| 132 | |||
| 133 | <example> | ||
| 134 | <title>Mapping buffers</title> | ||
| 135 | |||
| 136 | <programlisting> | ||
| 137 | &v4l2-requestbuffers; reqbuf; | ||
| 138 | struct { | ||
| 139 | void *start; | ||
| 140 | size_t length; | ||
| 141 | } *buffers; | ||
| 142 | unsigned int i; | ||
| 143 | |||
| 144 | memset (&reqbuf, 0, sizeof (reqbuf)); | ||
| 145 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 146 | reqbuf.memory = V4L2_MEMORY_MMAP; | ||
| 147 | reqbuf.count = 20; | ||
| 148 | |||
| 149 | if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { | ||
| 150 | if (errno == EINVAL) | ||
| 151 | printf ("Video capturing or mmap-streaming is not supported\n"); | ||
| 152 | else | ||
| 153 | perror ("VIDIOC_REQBUFS"); | ||
| 154 | |||
| 155 | exit (EXIT_FAILURE); | ||
| 156 | } | ||
| 157 | |||
| 158 | /* We want at least five buffers. */ | ||
| 159 | |||
| 160 | if (reqbuf.count < 5) { | ||
| 161 | /* You may need to free the buffers here. */ | ||
| 162 | printf ("Not enough buffer memory\n"); | ||
| 163 | exit (EXIT_FAILURE); | ||
| 164 | } | ||
| 165 | |||
| 166 | buffers = calloc (reqbuf.count, sizeof (*buffers)); | ||
| 167 | assert (buffers != NULL); | ||
| 168 | |||
| 169 | for (i = 0; i < reqbuf.count; i++) { | ||
| 170 | &v4l2-buffer; buffer; | ||
| 171 | |||
| 172 | memset (&buffer, 0, sizeof (buffer)); | ||
| 173 | buffer.type = reqbuf.type; | ||
| 174 | buffer.memory = V4L2_MEMORY_MMAP; | ||
| 175 | buffer.index = i; | ||
| 176 | |||
| 177 | if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { | ||
| 178 | perror ("VIDIOC_QUERYBUF"); | ||
| 179 | exit (EXIT_FAILURE); | ||
| 180 | } | ||
| 181 | |||
| 182 | buffers[i].length = buffer.length; /* remember for munmap() */ | ||
| 183 | |||
| 184 | buffers[i].start = mmap (NULL, buffer.length, | ||
| 185 | PROT_READ | PROT_WRITE, /* recommended */ | ||
| 186 | MAP_SHARED, /* recommended */ | ||
| 187 | fd, buffer.m.offset); | ||
| 188 | |||
| 189 | if (MAP_FAILED == buffers[i].start) { | ||
| 190 | /* If you do not exit here you should unmap() and free() | ||
| 191 | the buffers mapped so far. */ | ||
| 192 | perror ("mmap"); | ||
| 193 | exit (EXIT_FAILURE); | ||
| 194 | } | ||
| 195 | } | ||
| 196 | |||
| 197 | /* Cleanup. */ | ||
| 198 | |||
| 199 | for (i = 0; i < reqbuf.count; i++) | ||
| 200 | munmap (buffers[i].start, buffers[i].length); | ||
| 201 | </programlisting> | ||
| 202 | </example> | ||
| 203 | |||
| 204 | <para>Conceptually streaming drivers maintain two buffer queues, an incoming | ||
| 205 | and an outgoing queue. They separate the synchronous capture or output | ||
| 206 | operation locked to a video clock from the application which is | ||
| 207 | subject to random disk or network delays and preemption by | ||
| 208 | other processes, thereby reducing the probability of data loss. | ||
| 209 | The queues are organized as FIFOs, buffers will be | ||
| 210 | output in the order enqueued in the incoming FIFO, and were | ||
| 211 | captured in the order dequeued from the outgoing FIFO.</para> | ||
| 212 | |||
| 213 | <para>The driver may require a minimum number of buffers enqueued | ||
| 214 | at all times to function, apart of this no limit exists on the number | ||
| 215 | of buffers applications can enqueue in advance, or dequeue and | ||
| 216 | process. They can also enqueue in a different order than buffers have | ||
| 217 | been dequeued, and the driver can <emphasis>fill</emphasis> enqueued | ||
| 218 | <emphasis>empty</emphasis> buffers in any order. <footnote> | ||
| 219 | <para>Random enqueue order permits applications processing | ||
| 220 | images out of order (such as video codecs) to return buffers earlier, | ||
| 221 | reducing the probability of data loss. Random fill order allows | ||
| 222 | drivers to reuse buffers on a LIFO-basis, taking advantage of caches | ||
| 223 | holding scatter-gather lists and the like.</para> | ||
| 224 | </footnote> The index number of a buffer (&v4l2-buffer; | ||
| 225 | <structfield>index</structfield>) plays no role here, it only | ||
| 226 | identifies the buffer.</para> | ||
| 227 | |||
| 228 | <para>Initially all mapped buffers are in dequeued state, | ||
| 229 | inaccessible by the driver. For capturing applications it is customary | ||
| 230 | to first enqueue all mapped buffers, then to start capturing and enter | ||
| 231 | the read loop. Here the application waits until a filled buffer can be | ||
| 232 | dequeued, and re-enqueues the buffer when the data is no longer | ||
| 233 | needed. Output applications fill and enqueue buffers, when enough | ||
| 234 | buffers are stacked up the output is started with | ||
| 235 | <constant>VIDIOC_STREAMON</constant>. In the write loop, when | ||
| 236 | the application runs out of free buffers, it must wait until an empty | ||
| 237 | buffer can be dequeued and reused.</para> | ||
| 238 | |||
| 239 | <para>To enqueue and dequeue a buffer applications use the | ||
| 240 | &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being | ||
| 241 | mapped, enqueued, full or empty can be determined at any time using the | ||
| 242 | &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the | ||
| 243 | application until one or more buffers can be dequeued. By default | ||
| 244 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | ||
| 245 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | ||
| 246 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | ||
| 247 | returns immediately with an &EAGAIN; when no buffer is available. The | ||
| 248 | &func-select; or &func-poll; function are always available.</para> | ||
| 249 | |||
| 250 | <para>To start and stop capturing or output applications call the | ||
| 251 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | ||
| 252 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | ||
| 253 | queues as a side effect. Since there is no notion of doing anything | ||
| 254 | "now" on a multitasking system, if an application needs to synchronize | ||
| 255 | with another event it should examine the &v4l2-buffer; | ||
| 256 | <structfield>timestamp</structfield> of captured buffers, or set the | ||
| 257 | field before enqueuing buffers for output.</para> | ||
| 258 | |||
| 259 | <para>Drivers implementing memory mapping I/O must | ||
| 260 | support the <constant>VIDIOC_REQBUFS</constant>, | ||
| 261 | <constant>VIDIOC_QUERYBUF</constant>, | ||
| 262 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | ||
| 263 | <constant>VIDIOC_STREAMON</constant> and | ||
| 264 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | ||
| 265 | <function>mmap()</function>, <function>munmap()</function>, | ||
| 266 | <function>select()</function> and <function>poll()</function> | ||
| 267 | function.<footnote> | ||
| 268 | <para>At the driver level <function>select()</function> and | ||
| 269 | <function>poll()</function> are the same, and | ||
| 270 | <function>select()</function> is too important to be optional. The | ||
| 271 | rest should be evident.</para> | ||
| 272 | </footnote></para> | ||
| 273 | |||
| 274 | <para>[capture example]</para> | ||
| 275 | |||
| 276 | </section> | ||
| 277 | |||
| 278 | <section id="userp"> | ||
| 279 | <title>Streaming I/O (User Pointers)</title> | ||
| 280 | |||
| 281 | <para>Input and output devices support this I/O method when the | ||
| 282 | <constant>V4L2_CAP_STREAMING</constant> flag in the | ||
| 283 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 284 | returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user | ||
| 285 | pointer method (not only memory mapping) is supported must be | ||
| 286 | determined by calling the &VIDIOC-REQBUFS; ioctl.</para> | ||
| 287 | |||
| 288 | <para>This I/O method combines advantages of the read/write and | ||
| 289 | memory mapping methods. Buffers are allocated by the application | ||
| 290 | itself, and can reside for example in virtual or shared memory. Only | ||
| 291 | pointers to data are exchanged, these pointers and meta-information | ||
| 292 | are passed in &v4l2-buffer;. The driver must be switched | ||
| 293 | into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the | ||
| 294 | desired buffer type. No buffers are allocated beforehands, | ||
| 295 | consequently they are not indexed and cannot be queried like mapped | ||
| 296 | buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> | ||
| 297 | |||
| 298 | <example> | ||
| 299 | <title>Initiating streaming I/O with user pointers</title> | ||
| 300 | |||
| 301 | <programlisting> | ||
| 302 | &v4l2-requestbuffers; reqbuf; | ||
| 303 | |||
| 304 | memset (&reqbuf, 0, sizeof (reqbuf)); | ||
| 305 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 306 | reqbuf.memory = V4L2_MEMORY_USERPTR; | ||
| 307 | |||
| 308 | if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { | ||
| 309 | if (errno == EINVAL) | ||
| 310 | printf ("Video capturing or user pointer streaming is not supported\n"); | ||
| 311 | else | ||
| 312 | perror ("VIDIOC_REQBUFS"); | ||
| 313 | |||
| 314 | exit (EXIT_FAILURE); | ||
| 315 | } | ||
| 316 | </programlisting> | ||
| 317 | </example> | ||
| 318 | |||
| 319 | <para>Buffer addresses and sizes are passed on the fly with the | ||
| 320 | &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, | ||
| 321 | applications can pass different addresses and sizes at each | ||
| 322 | <constant>VIDIOC_QBUF</constant> call. If required by the hardware the | ||
| 323 | driver swaps memory pages within physical memory to create a | ||
| 324 | continuous area of memory. This happens transparently to the | ||
| 325 | application in the virtual memory subsystem of the kernel. When buffer | ||
| 326 | pages have been swapped out to disk they are brought back and finally | ||
| 327 | locked in physical memory for DMA.<footnote> | ||
| 328 | <para>We expect that frequently used buffers are typically not | ||
| 329 | swapped out. Anyway, the process of swapping, locking or generating | ||
| 330 | scatter-gather lists may be time consuming. The delay can be masked by | ||
| 331 | the depth of the incoming buffer queue, and perhaps by maintaining | ||
| 332 | caches assuming a buffer will be soon enqueued again. On the other | ||
| 333 | hand, to optimize memory usage drivers can limit the number of buffers | ||
| 334 | locked in advance and recycle the most recently used buffers first. Of | ||
| 335 | course, the pages of empty buffers in the incoming queue need not be | ||
| 336 | saved to disk. Output buffers must be saved on the incoming and | ||
| 337 | outgoing queue because an application may share them with other | ||
| 338 | processes.</para> | ||
| 339 | </footnote></para> | ||
| 340 | |||
| 341 | <para>Filled or displayed buffers are dequeued with the | ||
| 342 | &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any | ||
| 343 | time between the completion of the DMA and this ioctl. The memory is | ||
| 344 | also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or | ||
| 345 | when the device is closed. Applications must take care not to free | ||
| 346 | buffers without dequeuing. For once, the buffers remain locked until | ||
| 347 | further, wasting physical memory. Second the driver will not be | ||
| 348 | notified when the memory is returned to the application's free list | ||
| 349 | and subsequently reused for other purposes, possibly completing the | ||
| 350 | requested DMA and overwriting valuable data.</para> | ||
| 351 | |||
| 352 | <para>For capturing applications it is customary to enqueue a | ||
| 353 | number of empty buffers, to start capturing and enter the read loop. | ||
| 354 | Here the application waits until a filled buffer can be dequeued, and | ||
| 355 | re-enqueues the buffer when the data is no longer needed. Output | ||
| 356 | applications fill and enqueue buffers, when enough buffers are stacked | ||
| 357 | up output is started. In the write loop, when the application | ||
| 358 | runs out of free buffers it must wait until an empty buffer can be | ||
| 359 | dequeued and reused. Two methods exist to suspend execution of the | ||
| 360 | application until one or more buffers can be dequeued. By default | ||
| 361 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | ||
| 362 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | ||
| 363 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | ||
| 364 | returns immediately with an &EAGAIN; when no buffer is available. The | ||
| 365 | &func-select; or &func-poll; function are always available.</para> | ||
| 366 | |||
| 367 | <para>To start and stop capturing or output applications call the | ||
| 368 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | ||
| 369 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | ||
| 370 | queues and unlocks all buffers as a side effect. Since there is no | ||
| 371 | notion of doing anything "now" on a multitasking system, if an | ||
| 372 | application needs to synchronize with another event it should examine | ||
| 373 | the &v4l2-buffer; <structfield>timestamp</structfield> of captured | ||
| 374 | buffers, or set the field before enqueuing buffers for output.</para> | ||
| 375 | |||
| 376 | <para>Drivers implementing user pointer I/O must | ||
| 377 | support the <constant>VIDIOC_REQBUFS</constant>, | ||
| 378 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | ||
| 379 | <constant>VIDIOC_STREAMON</constant> and | ||
| 380 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | ||
| 381 | <function>select()</function> and <function>poll()</function> function.<footnote> | ||
| 382 | <para>At the driver level <function>select()</function> and | ||
| 383 | <function>poll()</function> are the same, and | ||
| 384 | <function>select()</function> is too important to be optional. The | ||
| 385 | rest should be evident.</para> | ||
| 386 | </footnote></para> | ||
| 387 | </section> | ||
| 388 | |||
| 389 | <section id="async"> | ||
| 390 | <title>Asynchronous I/O</title> | ||
| 391 | |||
| 392 | <para>This method is not defined yet.</para> | ||
| 393 | </section> | ||
| 394 | |||
| 395 | <section id="buffer"> | ||
| 396 | <title>Buffers</title> | ||
| 397 | |||
| 398 | <para>A buffer contains data exchanged by application and | ||
| 399 | driver using one of the Streaming I/O methods. Only pointers to | ||
| 400 | buffers are exchanged, the data itself is not copied. These pointers, | ||
| 401 | together with meta-information like timestamps or field parity, are | ||
| 402 | stored in a struct <structname>v4l2_buffer</structname>, argument to | ||
| 403 | the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para> | ||
| 404 | |||
| 405 | <para>Nominally timestamps refer to the first data byte transmitted. | ||
| 406 | In practice however the wide range of hardware covered by the V4L2 API | ||
| 407 | limits timestamp accuracy. Often an interrupt routine will | ||
| 408 | sample the system clock shortly after the field or frame was stored | ||
| 409 | completely in memory. So applications must expect a constant | ||
| 410 | difference up to one field or frame period plus a small (few scan | ||
| 411 | lines) random error. The delay and error can be much | ||
| 412 | larger due to compression or transmission over an external bus when | ||
| 413 | the frames are not properly stamped by the sender. This is frequently | ||
| 414 | the case with USB cameras. Here timestamps refer to the instant the | ||
| 415 | field or frame was received by the driver, not the capture time. These | ||
| 416 | devices identify by not enumerating any video standards, see <xref | ||
| 417 | linkend="standard" />.</para> | ||
| 418 | |||
| 419 | <para>Similar limitations apply to output timestamps. Typically | ||
| 420 | the video hardware locks to a clock controlling the video timing, the | ||
| 421 | horizontal and vertical synchronization pulses. At some point in the | ||
| 422 | line sequence, possibly the vertical blanking, an interrupt routine | ||
| 423 | samples the system clock, compares against the timestamp and programs | ||
| 424 | the hardware to repeat the previous field or frame, or to display the | ||
| 425 | buffer contents.</para> | ||
| 426 | |||
| 427 | <para>Apart of limitations of the video device and natural | ||
| 428 | inaccuracies of all clocks, it should be noted system time itself is | ||
| 429 | not perfectly stable. It can be affected by power saving cycles, | ||
| 430 | warped to insert leap seconds, or even turned back or forth by the | ||
| 431 | system administrator affecting long term measurements. <footnote> | ||
| 432 | <para>Since no other Linux multimedia | ||
| 433 | API supports unadjusted time it would be foolish to introduce here. We | ||
| 434 | must use a universally supported clock to synchronize different media, | ||
| 435 | hence time of day.</para> | ||
| 436 | </footnote></para> | ||
| 437 | |||
| 438 | <table frame="none" pgwide="1" id="v4l2-buffer"> | ||
| 439 | <title>struct <structname>v4l2_buffer</structname></title> | ||
| 440 | <tgroup cols="4"> | ||
| 441 | &cs-ustr; | ||
| 442 | <tbody valign="top"> | ||
| 443 | <row> | ||
| 444 | <entry>__u32</entry> | ||
| 445 | <entry><structfield>index</structfield></entry> | ||
| 446 | <entry></entry> | ||
| 447 | <entry>Number of the buffer, set by the application. This | ||
| 448 | field is only used for <link linkend="mmap">memory mapping</link> I/O | ||
| 449 | and can range from zero to the number of buffers allocated | ||
| 450 | with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry> | ||
| 451 | </row> | ||
| 452 | <row> | ||
| 453 | <entry>&v4l2-buf-type;</entry> | ||
| 454 | <entry><structfield>type</structfield></entry> | ||
| 455 | <entry></entry> | ||
| 456 | <entry>Type of the buffer, same as &v4l2-format; | ||
| 457 | <structfield>type</structfield> or &v4l2-requestbuffers; | ||
| 458 | <structfield>type</structfield>, set by the application.</entry> | ||
| 459 | </row> | ||
| 460 | <row> | ||
| 461 | <entry>__u32</entry> | ||
| 462 | <entry><structfield>bytesused</structfield></entry> | ||
| 463 | <entry></entry> | ||
| 464 | <entry>The number of bytes occupied by the data in the | ||
| 465 | buffer. It depends on the negotiated data format and may change with | ||
| 466 | each buffer for compressed variable size data like JPEG images. | ||
| 467 | Drivers must set this field when <structfield>type</structfield> | ||
| 468 | refers to an input stream, applications when an output stream.</entry> | ||
| 469 | </row> | ||
| 470 | <row> | ||
| 471 | <entry>__u32</entry> | ||
| 472 | <entry><structfield>flags</structfield></entry> | ||
| 473 | <entry></entry> | ||
| 474 | <entry>Flags set by the application or driver, see <xref | ||
| 475 | linkend="buffer-flags" />.</entry> | ||
| 476 | </row> | ||
| 477 | <row> | ||
| 478 | <entry>&v4l2-field;</entry> | ||
| 479 | <entry><structfield>field</structfield></entry> | ||
| 480 | <entry></entry> | ||
| 481 | <entry>Indicates the field order of the image in the | ||
| 482 | buffer, see <xref linkend="v4l2-field" />. This field is not used when | ||
| 483 | the buffer contains VBI data. Drivers must set it when | ||
| 484 | <structfield>type</structfield> refers to an input stream, | ||
| 485 | applications when an output stream.</entry> | ||
| 486 | </row> | ||
| 487 | <row> | ||
| 488 | <entry>struct timeval</entry> | ||
| 489 | <entry><structfield>timestamp</structfield></entry> | ||
| 490 | <entry></entry> | ||
| 491 | <entry><para>For input streams this is the | ||
| 492 | system time (as returned by the <function>gettimeofday()</function> | ||
| 493 | function) when the first data byte was captured. For output streams | ||
| 494 | the data will not be displayed before this time, secondary to the | ||
| 495 | nominal frame rate determined by the current video standard in | ||
| 496 | enqueued order. Applications can for example zero this field to | ||
| 497 | display frames as soon as possible. The driver stores the time at | ||
| 498 | which the first data byte was actually sent out in the | ||
| 499 | <structfield>timestamp</structfield> field. This permits | ||
| 500 | applications to monitor the drift between the video and system | ||
| 501 | clock.</para></entry> | ||
| 502 | </row> | ||
| 503 | <row> | ||
| 504 | <entry>&v4l2-timecode;</entry> | ||
| 505 | <entry><structfield>timecode</structfield></entry> | ||
| 506 | <entry></entry> | ||
| 507 | <entry>When <structfield>type</structfield> is | ||
| 508 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the | ||
| 509 | <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in | ||
| 510 | <structfield>flags</structfield>, this structure contains a frame | ||
| 511 | timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> | ||
| 512 | mode the top and bottom field contain the same timecode. | ||
| 513 | Timecodes are intended to help video editing and are typically recorded on | ||
| 514 | video tapes, but also embedded in compressed formats like MPEG. This | ||
| 515 | field is independent of the <structfield>timestamp</structfield> and | ||
| 516 | <structfield>sequence</structfield> fields.</entry> | ||
| 517 | </row> | ||
| 518 | <row> | ||
| 519 | <entry>__u32</entry> | ||
| 520 | <entry><structfield>sequence</structfield></entry> | ||
| 521 | <entry></entry> | ||
| 522 | <entry>Set by the driver, counting the frames in the | ||
| 523 | sequence.</entry> | ||
| 524 | </row> | ||
| 525 | <row> | ||
| 526 | <entry spanname="hspan"><para>In <link | ||
| 527 | linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and | ||
| 528 | bottom field have the same sequence number. The count starts at zero | ||
| 529 | and includes dropped or repeated frames. A dropped frame was received | ||
| 530 | by an input device but could not be stored due to lack of free buffer | ||
| 531 | space. A repeated frame was displayed again by an output device | ||
| 532 | because the application did not pass new data in | ||
| 533 | time.</para><para>Note this may count the frames received | ||
| 534 | e.g. over USB, without taking into account the frames dropped by the | ||
| 535 | remote hardware due to limited compression throughput or bus | ||
| 536 | bandwidth. These devices identify by not enumerating any video | ||
| 537 | standards, see <xref linkend="standard" />.</para></entry> | ||
| 538 | </row> | ||
| 539 | <row> | ||
| 540 | <entry>&v4l2-memory;</entry> | ||
| 541 | <entry><structfield>memory</structfield></entry> | ||
| 542 | <entry></entry> | ||
| 543 | <entry>This field must be set by applications and/or drivers | ||
| 544 | in accordance with the selected I/O method.</entry> | ||
| 545 | </row> | ||
| 546 | <row> | ||
| 547 | <entry>union</entry> | ||
| 548 | <entry><structfield>m</structfield></entry> | ||
| 549 | </row> | ||
| 550 | <row> | ||
| 551 | <entry></entry> | ||
| 552 | <entry>__u32</entry> | ||
| 553 | <entry><structfield>offset</structfield></entry> | ||
| 554 | <entry>When <structfield>memory</structfield> is | ||
| 555 | <constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer | ||
| 556 | from the start of the device memory. The value is returned by the | ||
| 557 | driver and apart of serving as parameter to the &func-mmap; function | ||
| 558 | not useful for applications. See <xref linkend="mmap" /> for details.</entry> | ||
| 559 | </row> | ||
| 560 | <row> | ||
| 561 | <entry></entry> | ||
| 562 | <entry>unsigned long</entry> | ||
| 563 | <entry><structfield>userptr</structfield></entry> | ||
| 564 | <entry>When <structfield>memory</structfield> is | ||
| 565 | <constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the | ||
| 566 | buffer (casted to unsigned long type) in virtual memory, set by the | ||
| 567 | application. See <xref linkend="userp" /> for details.</entry> | ||
| 568 | </row> | ||
| 569 | <row> | ||
| 570 | <entry>__u32</entry> | ||
| 571 | <entry><structfield>length</structfield></entry> | ||
| 572 | <entry></entry> | ||
| 573 | <entry>Size of the buffer (not the payload) in bytes.</entry> | ||
| 574 | </row> | ||
| 575 | <row> | ||
| 576 | <entry>__u32</entry> | ||
| 577 | <entry><structfield>input</structfield></entry> | ||
| 578 | <entry></entry> | ||
| 579 | <entry>Some video capture drivers support rapid and | ||
| 580 | synchronous video input changes, a function useful for example in | ||
| 581 | video surveillance applications. For this purpose applications set the | ||
| 582 | <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the | ||
| 583 | number of a video input as in &v4l2-input; field | ||
| 584 | <structfield>index</structfield>.</entry> | ||
| 585 | </row> | ||
| 586 | <row> | ||
| 587 | <entry>__u32</entry> | ||
| 588 | <entry><structfield>reserved</structfield></entry> | ||
| 589 | <entry></entry> | ||
| 590 | <entry>A place holder for future extensions and custom | ||
| 591 | (driver defined) buffer types | ||
| 592 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> | ||
| 593 | </row> | ||
| 594 | </tbody> | ||
| 595 | </tgroup> | ||
| 596 | </table> | ||
| 597 | |||
| 598 | <table frame="none" pgwide="1" id="v4l2-buf-type"> | ||
| 599 | <title>enum v4l2_buf_type</title> | ||
| 600 | <tgroup cols="3"> | ||
| 601 | &cs-def; | ||
| 602 | <tbody valign="top"> | ||
| 603 | <row> | ||
| 604 | <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> | ||
| 605 | <entry>1</entry> | ||
| 606 | <entry>Buffer of a video capture stream, see <xref | ||
| 607 | linkend="capture" />.</entry> | ||
| 608 | </row> | ||
| 609 | <row> | ||
| 610 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> | ||
| 611 | <entry>2</entry> | ||
| 612 | <entry>Buffer of a video output stream, see <xref | ||
| 613 | linkend="output" />.</entry> | ||
| 614 | </row> | ||
| 615 | <row> | ||
| 616 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> | ||
| 617 | <entry>3</entry> | ||
| 618 | <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> | ||
| 619 | </row> | ||
| 620 | <row> | ||
| 621 | <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> | ||
| 622 | <entry>4</entry> | ||
| 623 | <entry>Buffer of a raw VBI capture stream, see <xref | ||
| 624 | linkend="raw-vbi" />.</entry> | ||
| 625 | </row> | ||
| 626 | <row> | ||
| 627 | <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> | ||
| 628 | <entry>5</entry> | ||
| 629 | <entry>Buffer of a raw VBI output stream, see <xref | ||
| 630 | linkend="raw-vbi" />.</entry> | ||
| 631 | </row> | ||
| 632 | <row> | ||
| 633 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> | ||
| 634 | <entry>6</entry> | ||
| 635 | <entry>Buffer of a sliced VBI capture stream, see <xref | ||
| 636 | linkend="sliced" />.</entry> | ||
| 637 | </row> | ||
| 638 | <row> | ||
| 639 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> | ||
| 640 | <entry>7</entry> | ||
| 641 | <entry>Buffer of a sliced VBI output stream, see <xref | ||
| 642 | linkend="sliced" />.</entry> | ||
| 643 | </row> | ||
| 644 | <row> | ||
| 645 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> | ||
| 646 | <entry>8</entry> | ||
| 647 | <entry>Buffer for video output overlay (OSD), see <xref | ||
| 648 | linkend="osd" />. Status: <link | ||
| 649 | linkend="experimental">Experimental</link>.</entry> | ||
| 650 | </row> | ||
| 651 | <row> | ||
| 652 | <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> | ||
| 653 | <entry>0x80</entry> | ||
| 654 | <entry>This and higher values are reserved for custom | ||
| 655 | (driver defined) buffer types.</entry> | ||
| 656 | </row> | ||
| 657 | </tbody> | ||
| 658 | </tgroup> | ||
| 659 | </table> | ||
| 660 | |||
| 661 | <table frame="none" pgwide="1" id="buffer-flags"> | ||
| 662 | <title>Buffer Flags</title> | ||
| 663 | <tgroup cols="3"> | ||
| 664 | &cs-def; | ||
| 665 | <tbody valign="top"> | ||
| 666 | <row> | ||
| 667 | <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> | ||
| 668 | <entry>0x0001</entry> | ||
| 669 | <entry>The buffer resides in device memory and has been mapped | ||
| 670 | into the application's address space, see <xref linkend="mmap" /> for details. | ||
| 671 | Drivers set or clear this flag when the | ||
| 672 | <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link | ||
| 673 | linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link | ||
| 674 | linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> | ||
| 675 | </row> | ||
| 676 | <row> | ||
| 677 | <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> | ||
| 678 | <entry>0x0002</entry> | ||
| 679 | <entry>Internally drivers maintain two buffer queues, an | ||
| 680 | incoming and outgoing queue. When this flag is set, the buffer is | ||
| 681 | currently on the incoming queue. It automatically moves to the | ||
| 682 | outgoing queue after the buffer has been filled (capture devices) or | ||
| 683 | displayed (output devices). Drivers set or clear this flag when the | ||
| 684 | <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After | ||
| 685 | (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is | ||
| 686 | always set and after <constant>VIDIOC_DQBUF</constant> always | ||
| 687 | cleared.</entry> | ||
| 688 | </row> | ||
| 689 | <row> | ||
| 690 | <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> | ||
| 691 | <entry>0x0004</entry> | ||
| 692 | <entry>When this flag is set, the buffer is currently on | ||
| 693 | the outgoing queue, ready to be dequeued from the driver. Drivers set | ||
| 694 | or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl | ||
| 695 | is called. After calling the <constant>VIDIOC_QBUF</constant> or | ||
| 696 | <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a | ||
| 697 | buffer cannot be on both queues at the same time, the | ||
| 698 | <constant>V4L2_BUF_FLAG_QUEUED</constant> and | ||
| 699 | <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. | ||
| 700 | They can be both cleared however, then the buffer is in "dequeued" | ||
| 701 | state, in the application domain to say so.</entry> | ||
| 702 | </row> | ||
| 703 | <row> | ||
| 704 | <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> | ||
| 705 | <entry>0x0008</entry> | ||
| 706 | <entry>Drivers set or clear this flag when calling the | ||
| 707 | <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video | ||
| 708 | capture devices when the buffer contains a compressed image which is a | ||
| 709 | key frame (or field), &ie; can be decompressed on its own.</entry> | ||
| 710 | </row> | ||
| 711 | <row> | ||
| 712 | <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> | ||
| 713 | <entry>0x0010</entry> | ||
| 714 | <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> | ||
| 715 | this flags predicted frames or fields which contain only differences to a | ||
| 716 | previous key frame.</entry> | ||
| 717 | </row> | ||
| 718 | <row> | ||
| 719 | <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> | ||
| 720 | <entry>0x0020</entry> | ||
| 721 | <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant> | ||
| 722 | this is a bidirectional predicted frame or field. [ooc tbd]</entry> | ||
| 723 | </row> | ||
| 724 | <row> | ||
| 725 | <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> | ||
| 726 | <entry>0x0100</entry> | ||
| 727 | <entry>The <structfield>timecode</structfield> field is valid. | ||
| 728 | Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> | ||
| 729 | ioctl is called.</entry> | ||
| 730 | </row> | ||
| 731 | <row> | ||
| 732 | <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry> | ||
| 733 | <entry>0x0200</entry> | ||
| 734 | <entry>The <structfield>input</structfield> field is valid. | ||
| 735 | Applications set or clear this flag before calling the | ||
| 736 | <constant>VIDIOC_QBUF</constant> ioctl.</entry> | ||
| 737 | </row> | ||
| 738 | </tbody> | ||
| 739 | </tgroup> | ||
| 740 | </table> | ||
| 741 | |||
| 742 | <table pgwide="1" frame="none" id="v4l2-memory"> | ||
| 743 | <title>enum v4l2_memory</title> | ||
| 744 | <tgroup cols="3"> | ||
| 745 | &cs-def; | ||
| 746 | <tbody valign="top"> | ||
| 747 | <row> | ||
| 748 | <entry><constant>V4L2_MEMORY_MMAP</constant></entry> | ||
| 749 | <entry>1</entry> | ||
| 750 | <entry>The buffer is used for <link linkend="mmap">memory | ||
| 751 | mapping</link> I/O.</entry> | ||
| 752 | </row> | ||
| 753 | <row> | ||
| 754 | <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> | ||
| 755 | <entry>2</entry> | ||
| 756 | <entry>The buffer is used for <link linkend="userp">user | ||
| 757 | pointer</link> I/O.</entry> | ||
| 758 | </row> | ||
| 759 | <row> | ||
| 760 | <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> | ||
| 761 | <entry>3</entry> | ||
| 762 | <entry>[to do]</entry> | ||
| 763 | </row> | ||
| 764 | </tbody> | ||
| 765 | </tgroup> | ||
| 766 | </table> | ||
| 767 | |||
| 768 | <section> | ||
| 769 | <title>Timecodes</title> | ||
| 770 | |||
| 771 | <para>The <structname>v4l2_timecode</structname> structure is | ||
| 772 | designed to hold a <xref linkend="smpte12m" /> or similar timecode. | ||
| 773 | (struct <structname>timeval</structname> timestamps are stored in | ||
| 774 | &v4l2-buffer; field <structfield>timestamp</structfield>.)</para> | ||
| 775 | |||
| 776 | <table frame="none" pgwide="1" id="v4l2-timecode"> | ||
| 777 | <title>struct <structname>v4l2_timecode</structname></title> | ||
| 778 | <tgroup cols="3"> | ||
| 779 | &cs-str; | ||
| 780 | <tbody valign="top"> | ||
| 781 | <row> | ||
| 782 | <entry>__u32</entry> | ||
| 783 | <entry><structfield>type</structfield></entry> | ||
| 784 | <entry>Frame rate the timecodes are based on, see <xref | ||
| 785 | linkend="timecode-type" />.</entry> | ||
| 786 | </row> | ||
| 787 | <row> | ||
| 788 | <entry>__u32</entry> | ||
| 789 | <entry><structfield>flags</structfield></entry> | ||
| 790 | <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> | ||
| 791 | </row> | ||
| 792 | <row> | ||
| 793 | <entry>__u8</entry> | ||
| 794 | <entry><structfield>frames</structfield></entry> | ||
| 795 | <entry>Frame count, 0 ... 23/24/29/49/59, depending on the | ||
| 796 | type of timecode.</entry> | ||
| 797 | </row> | ||
| 798 | <row> | ||
| 799 | <entry>__u8</entry> | ||
| 800 | <entry><structfield>seconds</structfield></entry> | ||
| 801 | <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> | ||
| 802 | </row> | ||
| 803 | <row> | ||
| 804 | <entry>__u8</entry> | ||
| 805 | <entry><structfield>minutes</structfield></entry> | ||
| 806 | <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> | ||
| 807 | </row> | ||
| 808 | <row> | ||
| 809 | <entry>__u8</entry> | ||
| 810 | <entry><structfield>hours</structfield></entry> | ||
| 811 | <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> | ||
| 812 | </row> | ||
| 813 | <row> | ||
| 814 | <entry>__u8</entry> | ||
| 815 | <entry><structfield>userbits</structfield>[4]</entry> | ||
| 816 | <entry>The "user group" bits from the timecode.</entry> | ||
| 817 | </row> | ||
| 818 | </tbody> | ||
| 819 | </tgroup> | ||
| 820 | </table> | ||
| 821 | |||
| 822 | <table frame="none" pgwide="1" id="timecode-type"> | ||
| 823 | <title>Timecode Types</title> | ||
| 824 | <tgroup cols="3"> | ||
| 825 | &cs-def; | ||
| 826 | <tbody valign="top"> | ||
| 827 | <row> | ||
| 828 | <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> | ||
| 829 | <entry>1</entry> | ||
| 830 | <entry>24 frames per second, i. e. film.</entry> | ||
| 831 | </row> | ||
| 832 | <row> | ||
| 833 | <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> | ||
| 834 | <entry>2</entry> | ||
| 835 | <entry>25 frames per second, &ie; PAL or SECAM video.</entry> | ||
| 836 | </row> | ||
| 837 | <row> | ||
| 838 | <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> | ||
| 839 | <entry>3</entry> | ||
| 840 | <entry>30 frames per second, &ie; NTSC video.</entry> | ||
| 841 | </row> | ||
| 842 | <row> | ||
| 843 | <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> | ||
| 844 | <entry>4</entry> | ||
| 845 | <entry></entry> | ||
| 846 | </row> | ||
| 847 | <row> | ||
| 848 | <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> | ||
| 849 | <entry>5</entry> | ||
| 850 | <entry></entry> | ||
| 851 | </row> | ||
| 852 | </tbody> | ||
| 853 | </tgroup> | ||
| 854 | </table> | ||
| 855 | |||
| 856 | <table frame="none" pgwide="1" id="timecode-flags"> | ||
| 857 | <title>Timecode Flags</title> | ||
| 858 | <tgroup cols="3"> | ||
| 859 | &cs-def; | ||
| 860 | <tbody valign="top"> | ||
| 861 | <row> | ||
| 862 | <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> | ||
| 863 | <entry>0x0001</entry> | ||
| 864 | <entry>Indicates "drop frame" semantics for counting frames | ||
| 865 | in 29.97 fps material. When set, frame numbers 0 and 1 at the start of | ||
| 866 | each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the | ||
| 867 | count.</entry> | ||
| 868 | </row> | ||
| 869 | <row> | ||
| 870 | <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> | ||
| 871 | <entry>0x0002</entry> | ||
| 872 | <entry>The "color frame" flag.</entry> | ||
| 873 | </row> | ||
| 874 | <row> | ||
| 875 | <entry><constant>V4L2_TC_USERBITS_field</constant></entry> | ||
| 876 | <entry>0x000C</entry> | ||
| 877 | <entry>Field mask for the "binary group flags".</entry> | ||
| 878 | </row> | ||
| 879 | <row> | ||
| 880 | <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> | ||
| 881 | <entry>0x0000</entry> | ||
| 882 | <entry>Unspecified format.</entry> | ||
| 883 | </row> | ||
| 884 | <row> | ||
| 885 | <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> | ||
| 886 | <entry>0x0008</entry> | ||
| 887 | <entry>8-bit ISO characters.</entry> | ||
| 888 | </row> | ||
| 889 | </tbody> | ||
| 890 | </tgroup> | ||
| 891 | </table> | ||
| 892 | </section> | ||
| 893 | </section> | ||
| 894 | |||
| 895 | <section id="field-order"> | ||
| 896 | <title>Field Order</title> | ||
| 897 | |||
| 898 | <para>We have to distinguish between progressive and interlaced | ||
| 899 | video. Progressive video transmits all lines of a video image | ||
| 900 | sequentially. Interlaced video divides an image into two fields, | ||
| 901 | containing only the odd and even lines of the image, respectively. | ||
| 902 | Alternating the so called odd and even field are transmitted, and due | ||
| 903 | to a small delay between fields a cathode ray TV displays the lines | ||
| 904 | interleaved, yielding the original frame. This curious technique was | ||
| 905 | invented because at refresh rates similar to film the image would | ||
| 906 | fade out too quickly. Transmitting fields reduces the flicker without | ||
| 907 | the necessity of doubling the frame rate and with it the bandwidth | ||
| 908 | required for each channel.</para> | ||
| 909 | |||
| 910 | <para>It is important to understand a video camera does not expose | ||
| 911 | one frame at a time, merely transmitting the frames separated into | ||
| 912 | fields. The fields are in fact captured at two different instances in | ||
| 913 | time. An object on screen may well move between one field and the | ||
| 914 | next. For applications analysing motion it is of paramount importance | ||
| 915 | to recognize which field of a frame is older, the <emphasis>temporal | ||
| 916 | order</emphasis>.</para> | ||
| 917 | |||
| 918 | <para>When the driver provides or accepts images field by field | ||
| 919 | rather than interleaved, it is also important applications understand | ||
| 920 | how the fields combine to frames. We distinguish between top and | ||
| 921 | bottom fields, the <emphasis>spatial order</emphasis>: The first line | ||
| 922 | of the top field is the first line of an interlaced frame, the first | ||
| 923 | line of the bottom field is the second line of that frame.</para> | ||
| 924 | |||
| 925 | <para>However because fields were captured one after the other, | ||
| 926 | arguing whether a frame commences with the top or bottom field is | ||
| 927 | pointless. Any two successive top and bottom, or bottom and top fields | ||
| 928 | yield a valid frame. Only when the source was progressive to begin | ||
| 929 | with, ⪚ when transferring film to video, two fields may come from | ||
| 930 | the same frame, creating a natural order.</para> | ||
| 931 | |||
| 932 | <para>Counter to intuition the top field is not necessarily the | ||
| 933 | older field. Whether the older field contains the top or bottom lines | ||
| 934 | is a convention determined by the video standard. Hence the | ||
| 935 | distinction between temporal and spatial order of fields. The diagrams | ||
| 936 | below should make this clearer.</para> | ||
| 937 | |||
| 938 | <para>All video capture and output devices must report the current | ||
| 939 | field order. Some drivers may permit the selection of a different | ||
| 940 | order, to this end applications initialize the | ||
| 941 | <structfield>field</structfield> field of &v4l2-pix-format; before | ||
| 942 | calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should | ||
| 943 | have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> | ||
| 944 | |||
| 945 | <table frame="none" pgwide="1" id="v4l2-field"> | ||
| 946 | <title>enum v4l2_field</title> | ||
| 947 | <tgroup cols="3"> | ||
| 948 | &cs-def; | ||
| 949 | <tbody valign="top"> | ||
| 950 | <row> | ||
| 951 | <entry><constant>V4L2_FIELD_ANY</constant></entry> | ||
| 952 | <entry>0</entry> | ||
| 953 | <entry>Applications request this field order when any | ||
| 954 | one of the <constant>V4L2_FIELD_NONE</constant>, | ||
| 955 | <constant>V4L2_FIELD_TOP</constant>, | ||
| 956 | <constant>V4L2_FIELD_BOTTOM</constant>, or | ||
| 957 | <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. | ||
| 958 | Drivers choose depending on hardware capabilities or e. g. the | ||
| 959 | requested image size, and return the actual field order. &v4l2-buffer; | ||
| 960 | <structfield>field</structfield> can never be | ||
| 961 | <constant>V4L2_FIELD_ANY</constant>.</entry> | ||
| 962 | </row> | ||
| 963 | <row> | ||
| 964 | <entry><constant>V4L2_FIELD_NONE</constant></entry> | ||
| 965 | <entry>1</entry> | ||
| 966 | <entry>Images are in progressive format, not interlaced. | ||
| 967 | The driver may also indicate this order when it cannot distinguish | ||
| 968 | between <constant>V4L2_FIELD_TOP</constant> and | ||
| 969 | <constant>V4L2_FIELD_BOTTOM</constant>.</entry> | ||
| 970 | </row> | ||
| 971 | <row> | ||
| 972 | <entry><constant>V4L2_FIELD_TOP</constant></entry> | ||
| 973 | <entry>2</entry> | ||
| 974 | <entry>Images consist of the top field only.</entry> | ||
| 975 | </row> | ||
| 976 | <row> | ||
| 977 | <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> | ||
| 978 | <entry>3</entry> | ||
| 979 | <entry>Images consist of the bottom field only. | ||
| 980 | Applications may wish to prevent a device from capturing interlaced | ||
| 981 | images because they will have "comb" or "feathering" artefacts around | ||
| 982 | moving objects.</entry> | ||
| 983 | </row> | ||
| 984 | <row> | ||
| 985 | <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> | ||
| 986 | <entry>4</entry> | ||
| 987 | <entry>Images contain both fields, interleaved line by | ||
| 988 | line. The temporal order of the fields (whether the top or bottom | ||
| 989 | field is first transmitted) depends on the current video standard. | ||
| 990 | M/NTSC transmits the bottom field first, all other standards the top | ||
| 991 | field first.</entry> | ||
| 992 | </row> | ||
| 993 | <row> | ||
| 994 | <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> | ||
| 995 | <entry>5</entry> | ||
| 996 | <entry>Images contain both fields, the top field lines | ||
| 997 | are stored first in memory, immediately followed by the bottom field | ||
| 998 | lines. Fields are always stored in temporal order, the older one first | ||
| 999 | in memory. Image sizes refer to the frame, not fields.</entry> | ||
| 1000 | </row> | ||
| 1001 | <row> | ||
| 1002 | <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> | ||
| 1003 | <entry>6</entry> | ||
| 1004 | <entry>Images contain both fields, the bottom field | ||
| 1005 | lines are stored first in memory, immediately followed by the top | ||
| 1006 | field lines. Fields are always stored in temporal order, the older one | ||
| 1007 | first in memory. Image sizes refer to the frame, not fields.</entry> | ||
| 1008 | </row> | ||
| 1009 | <row> | ||
| 1010 | <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> | ||
| 1011 | <entry>7</entry> | ||
| 1012 | <entry>The two fields of a frame are passed in separate | ||
| 1013 | buffers, in temporal order, &ie; the older one first. To indicate the field | ||
| 1014 | parity (whether the current field is a top or bottom field) the driver | ||
| 1015 | or application, depending on data direction, must set &v4l2-buffer; | ||
| 1016 | <structfield>field</structfield> to | ||
| 1017 | <constant>V4L2_FIELD_TOP</constant> or | ||
| 1018 | <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair | ||
| 1019 | to build a frame. If fields are successive, without any dropped fields | ||
| 1020 | between them (fields can drop individually), can be determined from | ||
| 1021 | the &v4l2-buffer; <structfield>sequence</structfield> field. Image | ||
| 1022 | sizes refer to the frame, not fields. This format cannot be selected | ||
| 1023 | when using the read/write I/O method.<!-- Where it's indistinguishable | ||
| 1024 | from V4L2_FIELD_SEQ_*. --></entry> | ||
| 1025 | </row> | ||
| 1026 | <row> | ||
| 1027 | <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> | ||
| 1028 | <entry>8</entry> | ||
| 1029 | <entry>Images contain both fields, interleaved line by | ||
| 1030 | line, top field first. The top field is transmitted first.</entry> | ||
| 1031 | </row> | ||
| 1032 | <row> | ||
| 1033 | <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> | ||
| 1034 | <entry>9</entry> | ||
| 1035 | <entry>Images contain both fields, interleaved line by | ||
| 1036 | line, top field first. The bottom field is transmitted first.</entry> | ||
| 1037 | </row> | ||
| 1038 | </tbody> | ||
| 1039 | </tgroup> | ||
| 1040 | </table> | ||
| 1041 | |||
| 1042 | <figure id="fieldseq-tb"> | ||
| 1043 | <title>Field Order, Top Field First Transmitted</title> | ||
| 1044 | <mediaobject> | ||
| 1045 | <imageobject> | ||
| 1046 | <imagedata fileref="fieldseq_tb.pdf" format="PS" /> | ||
| 1047 | </imageobject> | ||
| 1048 | <imageobject> | ||
| 1049 | <imagedata fileref="fieldseq_tb.gif" format="GIF" /> | ||
| 1050 | </imageobject> | ||
| 1051 | </mediaobject> | ||
| 1052 | </figure> | ||
| 1053 | |||
| 1054 | <figure id="fieldseq-bt"> | ||
| 1055 | <title>Field Order, Bottom Field First Transmitted</title> | ||
| 1056 | <mediaobject> | ||
| 1057 | <imageobject> | ||
| 1058 | <imagedata fileref="fieldseq_bt.pdf" format="PS" /> | ||
| 1059 | </imageobject> | ||
| 1060 | <imageobject> | ||
| 1061 | <imagedata fileref="fieldseq_bt.gif" format="GIF" /> | ||
| 1062 | </imageobject> | ||
| 1063 | </mediaobject> | ||
| 1064 | </figure> | ||
| 1065 | </section> | ||
| 1066 | |||
| 1067 | <!-- | ||
| 1068 | Local Variables: | ||
| 1069 | mode: sgml | ||
| 1070 | sgml-parent-document: "v4l2.sgml" | ||
| 1071 | indent-tabs-mode: nil | ||
| 1072 | End: | ||
| 1073 | --> | ||
diff --git a/Documentation/DocBook/v4l/keytable.c.xml b/Documentation/DocBook/v4l/keytable.c.xml new file mode 100644 index 000000000000..d53254a3be15 --- /dev/null +++ b/Documentation/DocBook/v4l/keytable.c.xml | |||
| @@ -0,0 +1,172 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* keytable.c - This program allows checking/replacing keys at IR | ||
| 3 | |||
| 4 | Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org> | ||
| 5 | |||
| 6 | This program is free software; you can redistribute it and/or modify | ||
| 7 | it under the terms of the GNU General Public License as published by | ||
| 8 | the Free Software Foundation, version 2 of the License. | ||
| 9 | |||
| 10 | This program is distributed in the hope that it will be useful, | ||
| 11 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 13 | GNU General Public License for more details. | ||
| 14 | */ | ||
| 15 | |||
| 16 | #include <ctype.h> | ||
| 17 | #include <errno.h> | ||
| 18 | #include <fcntl.h> | ||
| 19 | #include <stdio.h> | ||
| 20 | #include <stdlib.h> | ||
| 21 | #include <string.h> | ||
| 22 | #include <linux/input.h> | ||
| 23 | #include <sys/ioctl.h> | ||
| 24 | |||
| 25 | #include "parse.h" | ||
| 26 | |||
| 27 | void prtcode (int *codes) | ||
| 28 | { | ||
| 29 | struct parse_key *p; | ||
| 30 | |||
| 31 | for (p=keynames;p->name!=NULL;p++) { | ||
| 32 | if (p->value == (unsigned)codes[1]) { | ||
| 33 | printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p->name, codes[1]); | ||
| 34 | return; | ||
| 35 | } | ||
| 36 | } | ||
| 37 | |||
| 38 | if (isprint (codes[1])) | ||
| 39 | printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]); | ||
| 40 | else | ||
| 41 | printf("scancode %d = 0x%02x\n", codes[0], codes[1]); | ||
| 42 | } | ||
| 43 | |||
| 44 | int parse_code(char *string) | ||
| 45 | { | ||
| 46 | struct parse_key *p; | ||
| 47 | |||
| 48 | for (p=keynames;p->name!=NULL;p++) { | ||
| 49 | if (!strcasecmp(p->name, string)) { | ||
| 50 | return p->value; | ||
| 51 | } | ||
| 52 | } | ||
| 53 | return -1; | ||
| 54 | } | ||
| 55 | |||
| 56 | int main (int argc, char *argv[]) | ||
| 57 | { | ||
| 58 | int fd; | ||
| 59 | unsigned int i, j; | ||
| 60 | int codes[2]; | ||
| 61 | |||
| 62 | if (argc<2 || argc>4) { | ||
| 63 | printf ("usage: %s <device> to get table; or\n" | ||
| 64 | " %s <device> <scancode> <keycode>\n" | ||
| 65 | " %s <device> <keycode_file>\n",*argv,*argv,*argv); | ||
| 66 | return -1; | ||
| 67 | } | ||
| 68 | |||
| 69 | if ((fd = open(argv[1], O_RDONLY)) < 0) { | ||
| 70 | perror("Couldn't open input device"); | ||
| 71 | return(-1); | ||
| 72 | } | ||
| 73 | |||
| 74 | if (argc==4) { | ||
| 75 | int value; | ||
| 76 | |||
| 77 | value=parse_code(argv[3]); | ||
| 78 | |||
| 79 | if (value==-1) { | ||
| 80 | value = strtol(argv[3], NULL, 0); | ||
| 81 | if (errno) | ||
| 82 | perror("value"); | ||
| 83 | } | ||
| 84 | |||
| 85 | codes [0] = (unsigned) strtol(argv[2], NULL, 0); | ||
| 86 | codes [1] = (unsigned) value; | ||
| 87 | |||
| 88 | if(ioctl(fd, EVIOCSKEYCODE, codes)) | ||
| 89 | perror ("EVIOCSKEYCODE"); | ||
| 90 | |||
| 91 | if(ioctl(fd, EVIOCGKEYCODE, codes)==0) | ||
| 92 | prtcode(codes); | ||
| 93 | return 0; | ||
| 94 | } | ||
| 95 | |||
| 96 | if (argc==3) { | ||
| 97 | FILE *fin; | ||
| 98 | int value; | ||
| 99 | char *scancode, *keycode, s[2048]; | ||
| 100 | |||
| 101 | fin=fopen(argv[2],"r"); | ||
| 102 | if (fin==NULL) { | ||
| 103 | perror ("opening keycode file"); | ||
| 104 | return -1; | ||
| 105 | } | ||
| 106 | |||
| 107 | /* Clears old table */ | ||
| 108 | for (j = 0; j < 256; j++) { | ||
| 109 | for (i = 0; i < 256; i++) { | ||
| 110 | codes[0] = (j << 8) | i; | ||
| 111 | codes[1] = KEY_RESERVED; | ||
| 112 | ioctl(fd, EVIOCSKEYCODE, codes); | ||
| 113 | } | ||
| 114 | } | ||
| 115 | |||
| 116 | while (fgets(s,sizeof(s),fin)) { | ||
| 117 | scancode=strtok(s,"\n\t =:"); | ||
| 118 | if (!scancode) { | ||
| 119 | perror ("parsing input file scancode"); | ||
| 120 | return -1; | ||
| 121 | } | ||
| 122 | if (!strcasecmp(scancode, "scancode")) { | ||
| 123 | scancode = strtok(NULL,"\n\t =:"); | ||
| 124 | if (!scancode) { | ||
| 125 | perror ("parsing input file scancode"); | ||
| 126 | return -1; | ||
| 127 | } | ||
| 128 | } | ||
| 129 | |||
| 130 | keycode=strtok(NULL,"\n\t =:("); | ||
| 131 | if (!keycode) { | ||
| 132 | perror ("parsing input file keycode"); | ||
| 133 | return -1; | ||
| 134 | } | ||
| 135 | |||
| 136 | // printf ("parsing %s=%s:", scancode, keycode); | ||
| 137 | value=parse_code(keycode); | ||
| 138 | // printf ("\tvalue=%d\n",value); | ||
| 139 | |||
| 140 | if (value==-1) { | ||
| 141 | value = strtol(keycode, NULL, 0); | ||
| 142 | if (errno) | ||
| 143 | perror("value"); | ||
| 144 | } | ||
| 145 | |||
| 146 | codes [0] = (unsigned) strtol(scancode, NULL, 0); | ||
| 147 | codes [1] = (unsigned) value; | ||
| 148 | |||
| 149 | // printf("\t%04x=%04x\n",codes[0], codes[1]); | ||
| 150 | if(ioctl(fd, EVIOCSKEYCODE, codes)) { | ||
| 151 | fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]); | ||
| 152 | perror ("EVIOCSKEYCODE"); | ||
| 153 | } | ||
| 154 | |||
| 155 | if(ioctl(fd, EVIOCGKEYCODE, codes)==0) | ||
| 156 | prtcode(codes); | ||
| 157 | } | ||
| 158 | return 0; | ||
| 159 | } | ||
| 160 | |||
| 161 | /* Get scancode table */ | ||
| 162 | for (j = 0; j < 256; j++) { | ||
| 163 | for (i = 0; i < 256; i++) { | ||
| 164 | codes[0] = (j << 8) | i; | ||
| 165 | if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED) | ||
| 166 | prtcode(codes); | ||
| 167 | } | ||
| 168 | } | ||
| 169 | return 0; | ||
| 170 | } | ||
| 171 | |||
| 172 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/libv4l.xml b/Documentation/DocBook/v4l/libv4l.xml new file mode 100644 index 000000000000..c14fc3db2a81 --- /dev/null +++ b/Documentation/DocBook/v4l/libv4l.xml | |||
| @@ -0,0 +1,167 @@ | |||
| 1 | <title>Libv4l Userspace Library</title> | ||
| 2 | <section id="libv4l-introduction"> | ||
| 3 | <title>Introduction</title> | ||
| 4 | |||
| 5 | <para>libv4l is a collection of libraries which adds a thin abstraction | ||
| 6 | layer on top of video4linux2 devices. The purpose of this (thin) layer | ||
| 7 | is to make it easy for application writers to support a wide variety of | ||
| 8 | devices without having to write separate code for different devices in the | ||
| 9 | same class.</para> | ||
| 10 | <para>An example of using libv4l is provided by | ||
| 11 | <link linkend='v4l2grab-example'>v4l2grab</link>. | ||
| 12 | </para> | ||
| 13 | |||
| 14 | <para>libv4l consists of 3 different libraries:</para> | ||
| 15 | <section> | ||
| 16 | <title>libv4lconvert</title> | ||
| 17 | |||
| 18 | <para>libv4lconvert is a library that converts several | ||
| 19 | different pixelformats found in V4L2 drivers into a few common RGB and | ||
| 20 | YUY formats.</para> | ||
| 21 | <para>It currently accepts the following V4L2 driver formats: | ||
| 22 | <link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, | ||
| 23 | <link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>, | ||
| 24 | <link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>, | ||
| 25 | <link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>, | ||
| 26 | <link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>, | ||
| 27 | <link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>, | ||
| 28 | <link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>, | ||
| 29 | <link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>, | ||
| 30 | <link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>, | ||
| 31 | <link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, | ||
| 32 | <link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>, | ||
| 33 | <link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>, | ||
| 34 | <link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>, | ||
| 35 | <link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>, | ||
| 36 | <link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>, | ||
| 37 | <link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>, | ||
| 38 | <link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>, | ||
| 39 | <link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>, | ||
| 40 | <link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>, | ||
| 41 | <link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>, | ||
| 42 | <constant>V4L2_PIX_FMT_SRGGB8</constant>, | ||
| 43 | <link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>, | ||
| 44 | <link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, | ||
| 45 | <link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>, | ||
| 46 | <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, | ||
| 47 | and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>. | ||
| 48 | </para> | ||
| 49 | <para>Later on libv4lconvert was expanded to also be able to do | ||
| 50 | various video processing functions to improve webcam video quality. | ||
| 51 | The video processing is split in to 2 parts: libv4lconvert/control and | ||
| 52 | libv4lconvert/processing.</para> | ||
| 53 | |||
| 54 | <para>The control part is used to offer video controls which can | ||
| 55 | be used to control the video processing functions made available by | ||
| 56 | libv4lconvert/processing. These controls are stored application wide | ||
| 57 | (until reboot) by using a persistent shared memory object.</para> | ||
| 58 | |||
| 59 | <para>libv4lconvert/processing offers the actual video | ||
| 60 | processing functionality.</para> | ||
| 61 | </section> | ||
| 62 | <section> | ||
| 63 | <title>libv4l1</title> | ||
| 64 | <para>This library offers functions that can be used to quickly | ||
| 65 | make v4l1 applications work with v4l2 devices. These functions work exactly | ||
| 66 | like the normal open/close/etc, except that libv4l1 does full emulation of | ||
| 67 | the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it | ||
| 68 | will just pass calls through.</para> | ||
| 69 | <para>Since those functions are emulations of the old V4L1 API, | ||
| 70 | it shouldn't be used for new applications.</para> | ||
| 71 | </section> | ||
| 72 | <section> | ||
| 73 | <title>libv4l2</title> | ||
| 74 | <para>This library should be used for all modern V4L2 | ||
| 75 | applications.</para> | ||
| 76 | <para>It provides handles to call V4L2 open/ioctl/close/poll | ||
| 77 | methods. Instead of just providing the raw output of the device, it enhances | ||
| 78 | the calls in the sense that it will use libv4lconvert to provide more video | ||
| 79 | formats and to enhance the image quality.</para> | ||
| 80 | <para>In most cases, libv4l2 just passes the calls directly | ||
| 81 | through to the v4l2 driver, intercepting the calls to | ||
| 82 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>, | ||
| 83 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link> | ||
| 84 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link> | ||
| 85 | <link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link> | ||
| 86 | and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link> | ||
| 87 | in order to emulate the formats | ||
| 88 | <link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, | ||
| 89 | <link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, | ||
| 90 | <link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, | ||
| 91 | and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, | ||
| 92 | if they aren't available in the driver. | ||
| 93 | <link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link> | ||
| 94 | keeps enumerating the hardware supported formats, plus the emulated formats | ||
| 95 | offered by libv4l at the end. | ||
| 96 | </para> | ||
| 97 | <section id="libv4l-ops"> | ||
| 98 | <title>Libv4l device control functions</title> | ||
| 99 | <para>The common file operation methods are provided by | ||
| 100 | libv4l.</para> | ||
| 101 | <para>Those functions operate just like glibc | ||
| 102 | open/close/dup/ioctl/read/mmap/munmap:</para> | ||
| 103 | <itemizedlist><listitem> | ||
| 104 | <para>int v4l2_open(const char *file, int oflag, | ||
| 105 | ...) - | ||
| 106 | operates like the standard <link linkend='func-open'>open()</link> function. | ||
| 107 | </para></listitem><listitem> | ||
| 108 | <para>int v4l2_close(int fd) - | ||
| 109 | operates like the standard <link linkend='func-close'>close()</link> function. | ||
| 110 | </para></listitem><listitem> | ||
| 111 | <para>int v4l2_dup(int fd) - | ||
| 112 | operates like the standard dup() function, duplicating a file handler. | ||
| 113 | </para></listitem><listitem> | ||
| 114 | <para>int v4l2_ioctl (int fd, unsigned long int request, ...) - | ||
| 115 | operates like the standard <link linkend='func-ioctl'>ioctl()</link> function. | ||
| 116 | </para></listitem><listitem> | ||
| 117 | <para>int v4l2_read (int fd, void* buffer, size_t n) - | ||
| 118 | operates like the standard <link linkend='func-read'>read()</link> function. | ||
| 119 | </para></listitem><listitem> | ||
| 120 | <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - | ||
| 121 | operates like the standard <link linkend='func-mmap'>mmap()</link> function. | ||
| 122 | </para></listitem><listitem> | ||
| 123 | <para>int v4l2_munmap(void *_start, size_t length); - | ||
| 124 | operates like the standard <link linkend='func-munmap'>munmap()</link> function. | ||
| 125 | </para></listitem> | ||
| 126 | </itemizedlist> | ||
| 127 | <para>Those functions provide additional control:</para> | ||
| 128 | <itemizedlist><listitem> | ||
| 129 | <para>int v4l2_fd_open(int fd, int v4l2_flags) - | ||
| 130 | opens an already opened fd for further use through v4l2lib and possibly | ||
| 131 | modify libv4l2's default behavior through the v4l2_flags argument. | ||
| 132 | Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>, | ||
| 133 | to disable format conversion. | ||
| 134 | </para></listitem><listitem> | ||
| 135 | <para>int v4l2_set_control(int fd, int cid, int value) - | ||
| 136 | This function takes a value of 0 - 65535, and then scales that range to | ||
| 137 | the actual range of the given v4l control id, and then if the cid exists | ||
| 138 | and is not locked sets the cid to the scaled value. | ||
| 139 | </para></listitem><listitem> | ||
| 140 | <para>int v4l2_get_control(int fd, int cid) - | ||
| 141 | This function returns a value of 0 - 65535, scaled to from the actual range | ||
| 142 | of the given v4l control id. when the cid does not exist, could not be | ||
| 143 | accessed for some reason, or some error occured 0 is returned. | ||
| 144 | </para></listitem> | ||
| 145 | </itemizedlist> | ||
| 146 | </section> | ||
| 147 | </section> | ||
| 148 | <section> | ||
| 149 | |||
| 150 | <title>v4l1compat.so wrapper library</title> | ||
| 151 | |||
| 152 | <para>This library intercepts calls to | ||
| 153 | open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l | ||
| 154 | counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also | ||
| 155 | emulates V4L1 calls via V4L2 API.</para> | ||
| 156 | <para>It allows usage of binary legacy applications that | ||
| 157 | still don't use libv4l.</para> | ||
| 158 | </section> | ||
| 159 | |||
| 160 | </section> | ||
| 161 | <!-- | ||
| 162 | Local Variables: | ||
| 163 | mode: sgml | ||
| 164 | sgml-parent-document: "v4l2.sgml" | ||
| 165 | indent-tabs-mode: nil | ||
| 166 | End: | ||
| 167 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-grey.xml b/Documentation/DocBook/v4l/pixfmt-grey.xml new file mode 100644 index 000000000000..3b72bc6b2de7 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-grey.xml | |||
| @@ -0,0 +1,70 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-GREY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_GREY</constant></refname> | ||
| 8 | <refpurpose>Grey-scale image</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is a grey-scale image. It is really a degenerate | ||
| 14 | Y'CbCr format which simply contains no Cb or Cr data.</para> | ||
| 15 | |||
| 16 | <example> | ||
| 17 | <title><constant>V4L2_PIX_FMT_GREY</constant> 4 × 4 | ||
| 18 | pixel image</title> | ||
| 19 | |||
| 20 | <formalpara> | ||
| 21 | <title>Byte Order.</title> | ||
| 22 | <para>Each cell is one byte. | ||
| 23 | <informaltable frame="none"> | ||
| 24 | <tgroup cols="5" align="center"> | ||
| 25 | <colspec align="left" colwidth="2*" /> | ||
| 26 | <tbody valign="top"> | ||
| 27 | <row> | ||
| 28 | <entry>start + 0:</entry> | ||
| 29 | <entry>Y'<subscript>00</subscript></entry> | ||
| 30 | <entry>Y'<subscript>01</subscript></entry> | ||
| 31 | <entry>Y'<subscript>02</subscript></entry> | ||
| 32 | <entry>Y'<subscript>03</subscript></entry> | ||
| 33 | </row> | ||
| 34 | <row> | ||
| 35 | <entry>start + 4:</entry> | ||
| 36 | <entry>Y'<subscript>10</subscript></entry> | ||
| 37 | <entry>Y'<subscript>11</subscript></entry> | ||
| 38 | <entry>Y'<subscript>12</subscript></entry> | ||
| 39 | <entry>Y'<subscript>13</subscript></entry> | ||
| 40 | </row> | ||
| 41 | <row> | ||
| 42 | <entry>start + 8:</entry> | ||
| 43 | <entry>Y'<subscript>20</subscript></entry> | ||
| 44 | <entry>Y'<subscript>21</subscript></entry> | ||
| 45 | <entry>Y'<subscript>22</subscript></entry> | ||
| 46 | <entry>Y'<subscript>23</subscript></entry> | ||
| 47 | </row> | ||
| 48 | <row> | ||
| 49 | <entry>start + 12:</entry> | ||
| 50 | <entry>Y'<subscript>30</subscript></entry> | ||
| 51 | <entry>Y'<subscript>31</subscript></entry> | ||
| 52 | <entry>Y'<subscript>32</subscript></entry> | ||
| 53 | <entry>Y'<subscript>33</subscript></entry> | ||
| 54 | </row> | ||
| 55 | </tbody> | ||
| 56 | </tgroup> | ||
| 57 | </informaltable> | ||
| 58 | </para> | ||
| 59 | </formalpara> | ||
| 60 | </example> | ||
| 61 | </refsect1> | ||
| 62 | </refentry> | ||
| 63 | |||
| 64 | <!-- | ||
| 65 | Local Variables: | ||
| 66 | mode: sgml | ||
| 67 | sgml-parent-document: "pixfmt.sgml" | ||
| 68 | indent-tabs-mode: nil | ||
| 69 | End: | ||
| 70 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-nv12.xml b/Documentation/DocBook/v4l/pixfmt-nv12.xml new file mode 100644 index 000000000000..873f67035181 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv12.xml | |||
| @@ -0,0 +1,151 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname> | ||
| 9 | <refpurpose>Formats with ½ horizontal and vertical | ||
| 10 | chroma resolution, also known as YUV 4:2:0. One luminance and one | ||
| 11 | chrominance plane with alternating chroma samples as opposed to | ||
| 12 | <constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | <refsect1> | ||
| 15 | <title>Description</title> | ||
| 16 | |||
| 17 | <para>These are two-plane versions of the YUV 4:2:0 format. | ||
| 18 | The three components are separated into two sub-images or planes. The | ||
| 19 | Y plane is first. The Y plane has one byte per pixel. For | ||
| 20 | <constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane | ||
| 21 | immediately follows the Y plane in memory. The CbCr plane is the same | ||
| 22 | width, in bytes, as the Y plane (and of the image), but is half as | ||
| 23 | tall in pixels. Each CbCr pair belongs to four pixels. For example, | ||
| 24 | Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to | ||
| 25 | Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, | ||
| 26 | Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. | ||
| 27 | <constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and | ||
| 28 | Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> | ||
| 29 | |||
| 30 | <para>If the Y plane has pad bytes after each row, then the | ||
| 31 | CbCr plane has as many pad bytes after its rows.</para> | ||
| 32 | |||
| 33 | <example> | ||
| 34 | <title><constant>V4L2_PIX_FMT_NV12</constant> 4 × 4 | ||
| 35 | pixel image</title> | ||
| 36 | |||
| 37 | <formalpara> | ||
| 38 | <title>Byte Order.</title> | ||
| 39 | <para>Each cell is one byte. | ||
| 40 | <informaltable frame="none"> | ||
| 41 | <tgroup cols="5" align="center"> | ||
| 42 | <colspec align="left" colwidth="2*" /> | ||
| 43 | <tbody valign="top"> | ||
| 44 | <row> | ||
| 45 | <entry>start + 0:</entry> | ||
| 46 | <entry>Y'<subscript>00</subscript></entry> | ||
| 47 | <entry>Y'<subscript>01</subscript></entry> | ||
| 48 | <entry>Y'<subscript>02</subscript></entry> | ||
| 49 | <entry>Y'<subscript>03</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 4:</entry> | ||
| 53 | <entry>Y'<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>11</subscript></entry> | ||
| 55 | <entry>Y'<subscript>12</subscript></entry> | ||
| 56 | <entry>Y'<subscript>13</subscript></entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>start + 8:</entry> | ||
| 60 | <entry>Y'<subscript>20</subscript></entry> | ||
| 61 | <entry>Y'<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>22</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 12:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32</subscript></entry> | ||
| 70 | <entry>Y'<subscript>33</subscript></entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry>start + 16:</entry> | ||
| 74 | <entry>Cb<subscript>00</subscript></entry> | ||
| 75 | <entry>Cr<subscript>00</subscript></entry> | ||
| 76 | <entry>Cb<subscript>01</subscript></entry> | ||
| 77 | <entry>Cr<subscript>01</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 20:</entry> | ||
| 81 | <entry>Cb<subscript>10</subscript></entry> | ||
| 82 | <entry>Cr<subscript>10</subscript></entry> | ||
| 83 | <entry>Cb<subscript>11</subscript></entry> | ||
| 84 | <entry>Cr<subscript>11</subscript></entry> | ||
| 85 | </row> | ||
| 86 | </tbody> | ||
| 87 | </tgroup> | ||
| 88 | </informaltable> | ||
| 89 | </para> | ||
| 90 | </formalpara> | ||
| 91 | |||
| 92 | <formalpara> | ||
| 93 | <title>Color Sample Location.</title> | ||
| 94 | <para> | ||
| 95 | <informaltable frame="none"> | ||
| 96 | <tgroup cols="7" align="center"> | ||
| 97 | <tbody valign="top"> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 101 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>0</entry> | ||
| 105 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry></entry> | ||
| 110 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 111 | <entry></entry><entry>C</entry><entry></entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>1</entry> | ||
| 115 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>2</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry></entry> | ||
| 128 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 129 | <entry></entry><entry>C</entry><entry></entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>3</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 134 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 135 | </row> | ||
| 136 | </tbody> | ||
| 137 | </tgroup> | ||
| 138 | </informaltable> | ||
| 139 | </para> | ||
| 140 | </formalpara> | ||
| 141 | </example> | ||
| 142 | </refsect1> | ||
| 143 | </refentry> | ||
| 144 | |||
| 145 | <!-- | ||
| 146 | Local Variables: | ||
| 147 | mode: sgml | ||
| 148 | sgml-parent-document: "pixfmt.sgml" | ||
| 149 | indent-tabs-mode: nil | ||
| 150 | End: | ||
| 151 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-nv16.xml b/Documentation/DocBook/v4l/pixfmt-nv16.xml new file mode 100644 index 000000000000..26094035fc04 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv16.xml | |||
| @@ -0,0 +1,174 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname> | ||
| 9 | <refpurpose>Formats with ½ horizontal | ||
| 10 | chroma resolution, also known as YUV 4:2:2. One luminance and one | ||
| 11 | chrominance plane with alternating chroma samples as opposed to | ||
| 12 | <constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | <refsect1> | ||
| 15 | <title>Description</title> | ||
| 16 | |||
| 17 | <para>These are two-plane versions of the YUV 4:2:2 format. | ||
| 18 | The three components are separated into two sub-images or planes. The | ||
| 19 | Y plane is first. The Y plane has one byte per pixel. For | ||
| 20 | <constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane | ||
| 21 | immediately follows the Y plane in memory. The CbCr plane is the same | ||
| 22 | width and height, in bytes, as the Y plane (and of the image). | ||
| 23 | Each CbCr pair belongs to two pixels. For example, | ||
| 24 | Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to | ||
| 25 | Y'<subscript>00</subscript>, Y'<subscript>01</subscript>. | ||
| 26 | <constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and | ||
| 27 | Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> | ||
| 28 | |||
| 29 | <para>If the Y plane has pad bytes after each row, then the | ||
| 30 | CbCr plane has as many pad bytes after its rows.</para> | ||
| 31 | |||
| 32 | <example> | ||
| 33 | <title><constant>V4L2_PIX_FMT_NV16</constant> 4 × 4 | ||
| 34 | pixel image</title> | ||
| 35 | |||
| 36 | <formalpara> | ||
| 37 | <title>Byte Order.</title> | ||
| 38 | <para>Each cell is one byte. | ||
| 39 | <informaltable frame="none"> | ||
| 40 | <tgroup cols="5" align="center"> | ||
| 41 | <colspec align="left" colwidth="2*" /> | ||
| 42 | <tbody valign="top"> | ||
| 43 | <row> | ||
| 44 | <entry>start + 0:</entry> | ||
| 45 | <entry>Y'<subscript>00</subscript></entry> | ||
| 46 | <entry>Y'<subscript>01</subscript></entry> | ||
| 47 | <entry>Y'<subscript>02</subscript></entry> | ||
| 48 | <entry>Y'<subscript>03</subscript></entry> | ||
| 49 | </row> | ||
| 50 | <row> | ||
| 51 | <entry>start + 4:</entry> | ||
| 52 | <entry>Y'<subscript>10</subscript></entry> | ||
| 53 | <entry>Y'<subscript>11</subscript></entry> | ||
| 54 | <entry>Y'<subscript>12</subscript></entry> | ||
| 55 | <entry>Y'<subscript>13</subscript></entry> | ||
| 56 | </row> | ||
| 57 | <row> | ||
| 58 | <entry>start + 8:</entry> | ||
| 59 | <entry>Y'<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | </row> | ||
| 64 | <row> | ||
| 65 | <entry>start + 12:</entry> | ||
| 66 | <entry>Y'<subscript>30</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31</subscript></entry> | ||
| 68 | <entry>Y'<subscript>32</subscript></entry> | ||
| 69 | <entry>Y'<subscript>33</subscript></entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>start + 16:</entry> | ||
| 73 | <entry>Cb<subscript>00</subscript></entry> | ||
| 74 | <entry>Cr<subscript>00</subscript></entry> | ||
| 75 | <entry>Cb<subscript>01</subscript></entry> | ||
| 76 | <entry>Cr<subscript>01</subscript></entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>start + 20:</entry> | ||
| 80 | <entry>Cb<subscript>10</subscript></entry> | ||
| 81 | <entry>Cr<subscript>10</subscript></entry> | ||
| 82 | <entry>Cb<subscript>11</subscript></entry> | ||
| 83 | <entry>Cr<subscript>11</subscript></entry> | ||
| 84 | </row> | ||
| 85 | <row> | ||
| 86 | <entry>start + 24:</entry> | ||
| 87 | <entry>Cb<subscript>20</subscript></entry> | ||
| 88 | <entry>Cr<subscript>20</subscript></entry> | ||
| 89 | <entry>Cb<subscript>21</subscript></entry> | ||
| 90 | <entry>Cr<subscript>21</subscript></entry> | ||
| 91 | </row> | ||
| 92 | <row> | ||
| 93 | <entry>start + 28:</entry> | ||
| 94 | <entry>Cb<subscript>30</subscript></entry> | ||
| 95 | <entry>Cr<subscript>30</subscript></entry> | ||
| 96 | <entry>Cb<subscript>31</subscript></entry> | ||
| 97 | <entry>Cr<subscript>31</subscript></entry> | ||
| 98 | </row> | ||
| 99 | </tbody> | ||
| 100 | </tgroup> | ||
| 101 | </informaltable> | ||
| 102 | </para> | ||
| 103 | </formalpara> | ||
| 104 | |||
| 105 | <formalpara> | ||
| 106 | <title>Color Sample Location.</title> | ||
| 107 | <para> | ||
| 108 | <informaltable frame="none"> | ||
| 109 | <tgroup cols="7" align="center"> | ||
| 110 | <tbody valign="top"> | ||
| 111 | <row> | ||
| 112 | <entry></entry> | ||
| 113 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 114 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>0</entry> | ||
| 118 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 119 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry></entry> | ||
| 123 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 124 | <entry></entry><entry>C</entry><entry></entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>1</entry> | ||
| 128 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 129 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry></entry> | ||
| 133 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 134 | <entry></entry><entry>C</entry><entry></entry> | ||
| 135 | </row> | ||
| 136 | <row> | ||
| 137 | <entry></entry> | ||
| 138 | </row> | ||
| 139 | <row> | ||
| 140 | <entry>2</entry> | ||
| 141 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 142 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry></entry> | ||
| 146 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 147 | <entry></entry><entry>C</entry><entry></entry> | ||
| 148 | </row> | ||
| 149 | <row> | ||
| 150 | <entry>3</entry> | ||
| 151 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 152 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry></entry> | ||
| 156 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 157 | <entry></entry><entry>C</entry><entry></entry> | ||
| 158 | </row> | ||
| 159 | </tbody> | ||
| 160 | </tgroup> | ||
| 161 | </informaltable> | ||
| 162 | </para> | ||
| 163 | </formalpara> | ||
| 164 | </example> | ||
| 165 | </refsect1> | ||
| 166 | </refentry> | ||
| 167 | |||
| 168 | <!-- | ||
| 169 | Local Variables: | ||
| 170 | mode: sgml | ||
| 171 | sgml-parent-document: "pixfmt.sgml" | ||
| 172 | indent-tabs-mode: nil | ||
| 173 | End: | ||
| 174 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml new file mode 100644 index 000000000000..d2dd697a81d8 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml | |||
| @@ -0,0 +1,862 @@ | |||
| 1 | <refentry id="packed-rgb"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>Packed RGB formats</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname>Packed RGB formats</refname> | ||
| 8 | <refpurpose>Packed RGB formats</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>These formats are designed to match the pixel formats of | ||
| 14 | typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits | ||
| 15 | per pixel. These are all packed-pixel formats, meaning all the data | ||
| 16 | for a pixel lie next to each other in memory.</para> | ||
| 17 | |||
| 18 | <para>When one of these formats is used, drivers shall report the | ||
| 19 | colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> | ||
| 20 | |||
| 21 | <table pgwide="1" frame="none" id="rgb-formats"> | ||
| 22 | <title>Packed RGB Image Formats</title> | ||
| 23 | <tgroup cols="37" align="center"> | ||
| 24 | <colspec colname="id" align="left" /> | ||
| 25 | <colspec colname="fourcc" /> | ||
| 26 | <colspec colname="bit" /> | ||
| 27 | |||
| 28 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 29 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 30 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 31 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 32 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 33 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 34 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 35 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 36 | |||
| 37 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 38 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 39 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 40 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 41 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 42 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 43 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 44 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 45 | |||
| 46 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 47 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 48 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 49 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 50 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 51 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 52 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 53 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 54 | |||
| 55 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 56 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 57 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 58 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 59 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 60 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 61 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 62 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 63 | |||
| 64 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 65 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 66 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 67 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 68 | <thead> | ||
| 69 | <row> | ||
| 70 | <entry>Identifier</entry> | ||
| 71 | <entry>Code</entry> | ||
| 72 | <entry> </entry> | ||
| 73 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 74 | <entry spanname="b1">Byte 1</entry> | ||
| 75 | <entry spanname="b2">Byte 2</entry> | ||
| 76 | <entry spanname="b3">Byte 3</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry> </entry> | ||
| 80 | <entry> </entry> | ||
| 81 | <entry>Bit</entry> | ||
| 82 | <entry>7</entry> | ||
| 83 | <entry>6</entry> | ||
| 84 | <entry>5</entry> | ||
| 85 | <entry>4</entry> | ||
| 86 | <entry>3</entry> | ||
| 87 | <entry>2</entry> | ||
| 88 | <entry>1</entry> | ||
| 89 | <entry>0</entry> | ||
| 90 | <entry> </entry> | ||
| 91 | <entry>7</entry> | ||
| 92 | <entry>6</entry> | ||
| 93 | <entry>5</entry> | ||
| 94 | <entry>4</entry> | ||
| 95 | <entry>3</entry> | ||
| 96 | <entry>2</entry> | ||
| 97 | <entry>1</entry> | ||
| 98 | <entry>0</entry> | ||
| 99 | <entry> </entry> | ||
| 100 | <entry>7</entry> | ||
| 101 | <entry>6</entry> | ||
| 102 | <entry>5</entry> | ||
| 103 | <entry>4</entry> | ||
| 104 | <entry>3</entry> | ||
| 105 | <entry>2</entry> | ||
| 106 | <entry>1</entry> | ||
| 107 | <entry>0</entry> | ||
| 108 | <entry> </entry> | ||
| 109 | <entry>7</entry> | ||
| 110 | <entry>6</entry> | ||
| 111 | <entry>5</entry> | ||
| 112 | <entry>4</entry> | ||
| 113 | <entry>3</entry> | ||
| 114 | <entry>2</entry> | ||
| 115 | <entry>1</entry> | ||
| 116 | <entry>0</entry> | ||
| 117 | </row> | ||
| 118 | </thead> | ||
| 119 | <tbody valign="top"> | ||
| 120 | <row id="V4L2-PIX-FMT-RGB332"> | ||
| 121 | <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> | ||
| 122 | <entry>'RGB1'</entry> | ||
| 123 | <entry></entry> | ||
| 124 | <entry>b<subscript>1</subscript></entry> | ||
| 125 | <entry>b<subscript>0</subscript></entry> | ||
| 126 | <entry>g<subscript>2</subscript></entry> | ||
| 127 | <entry>g<subscript>1</subscript></entry> | ||
| 128 | <entry>g<subscript>0</subscript></entry> | ||
| 129 | <entry>r<subscript>2</subscript></entry> | ||
| 130 | <entry>r<subscript>1</subscript></entry> | ||
| 131 | <entry>r<subscript>0</subscript></entry> | ||
| 132 | </row> | ||
| 133 | <row id="V4L2-PIX-FMT-RGB444"> | ||
| 134 | <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> | ||
| 135 | <entry>'R444'</entry> | ||
| 136 | <entry></entry> | ||
| 137 | <entry>g<subscript>3</subscript></entry> | ||
| 138 | <entry>g<subscript>2</subscript></entry> | ||
| 139 | <entry>g<subscript>1</subscript></entry> | ||
| 140 | <entry>g<subscript>0</subscript></entry> | ||
| 141 | <entry>b<subscript>3</subscript></entry> | ||
| 142 | <entry>b<subscript>2</subscript></entry> | ||
| 143 | <entry>b<subscript>1</subscript></entry> | ||
| 144 | <entry>b<subscript>0</subscript></entry> | ||
| 145 | <entry></entry> | ||
| 146 | <entry>a<subscript>3</subscript></entry> | ||
| 147 | <entry>a<subscript>2</subscript></entry> | ||
| 148 | <entry>a<subscript>1</subscript></entry> | ||
| 149 | <entry>a<subscript>0</subscript></entry> | ||
| 150 | <entry>r<subscript>3</subscript></entry> | ||
| 151 | <entry>r<subscript>2</subscript></entry> | ||
| 152 | <entry>r<subscript>1</subscript></entry> | ||
| 153 | <entry>r<subscript>0</subscript></entry> | ||
| 154 | </row> | ||
| 155 | <row id="V4L2-PIX-FMT-RGB555"> | ||
| 156 | <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> | ||
| 157 | <entry>'RGBO'</entry> | ||
| 158 | <entry></entry> | ||
| 159 | <entry>g<subscript>2</subscript></entry> | ||
| 160 | <entry>g<subscript>1</subscript></entry> | ||
| 161 | <entry>g<subscript>0</subscript></entry> | ||
| 162 | <entry>r<subscript>4</subscript></entry> | ||
| 163 | <entry>r<subscript>3</subscript></entry> | ||
| 164 | <entry>r<subscript>2</subscript></entry> | ||
| 165 | <entry>r<subscript>1</subscript></entry> | ||
| 166 | <entry>r<subscript>0</subscript></entry> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>a</entry> | ||
| 169 | <entry>b<subscript>4</subscript></entry> | ||
| 170 | <entry>b<subscript>3</subscript></entry> | ||
| 171 | <entry>b<subscript>2</subscript></entry> | ||
| 172 | <entry>b<subscript>1</subscript></entry> | ||
| 173 | <entry>b<subscript>0</subscript></entry> | ||
| 174 | <entry>g<subscript>4</subscript></entry> | ||
| 175 | <entry>g<subscript>3</subscript></entry> | ||
| 176 | </row> | ||
| 177 | <row id="V4L2-PIX-FMT-RGB565"> | ||
| 178 | <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> | ||
| 179 | <entry>'RGBP'</entry> | ||
| 180 | <entry></entry> | ||
| 181 | <entry>g<subscript>2</subscript></entry> | ||
| 182 | <entry>g<subscript>1</subscript></entry> | ||
| 183 | <entry>g<subscript>0</subscript></entry> | ||
| 184 | <entry>r<subscript>4</subscript></entry> | ||
| 185 | <entry>r<subscript>3</subscript></entry> | ||
| 186 | <entry>r<subscript>2</subscript></entry> | ||
| 187 | <entry>r<subscript>1</subscript></entry> | ||
| 188 | <entry>r<subscript>0</subscript></entry> | ||
| 189 | <entry></entry> | ||
| 190 | <entry>b<subscript>4</subscript></entry> | ||
| 191 | <entry>b<subscript>3</subscript></entry> | ||
| 192 | <entry>b<subscript>2</subscript></entry> | ||
| 193 | <entry>b<subscript>1</subscript></entry> | ||
| 194 | <entry>b<subscript>0</subscript></entry> | ||
| 195 | <entry>g<subscript>5</subscript></entry> | ||
| 196 | <entry>g<subscript>4</subscript></entry> | ||
| 197 | <entry>g<subscript>3</subscript></entry> | ||
| 198 | </row> | ||
| 199 | <row id="V4L2-PIX-FMT-RGB555X"> | ||
| 200 | <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> | ||
| 201 | <entry>'RGBQ'</entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>a</entry> | ||
| 204 | <entry>b<subscript>4</subscript></entry> | ||
| 205 | <entry>b<subscript>3</subscript></entry> | ||
| 206 | <entry>b<subscript>2</subscript></entry> | ||
| 207 | <entry>b<subscript>1</subscript></entry> | ||
| 208 | <entry>b<subscript>0</subscript></entry> | ||
| 209 | <entry>g<subscript>4</subscript></entry> | ||
| 210 | <entry>g<subscript>3</subscript></entry> | ||
| 211 | <entry></entry> | ||
| 212 | <entry>g<subscript>2</subscript></entry> | ||
| 213 | <entry>g<subscript>1</subscript></entry> | ||
| 214 | <entry>g<subscript>0</subscript></entry> | ||
| 215 | <entry>r<subscript>4</subscript></entry> | ||
| 216 | <entry>r<subscript>3</subscript></entry> | ||
| 217 | <entry>r<subscript>2</subscript></entry> | ||
| 218 | <entry>r<subscript>1</subscript></entry> | ||
| 219 | <entry>r<subscript>0</subscript></entry> | ||
| 220 | </row> | ||
| 221 | <row id="V4L2-PIX-FMT-RGB565X"> | ||
| 222 | <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> | ||
| 223 | <entry>'RGBR'</entry> | ||
| 224 | <entry></entry> | ||
| 225 | <entry>b<subscript>4</subscript></entry> | ||
| 226 | <entry>b<subscript>3</subscript></entry> | ||
| 227 | <entry>b<subscript>2</subscript></entry> | ||
| 228 | <entry>b<subscript>1</subscript></entry> | ||
| 229 | <entry>b<subscript>0</subscript></entry> | ||
| 230 | <entry>g<subscript>5</subscript></entry> | ||
| 231 | <entry>g<subscript>4</subscript></entry> | ||
| 232 | <entry>g<subscript>3</subscript></entry> | ||
| 233 | <entry></entry> | ||
| 234 | <entry>g<subscript>2</subscript></entry> | ||
| 235 | <entry>g<subscript>1</subscript></entry> | ||
| 236 | <entry>g<subscript>0</subscript></entry> | ||
| 237 | <entry>r<subscript>4</subscript></entry> | ||
| 238 | <entry>r<subscript>3</subscript></entry> | ||
| 239 | <entry>r<subscript>2</subscript></entry> | ||
| 240 | <entry>r<subscript>1</subscript></entry> | ||
| 241 | <entry>r<subscript>0</subscript></entry> | ||
| 242 | </row> | ||
| 243 | <row id="V4L2-PIX-FMT-BGR24"> | ||
| 244 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 245 | <entry>'BGR3'</entry> | ||
| 246 | <entry></entry> | ||
| 247 | <entry>b<subscript>7</subscript></entry> | ||
| 248 | <entry>b<subscript>6</subscript></entry> | ||
| 249 | <entry>b<subscript>5</subscript></entry> | ||
| 250 | <entry>b<subscript>4</subscript></entry> | ||
| 251 | <entry>b<subscript>3</subscript></entry> | ||
| 252 | <entry>b<subscript>2</subscript></entry> | ||
| 253 | <entry>b<subscript>1</subscript></entry> | ||
| 254 | <entry>b<subscript>0</subscript></entry> | ||
| 255 | <entry></entry> | ||
| 256 | <entry>g<subscript>7</subscript></entry> | ||
| 257 | <entry>g<subscript>6</subscript></entry> | ||
| 258 | <entry>g<subscript>5</subscript></entry> | ||
| 259 | <entry>g<subscript>4</subscript></entry> | ||
| 260 | <entry>g<subscript>3</subscript></entry> | ||
| 261 | <entry>g<subscript>2</subscript></entry> | ||
| 262 | <entry>g<subscript>1</subscript></entry> | ||
| 263 | <entry>g<subscript>0</subscript></entry> | ||
| 264 | <entry></entry> | ||
| 265 | <entry>r<subscript>7</subscript></entry> | ||
| 266 | <entry>r<subscript>6</subscript></entry> | ||
| 267 | <entry>r<subscript>5</subscript></entry> | ||
| 268 | <entry>r<subscript>4</subscript></entry> | ||
| 269 | <entry>r<subscript>3</subscript></entry> | ||
| 270 | <entry>r<subscript>2</subscript></entry> | ||
| 271 | <entry>r<subscript>1</subscript></entry> | ||
| 272 | <entry>r<subscript>0</subscript></entry> | ||
| 273 | </row> | ||
| 274 | <row id="V4L2-PIX-FMT-RGB24"> | ||
| 275 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 276 | <entry>'RGB3'</entry> | ||
| 277 | <entry></entry> | ||
| 278 | <entry>r<subscript>7</subscript></entry> | ||
| 279 | <entry>r<subscript>6</subscript></entry> | ||
| 280 | <entry>r<subscript>5</subscript></entry> | ||
| 281 | <entry>r<subscript>4</subscript></entry> | ||
| 282 | <entry>r<subscript>3</subscript></entry> | ||
| 283 | <entry>r<subscript>2</subscript></entry> | ||
| 284 | <entry>r<subscript>1</subscript></entry> | ||
| 285 | <entry>r<subscript>0</subscript></entry> | ||
| 286 | <entry></entry> | ||
| 287 | <entry>g<subscript>7</subscript></entry> | ||
| 288 | <entry>g<subscript>6</subscript></entry> | ||
| 289 | <entry>g<subscript>5</subscript></entry> | ||
| 290 | <entry>g<subscript>4</subscript></entry> | ||
| 291 | <entry>g<subscript>3</subscript></entry> | ||
| 292 | <entry>g<subscript>2</subscript></entry> | ||
| 293 | <entry>g<subscript>1</subscript></entry> | ||
| 294 | <entry>g<subscript>0</subscript></entry> | ||
| 295 | <entry></entry> | ||
| 296 | <entry>b<subscript>7</subscript></entry> | ||
| 297 | <entry>b<subscript>6</subscript></entry> | ||
| 298 | <entry>b<subscript>5</subscript></entry> | ||
| 299 | <entry>b<subscript>4</subscript></entry> | ||
| 300 | <entry>b<subscript>3</subscript></entry> | ||
| 301 | <entry>b<subscript>2</subscript></entry> | ||
| 302 | <entry>b<subscript>1</subscript></entry> | ||
| 303 | <entry>b<subscript>0</subscript></entry> | ||
| 304 | </row> | ||
| 305 | <row id="V4L2-PIX-FMT-BGR32"> | ||
| 306 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 307 | <entry>'BGR4'</entry> | ||
| 308 | <entry></entry> | ||
| 309 | <entry>b<subscript>7</subscript></entry> | ||
| 310 | <entry>b<subscript>6</subscript></entry> | ||
| 311 | <entry>b<subscript>5</subscript></entry> | ||
| 312 | <entry>b<subscript>4</subscript></entry> | ||
| 313 | <entry>b<subscript>3</subscript></entry> | ||
| 314 | <entry>b<subscript>2</subscript></entry> | ||
| 315 | <entry>b<subscript>1</subscript></entry> | ||
| 316 | <entry>b<subscript>0</subscript></entry> | ||
| 317 | <entry></entry> | ||
| 318 | <entry>g<subscript>7</subscript></entry> | ||
| 319 | <entry>g<subscript>6</subscript></entry> | ||
| 320 | <entry>g<subscript>5</subscript></entry> | ||
| 321 | <entry>g<subscript>4</subscript></entry> | ||
| 322 | <entry>g<subscript>3</subscript></entry> | ||
| 323 | <entry>g<subscript>2</subscript></entry> | ||
| 324 | <entry>g<subscript>1</subscript></entry> | ||
| 325 | <entry>g<subscript>0</subscript></entry> | ||
| 326 | <entry></entry> | ||
| 327 | <entry>r<subscript>7</subscript></entry> | ||
| 328 | <entry>r<subscript>6</subscript></entry> | ||
| 329 | <entry>r<subscript>5</subscript></entry> | ||
| 330 | <entry>r<subscript>4</subscript></entry> | ||
| 331 | <entry>r<subscript>3</subscript></entry> | ||
| 332 | <entry>r<subscript>2</subscript></entry> | ||
| 333 | <entry>r<subscript>1</subscript></entry> | ||
| 334 | <entry>r<subscript>0</subscript></entry> | ||
| 335 | <entry></entry> | ||
| 336 | <entry>a<subscript>7</subscript></entry> | ||
| 337 | <entry>a<subscript>6</subscript></entry> | ||
| 338 | <entry>a<subscript>5</subscript></entry> | ||
| 339 | <entry>a<subscript>4</subscript></entry> | ||
| 340 | <entry>a<subscript>3</subscript></entry> | ||
| 341 | <entry>a<subscript>2</subscript></entry> | ||
| 342 | <entry>a<subscript>1</subscript></entry> | ||
| 343 | <entry>a<subscript>0</subscript></entry> | ||
| 344 | </row> | ||
| 345 | <row id="V4L2-PIX-FMT-RGB32"> | ||
| 346 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 347 | <entry>'RGB4'</entry> | ||
| 348 | <entry></entry> | ||
| 349 | <entry>r<subscript>7</subscript></entry> | ||
| 350 | <entry>r<subscript>6</subscript></entry> | ||
| 351 | <entry>r<subscript>5</subscript></entry> | ||
| 352 | <entry>r<subscript>4</subscript></entry> | ||
| 353 | <entry>r<subscript>3</subscript></entry> | ||
| 354 | <entry>r<subscript>2</subscript></entry> | ||
| 355 | <entry>r<subscript>1</subscript></entry> | ||
| 356 | <entry>r<subscript>0</subscript></entry> | ||
| 357 | <entry></entry> | ||
| 358 | <entry>g<subscript>7</subscript></entry> | ||
| 359 | <entry>g<subscript>6</subscript></entry> | ||
| 360 | <entry>g<subscript>5</subscript></entry> | ||
| 361 | <entry>g<subscript>4</subscript></entry> | ||
| 362 | <entry>g<subscript>3</subscript></entry> | ||
| 363 | <entry>g<subscript>2</subscript></entry> | ||
| 364 | <entry>g<subscript>1</subscript></entry> | ||
| 365 | <entry>g<subscript>0</subscript></entry> | ||
| 366 | <entry></entry> | ||
| 367 | <entry>b<subscript>7</subscript></entry> | ||
| 368 | <entry>b<subscript>6</subscript></entry> | ||
| 369 | <entry>b<subscript>5</subscript></entry> | ||
| 370 | <entry>b<subscript>4</subscript></entry> | ||
| 371 | <entry>b<subscript>3</subscript></entry> | ||
| 372 | <entry>b<subscript>2</subscript></entry> | ||
| 373 | <entry>b<subscript>1</subscript></entry> | ||
| 374 | <entry>b<subscript>0</subscript></entry> | ||
| 375 | <entry></entry> | ||
| 376 | <entry>a<subscript>7</subscript></entry> | ||
| 377 | <entry>a<subscript>6</subscript></entry> | ||
| 378 | <entry>a<subscript>5</subscript></entry> | ||
| 379 | <entry>a<subscript>4</subscript></entry> | ||
| 380 | <entry>a<subscript>3</subscript></entry> | ||
| 381 | <entry>a<subscript>2</subscript></entry> | ||
| 382 | <entry>a<subscript>1</subscript></entry> | ||
| 383 | <entry>a<subscript>0</subscript></entry> | ||
| 384 | </row> | ||
| 385 | </tbody> | ||
| 386 | </tgroup> | ||
| 387 | </table> | ||
| 388 | |||
| 389 | <para>Bit 7 is the most significant bit. The value of a = alpha | ||
| 390 | bits is undefined when reading from the driver, ignored when writing | ||
| 391 | to the driver, except when alpha blending has been negotiated for a | ||
| 392 | <link linkend="overlay">Video Overlay</link> or <link | ||
| 393 | linkend="osd">Video Output Overlay</link>.</para> | ||
| 394 | |||
| 395 | <example> | ||
| 396 | <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 × 4 pixel | ||
| 397 | image</title> | ||
| 398 | |||
| 399 | <formalpara> | ||
| 400 | <title>Byte Order.</title> | ||
| 401 | <para>Each cell is one byte. | ||
| 402 | <informaltable frame="none"> | ||
| 403 | <tgroup cols="13" align="center"> | ||
| 404 | <colspec align="left" colwidth="2*" /> | ||
| 405 | <tbody valign="top"> | ||
| 406 | <row> | ||
| 407 | <entry>start + 0:</entry> | ||
| 408 | <entry>B<subscript>00</subscript></entry> | ||
| 409 | <entry>G<subscript>00</subscript></entry> | ||
| 410 | <entry>R<subscript>00</subscript></entry> | ||
| 411 | <entry>B<subscript>01</subscript></entry> | ||
| 412 | <entry>G<subscript>01</subscript></entry> | ||
| 413 | <entry>R<subscript>01</subscript></entry> | ||
| 414 | <entry>B<subscript>02</subscript></entry> | ||
| 415 | <entry>G<subscript>02</subscript></entry> | ||
| 416 | <entry>R<subscript>02</subscript></entry> | ||
| 417 | <entry>B<subscript>03</subscript></entry> | ||
| 418 | <entry>G<subscript>03</subscript></entry> | ||
| 419 | <entry>R<subscript>03</subscript></entry> | ||
| 420 | </row> | ||
| 421 | <row> | ||
| 422 | <entry>start + 12:</entry> | ||
| 423 | <entry>B<subscript>10</subscript></entry> | ||
| 424 | <entry>G<subscript>10</subscript></entry> | ||
| 425 | <entry>R<subscript>10</subscript></entry> | ||
| 426 | <entry>B<subscript>11</subscript></entry> | ||
| 427 | <entry>G<subscript>11</subscript></entry> | ||
| 428 | <entry>R<subscript>11</subscript></entry> | ||
| 429 | <entry>B<subscript>12</subscript></entry> | ||
| 430 | <entry>G<subscript>12</subscript></entry> | ||
| 431 | <entry>R<subscript>12</subscript></entry> | ||
| 432 | <entry>B<subscript>13</subscript></entry> | ||
| 433 | <entry>G<subscript>13</subscript></entry> | ||
| 434 | <entry>R<subscript>13</subscript></entry> | ||
| 435 | </row> | ||
| 436 | <row> | ||
| 437 | <entry>start + 24:</entry> | ||
| 438 | <entry>B<subscript>20</subscript></entry> | ||
| 439 | <entry>G<subscript>20</subscript></entry> | ||
| 440 | <entry>R<subscript>20</subscript></entry> | ||
| 441 | <entry>B<subscript>21</subscript></entry> | ||
| 442 | <entry>G<subscript>21</subscript></entry> | ||
| 443 | <entry>R<subscript>21</subscript></entry> | ||
| 444 | <entry>B<subscript>22</subscript></entry> | ||
| 445 | <entry>G<subscript>22</subscript></entry> | ||
| 446 | <entry>R<subscript>22</subscript></entry> | ||
| 447 | <entry>B<subscript>23</subscript></entry> | ||
| 448 | <entry>G<subscript>23</subscript></entry> | ||
| 449 | <entry>R<subscript>23</subscript></entry> | ||
| 450 | </row> | ||
| 451 | <row> | ||
| 452 | <entry>start + 36:</entry> | ||
| 453 | <entry>B<subscript>30</subscript></entry> | ||
| 454 | <entry>G<subscript>30</subscript></entry> | ||
| 455 | <entry>R<subscript>30</subscript></entry> | ||
| 456 | <entry>B<subscript>31</subscript></entry> | ||
| 457 | <entry>G<subscript>31</subscript></entry> | ||
| 458 | <entry>R<subscript>31</subscript></entry> | ||
| 459 | <entry>B<subscript>32</subscript></entry> | ||
| 460 | <entry>G<subscript>32</subscript></entry> | ||
| 461 | <entry>R<subscript>32</subscript></entry> | ||
| 462 | <entry>B<subscript>33</subscript></entry> | ||
| 463 | <entry>G<subscript>33</subscript></entry> | ||
| 464 | <entry>R<subscript>33</subscript></entry> | ||
| 465 | </row> | ||
| 466 | </tbody> | ||
| 467 | </tgroup> | ||
| 468 | </informaltable> | ||
| 469 | </para> | ||
| 470 | </formalpara> | ||
| 471 | </example> | ||
| 472 | |||
| 473 | <important> | ||
| 474 | <para>Drivers may interpret these formats differently.</para> | ||
| 475 | </important> | ||
| 476 | |||
| 477 | <para>Some RGB formats above are uncommon and were probably | ||
| 478 | defined in error. Drivers may interpret them as in <xref | ||
| 479 | linkend="rgb-formats-corrected" />.</para> | ||
| 480 | |||
| 481 | <table pgwide="1" frame="none" id="rgb-formats-corrected"> | ||
| 482 | <title>Packed RGB Image Formats (corrected)</title> | ||
| 483 | <tgroup cols="37" align="center"> | ||
| 484 | <colspec colname="id" align="left" /> | ||
| 485 | <colspec colname="fourcc" /> | ||
| 486 | <colspec colname="bit" /> | ||
| 487 | |||
| 488 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 489 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 490 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 491 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 492 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 493 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 494 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 495 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 496 | |||
| 497 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 498 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 499 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 500 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 501 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 502 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 503 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 504 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 505 | |||
| 506 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 507 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 508 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 509 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 510 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 511 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 512 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 513 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 514 | |||
| 515 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 516 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 517 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 518 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 519 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 520 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 521 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 522 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 523 | |||
| 524 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 525 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 526 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 527 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 528 | <thead> | ||
| 529 | <row> | ||
| 530 | <entry>Identifier</entry> | ||
| 531 | <entry>Code</entry> | ||
| 532 | <entry> </entry> | ||
| 533 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 534 | <entry spanname="b1">Byte 1</entry> | ||
| 535 | <entry spanname="b2">Byte 2</entry> | ||
| 536 | <entry spanname="b3">Byte 3</entry> | ||
| 537 | </row> | ||
| 538 | <row> | ||
| 539 | <entry> </entry> | ||
| 540 | <entry> </entry> | ||
| 541 | <entry>Bit</entry> | ||
| 542 | <entry>7</entry> | ||
| 543 | <entry>6</entry> | ||
| 544 | <entry>5</entry> | ||
| 545 | <entry>4</entry> | ||
| 546 | <entry>3</entry> | ||
| 547 | <entry>2</entry> | ||
| 548 | <entry>1</entry> | ||
| 549 | <entry>0</entry> | ||
| 550 | <entry> </entry> | ||
| 551 | <entry>7</entry> | ||
| 552 | <entry>6</entry> | ||
| 553 | <entry>5</entry> | ||
| 554 | <entry>4</entry> | ||
| 555 | <entry>3</entry> | ||
| 556 | <entry>2</entry> | ||
| 557 | <entry>1</entry> | ||
| 558 | <entry>0</entry> | ||
| 559 | <entry> </entry> | ||
| 560 | <entry>7</entry> | ||
| 561 | <entry>6</entry> | ||
| 562 | <entry>5</entry> | ||
| 563 | <entry>4</entry> | ||
| 564 | <entry>3</entry> | ||
| 565 | <entry>2</entry> | ||
| 566 | <entry>1</entry> | ||
| 567 | <entry>0</entry> | ||
| 568 | <entry> </entry> | ||
| 569 | <entry>7</entry> | ||
| 570 | <entry>6</entry> | ||
| 571 | <entry>5</entry> | ||
| 572 | <entry>4</entry> | ||
| 573 | <entry>3</entry> | ||
| 574 | <entry>2</entry> | ||
| 575 | <entry>1</entry> | ||
| 576 | <entry>0</entry> | ||
| 577 | </row> | ||
| 578 | </thead> | ||
| 579 | <tbody valign="top"> | ||
| 580 | <row><!-- id="V4L2-PIX-FMT-RGB332" --> | ||
| 581 | <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> | ||
| 582 | <entry>'RGB1'</entry> | ||
| 583 | <entry></entry> | ||
| 584 | <entry>r<subscript>2</subscript></entry> | ||
| 585 | <entry>r<subscript>1</subscript></entry> | ||
| 586 | <entry>r<subscript>0</subscript></entry> | ||
| 587 | <entry>g<subscript>2</subscript></entry> | ||
| 588 | <entry>g<subscript>1</subscript></entry> | ||
| 589 | <entry>g<subscript>0</subscript></entry> | ||
| 590 | <entry>b<subscript>1</subscript></entry> | ||
| 591 | <entry>b<subscript>0</subscript></entry> | ||
| 592 | </row> | ||
| 593 | <row><!-- id="V4L2-PIX-FMT-RGB444" --> | ||
| 594 | <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> | ||
| 595 | <entry>'R444'</entry> | ||
| 596 | <entry></entry> | ||
| 597 | <entry>g<subscript>3</subscript></entry> | ||
| 598 | <entry>g<subscript>2</subscript></entry> | ||
| 599 | <entry>g<subscript>1</subscript></entry> | ||
| 600 | <entry>g<subscript>0</subscript></entry> | ||
| 601 | <entry>b<subscript>3</subscript></entry> | ||
| 602 | <entry>b<subscript>2</subscript></entry> | ||
| 603 | <entry>b<subscript>1</subscript></entry> | ||
| 604 | <entry>b<subscript>0</subscript></entry> | ||
| 605 | <entry></entry> | ||
| 606 | <entry>a<subscript>3</subscript></entry> | ||
| 607 | <entry>a<subscript>2</subscript></entry> | ||
| 608 | <entry>a<subscript>1</subscript></entry> | ||
| 609 | <entry>a<subscript>0</subscript></entry> | ||
| 610 | <entry>r<subscript>3</subscript></entry> | ||
| 611 | <entry>r<subscript>2</subscript></entry> | ||
| 612 | <entry>r<subscript>1</subscript></entry> | ||
| 613 | <entry>r<subscript>0</subscript></entry> | ||
| 614 | </row> | ||
| 615 | <row><!-- id="V4L2-PIX-FMT-RGB555" --> | ||
| 616 | <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> | ||
| 617 | <entry>'RGBO'</entry> | ||
| 618 | <entry></entry> | ||
| 619 | <entry>g<subscript>2</subscript></entry> | ||
| 620 | <entry>g<subscript>1</subscript></entry> | ||
| 621 | <entry>g<subscript>0</subscript></entry> | ||
| 622 | <entry>b<subscript>4</subscript></entry> | ||
| 623 | <entry>b<subscript>3</subscript></entry> | ||
| 624 | <entry>b<subscript>2</subscript></entry> | ||
| 625 | <entry>b<subscript>1</subscript></entry> | ||
| 626 | <entry>b<subscript>0</subscript></entry> | ||
| 627 | <entry></entry> | ||
| 628 | <entry>a</entry> | ||
| 629 | <entry>r<subscript>4</subscript></entry> | ||
| 630 | <entry>r<subscript>3</subscript></entry> | ||
| 631 | <entry>r<subscript>2</subscript></entry> | ||
| 632 | <entry>r<subscript>1</subscript></entry> | ||
| 633 | <entry>r<subscript>0</subscript></entry> | ||
| 634 | <entry>g<subscript>4</subscript></entry> | ||
| 635 | <entry>g<subscript>3</subscript></entry> | ||
| 636 | </row> | ||
| 637 | <row><!-- id="V4L2-PIX-FMT-RGB565" --> | ||
| 638 | <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> | ||
| 639 | <entry>'RGBP'</entry> | ||
| 640 | <entry></entry> | ||
| 641 | <entry>g<subscript>2</subscript></entry> | ||
| 642 | <entry>g<subscript>1</subscript></entry> | ||
| 643 | <entry>g<subscript>0</subscript></entry> | ||
| 644 | <entry>b<subscript>4</subscript></entry> | ||
| 645 | <entry>b<subscript>3</subscript></entry> | ||
| 646 | <entry>b<subscript>2</subscript></entry> | ||
| 647 | <entry>b<subscript>1</subscript></entry> | ||
| 648 | <entry>b<subscript>0</subscript></entry> | ||
| 649 | <entry></entry> | ||
| 650 | <entry>r<subscript>4</subscript></entry> | ||
| 651 | <entry>r<subscript>3</subscript></entry> | ||
| 652 | <entry>r<subscript>2</subscript></entry> | ||
| 653 | <entry>r<subscript>1</subscript></entry> | ||
| 654 | <entry>r<subscript>0</subscript></entry> | ||
| 655 | <entry>g<subscript>5</subscript></entry> | ||
| 656 | <entry>g<subscript>4</subscript></entry> | ||
| 657 | <entry>g<subscript>3</subscript></entry> | ||
| 658 | </row> | ||
| 659 | <row><!-- id="V4L2-PIX-FMT-RGB555X" --> | ||
| 660 | <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> | ||
| 661 | <entry>'RGBQ'</entry> | ||
| 662 | <entry></entry> | ||
| 663 | <entry>a</entry> | ||
| 664 | <entry>r<subscript>4</subscript></entry> | ||
| 665 | <entry>r<subscript>3</subscript></entry> | ||
| 666 | <entry>r<subscript>2</subscript></entry> | ||
| 667 | <entry>r<subscript>1</subscript></entry> | ||
| 668 | <entry>r<subscript>0</subscript></entry> | ||
| 669 | <entry>g<subscript>4</subscript></entry> | ||
| 670 | <entry>g<subscript>3</subscript></entry> | ||
| 671 | <entry></entry> | ||
| 672 | <entry>g<subscript>2</subscript></entry> | ||
| 673 | <entry>g<subscript>1</subscript></entry> | ||
| 674 | <entry>g<subscript>0</subscript></entry> | ||
| 675 | <entry>b<subscript>4</subscript></entry> | ||
| 676 | <entry>b<subscript>3</subscript></entry> | ||
| 677 | <entry>b<subscript>2</subscript></entry> | ||
| 678 | <entry>b<subscript>1</subscript></entry> | ||
| 679 | <entry>b<subscript>0</subscript></entry> | ||
| 680 | </row> | ||
| 681 | <row><!-- id="V4L2-PIX-FMT-RGB565X" --> | ||
| 682 | <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> | ||
| 683 | <entry>'RGBR'</entry> | ||
| 684 | <entry></entry> | ||
| 685 | <entry>r<subscript>4</subscript></entry> | ||
| 686 | <entry>r<subscript>3</subscript></entry> | ||
| 687 | <entry>r<subscript>2</subscript></entry> | ||
| 688 | <entry>r<subscript>1</subscript></entry> | ||
| 689 | <entry>r<subscript>0</subscript></entry> | ||
| 690 | <entry>g<subscript>5</subscript></entry> | ||
| 691 | <entry>g<subscript>4</subscript></entry> | ||
| 692 | <entry>g<subscript>3</subscript></entry> | ||
| 693 | <entry></entry> | ||
| 694 | <entry>g<subscript>2</subscript></entry> | ||
| 695 | <entry>g<subscript>1</subscript></entry> | ||
| 696 | <entry>g<subscript>0</subscript></entry> | ||
| 697 | <entry>b<subscript>4</subscript></entry> | ||
| 698 | <entry>b<subscript>3</subscript></entry> | ||
| 699 | <entry>b<subscript>2</subscript></entry> | ||
| 700 | <entry>b<subscript>1</subscript></entry> | ||
| 701 | <entry>b<subscript>0</subscript></entry> | ||
| 702 | </row> | ||
| 703 | <row><!-- id="V4L2-PIX-FMT-BGR24" --> | ||
| 704 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 705 | <entry>'BGR3'</entry> | ||
| 706 | <entry></entry> | ||
| 707 | <entry>b<subscript>7</subscript></entry> | ||
| 708 | <entry>b<subscript>6</subscript></entry> | ||
| 709 | <entry>b<subscript>5</subscript></entry> | ||
| 710 | <entry>b<subscript>4</subscript></entry> | ||
| 711 | <entry>b<subscript>3</subscript></entry> | ||
| 712 | <entry>b<subscript>2</subscript></entry> | ||
| 713 | <entry>b<subscript>1</subscript></entry> | ||
| 714 | <entry>b<subscript>0</subscript></entry> | ||
| 715 | <entry></entry> | ||
| 716 | <entry>g<subscript>7</subscript></entry> | ||
| 717 | <entry>g<subscript>6</subscript></entry> | ||
| 718 | <entry>g<subscript>5</subscript></entry> | ||
| 719 | <entry>g<subscript>4</subscript></entry> | ||
| 720 | <entry>g<subscript>3</subscript></entry> | ||
| 721 | <entry>g<subscript>2</subscript></entry> | ||
| 722 | <entry>g<subscript>1</subscript></entry> | ||
| 723 | <entry>g<subscript>0</subscript></entry> | ||
| 724 | <entry></entry> | ||
| 725 | <entry>r<subscript>7</subscript></entry> | ||
| 726 | <entry>r<subscript>6</subscript></entry> | ||
| 727 | <entry>r<subscript>5</subscript></entry> | ||
| 728 | <entry>r<subscript>4</subscript></entry> | ||
| 729 | <entry>r<subscript>3</subscript></entry> | ||
| 730 | <entry>r<subscript>2</subscript></entry> | ||
| 731 | <entry>r<subscript>1</subscript></entry> | ||
| 732 | <entry>r<subscript>0</subscript></entry> | ||
| 733 | </row> | ||
| 734 | <row><!-- id="V4L2-PIX-FMT-RGB24" --> | ||
| 735 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 736 | <entry>'RGB3'</entry> | ||
| 737 | <entry></entry> | ||
| 738 | <entry>r<subscript>7</subscript></entry> | ||
| 739 | <entry>r<subscript>6</subscript></entry> | ||
| 740 | <entry>r<subscript>5</subscript></entry> | ||
| 741 | <entry>r<subscript>4</subscript></entry> | ||
| 742 | <entry>r<subscript>3</subscript></entry> | ||
| 743 | <entry>r<subscript>2</subscript></entry> | ||
| 744 | <entry>r<subscript>1</subscript></entry> | ||
| 745 | <entry>r<subscript>0</subscript></entry> | ||
| 746 | <entry></entry> | ||
| 747 | <entry>g<subscript>7</subscript></entry> | ||
| 748 | <entry>g<subscript>6</subscript></entry> | ||
| 749 | <entry>g<subscript>5</subscript></entry> | ||
| 750 | <entry>g<subscript>4</subscript></entry> | ||
| 751 | <entry>g<subscript>3</subscript></entry> | ||
| 752 | <entry>g<subscript>2</subscript></entry> | ||
| 753 | <entry>g<subscript>1</subscript></entry> | ||
| 754 | <entry>g<subscript>0</subscript></entry> | ||
| 755 | <entry></entry> | ||
| 756 | <entry>b<subscript>7</subscript></entry> | ||
| 757 | <entry>b<subscript>6</subscript></entry> | ||
| 758 | <entry>b<subscript>5</subscript></entry> | ||
| 759 | <entry>b<subscript>4</subscript></entry> | ||
| 760 | <entry>b<subscript>3</subscript></entry> | ||
| 761 | <entry>b<subscript>2</subscript></entry> | ||
| 762 | <entry>b<subscript>1</subscript></entry> | ||
| 763 | <entry>b<subscript>0</subscript></entry> | ||
| 764 | </row> | ||
| 765 | <row><!-- id="V4L2-PIX-FMT-BGR32" --> | ||
| 766 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 767 | <entry>'BGR4'</entry> | ||
| 768 | <entry></entry> | ||
| 769 | <entry>b<subscript>7</subscript></entry> | ||
| 770 | <entry>b<subscript>6</subscript></entry> | ||
| 771 | <entry>b<subscript>5</subscript></entry> | ||
| 772 | <entry>b<subscript>4</subscript></entry> | ||
| 773 | <entry>b<subscript>3</subscript></entry> | ||
| 774 | <entry>b<subscript>2</subscript></entry> | ||
| 775 | <entry>b<subscript>1</subscript></entry> | ||
| 776 | <entry>b<subscript>0</subscript></entry> | ||
| 777 | <entry></entry> | ||
| 778 | <entry>g<subscript>7</subscript></entry> | ||
| 779 | <entry>g<subscript>6</subscript></entry> | ||
| 780 | <entry>g<subscript>5</subscript></entry> | ||
| 781 | <entry>g<subscript>4</subscript></entry> | ||
| 782 | <entry>g<subscript>3</subscript></entry> | ||
| 783 | <entry>g<subscript>2</subscript></entry> | ||
| 784 | <entry>g<subscript>1</subscript></entry> | ||
| 785 | <entry>g<subscript>0</subscript></entry> | ||
| 786 | <entry></entry> | ||
| 787 | <entry>r<subscript>7</subscript></entry> | ||
| 788 | <entry>r<subscript>6</subscript></entry> | ||
| 789 | <entry>r<subscript>5</subscript></entry> | ||
| 790 | <entry>r<subscript>4</subscript></entry> | ||
| 791 | <entry>r<subscript>3</subscript></entry> | ||
| 792 | <entry>r<subscript>2</subscript></entry> | ||
| 793 | <entry>r<subscript>1</subscript></entry> | ||
| 794 | <entry>r<subscript>0</subscript></entry> | ||
| 795 | <entry></entry> | ||
| 796 | <entry>a<subscript>7</subscript></entry> | ||
| 797 | <entry>a<subscript>6</subscript></entry> | ||
| 798 | <entry>a<subscript>5</subscript></entry> | ||
| 799 | <entry>a<subscript>4</subscript></entry> | ||
| 800 | <entry>a<subscript>3</subscript></entry> | ||
| 801 | <entry>a<subscript>2</subscript></entry> | ||
| 802 | <entry>a<subscript>1</subscript></entry> | ||
| 803 | <entry>a<subscript>0</subscript></entry> | ||
| 804 | </row> | ||
| 805 | <row><!-- id="V4L2-PIX-FMT-RGB32" --> | ||
| 806 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 807 | <entry>'RGB4'</entry> | ||
| 808 | <entry></entry> | ||
| 809 | <entry>a<subscript>7</subscript></entry> | ||
| 810 | <entry>a<subscript>6</subscript></entry> | ||
| 811 | <entry>a<subscript>5</subscript></entry> | ||
| 812 | <entry>a<subscript>4</subscript></entry> | ||
| 813 | <entry>a<subscript>3</subscript></entry> | ||
| 814 | <entry>a<subscript>2</subscript></entry> | ||
| 815 | <entry>a<subscript>1</subscript></entry> | ||
| 816 | <entry>a<subscript>0</subscript></entry> | ||
| 817 | <entry></entry> | ||
| 818 | <entry>r<subscript>7</subscript></entry> | ||
| 819 | <entry>r<subscript>6</subscript></entry> | ||
| 820 | <entry>r<subscript>5</subscript></entry> | ||
| 821 | <entry>r<subscript>4</subscript></entry> | ||
| 822 | <entry>r<subscript>3</subscript></entry> | ||
| 823 | <entry>r<subscript>2</subscript></entry> | ||
| 824 | <entry>r<subscript>1</subscript></entry> | ||
| 825 | <entry>r<subscript>0</subscript></entry> | ||
| 826 | <entry></entry> | ||
| 827 | <entry>g<subscript>7</subscript></entry> | ||
| 828 | <entry>g<subscript>6</subscript></entry> | ||
| 829 | <entry>g<subscript>5</subscript></entry> | ||
| 830 | <entry>g<subscript>4</subscript></entry> | ||
| 831 | <entry>g<subscript>3</subscript></entry> | ||
| 832 | <entry>g<subscript>2</subscript></entry> | ||
| 833 | <entry>g<subscript>1</subscript></entry> | ||
| 834 | <entry>g<subscript>0</subscript></entry> | ||
| 835 | <entry></entry> | ||
| 836 | <entry>b<subscript>7</subscript></entry> | ||
| 837 | <entry>b<subscript>6</subscript></entry> | ||
| 838 | <entry>b<subscript>5</subscript></entry> | ||
| 839 | <entry>b<subscript>4</subscript></entry> | ||
| 840 | <entry>b<subscript>3</subscript></entry> | ||
| 841 | <entry>b<subscript>2</subscript></entry> | ||
| 842 | <entry>b<subscript>1</subscript></entry> | ||
| 843 | <entry>b<subscript>0</subscript></entry> | ||
| 844 | </row> | ||
| 845 | </tbody> | ||
| 846 | </tgroup> | ||
| 847 | </table> | ||
| 848 | |||
| 849 | <para>A test utility to determine which RGB formats a driver | ||
| 850 | actually supports is available from the LinuxTV v4l-dvb repository. | ||
| 851 | See &v4l-dvb; for access instructions.</para> | ||
| 852 | |||
| 853 | </refsect1> | ||
| 854 | </refentry> | ||
| 855 | |||
| 856 | <!-- | ||
| 857 | Local Variables: | ||
| 858 | mode: sgml | ||
| 859 | sgml-parent-document: "pixfmt.sgml" | ||
| 860 | indent-tabs-mode: nil | ||
| 861 | End: | ||
| 862 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml new file mode 100644 index 000000000000..3cab5d0ca75d --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml | |||
| @@ -0,0 +1,244 @@ | |||
| 1 | <refentry id="packed-yuv"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>Packed YUV formats</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname>Packed YUV formats</refname> | ||
| 8 | <refpurpose>Packed YUV formats</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>Similar to the packed RGB formats these formats store | ||
| 14 | the Y, Cb and Cr component of each pixel in one 16 or 32 bit | ||
| 15 | word.</para> | ||
| 16 | |||
| 17 | <table pgwide="1" frame="none"> | ||
| 18 | <title>Packed YUV Image Formats</title> | ||
| 19 | <tgroup cols="37" align="center"> | ||
| 20 | <colspec colname="id" align="left" /> | ||
| 21 | <colspec colname="fourcc" /> | ||
| 22 | <colspec colname="bit" /> | ||
| 23 | |||
| 24 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 25 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 26 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 27 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 28 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 29 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 30 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 31 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 32 | |||
| 33 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 34 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 35 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 36 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 37 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 38 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 39 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 40 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 41 | |||
| 42 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 43 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 44 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 45 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 46 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 47 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 48 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 49 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 50 | |||
| 51 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 52 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 53 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 54 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 55 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 56 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 57 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 58 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 59 | |||
| 60 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 61 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 62 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 63 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 64 | <thead> | ||
| 65 | <row> | ||
| 66 | <entry>Identifier</entry> | ||
| 67 | <entry>Code</entry> | ||
| 68 | <entry> </entry> | ||
| 69 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 70 | <entry spanname="b1">Byte 1</entry> | ||
| 71 | <entry spanname="b2">Byte 2</entry> | ||
| 72 | <entry spanname="b3">Byte 3</entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry> </entry> | ||
| 76 | <entry> </entry> | ||
| 77 | <entry>Bit</entry> | ||
| 78 | <entry>7</entry> | ||
| 79 | <entry>6</entry> | ||
| 80 | <entry>5</entry> | ||
| 81 | <entry>4</entry> | ||
| 82 | <entry>3</entry> | ||
| 83 | <entry>2</entry> | ||
| 84 | <entry>1</entry> | ||
| 85 | <entry>0</entry> | ||
| 86 | <entry> </entry> | ||
| 87 | <entry>7</entry> | ||
| 88 | <entry>6</entry> | ||
| 89 | <entry>5</entry> | ||
| 90 | <entry>4</entry> | ||
| 91 | <entry>3</entry> | ||
| 92 | <entry>2</entry> | ||
| 93 | <entry>1</entry> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry> </entry> | ||
| 96 | <entry>7</entry> | ||
| 97 | <entry>6</entry> | ||
| 98 | <entry>5</entry> | ||
| 99 | <entry>4</entry> | ||
| 100 | <entry>3</entry> | ||
| 101 | <entry>2</entry> | ||
| 102 | <entry>1</entry> | ||
| 103 | <entry>0</entry> | ||
| 104 | <entry> </entry> | ||
| 105 | <entry>7</entry> | ||
| 106 | <entry>6</entry> | ||
| 107 | <entry>5</entry> | ||
| 108 | <entry>4</entry> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>2</entry> | ||
| 111 | <entry>1</entry> | ||
| 112 | <entry>0</entry> | ||
| 113 | </row> | ||
| 114 | </thead> | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row id="V4L2-PIX-FMT-YUV444"> | ||
| 117 | <entry><constant>V4L2_PIX_FMT_YUV444</constant></entry> | ||
| 118 | <entry>'Y444'</entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Cb<subscript>3</subscript></entry> | ||
| 121 | <entry>Cb<subscript>2</subscript></entry> | ||
| 122 | <entry>Cb<subscript>1</subscript></entry> | ||
| 123 | <entry>Cb<subscript>0</subscript></entry> | ||
| 124 | <entry>Cr<subscript>3</subscript></entry> | ||
| 125 | <entry>Cr<subscript>2</subscript></entry> | ||
| 126 | <entry>Cr<subscript>1</subscript></entry> | ||
| 127 | <entry>Cr<subscript>0</subscript></entry> | ||
| 128 | <entry></entry> | ||
| 129 | <entry>a<subscript>3</subscript></entry> | ||
| 130 | <entry>a<subscript>2</subscript></entry> | ||
| 131 | <entry>a<subscript>1</subscript></entry> | ||
| 132 | <entry>a<subscript>0</subscript></entry> | ||
| 133 | <entry>Y'<subscript>3</subscript></entry> | ||
| 134 | <entry>Y'<subscript>2</subscript></entry> | ||
| 135 | <entry>Y'<subscript>1</subscript></entry> | ||
| 136 | <entry>Y'<subscript>0</subscript></entry> | ||
| 137 | </row> | ||
| 138 | |||
| 139 | <row id="V4L2-PIX-FMT-YUV555"> | ||
| 140 | <entry><constant>V4L2_PIX_FMT_YUV555</constant></entry> | ||
| 141 | <entry>'YUVO'</entry> | ||
| 142 | <entry></entry> | ||
| 143 | <entry>Cb<subscript>2</subscript></entry> | ||
| 144 | <entry>Cb<subscript>1</subscript></entry> | ||
| 145 | <entry>Cb<subscript>0</subscript></entry> | ||
| 146 | <entry>Cr<subscript>4</subscript></entry> | ||
| 147 | <entry>Cr<subscript>3</subscript></entry> | ||
| 148 | <entry>Cr<subscript>2</subscript></entry> | ||
| 149 | <entry>Cr<subscript>1</subscript></entry> | ||
| 150 | <entry>Cr<subscript>0</subscript></entry> | ||
| 151 | <entry></entry> | ||
| 152 | <entry>a</entry> | ||
| 153 | <entry>Y'<subscript>4</subscript></entry> | ||
| 154 | <entry>Y'<subscript>3</subscript></entry> | ||
| 155 | <entry>Y'<subscript>2</subscript></entry> | ||
| 156 | <entry>Y'<subscript>1</subscript></entry> | ||
| 157 | <entry>Y'<subscript>0</subscript></entry> | ||
| 158 | <entry>Cb<subscript>4</subscript></entry> | ||
| 159 | <entry>Cb<subscript>3</subscript></entry> | ||
| 160 | </row> | ||
| 161 | |||
| 162 | <row id="V4L2-PIX-FMT-YUV565"> | ||
| 163 | <entry><constant>V4L2_PIX_FMT_YUV565</constant></entry> | ||
| 164 | <entry>'YUVP'</entry> | ||
| 165 | <entry></entry> | ||
| 166 | <entry>Cb<subscript>2</subscript></entry> | ||
| 167 | <entry>Cb<subscript>1</subscript></entry> | ||
| 168 | <entry>Cb<subscript>0</subscript></entry> | ||
| 169 | <entry>Cr<subscript>4</subscript></entry> | ||
| 170 | <entry>Cr<subscript>3</subscript></entry> | ||
| 171 | <entry>Cr<subscript>2</subscript></entry> | ||
| 172 | <entry>Cr<subscript>1</subscript></entry> | ||
| 173 | <entry>Cr<subscript>0</subscript></entry> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>Y'<subscript>4</subscript></entry> | ||
| 176 | <entry>Y'<subscript>3</subscript></entry> | ||
| 177 | <entry>Y'<subscript>2</subscript></entry> | ||
| 178 | <entry>Y'<subscript>1</subscript></entry> | ||
| 179 | <entry>Y'<subscript>0</subscript></entry> | ||
| 180 | <entry>Cb<subscript>5</subscript></entry> | ||
| 181 | <entry>Cb<subscript>4</subscript></entry> | ||
| 182 | <entry>Cb<subscript>3</subscript></entry> | ||
| 183 | </row> | ||
| 184 | |||
| 185 | <row id="V4L2-PIX-FMT-YUV32"> | ||
| 186 | <entry><constant>V4L2_PIX_FMT_YUV32</constant></entry> | ||
| 187 | <entry>'YUV4'</entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry>a<subscript>7</subscript></entry> | ||
| 190 | <entry>a<subscript>6</subscript></entry> | ||
| 191 | <entry>a<subscript>5</subscript></entry> | ||
| 192 | <entry>a<subscript>4</subscript></entry> | ||
| 193 | <entry>a<subscript>3</subscript></entry> | ||
| 194 | <entry>a<subscript>2</subscript></entry> | ||
| 195 | <entry>a<subscript>1</subscript></entry> | ||
| 196 | <entry>a<subscript>0</subscript></entry> | ||
| 197 | <entry></entry> | ||
| 198 | <entry>Y'<subscript>7</subscript></entry> | ||
| 199 | <entry>Y'<subscript>6</subscript></entry> | ||
| 200 | <entry>Y'<subscript>5</subscript></entry> | ||
| 201 | <entry>Y'<subscript>4</subscript></entry> | ||
| 202 | <entry>Y'<subscript>3</subscript></entry> | ||
| 203 | <entry>Y'<subscript>2</subscript></entry> | ||
| 204 | <entry>Y'<subscript>1</subscript></entry> | ||
| 205 | <entry>Y'<subscript>0</subscript></entry> | ||
| 206 | <entry></entry> | ||
| 207 | <entry>Cb<subscript>7</subscript></entry> | ||
| 208 | <entry>Cb<subscript>6</subscript></entry> | ||
| 209 | <entry>Cb<subscript>5</subscript></entry> | ||
| 210 | <entry>Cb<subscript>4</subscript></entry> | ||
| 211 | <entry>Cb<subscript>3</subscript></entry> | ||
| 212 | <entry>Cb<subscript>2</subscript></entry> | ||
| 213 | <entry>Cb<subscript>1</subscript></entry> | ||
| 214 | <entry>Cb<subscript>0</subscript></entry> | ||
| 215 | <entry></entry> | ||
| 216 | <entry>Cr<subscript>7</subscript></entry> | ||
| 217 | <entry>Cr<subscript>6</subscript></entry> | ||
| 218 | <entry>Cr<subscript>5</subscript></entry> | ||
| 219 | <entry>Cr<subscript>4</subscript></entry> | ||
| 220 | <entry>Cr<subscript>3</subscript></entry> | ||
| 221 | <entry>Cr<subscript>2</subscript></entry> | ||
| 222 | <entry>Cr<subscript>1</subscript></entry> | ||
| 223 | <entry>Cr<subscript>0</subscript></entry> | ||
| 224 | </row> | ||
| 225 | </tbody> | ||
| 226 | </tgroup> | ||
| 227 | </table> | ||
| 228 | |||
| 229 | <para>Bit 7 is the most significant bit. The value of a = alpha | ||
| 230 | bits is undefined when reading from the driver, ignored when writing | ||
| 231 | to the driver, except when alpha blending has been negotiated for a | ||
| 232 | <link linkend="overlay">Video Overlay</link> or <link | ||
| 233 | linkend="osd">Video Output Overlay</link>.</para> | ||
| 234 | |||
| 235 | </refsect1> | ||
| 236 | </refentry> | ||
| 237 | |||
| 238 | <!-- | ||
| 239 | Local Variables: | ||
| 240 | mode: sgml | ||
| 241 | sgml-parent-document: "pixfmt.sgml" | ||
| 242 | indent-tabs-mode: nil | ||
| 243 | End: | ||
| 244 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/v4l/pixfmt-sbggr16.xml new file mode 100644 index 000000000000..519a9efbac10 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sbggr16.xml | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SBGGR16"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This format is similar to <link | ||
| 14 | linkend="V4L2-PIX-FMT-SBGGR8"> | ||
| 15 | <constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has | ||
| 16 | a depth of 16 bits. The least significant byte is stored at lower | ||
| 17 | memory addresses (little-endian). Note the actual sampling precision | ||
| 18 | may be lower than 16 bits, for example 10 bits per pixel with values | ||
| 19 | in range 0 to 1023.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>B<subscript>00low</subscript></entry> | ||
| 35 | <entry>B<subscript>00high</subscript></entry> | ||
| 36 | <entry>G<subscript>01low</subscript></entry> | ||
| 37 | <entry>G<subscript>01high</subscript></entry> | ||
| 38 | <entry>B<subscript>02low</subscript></entry> | ||
| 39 | <entry>B<subscript>02high</subscript></entry> | ||
| 40 | <entry>G<subscript>03low</subscript></entry> | ||
| 41 | <entry>G<subscript>03high</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>G<subscript>10low</subscript></entry> | ||
| 46 | <entry>G<subscript>10high</subscript></entry> | ||
| 47 | <entry>R<subscript>11low</subscript></entry> | ||
| 48 | <entry>R<subscript>11high</subscript></entry> | ||
| 49 | <entry>G<subscript>12low</subscript></entry> | ||
| 50 | <entry>G<subscript>12high</subscript></entry> | ||
| 51 | <entry>R<subscript>13low</subscript></entry> | ||
| 52 | <entry>R<subscript>13high</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>B<subscript>20low</subscript></entry> | ||
| 57 | <entry>B<subscript>20high</subscript></entry> | ||
| 58 | <entry>G<subscript>21low</subscript></entry> | ||
| 59 | <entry>G<subscript>21high</subscript></entry> | ||
| 60 | <entry>B<subscript>22low</subscript></entry> | ||
| 61 | <entry>B<subscript>22high</subscript></entry> | ||
| 62 | <entry>G<subscript>23low</subscript></entry> | ||
| 63 | <entry>G<subscript>23high</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>G<subscript>30low</subscript></entry> | ||
| 68 | <entry>G<subscript>30high</subscript></entry> | ||
| 69 | <entry>R<subscript>31low</subscript></entry> | ||
| 70 | <entry>R<subscript>31high</subscript></entry> | ||
| 71 | <entry>G<subscript>32low</subscript></entry> | ||
| 72 | <entry>G<subscript>32high</subscript></entry> | ||
| 73 | <entry>R<subscript>33low</subscript></entry> | ||
| 74 | <entry>R<subscript>33high</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | </example> | ||
| 82 | </refsect1> | ||
| 83 | </refentry> | ||
| 84 | |||
| 85 | <!-- | ||
| 86 | Local Variables: | ||
| 87 | mode: sgml | ||
| 88 | sgml-parent-document: "pixfmt.sgml" | ||
| 89 | indent-tabs-mode: nil | ||
| 90 | End: | ||
| 91 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/v4l/pixfmt-sbggr8.xml new file mode 100644 index 000000000000..5fe84ecc2ebe --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sbggr8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SBGGR8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a blue and green value, the second row of a green and | ||
| 18 | red value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>B<subscript>00</subscript></entry> | ||
| 35 | <entry>G<subscript>01</subscript></entry> | ||
| 36 | <entry>B<subscript>02</subscript></entry> | ||
| 37 | <entry>G<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>G<subscript>10</subscript></entry> | ||
| 42 | <entry>R<subscript>11</subscript></entry> | ||
| 43 | <entry>G<subscript>12</subscript></entry> | ||
| 44 | <entry>R<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>B<subscript>20</subscript></entry> | ||
| 49 | <entry>G<subscript>21</subscript></entry> | ||
| 50 | <entry>B<subscript>22</subscript></entry> | ||
| 51 | <entry>G<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>G<subscript>30</subscript></entry> | ||
| 56 | <entry>R<subscript>31</subscript></entry> | ||
| 57 | <entry>G<subscript>32</subscript></entry> | ||
| 58 | <entry>R<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml new file mode 100644 index 000000000000..d67a472b0880 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SGBRG8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a green and blue value, the second row of a red and | ||
| 18 | green value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>G<subscript>00</subscript></entry> | ||
| 35 | <entry>B<subscript>01</subscript></entry> | ||
| 36 | <entry>G<subscript>02</subscript></entry> | ||
| 37 | <entry>B<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>R<subscript>10</subscript></entry> | ||
| 42 | <entry>G<subscript>11</subscript></entry> | ||
| 43 | <entry>R<subscript>12</subscript></entry> | ||
| 44 | <entry>G<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>G<subscript>20</subscript></entry> | ||
| 49 | <entry>B<subscript>21</subscript></entry> | ||
| 50 | <entry>G<subscript>22</subscript></entry> | ||
| 51 | <entry>B<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>R<subscript>30</subscript></entry> | ||
| 56 | <entry>G<subscript>31</subscript></entry> | ||
| 57 | <entry>R<subscript>32</subscript></entry> | ||
| 58 | <entry>G<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml new file mode 100644 index 000000000000..0cdf13b8ac1c --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SGRBG8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a green and blue value, the second row of a red and | ||
| 18 | green value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 × | ||
| 23 | 4 pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>G<subscript>00</subscript></entry> | ||
| 35 | <entry>R<subscript>01</subscript></entry> | ||
| 36 | <entry>G<subscript>02</subscript></entry> | ||
| 37 | <entry>R<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>R<subscript>10</subscript></entry> | ||
| 42 | <entry>B<subscript>11</subscript></entry> | ||
| 43 | <entry>R<subscript>12</subscript></entry> | ||
| 44 | <entry>B<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>G<subscript>20</subscript></entry> | ||
| 49 | <entry>R<subscript>21</subscript></entry> | ||
| 50 | <entry>G<subscript>22</subscript></entry> | ||
| 51 | <entry>R<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>R<subscript>30</subscript></entry> | ||
| 56 | <entry>B<subscript>31</subscript></entry> | ||
| 57 | <entry>R<subscript>32</subscript></entry> | ||
| 58 | <entry>B<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/v4l/pixfmt-uyvy.xml new file mode 100644 index 000000000000..816c8d467c16 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-uyvy.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-UYVY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_UYVY</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Cb<subscript>00</subscript></entry> | ||
| 35 | <entry>Y'<subscript>00</subscript></entry> | ||
| 36 | <entry>Cr<subscript>00</subscript></entry> | ||
| 37 | <entry>Y'<subscript>01</subscript></entry> | ||
| 38 | <entry>Cb<subscript>01</subscript></entry> | ||
| 39 | <entry>Y'<subscript>02</subscript></entry> | ||
| 40 | <entry>Cr<subscript>01</subscript></entry> | ||
| 41 | <entry>Y'<subscript>03</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Cb<subscript>10</subscript></entry> | ||
| 46 | <entry>Y'<subscript>10</subscript></entry> | ||
| 47 | <entry>Cr<subscript>10</subscript></entry> | ||
| 48 | <entry>Y'<subscript>11</subscript></entry> | ||
| 49 | <entry>Cb<subscript>11</subscript></entry> | ||
| 50 | <entry>Y'<subscript>12</subscript></entry> | ||
| 51 | <entry>Cr<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>13</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Cb<subscript>20</subscript></entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Cr<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Cb<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Cr<subscript>21</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Cb<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>30</subscript></entry> | ||
| 69 | <entry>Cr<subscript>30</subscript></entry> | ||
| 70 | <entry>Y'<subscript>31</subscript></entry> | ||
| 71 | <entry>Cb<subscript>31</subscript></entry> | ||
| 72 | <entry>Y'<subscript>32</subscript></entry> | ||
| 73 | <entry>Cr<subscript>31</subscript></entry> | ||
| 74 | <entry>Y'<subscript>33</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/v4l/pixfmt-vyuy.xml new file mode 100644 index 000000000000..61f12a5e68d9 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-vyuy.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-VYUY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_VYUY</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Cr<subscript>00</subscript></entry> | ||
| 35 | <entry>Y'<subscript>00</subscript></entry> | ||
| 36 | <entry>Cb<subscript>00</subscript></entry> | ||
| 37 | <entry>Y'<subscript>01</subscript></entry> | ||
| 38 | <entry>Cr<subscript>01</subscript></entry> | ||
| 39 | <entry>Y'<subscript>02</subscript></entry> | ||
| 40 | <entry>Cb<subscript>01</subscript></entry> | ||
| 41 | <entry>Y'<subscript>03</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Cr<subscript>10</subscript></entry> | ||
| 46 | <entry>Y'<subscript>10</subscript></entry> | ||
| 47 | <entry>Cb<subscript>10</subscript></entry> | ||
| 48 | <entry>Y'<subscript>11</subscript></entry> | ||
| 49 | <entry>Cr<subscript>11</subscript></entry> | ||
| 50 | <entry>Y'<subscript>12</subscript></entry> | ||
| 51 | <entry>Cb<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>13</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Cr<subscript>20</subscript></entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Cb<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Cr<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Cb<subscript>21</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Cr<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>30</subscript></entry> | ||
| 69 | <entry>Cb<subscript>30</subscript></entry> | ||
| 70 | <entry>Y'<subscript>31</subscript></entry> | ||
| 71 | <entry>Cr<subscript>31</subscript></entry> | ||
| 72 | <entry>Y'<subscript>32</subscript></entry> | ||
| 73 | <entry>Cb<subscript>31</subscript></entry> | ||
| 74 | <entry>Y'<subscript>33</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-y16.xml b/Documentation/DocBook/v4l/pixfmt-y16.xml new file mode 100644 index 000000000000..d58404015078 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-y16.xml | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-Y16"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_Y16</constant></refname> | ||
| 8 | <refpurpose>Grey-scale image</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is a grey-scale image with a depth of 16 bits per | ||
| 14 | pixel. The least significant byte is stored at lower memory addresses | ||
| 15 | (little-endian). Note the actual sampling precision may be lower than | ||
| 16 | 16 bits, for example 10 bits per pixel with values in range 0 to | ||
| 17 | 1023.</para> | ||
| 18 | |||
| 19 | <example> | ||
| 20 | <title><constant>V4L2_PIX_FMT_Y16</constant> 4 × 4 | ||
| 21 | pixel image</title> | ||
| 22 | |||
| 23 | <formalpara> | ||
| 24 | <title>Byte Order.</title> | ||
| 25 | <para>Each cell is one byte. | ||
| 26 | <informaltable frame="none"> | ||
| 27 | <tgroup cols="9" align="center"> | ||
| 28 | <colspec align="left" colwidth="2*" /> | ||
| 29 | <tbody valign="top"> | ||
| 30 | <row> | ||
| 31 | <entry>start + 0:</entry> | ||
| 32 | <entry>Y'<subscript>00low</subscript></entry> | ||
| 33 | <entry>Y'<subscript>00high</subscript></entry> | ||
| 34 | <entry>Y'<subscript>01low</subscript></entry> | ||
| 35 | <entry>Y'<subscript>01high</subscript></entry> | ||
| 36 | <entry>Y'<subscript>02low</subscript></entry> | ||
| 37 | <entry>Y'<subscript>02high</subscript></entry> | ||
| 38 | <entry>Y'<subscript>03low</subscript></entry> | ||
| 39 | <entry>Y'<subscript>03high</subscript></entry> | ||
| 40 | </row> | ||
| 41 | <row> | ||
| 42 | <entry>start + 8:</entry> | ||
| 43 | <entry>Y'<subscript>10low</subscript></entry> | ||
| 44 | <entry>Y'<subscript>10high</subscript></entry> | ||
| 45 | <entry>Y'<subscript>11low</subscript></entry> | ||
| 46 | <entry>Y'<subscript>11high</subscript></entry> | ||
| 47 | <entry>Y'<subscript>12low</subscript></entry> | ||
| 48 | <entry>Y'<subscript>12high</subscript></entry> | ||
| 49 | <entry>Y'<subscript>13low</subscript></entry> | ||
| 50 | <entry>Y'<subscript>13high</subscript></entry> | ||
| 51 | </row> | ||
| 52 | <row> | ||
| 53 | <entry>start + 16:</entry> | ||
| 54 | <entry>Y'<subscript>20low</subscript></entry> | ||
| 55 | <entry>Y'<subscript>20high</subscript></entry> | ||
| 56 | <entry>Y'<subscript>21low</subscript></entry> | ||
| 57 | <entry>Y'<subscript>21high</subscript></entry> | ||
| 58 | <entry>Y'<subscript>22low</subscript></entry> | ||
| 59 | <entry>Y'<subscript>22high</subscript></entry> | ||
| 60 | <entry>Y'<subscript>23low</subscript></entry> | ||
| 61 | <entry>Y'<subscript>23high</subscript></entry> | ||
| 62 | </row> | ||
| 63 | <row> | ||
| 64 | <entry>start + 24:</entry> | ||
| 65 | <entry>Y'<subscript>30low</subscript></entry> | ||
| 66 | <entry>Y'<subscript>30high</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31low</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31high</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32low</subscript></entry> | ||
| 70 | <entry>Y'<subscript>32high</subscript></entry> | ||
| 71 | <entry>Y'<subscript>33low</subscript></entry> | ||
| 72 | <entry>Y'<subscript>33high</subscript></entry> | ||
| 73 | </row> | ||
| 74 | </tbody> | ||
| 75 | </tgroup> | ||
| 76 | </informaltable> | ||
| 77 | </para> | ||
| 78 | </formalpara> | ||
| 79 | </example> | ||
| 80 | </refsect1> | ||
| 81 | </refentry> | ||
| 82 | |||
| 83 | <!-- | ||
| 84 | Local Variables: | ||
| 85 | mode: sgml | ||
| 86 | sgml-parent-document: "pixfmt.sgml" | ||
| 87 | indent-tabs-mode: nil | ||
| 88 | End: | ||
| 89 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-y41p.xml b/Documentation/DocBook/v4l/pixfmt-y41p.xml new file mode 100644 index 000000000000..73c8536efb05 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-y41p.xml | |||
| @@ -0,0 +1,157 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-Y41P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_Y41P</constant></refname> | ||
| 8 | <refpurpose>Format with ¼ horizontal chroma | ||
| 9 | resolution, also known as YUV 4:1:1</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | <refsect1> | ||
| 12 | <title>Description</title> | ||
| 13 | |||
| 14 | <para>In this format each 12 bytes is eight pixels. In the | ||
| 15 | twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair | ||
| 16 | goes with the first four Y's, and the second CbCr pair goes with the | ||
| 17 | other four Y's. The Cb and Cr components have one fourth the | ||
| 18 | horizontal resolution of the Y component.</para> | ||
| 19 | |||
| 20 | <para>Do not confuse this format with <link | ||
| 21 | linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>. | ||
| 22 | Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while | ||
| 23 | YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para> | ||
| 24 | |||
| 25 | <example> | ||
| 26 | <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 × 4 | ||
| 27 | pixel image</title> | ||
| 28 | |||
| 29 | <formalpara> | ||
| 30 | <title>Byte Order</title> | ||
| 31 | <para>Each cell is one byte. | ||
| 32 | <informaltable frame="none"> | ||
| 33 | <tgroup cols="13" align="center"> | ||
| 34 | <colspec align="left" colwidth="2*" /> | ||
| 35 | <tbody valign="top"> | ||
| 36 | <row> | ||
| 37 | <entry>start + 0:</entry> | ||
| 38 | <entry>Cb<subscript>00</subscript></entry> | ||
| 39 | <entry>Y'<subscript>00</subscript></entry> | ||
| 40 | <entry>Cr<subscript>00</subscript></entry> | ||
| 41 | <entry>Y'<subscript>01</subscript></entry> | ||
| 42 | <entry>Cb<subscript>01</subscript></entry> | ||
| 43 | <entry>Y'<subscript>02</subscript></entry> | ||
| 44 | <entry>Cr<subscript>01</subscript></entry> | ||
| 45 | <entry>Y'<subscript>03</subscript></entry> | ||
| 46 | <entry>Y'<subscript>04</subscript></entry> | ||
| 47 | <entry>Y'<subscript>05</subscript></entry> | ||
| 48 | <entry>Y'<subscript>06</subscript></entry> | ||
| 49 | <entry>Y'<subscript>07</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 12:</entry> | ||
| 53 | <entry>Cb<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>10</subscript></entry> | ||
| 55 | <entry>Cr<subscript>10</subscript></entry> | ||
| 56 | <entry>Y'<subscript>11</subscript></entry> | ||
| 57 | <entry>Cb<subscript>11</subscript></entry> | ||
| 58 | <entry>Y'<subscript>12</subscript></entry> | ||
| 59 | <entry>Cr<subscript>11</subscript></entry> | ||
| 60 | <entry>Y'<subscript>13</subscript></entry> | ||
| 61 | <entry>Y'<subscript>14</subscript></entry> | ||
| 62 | <entry>Y'<subscript>15</subscript></entry> | ||
| 63 | <entry>Y'<subscript>16</subscript></entry> | ||
| 64 | <entry>Y'<subscript>17</subscript></entry> | ||
| 65 | </row> | ||
| 66 | <row> | ||
| 67 | <entry>start + 24:</entry> | ||
| 68 | <entry>Cb<subscript>20</subscript></entry> | ||
| 69 | <entry>Y'<subscript>20</subscript></entry> | ||
| 70 | <entry>Cr<subscript>20</subscript></entry> | ||
| 71 | <entry>Y'<subscript>21</subscript></entry> | ||
| 72 | <entry>Cb<subscript>21</subscript></entry> | ||
| 73 | <entry>Y'<subscript>22</subscript></entry> | ||
| 74 | <entry>Cr<subscript>21</subscript></entry> | ||
| 75 | <entry>Y'<subscript>23</subscript></entry> | ||
| 76 | <entry>Y'<subscript>24</subscript></entry> | ||
| 77 | <entry>Y'<subscript>25</subscript></entry> | ||
| 78 | <entry>Y'<subscript>26</subscript></entry> | ||
| 79 | <entry>Y'<subscript>27</subscript></entry> | ||
| 80 | </row> | ||
| 81 | <row> | ||
| 82 | <entry>start + 36:</entry> | ||
| 83 | <entry>Cb<subscript>30</subscript></entry> | ||
| 84 | <entry>Y'<subscript>30</subscript></entry> | ||
| 85 | <entry>Cr<subscript>30</subscript></entry> | ||
| 86 | <entry>Y'<subscript>31</subscript></entry> | ||
| 87 | <entry>Cb<subscript>31</subscript></entry> | ||
| 88 | <entry>Y'<subscript>32</subscript></entry> | ||
| 89 | <entry>Cr<subscript>31</subscript></entry> | ||
| 90 | <entry>Y'<subscript>33</subscript></entry> | ||
| 91 | <entry>Y'<subscript>34</subscript></entry> | ||
| 92 | <entry>Y'<subscript>35</subscript></entry> | ||
| 93 | <entry>Y'<subscript>36</subscript></entry> | ||
| 94 | <entry>Y'<subscript>37</subscript></entry> | ||
| 95 | </row> | ||
| 96 | </tbody> | ||
| 97 | </tgroup> | ||
| 98 | </informaltable></para> | ||
| 99 | </formalpara> | ||
| 100 | |||
| 101 | <formalpara> | ||
| 102 | <title>Color Sample Location.</title> | ||
| 103 | <para> | ||
| 104 | <informaltable frame="none"> | ||
| 105 | <tgroup cols="15" align="center"> | ||
| 106 | <tbody valign="top"> | ||
| 107 | <row> | ||
| 108 | <entry></entry> | ||
| 109 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 110 | <entry>2</entry><entry></entry><entry>3</entry><entry></entry> | ||
| 111 | <entry>4</entry><entry></entry><entry>5</entry><entry></entry> | ||
| 112 | <entry>6</entry><entry></entry><entry>7</entry> | ||
| 113 | </row> | ||
| 114 | <row> | ||
| 115 | <entry>0</entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 117 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 118 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 119 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>1</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 125 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 126 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>2</entry> | ||
| 130 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 131 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 132 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>3</entry> | ||
| 137 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 138 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 139 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 140 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </informaltable> | ||
| 145 | </para> | ||
| 146 | </formalpara> | ||
| 147 | </example> | ||
| 148 | </refsect1> | ||
| 149 | </refentry> | ||
| 150 | |||
| 151 | <!-- | ||
| 152 | Local Variables: | ||
| 153 | mode: sgml | ||
| 154 | sgml-parent-document: "pixfmt.sgml" | ||
| 155 | indent-tabs-mode: nil | ||
| 156 | End: | ||
| 157 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/v4l/pixfmt-yuv410.xml new file mode 100644 index 000000000000..8eb4a193d770 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv410.xml | |||
| @@ -0,0 +1,141 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname> | ||
| 9 | <refpurpose>Planar formats with ¼ horizontal and | ||
| 10 | vertical chroma resolution, also known as YUV 4:1:0</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>These are planar formats, as opposed to a packed format. | ||
| 16 | The three components are separated into three sub-images or planes. | ||
| 17 | The Y plane is first. The Y plane has one byte per pixel. For | ||
| 18 | <constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately | ||
| 19 | follows the Y plane in memory. The Cr plane is ¼ the width and | ||
| 20 | ¼ the height of the Y plane (and of the image). Each Cr belongs | ||
| 21 | to 16 pixels, a four-by-four square of the image. Following the Cr | ||
| 22 | plane is the Cb plane, just like the Cr plane. | ||
| 23 | <constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb | ||
| 24 | plane comes first, then the Cr plane.</para> | ||
| 25 | |||
| 26 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 27 | and Cb planes have ¼ as many pad bytes after their rows. In | ||
| 28 | other words, four Cx rows (including padding) are exactly as long as | ||
| 29 | one Y row (including padding).</para> | ||
| 30 | |||
| 31 | <example> | ||
| 32 | <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 × 4 | ||
| 33 | pixel image</title> | ||
| 34 | |||
| 35 | <formalpara> | ||
| 36 | <title>Byte Order.</title> | ||
| 37 | <para>Each cell is one byte. | ||
| 38 | <informaltable frame="none"> | ||
| 39 | <tgroup cols="5" align="center"> | ||
| 40 | <colspec align="left" colwidth="2*" /> | ||
| 41 | <tbody valign="top"> | ||
| 42 | <row> | ||
| 43 | <entry>start + 0:</entry> | ||
| 44 | <entry>Y'<subscript>00</subscript></entry> | ||
| 45 | <entry>Y'<subscript>01</subscript></entry> | ||
| 46 | <entry>Y'<subscript>02</subscript></entry> | ||
| 47 | <entry>Y'<subscript>03</subscript></entry> | ||
| 48 | </row> | ||
| 49 | <row> | ||
| 50 | <entry>start + 4:</entry> | ||
| 51 | <entry>Y'<subscript>10</subscript></entry> | ||
| 52 | <entry>Y'<subscript>11</subscript></entry> | ||
| 53 | <entry>Y'<subscript>12</subscript></entry> | ||
| 54 | <entry>Y'<subscript>13</subscript></entry> | ||
| 55 | </row> | ||
| 56 | <row> | ||
| 57 | <entry>start + 8:</entry> | ||
| 58 | <entry>Y'<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Y'<subscript>23</subscript></entry> | ||
| 62 | </row> | ||
| 63 | <row> | ||
| 64 | <entry>start + 12:</entry> | ||
| 65 | <entry>Y'<subscript>30</subscript></entry> | ||
| 66 | <entry>Y'<subscript>31</subscript></entry> | ||
| 67 | <entry>Y'<subscript>32</subscript></entry> | ||
| 68 | <entry>Y'<subscript>33</subscript></entry> | ||
| 69 | </row> | ||
| 70 | <row> | ||
| 71 | <entry>start + 16:</entry> | ||
| 72 | <entry>Cr<subscript>00</subscript></entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>start + 17:</entry> | ||
| 76 | <entry>Cb<subscript>00</subscript></entry> | ||
| 77 | </row> | ||
| 78 | </tbody> | ||
| 79 | </tgroup> | ||
| 80 | </informaltable> | ||
| 81 | </para> | ||
| 82 | </formalpara> | ||
| 83 | |||
| 84 | <formalpara> | ||
| 85 | <title>Color Sample Location.</title> | ||
| 86 | <para> | ||
| 87 | <informaltable frame="none"> | ||
| 88 | <tgroup cols="7" align="center"> | ||
| 89 | <tbody valign="top"> | ||
| 90 | <row> | ||
| 91 | <entry></entry> | ||
| 92 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 93 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>0</entry> | ||
| 97 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 98 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry></entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>1</entry> | ||
| 105 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry></entry> | ||
| 110 | <entry></entry><entry></entry><entry></entry><entry>C</entry> | ||
| 111 | <entry></entry><entry></entry><entry></entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>2</entry> | ||
| 115 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>3</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 125 | </row> | ||
| 126 | </tbody> | ||
| 127 | </tgroup> | ||
| 128 | </informaltable> | ||
| 129 | </para> | ||
| 130 | </formalpara> | ||
| 131 | </example> | ||
| 132 | </refsect1> | ||
| 133 | </refentry> | ||
| 134 | |||
| 135 | <!-- | ||
| 136 | Local Variables: | ||
| 137 | mode: sgml | ||
| 138 | sgml-parent-document: "pixfmt.sgml" | ||
| 139 | indent-tabs-mode: nil | ||
| 140 | End: | ||
| 141 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/v4l/pixfmt-yuv411p.xml new file mode 100644 index 000000000000..00e0960a9869 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv411p.xml | |||
| @@ -0,0 +1,155 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUV411P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname> | ||
| 8 | <refpurpose>Format with ¼ horizontal chroma resolution, | ||
| 9 | also known as YUV 4:1:1. Planar layout as opposed to | ||
| 10 | <constant>V4L2_PIX_FMT_Y41P</constant></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>This format is not commonly used. This is a planar | ||
| 16 | format similar to the 4:2:2 planar format except with half as many | ||
| 17 | chroma. The three components are separated into three sub-images or | ||
| 18 | planes. The Y plane is first. The Y plane has one byte per pixel. The | ||
| 19 | Cb plane immediately follows the Y plane in memory. The Cb plane is | ||
| 20 | ¼ the width of the Y plane (and of the image). Each Cb belongs | ||
| 21 | to 4 pixels all on the same row. For example, | ||
| 22 | Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 23 | Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and | ||
| 24 | Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane, | ||
| 25 | just like the Cb plane.</para> | ||
| 26 | |||
| 27 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 28 | and Cb planes have ¼ as many pad bytes after their rows. In | ||
| 29 | other words, four C x rows (including padding) is exactly as long as | ||
| 30 | one Y row (including padding).</para> | ||
| 31 | |||
| 32 | <example> | ||
| 33 | <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 × 4 | ||
| 34 | pixel image</title> | ||
| 35 | |||
| 36 | <formalpara> | ||
| 37 | <title>Byte Order.</title> | ||
| 38 | <para>Each cell is one byte. | ||
| 39 | <informaltable frame="none"> | ||
| 40 | <tgroup cols="5" align="center"> | ||
| 41 | <colspec align="left" colwidth="2*" /> | ||
| 42 | <tbody valign="top"> | ||
| 43 | <row> | ||
| 44 | <entry>start + 0:</entry> | ||
| 45 | <entry>Y'<subscript>00</subscript></entry> | ||
| 46 | <entry>Y'<subscript>01</subscript></entry> | ||
| 47 | <entry>Y'<subscript>02</subscript></entry> | ||
| 48 | <entry>Y'<subscript>03</subscript></entry> | ||
| 49 | </row> | ||
| 50 | <row> | ||
| 51 | <entry>start + 4:</entry> | ||
| 52 | <entry>Y'<subscript>10</subscript></entry> | ||
| 53 | <entry>Y'<subscript>11</subscript></entry> | ||
| 54 | <entry>Y'<subscript>12</subscript></entry> | ||
| 55 | <entry>Y'<subscript>13</subscript></entry> | ||
| 56 | </row> | ||
| 57 | <row> | ||
| 58 | <entry>start + 8:</entry> | ||
| 59 | <entry>Y'<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | </row> | ||
| 64 | <row> | ||
| 65 | <entry>start + 12:</entry> | ||
| 66 | <entry>Y'<subscript>30</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31</subscript></entry> | ||
| 68 | <entry>Y'<subscript>32</subscript></entry> | ||
| 69 | <entry>Y'<subscript>33</subscript></entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>start + 16:</entry> | ||
| 73 | <entry>Cb<subscript>00</subscript></entry> | ||
| 74 | </row> | ||
| 75 | <row> | ||
| 76 | <entry>start + 17:</entry> | ||
| 77 | <entry>Cb<subscript>10</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 18:</entry> | ||
| 81 | <entry>Cb<subscript>20</subscript></entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry>start + 19:</entry> | ||
| 85 | <entry>Cb<subscript>30</subscript></entry> | ||
| 86 | </row> | ||
| 87 | <row> | ||
| 88 | <entry>start + 20:</entry> | ||
| 89 | <entry>Cr<subscript>00</subscript></entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>start + 21:</entry> | ||
| 93 | <entry>Cr<subscript>10</subscript></entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>start + 22:</entry> | ||
| 97 | <entry>Cr<subscript>20</subscript></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>start + 23:</entry> | ||
| 101 | <entry>Cr<subscript>30</subscript></entry> | ||
| 102 | </row> | ||
| 103 | </tbody> | ||
| 104 | </tgroup> | ||
| 105 | </informaltable> | ||
| 106 | </para> | ||
| 107 | </formalpara> | ||
| 108 | |||
| 109 | <formalpara> | ||
| 110 | <title>Color Sample Location.</title> | ||
| 111 | <para> | ||
| 112 | <informaltable frame="none"> | ||
| 113 | <tgroup cols="7" align="center"> | ||
| 114 | <tbody valign="top"> | ||
| 115 | <row> | ||
| 116 | <entry></entry> | ||
| 117 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 118 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 119 | </row> | ||
| 120 | <row> | ||
| 121 | <entry>0</entry> | ||
| 122 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>1</entry> | ||
| 127 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 128 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry>2</entry> | ||
| 132 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>3</entry> | ||
| 137 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 138 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 139 | </row> | ||
| 140 | </tbody> | ||
| 141 | </tgroup> | ||
| 142 | </informaltable> | ||
| 143 | </para> | ||
| 144 | </formalpara> | ||
| 145 | </example> | ||
| 146 | </refsect1> | ||
| 147 | </refentry> | ||
| 148 | |||
| 149 | <!-- | ||
| 150 | Local Variables: | ||
| 151 | mode: sgml | ||
| 152 | sgml-parent-document: "v4l2.sgml" | ||
| 153 | indent-tabs-mode: nil | ||
| 154 | End: | ||
| 155 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/v4l/pixfmt-yuv420.xml new file mode 100644 index 000000000000..42d7de5e456d --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv420.xml | |||
| @@ -0,0 +1,157 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname> | ||
| 9 | <refpurpose>Planar formats with ½ horizontal and | ||
| 10 | vertical chroma resolution, also known as YUV 4:2:0</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>These are planar formats, as opposed to a packed format. | ||
| 16 | The three components are separated into three sub- images or planes. | ||
| 17 | The Y plane is first. The Y plane has one byte per pixel. For | ||
| 18 | <constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately | ||
| 19 | follows the Y plane in memory. The Cr plane is half the width and half | ||
| 20 | the height of the Y plane (and of the image). Each Cr belongs to four | ||
| 21 | pixels, a two-by-two square of the image. For example, | ||
| 22 | Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 23 | Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and | ||
| 24 | Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane, | ||
| 25 | just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is | ||
| 26 | the same except the Cb plane comes first, then the Cr plane.</para> | ||
| 27 | |||
| 28 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 29 | and Cb planes have half as many pad bytes after their rows. In other | ||
| 30 | words, two Cx rows (including padding) is exactly as long as one Y row | ||
| 31 | (including padding).</para> | ||
| 32 | |||
| 33 | <example> | ||
| 34 | <title><constant>V4L2_PIX_FMT_YVU420</constant> 4 × 4 | ||
| 35 | pixel image</title> | ||
| 36 | |||
| 37 | <formalpara> | ||
| 38 | <title>Byte Order.</title> | ||
| 39 | <para>Each cell is one byte. | ||
| 40 | <informaltable frame="none"> | ||
| 41 | <tgroup cols="5" align="center"> | ||
| 42 | <colspec align="left" colwidth="2*" /> | ||
| 43 | <tbody valign="top"> | ||
| 44 | <row> | ||
| 45 | <entry>start + 0:</entry> | ||
| 46 | <entry>Y'<subscript>00</subscript></entry> | ||
| 47 | <entry>Y'<subscript>01</subscript></entry> | ||
| 48 | <entry>Y'<subscript>02</subscript></entry> | ||
| 49 | <entry>Y'<subscript>03</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 4:</entry> | ||
| 53 | <entry>Y'<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>11</subscript></entry> | ||
| 55 | <entry>Y'<subscript>12</subscript></entry> | ||
| 56 | <entry>Y'<subscript>13</subscript></entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>start + 8:</entry> | ||
| 60 | <entry>Y'<subscript>20</subscript></entry> | ||
| 61 | <entry>Y'<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>22</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 12:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32</subscript></entry> | ||
| 70 | <entry>Y'<subscript>33</subscript></entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry>start + 16:</entry> | ||
| 74 | <entry>Cr<subscript>00</subscript></entry> | ||
| 75 | <entry>Cr<subscript>01</subscript></entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>start + 18:</entry> | ||
| 79 | <entry>Cr<subscript>10</subscript></entry> | ||
| 80 | <entry>Cr<subscript>11</subscript></entry> | ||
| 81 | </row> | ||
| 82 | <row> | ||
| 83 | <entry>start + 20:</entry> | ||
| 84 | <entry>Cb<subscript>00</subscript></entry> | ||
| 85 | <entry>Cb<subscript>01</subscript></entry> | ||
| 86 | </row> | ||
| 87 | <row> | ||
| 88 | <entry>start + 22:</entry> | ||
| 89 | <entry>Cb<subscript>10</subscript></entry> | ||
| 90 | <entry>Cb<subscript>11</subscript></entry> | ||
| 91 | </row> | ||
| 92 | </tbody> | ||
| 93 | </tgroup> | ||
| 94 | </informaltable> | ||
| 95 | </para> | ||
| 96 | </formalpara> | ||
| 97 | |||
| 98 | <formalpara> | ||
| 99 | <title>Color Sample Location.</title> | ||
| 100 | <para> | ||
| 101 | <informaltable frame="none"> | ||
| 102 | <tgroup cols="7" align="center"> | ||
| 103 | <tbody valign="top"> | ||
| 104 | <row> | ||
| 105 | <entry></entry> | ||
| 106 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 107 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>0</entry> | ||
| 111 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 112 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 113 | </row> | ||
| 114 | <row> | ||
| 115 | <entry></entry> | ||
| 116 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 117 | <entry></entry><entry>C</entry><entry></entry> | ||
| 118 | </row> | ||
| 119 | <row> | ||
| 120 | <entry>1</entry> | ||
| 121 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 122 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 123 | </row> | ||
| 124 | <row> | ||
| 125 | <entry></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>2</entry> | ||
| 129 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 130 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry></entry> | ||
| 134 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 135 | <entry></entry><entry>C</entry><entry></entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>3</entry> | ||
| 139 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 140 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </informaltable> | ||
| 145 | </para> | ||
| 146 | </formalpara> | ||
| 147 | </example> | ||
| 148 | </refsect1> | ||
| 149 | </refentry> | ||
| 150 | |||
| 151 | <!-- | ||
| 152 | Local Variables: | ||
| 153 | mode: sgml | ||
| 154 | sgml-parent-document: "pixfmt.sgml" | ||
| 155 | indent-tabs-mode: nil | ||
| 156 | End: | ||
| 157 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/v4l/pixfmt-yuv422p.xml new file mode 100644 index 000000000000..4348bd9f0d01 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv422p.xml | |||
| @@ -0,0 +1,161 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUV422P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname> | ||
| 8 | <refpurpose>Format with ½ horizontal chroma resolution, | ||
| 9 | also known as YUV 4:2:2. Planar layout as opposed to | ||
| 10 | <constant>V4L2_PIX_FMT_YUYV</constant></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>This format is not commonly used. This is a planar | ||
| 16 | version of the YUYV format. The three components are separated into | ||
| 17 | three sub-images or planes. The Y plane is first. The Y plane has one | ||
| 18 | byte per pixel. The Cb plane immediately follows the Y plane in | ||
| 19 | memory. The Cb plane is half the width of the Y plane (and of the | ||
| 20 | image). Each Cb belongs to two pixels. For example, | ||
| 21 | Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 22 | Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane, | ||
| 23 | just like the Cb plane.</para> | ||
| 24 | |||
| 25 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 26 | and Cb planes have half as many pad bytes after their rows. In other | ||
| 27 | words, two Cx rows (including padding) is exactly as long as one Y row | ||
| 28 | (including padding).</para> | ||
| 29 | |||
| 30 | <example> | ||
| 31 | <title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 × 4 | ||
| 32 | pixel image</title> | ||
| 33 | |||
| 34 | <formalpara> | ||
| 35 | <title>Byte Order.</title> | ||
| 36 | <para>Each cell is one byte. | ||
| 37 | <informaltable frame="none"> | ||
| 38 | <tgroup cols="5" align="center"> | ||
| 39 | <colspec align="left" colwidth="2*" /> | ||
| 40 | <tbody valign="top"> | ||
| 41 | <row> | ||
| 42 | <entry>start + 0:</entry> | ||
| 43 | <entry>Y'<subscript>00</subscript></entry> | ||
| 44 | <entry>Y'<subscript>01</subscript></entry> | ||
| 45 | <entry>Y'<subscript>02</subscript></entry> | ||
| 46 | <entry>Y'<subscript>03</subscript></entry> | ||
| 47 | </row> | ||
| 48 | <row> | ||
| 49 | <entry>start + 4:</entry> | ||
| 50 | <entry>Y'<subscript>10</subscript></entry> | ||
| 51 | <entry>Y'<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>12</subscript></entry> | ||
| 53 | <entry>Y'<subscript>13</subscript></entry> | ||
| 54 | </row> | ||
| 55 | <row> | ||
| 56 | <entry>start + 8:</entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Y'<subscript>22</subscript></entry> | ||
| 60 | <entry>Y'<subscript>23</subscript></entry> | ||
| 61 | </row> | ||
| 62 | <row> | ||
| 63 | <entry>start + 12:</entry> | ||
| 64 | <entry>Y'<subscript>30</subscript></entry> | ||
| 65 | <entry>Y'<subscript>31</subscript></entry> | ||
| 66 | <entry>Y'<subscript>32</subscript></entry> | ||
| 67 | <entry>Y'<subscript>33</subscript></entry> | ||
| 68 | </row> | ||
| 69 | <row> | ||
| 70 | <entry>start + 16:</entry> | ||
| 71 | <entry>Cb<subscript>00</subscript></entry> | ||
| 72 | <entry>Cb<subscript>01</subscript></entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>start + 18:</entry> | ||
| 76 | <entry>Cb<subscript>10</subscript></entry> | ||
| 77 | <entry>Cb<subscript>11</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 20:</entry> | ||
| 81 | <entry>Cb<subscript>20</subscript></entry> | ||
| 82 | <entry>Cb<subscript>21</subscript></entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>start + 22:</entry> | ||
| 86 | <entry>Cb<subscript>30</subscript></entry> | ||
| 87 | <entry>Cb<subscript>31</subscript></entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>start + 24:</entry> | ||
| 91 | <entry>Cr<subscript>00</subscript></entry> | ||
| 92 | <entry>Cr<subscript>01</subscript></entry> | ||
| 93 | </row> | ||
| 94 | <row> | ||
| 95 | <entry>start + 26:</entry> | ||
| 96 | <entry>Cr<subscript>10</subscript></entry> | ||
| 97 | <entry>Cr<subscript>11</subscript></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>start + 28:</entry> | ||
| 101 | <entry>Cr<subscript>20</subscript></entry> | ||
| 102 | <entry>Cr<subscript>21</subscript></entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>start + 30:</entry> | ||
| 106 | <entry>Cr<subscript>30</subscript></entry> | ||
| 107 | <entry>Cr<subscript>31</subscript></entry> | ||
| 108 | </row> | ||
| 109 | </tbody> | ||
| 110 | </tgroup> | ||
| 111 | </informaltable> | ||
| 112 | </para> | ||
| 113 | </formalpara> | ||
| 114 | |||
| 115 | <formalpara> | ||
| 116 | <title>Color Sample Location.</title> | ||
| 117 | <para> | ||
| 118 | <informaltable frame="none"> | ||
| 119 | <tgroup cols="7" align="center"> | ||
| 120 | <tbody valign="top"> | ||
| 121 | <row> | ||
| 122 | <entry></entry> | ||
| 123 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 124 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>0</entry> | ||
| 128 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 129 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 134 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 135 | </row> | ||
| 136 | <row> | ||
| 137 | <entry>2</entry> | ||
| 138 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 139 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry>3</entry> | ||
| 143 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 144 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </informaltable> | ||
| 149 | </para> | ||
| 150 | </formalpara> | ||
| 151 | </example> | ||
| 152 | </refsect1> | ||
| 153 | </refentry> | ||
| 154 | |||
| 155 | <!-- | ||
| 156 | Local Variables: | ||
| 157 | mode: sgml | ||
| 158 | sgml-parent-document: "pixfmt.sgml" | ||
| 159 | indent-tabs-mode: nil | ||
| 160 | End: | ||
| 161 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/v4l/pixfmt-yuyv.xml new file mode 100644 index 000000000000..bdb2ffacbbcc --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuyv.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUYV"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUYV</constant></refname> | ||
| 8 | <refpurpose>Packed format with ½ horizontal chroma | ||
| 9 | resolution, also known as YUV 4:2:2</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | <refsect1> | ||
| 12 | <title>Description</title> | ||
| 13 | |||
| 14 | <para>In this format each four bytes is two pixels. Each four | ||
| 15 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 16 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 17 | components have half the horizontal resolution of the Y component. | ||
| 18 | <constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows | ||
| 19 | environment as YUY2.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Y'<subscript>00</subscript></entry> | ||
| 35 | <entry>Cb<subscript>00</subscript></entry> | ||
| 36 | <entry>Y'<subscript>01</subscript></entry> | ||
| 37 | <entry>Cr<subscript>00</subscript></entry> | ||
| 38 | <entry>Y'<subscript>02</subscript></entry> | ||
| 39 | <entry>Cb<subscript>01</subscript></entry> | ||
| 40 | <entry>Y'<subscript>03</subscript></entry> | ||
| 41 | <entry>Cr<subscript>01</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Y'<subscript>10</subscript></entry> | ||
| 46 | <entry>Cb<subscript>10</subscript></entry> | ||
| 47 | <entry>Y'<subscript>11</subscript></entry> | ||
| 48 | <entry>Cr<subscript>10</subscript></entry> | ||
| 49 | <entry>Y'<subscript>12</subscript></entry> | ||
| 50 | <entry>Cb<subscript>11</subscript></entry> | ||
| 51 | <entry>Y'<subscript>13</subscript></entry> | ||
| 52 | <entry>Cr<subscript>11</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Y'<subscript>20</subscript></entry> | ||
| 57 | <entry>Cb<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Cr<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Cb<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | <entry>Cr<subscript>21</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Cb<subscript>30</subscript></entry> | ||
| 69 | <entry>Y'<subscript>31</subscript></entry> | ||
| 70 | <entry>Cr<subscript>30</subscript></entry> | ||
| 71 | <entry>Y'<subscript>32</subscript></entry> | ||
| 72 | <entry>Cb<subscript>31</subscript></entry> | ||
| 73 | <entry>Y'<subscript>33</subscript></entry> | ||
| 74 | <entry>Cr<subscript>31</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/v4l/pixfmt-yvyu.xml new file mode 100644 index 000000000000..40d17ae39dde --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yvyu.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YVYU"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YVYU</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Y'<subscript>00</subscript></entry> | ||
| 35 | <entry>Cr<subscript>00</subscript></entry> | ||
| 36 | <entry>Y'<subscript>01</subscript></entry> | ||
| 37 | <entry>Cb<subscript>00</subscript></entry> | ||
| 38 | <entry>Y'<subscript>02</subscript></entry> | ||
| 39 | <entry>Cr<subscript>01</subscript></entry> | ||
| 40 | <entry>Y'<subscript>03</subscript></entry> | ||
| 41 | <entry>Cb<subscript>01</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Y'<subscript>10</subscript></entry> | ||
| 46 | <entry>Cr<subscript>10</subscript></entry> | ||
| 47 | <entry>Y'<subscript>11</subscript></entry> | ||
| 48 | <entry>Cb<subscript>10</subscript></entry> | ||
| 49 | <entry>Y'<subscript>12</subscript></entry> | ||
| 50 | <entry>Cr<subscript>11</subscript></entry> | ||
| 51 | <entry>Y'<subscript>13</subscript></entry> | ||
| 52 | <entry>Cb<subscript>11</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Y'<subscript>20</subscript></entry> | ||
| 57 | <entry>Cr<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Cb<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Cr<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | <entry>Cb<subscript>21</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Cr<subscript>30</subscript></entry> | ||
| 69 | <entry>Y'<subscript>31</subscript></entry> | ||
| 70 | <entry>Cb<subscript>30</subscript></entry> | ||
| 71 | <entry>Y'<subscript>32</subscript></entry> | ||
| 72 | <entry>Cr<subscript>31</subscript></entry> | ||
| 73 | <entry>Y'<subscript>33</subscript></entry> | ||
| 74 | <entry>Cb<subscript>31</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml new file mode 100644 index 000000000000..7d396a3785f5 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt.xml | |||
| @@ -0,0 +1,801 @@ | |||
| 1 | <title>Image Formats</title> | ||
| 2 | |||
| 3 | <para>The V4L2 API was primarily designed for devices exchanging | ||
| 4 | image data with applications. The | ||
| 5 | <structname>v4l2_pix_format</structname> structure defines the format | ||
| 6 | and layout of an image in memory. Image formats are negotiated with | ||
| 7 | the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video | ||
| 8 | capturing and output, for overlay frame buffer formats see also | ||
| 9 | &VIDIOC-G-FBUF;.)</para> | ||
| 10 | |||
| 11 | <table pgwide="1" frame="none" id="v4l2-pix-format"> | ||
| 12 | <title>struct <structname>v4l2_pix_format</structname></title> | ||
| 13 | <tgroup cols="3"> | ||
| 14 | &cs-str; | ||
| 15 | <tbody valign="top"> | ||
| 16 | <row> | ||
| 17 | <entry>__u32</entry> | ||
| 18 | <entry><structfield>width</structfield></entry> | ||
| 19 | <entry>Image width in pixels.</entry> | ||
| 20 | </row> | ||
| 21 | <row> | ||
| 22 | <entry>__u32</entry> | ||
| 23 | <entry><structfield>height</structfield></entry> | ||
| 24 | <entry>Image height in pixels.</entry> | ||
| 25 | </row> | ||
| 26 | <row> | ||
| 27 | <entry spanname="hspan">Applications set these fields to | ||
| 28 | request an image size, drivers return the closest possible values. In | ||
| 29 | case of planar formats the <structfield>width</structfield> and | ||
| 30 | <structfield>height</structfield> applies to the largest plane. To | ||
| 31 | avoid ambiguities drivers must return values rounded up to a multiple | ||
| 32 | of the scale factor of any smaller planes. For example when the image | ||
| 33 | format is YUV 4:2:0, <structfield>width</structfield> and | ||
| 34 | <structfield>height</structfield> must be multiples of two.</entry> | ||
| 35 | </row> | ||
| 36 | <row> | ||
| 37 | <entry>__u32</entry> | ||
| 38 | <entry><structfield>pixelformat</structfield></entry> | ||
| 39 | <entry>The pixel format or type of compression, set by the | ||
| 40 | application. This is a little endian <link | ||
| 41 | linkend="v4l2-fourcc">four character code</link>. V4L2 defines | ||
| 42 | standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref | ||
| 43 | linkend="yuv-formats" />, and reserved codes in <xref | ||
| 44 | linkend="reserved-formats" /></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>&v4l2-field;</entry> | ||
| 48 | <entry><structfield>field</structfield></entry> | ||
| 49 | <entry>Video images are typically interlaced. Applications | ||
| 50 | can request to capture or output only the top or bottom field, or both | ||
| 51 | fields interlaced or sequentially stored in one buffer or alternating | ||
| 52 | in separate buffers. Drivers return the actual field order selected. | ||
| 53 | For details see <xref linkend="field-order" />.</entry> | ||
| 54 | </row> | ||
| 55 | <row> | ||
| 56 | <entry>__u32</entry> | ||
| 57 | <entry><structfield>bytesperline</structfield></entry> | ||
| 58 | <entry>Distance in bytes between the leftmost pixels in two | ||
| 59 | adjacent lines.</entry> | ||
| 60 | </row> | ||
| 61 | <row> | ||
| 62 | <entry spanname="hspan"><para>Both applications and drivers | ||
| 63 | can set this field to request padding bytes at the end of each line. | ||
| 64 | Drivers however may ignore the value requested by the application, | ||
| 65 | returning <structfield>width</structfield> times bytes per pixel or a | ||
| 66 | larger value required by the hardware. That implies applications can | ||
| 67 | just set this field to zero to get a reasonable | ||
| 68 | default.</para><para>Video hardware may access padding bytes, | ||
| 69 | therefore they must reside in accessible memory. Consider cases where | ||
| 70 | padding bytes after the last line of an image cross a system page | ||
| 71 | boundary. Input devices may write padding bytes, the value is | ||
| 72 | undefined. Output devices ignore the contents of padding | ||
| 73 | bytes.</para><para>When the image format is planar the | ||
| 74 | <structfield>bytesperline</structfield> value applies to the largest | ||
| 75 | plane and is divided by the same factor as the | ||
| 76 | <structfield>width</structfield> field for any smaller planes. For | ||
| 77 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many | ||
| 78 | padding bytes following each line as the Y plane. To avoid ambiguities | ||
| 79 | drivers must return a <structfield>bytesperline</structfield> value | ||
| 80 | rounded up to a multiple of the scale factor.</para></entry> | ||
| 81 | </row> | ||
| 82 | <row> | ||
| 83 | <entry>__u32</entry> | ||
| 84 | <entry><structfield>sizeimage</structfield></entry> | ||
| 85 | <entry>Size in bytes of the buffer to hold a complete image, | ||
| 86 | set by the driver. Usually this is | ||
| 87 | <structfield>bytesperline</structfield> times | ||
| 88 | <structfield>height</structfield>. When the image consists of variable | ||
| 89 | length compressed data this is the maximum number of bytes required to | ||
| 90 | hold an image.</entry> | ||
| 91 | </row> | ||
| 92 | <row> | ||
| 93 | <entry>&v4l2-colorspace;</entry> | ||
| 94 | <entry><structfield>colorspace</structfield></entry> | ||
| 95 | <entry>This information supplements the | ||
| 96 | <structfield>pixelformat</structfield> and must be set by the driver, | ||
| 97 | see <xref linkend="colorspaces" />.</entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>__u32</entry> | ||
| 101 | <entry><structfield>priv</structfield></entry> | ||
| 102 | <entry>Reserved for custom (driver defined) additional | ||
| 103 | information about formats. When not used drivers and applications must | ||
| 104 | set this field to zero.</entry> | ||
| 105 | </row> | ||
| 106 | </tbody> | ||
| 107 | </tgroup> | ||
| 108 | </table> | ||
| 109 | |||
| 110 | <section> | ||
| 111 | <title>Standard Image Formats</title> | ||
| 112 | |||
| 113 | <para>In order to exchange images between drivers and | ||
| 114 | applications, it is necessary to have standard image data formats | ||
| 115 | which both sides will interpret the same way. V4L2 includes several | ||
| 116 | such formats, and this section is intended to be an unambiguous | ||
| 117 | specification of the standard image data formats in V4L2.</para> | ||
| 118 | |||
| 119 | <para>V4L2 drivers are not limited to these formats, however. | ||
| 120 | Driver-specific formats are possible. In that case the application may | ||
| 121 | depend on a codec to convert images to one of the standard formats | ||
| 122 | when needed. But the data can still be stored and retrieved in the | ||
| 123 | proprietary format. For example, a device may support a proprietary | ||
| 124 | compressed format. Applications can still capture and save the data in | ||
| 125 | the compressed format, saving much disk space, and later use a codec | ||
| 126 | to convert the images to the X Windows screen format when the video is | ||
| 127 | to be displayed.</para> | ||
| 128 | |||
| 129 | <para>Even so, ultimately, some standard formats are needed, so | ||
| 130 | the V4L2 specification would not be complete without well-defined | ||
| 131 | standard formats.</para> | ||
| 132 | |||
| 133 | <para>The V4L2 standard formats are mainly uncompressed formats. The | ||
| 134 | pixels are always arranged in memory from left to right, and from top | ||
| 135 | to bottom. The first byte of data in the image buffer is always for | ||
| 136 | the leftmost pixel of the topmost row. Following that is the pixel | ||
| 137 | immediately to its right, and so on until the end of the top row of | ||
| 138 | pixels. Following the rightmost pixel of the row there may be zero or | ||
| 139 | more bytes of padding to guarantee that each row of pixel data has a | ||
| 140 | certain alignment. Following the pad bytes, if any, is data for the | ||
| 141 | leftmost pixel of the second row from the top, and so on. The last row | ||
| 142 | has just as many pad bytes after it as the other rows.</para> | ||
| 143 | |||
| 144 | <para>In V4L2 each format has an identifier which looks like | ||
| 145 | <constant>PIX_FMT_XXX</constant>, defined in the <link | ||
| 146 | linkend="videodev">videodev.h</link> header file. These identifiers | ||
| 147 | represent <link linkend="v4l2-fourcc">four character codes</link> | ||
| 148 | which are also listed below, however they are not the same as those | ||
| 149 | used in the Windows world.</para> | ||
| 150 | </section> | ||
| 151 | |||
| 152 | <section id="colorspaces"> | ||
| 153 | <title>Colorspaces</title> | ||
| 154 | |||
| 155 | <para>[intro]</para> | ||
| 156 | |||
| 157 | <!-- See proposal by Billy Biggs, video4linux-list@redhat.com | ||
| 158 | on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and | ||
| 159 | http://vektor.theorem.ca/graphics/ycbcr/ and | ||
| 160 | http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> | ||
| 161 | |||
| 162 | <para> | ||
| 163 | <variablelist> | ||
| 164 | <varlistentry> | ||
| 165 | <term>Gamma Correction</term> | ||
| 166 | <listitem> | ||
| 167 | <para>[to do]</para> | ||
| 168 | <para>E'<subscript>R</subscript> = f(R)</para> | ||
| 169 | <para>E'<subscript>G</subscript> = f(G)</para> | ||
| 170 | <para>E'<subscript>B</subscript> = f(B)</para> | ||
| 171 | </listitem> | ||
| 172 | </varlistentry> | ||
| 173 | <varlistentry> | ||
| 174 | <term>Construction of luminance and color-difference | ||
| 175 | signals</term> | ||
| 176 | <listitem> | ||
| 177 | <para>[to do]</para> | ||
| 178 | <para>E'<subscript>Y</subscript> = | ||
| 179 | Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 180 | + Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 181 | + Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 182 | <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> | ||
| 183 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 184 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 185 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 186 | <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> | ||
| 187 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 188 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 189 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 190 | </listitem> | ||
| 191 | </varlistentry> | ||
| 192 | <varlistentry> | ||
| 193 | <term>Re-normalized color-difference signals</term> | ||
| 194 | <listitem> | ||
| 195 | <para>The color-difference signals are scaled back to unity | ||
| 196 | range [-0.5;+0.5]:</para> | ||
| 197 | <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> | ||
| 198 | <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> | ||
| 199 | <para>P<subscript>B</subscript> = | ||
| 200 | K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = | ||
| 201 | 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> | ||
| 202 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> | ||
| 203 | + 0.5 E'<subscript>B</subscript></para> | ||
| 204 | <para>P<subscript>R</subscript> = | ||
| 205 | K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = | ||
| 206 | 0.5 E'<subscript>R</subscript> | ||
| 207 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> | ||
| 208 | + 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> | ||
| 209 | </listitem> | ||
| 210 | </varlistentry> | ||
| 211 | <varlistentry> | ||
| 212 | <term>Quantization</term> | ||
| 213 | <listitem> | ||
| 214 | <para>[to do]</para> | ||
| 215 | <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> | ||
| 216 | <para>C<subscript>B</subscript> = (Chrom. Levels - 1) | ||
| 217 | · P<subscript>B</subscript> + Chrom. Offset</para> | ||
| 218 | <para>C<subscript>R</subscript> = (Chrom. Levels - 1) | ||
| 219 | · P<subscript>R</subscript> + Chrom. Offset</para> | ||
| 220 | <para>Rounding to the nearest integer and clamping to the range | ||
| 221 | [0;255] finally yields the digital color components Y'CbCr | ||
| 222 | stored in YUV images.</para> | ||
| 223 | </listitem> | ||
| 224 | </varlistentry> | ||
| 225 | </variablelist> | ||
| 226 | </para> | ||
| 227 | |||
| 228 | <example> | ||
| 229 | <title>ITU-R Rec. BT.601 color conversion</title> | ||
| 230 | |||
| 231 | <para>Forward Transformation</para> | ||
| 232 | |||
| 233 | <programlisting> | ||
| 234 | int ER, EG, EB; /* gamma corrected RGB input [0;255] */ | ||
| 235 | int Y1, Cb, Cr; /* output [0;255] */ | ||
| 236 | |||
| 237 | double r, g, b; /* temporaries */ | ||
| 238 | double y1, pb, pr; | ||
| 239 | |||
| 240 | int | ||
| 241 | clamp (double x) | ||
| 242 | { | ||
| 243 | int r = x; /* round to nearest */ | ||
| 244 | |||
| 245 | if (r < 0) return 0; | ||
| 246 | else if (r > 255) return 255; | ||
| 247 | else return r; | ||
| 248 | } | ||
| 249 | |||
| 250 | r = ER / 255.0; | ||
| 251 | g = EG / 255.0; | ||
| 252 | b = EB / 255.0; | ||
| 253 | |||
| 254 | y1 = 0.299 * r + 0.587 * g + 0.114 * b; | ||
| 255 | pb = -0.169 * r - 0.331 * g + 0.5 * b; | ||
| 256 | pr = 0.5 * r - 0.419 * g - 0.081 * b; | ||
| 257 | |||
| 258 | Y1 = clamp (219 * y1 + 16); | ||
| 259 | Cb = clamp (224 * pb + 128); | ||
| 260 | Cr = clamp (224 * pr + 128); | ||
| 261 | |||
| 262 | /* or shorter */ | ||
| 263 | |||
| 264 | y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; | ||
| 265 | |||
| 266 | Y1 = clamp ( (219 / 255.0) * y1 + 16); | ||
| 267 | Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); | ||
| 268 | Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); | ||
| 269 | </programlisting> | ||
| 270 | |||
| 271 | <para>Inverse Transformation</para> | ||
| 272 | |||
| 273 | <programlisting> | ||
| 274 | int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ | ||
| 275 | int ER, EG, EB; /* output [0;255] */ | ||
| 276 | |||
| 277 | double r, g, b; /* temporaries */ | ||
| 278 | double y1, pb, pr; | ||
| 279 | |||
| 280 | int | ||
| 281 | clamp (double x) | ||
| 282 | { | ||
| 283 | int r = x; /* round to nearest */ | ||
| 284 | |||
| 285 | if (r < 0) return 0; | ||
| 286 | else if (r > 255) return 255; | ||
| 287 | else return r; | ||
| 288 | } | ||
| 289 | |||
| 290 | y1 = (255 / 219.0) * (Y1 - 16); | ||
| 291 | pb = (255 / 224.0) * (Cb - 128); | ||
| 292 | pr = (255 / 224.0) * (Cr - 128); | ||
| 293 | |||
| 294 | r = 1.0 * y1 + 0 * pb + 1.402 * pr; | ||
| 295 | g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; | ||
| 296 | b = 1.0 * y1 + 1.772 * pb + 0 * pr; | ||
| 297 | |||
| 298 | ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ | ||
| 299 | EG = clamp (g * 255); | ||
| 300 | EB = clamp (b * 255); | ||
| 301 | </programlisting> | ||
| 302 | </example> | ||
| 303 | |||
| 304 | <table pgwide="1" id="v4l2-colorspace" orient="land"> | ||
| 305 | <title>enum v4l2_colorspace</title> | ||
| 306 | <tgroup cols="11" align="center"> | ||
| 307 | <colspec align="left" /> | ||
| 308 | <colspec align="center" /> | ||
| 309 | <colspec align="left" /> | ||
| 310 | <colspec colname="cr" /> | ||
| 311 | <colspec colname="cg" /> | ||
| 312 | <colspec colname="cb" /> | ||
| 313 | <colspec colname="wp" /> | ||
| 314 | <colspec colname="gc" /> | ||
| 315 | <colspec colname="lum" /> | ||
| 316 | <colspec colname="qy" /> | ||
| 317 | <colspec colname="qc" /> | ||
| 318 | <spanspec namest="cr" nameend="cb" spanname="chrom" /> | ||
| 319 | <spanspec namest="qy" nameend="qc" spanname="quant" /> | ||
| 320 | <spanspec namest="lum" nameend="qc" spanname="spam" /> | ||
| 321 | <thead> | ||
| 322 | <row> | ||
| 323 | <entry morerows="1">Identifier</entry> | ||
| 324 | <entry morerows="1">Value</entry> | ||
| 325 | <entry morerows="1">Description</entry> | ||
| 326 | <entry spanname="chrom">Chromaticities<footnote> | ||
| 327 | <para>The coordinates of the color primaries are | ||
| 328 | given in the CIE system (1931)</para> | ||
| 329 | </footnote></entry> | ||
| 330 | <entry morerows="1">White Point</entry> | ||
| 331 | <entry morerows="1">Gamma Correction</entry> | ||
| 332 | <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> | ||
| 333 | <entry spanname="quant">Quantization</entry> | ||
| 334 | </row> | ||
| 335 | <row> | ||
| 336 | <entry>Red</entry> | ||
| 337 | <entry>Green</entry> | ||
| 338 | <entry>Blue</entry> | ||
| 339 | <entry>Y'</entry> | ||
| 340 | <entry>Cb, Cr</entry> | ||
| 341 | </row> | ||
| 342 | </thead> | ||
| 343 | <tbody valign="top"> | ||
| 344 | <row> | ||
| 345 | <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> | ||
| 346 | <entry>1</entry> | ||
| 347 | <entry>NTSC/PAL according to <xref linkend="smpte170m" />, | ||
| 348 | <xref linkend="itu601" /></entry> | ||
| 349 | <entry>x = 0.630, y = 0.340</entry> | ||
| 350 | <entry>x = 0.310, y = 0.595</entry> | ||
| 351 | <entry>x = 0.155, y = 0.070</entry> | ||
| 352 | <entry>x = 0.3127, y = 0.3290, | ||
| 353 | Illuminant D<subscript>65</subscript></entry> | ||
| 354 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 355 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 356 | <entry>0.299 E'<subscript>R</subscript> | ||
| 357 | + 0.587 E'<subscript>G</subscript> | ||
| 358 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 359 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 360 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 361 | </row> | ||
| 362 | <row> | ||
| 363 | <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> | ||
| 364 | <entry>2</entry> | ||
| 365 | <entry>1125-Line (US) HDTV, see <xref | ||
| 366 | linkend="smpte240m" /></entry> | ||
| 367 | <entry>x = 0.630, y = 0.340</entry> | ||
| 368 | <entry>x = 0.310, y = 0.595</entry> | ||
| 369 | <entry>x = 0.155, y = 0.070</entry> | ||
| 370 | <entry>x = 0.3127, y = 0.3290, | ||
| 371 | Illuminant D<subscript>65</subscript></entry> | ||
| 372 | <entry>E' = 4 I for I ≤0.0228, | ||
| 373 | 1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> | ||
| 374 | <entry>0.212 E'<subscript>R</subscript> | ||
| 375 | + 0.701 E'<subscript>G</subscript> | ||
| 376 | + 0.087 E'<subscript>B</subscript></entry> | ||
| 377 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 378 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 379 | </row> | ||
| 380 | <row> | ||
| 381 | <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> | ||
| 382 | <entry>3</entry> | ||
| 383 | <entry>HDTV and modern devices, see <xref | ||
| 384 | linkend="itu709" /></entry> | ||
| 385 | <entry>x = 0.640, y = 0.330</entry> | ||
| 386 | <entry>x = 0.300, y = 0.600</entry> | ||
| 387 | <entry>x = 0.150, y = 0.060</entry> | ||
| 388 | <entry>x = 0.3127, y = 0.3290, | ||
| 389 | Illuminant D<subscript>65</subscript></entry> | ||
| 390 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 391 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 392 | <entry>0.2125 E'<subscript>R</subscript> | ||
| 393 | + 0.7154 E'<subscript>G</subscript> | ||
| 394 | + 0.0721 E'<subscript>B</subscript></entry> | ||
| 395 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 396 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 397 | </row> | ||
| 398 | <row> | ||
| 399 | <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> | ||
| 400 | <entry>4</entry> | ||
| 401 | <entry>Broken Bt878 extents<footnote> | ||
| 402 | <para>The ubiquitous Bt878 video capture chip | ||
| 403 | quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range | ||
| 404 | of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … | ||
| 405 | 235. This is not a typo in the Bt878 documentation, it has been | ||
| 406 | implemented in silicon. The chroma extents are unclear.</para> | ||
| 407 | </footnote>, <xref linkend="itu601" /></entry> | ||
| 408 | <entry>?</entry> | ||
| 409 | <entry>?</entry> | ||
| 410 | <entry>?</entry> | ||
| 411 | <entry>?</entry> | ||
| 412 | <entry>?</entry> | ||
| 413 | <entry>0.299 E'<subscript>R</subscript> | ||
| 414 | + 0.587 E'<subscript>G</subscript> | ||
| 415 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 416 | <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> | ||
| 417 | <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> | ||
| 418 | </row> | ||
| 419 | <row> | ||
| 420 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> | ||
| 421 | <entry>5</entry> | ||
| 422 | <entry>M/NTSC<footnote> | ||
| 423 | <para>No identifier exists for M/PAL which uses | ||
| 424 | the chromaticities of M/NTSC, the remaining parameters are equal to B and | ||
| 425 | G/PAL.</para> | ||
| 426 | </footnote> according to <xref linkend="itu470" />, <xref | ||
| 427 | linkend="itu601" /></entry> | ||
| 428 | <entry>x = 0.67, y = 0.33</entry> | ||
| 429 | <entry>x = 0.21, y = 0.71</entry> | ||
| 430 | <entry>x = 0.14, y = 0.08</entry> | ||
| 431 | <entry>x = 0.310, y = 0.316, Illuminant C</entry> | ||
| 432 | <entry>?</entry> | ||
| 433 | <entry>0.299 E'<subscript>R</subscript> | ||
| 434 | + 0.587 E'<subscript>G</subscript> | ||
| 435 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 436 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 437 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 438 | </row> | ||
| 439 | <row> | ||
| 440 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> | ||
| 441 | <entry>6</entry> | ||
| 442 | <entry>625-line PAL and SECAM systems according to <xref | ||
| 443 | linkend="itu470" />, <xref linkend="itu601" /></entry> | ||
| 444 | <entry>x = 0.64, y = 0.33</entry> | ||
| 445 | <entry>x = 0.29, y = 0.60</entry> | ||
| 446 | <entry>x = 0.15, y = 0.06</entry> | ||
| 447 | <entry>x = 0.313, y = 0.329, | ||
| 448 | Illuminant D<subscript>65</subscript></entry> | ||
| 449 | <entry>?</entry> | ||
| 450 | <entry>0.299 E'<subscript>R</subscript> | ||
| 451 | + 0.587 E'<subscript>G</subscript> | ||
| 452 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 453 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 454 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 455 | </row> | ||
| 456 | <row> | ||
| 457 | <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> | ||
| 458 | <entry>7</entry> | ||
| 459 | <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> | ||
| 460 | <entry>?</entry> | ||
| 461 | <entry>?</entry> | ||
| 462 | <entry>?</entry> | ||
| 463 | <entry>?</entry> | ||
| 464 | <entry>?</entry> | ||
| 465 | <entry>0.299 E'<subscript>R</subscript> | ||
| 466 | + 0.587 E'<subscript>G</subscript> | ||
| 467 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 468 | <entry>256 E'<subscript>Y</subscript> + 16<footnote> | ||
| 469 | <para>Note JFIF quantizes | ||
| 470 | Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and | ||
| 471 | [-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals | ||
| 472 | are still clamped to [0;255].</para> | ||
| 473 | </footnote></entry> | ||
| 474 | <entry>256 P<subscript>B,R</subscript> + 128</entry> | ||
| 475 | </row> | ||
| 476 | <row> | ||
| 477 | <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> | ||
| 478 | <entry>8</entry> | ||
| 479 | <entry>[?]</entry> | ||
| 480 | <entry>x = 0.640, y = 0.330</entry> | ||
| 481 | <entry>x = 0.300, y = 0.600</entry> | ||
| 482 | <entry>x = 0.150, y = 0.060</entry> | ||
| 483 | <entry>x = 0.3127, y = 0.3290, | ||
| 484 | Illuminant D<subscript>65</subscript></entry> | ||
| 485 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 486 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 487 | <entry spanname="spam">n/a</entry> | ||
| 488 | </row> | ||
| 489 | </tbody> | ||
| 490 | </tgroup> | ||
| 491 | </table> | ||
| 492 | </section> | ||
| 493 | |||
| 494 | <section id="pixfmt-indexed"> | ||
| 495 | <title>Indexed Format</title> | ||
| 496 | |||
| 497 | <para>In this format each pixel is represented by an 8 bit index | ||
| 498 | into a 256 entry ARGB palette. It is intended for <link | ||
| 499 | linkend="osd">Video Output Overlays</link> only. There are no ioctls to | ||
| 500 | access the palette, this must be done with ioctls of the Linux framebuffer API.</para> | ||
| 501 | |||
| 502 | <table pgwide="0" frame="none"> | ||
| 503 | <title>Indexed Image Format</title> | ||
| 504 | <tgroup cols="37" align="center"> | ||
| 505 | <colspec colname="id" align="left" /> | ||
| 506 | <colspec colname="fourcc" /> | ||
| 507 | <colspec colname="bit" /> | ||
| 508 | |||
| 509 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 510 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 511 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 512 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 513 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 514 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 515 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 516 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 517 | |||
| 518 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 519 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 520 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 521 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 522 | <thead> | ||
| 523 | <row> | ||
| 524 | <entry>Identifier</entry> | ||
| 525 | <entry>Code</entry> | ||
| 526 | <entry> </entry> | ||
| 527 | <entry spanname="b0">Byte 0</entry> | ||
| 528 | </row> | ||
| 529 | <row> | ||
| 530 | <entry> </entry> | ||
| 531 | <entry> </entry> | ||
| 532 | <entry>Bit</entry> | ||
| 533 | <entry>7</entry> | ||
| 534 | <entry>6</entry> | ||
| 535 | <entry>5</entry> | ||
| 536 | <entry>4</entry> | ||
| 537 | <entry>3</entry> | ||
| 538 | <entry>2</entry> | ||
| 539 | <entry>1</entry> | ||
| 540 | <entry>0</entry> | ||
| 541 | </row> | ||
| 542 | </thead> | ||
| 543 | <tbody valign="top"> | ||
| 544 | <row id="V4L2-PIX-FMT-PAL8"> | ||
| 545 | <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry> | ||
| 546 | <entry>'PAL8'</entry> | ||
| 547 | <entry></entry> | ||
| 548 | <entry>i<subscript>7</subscript></entry> | ||
| 549 | <entry>i<subscript>6</subscript></entry> | ||
| 550 | <entry>i<subscript>5</subscript></entry> | ||
| 551 | <entry>i<subscript>4</subscript></entry> | ||
| 552 | <entry>i<subscript>3</subscript></entry> | ||
| 553 | <entry>i<subscript>2</subscript></entry> | ||
| 554 | <entry>i<subscript>1</subscript></entry> | ||
| 555 | <entry>i<subscript>0</subscript></entry> | ||
| 556 | </row> | ||
| 557 | </tbody> | ||
| 558 | </tgroup> | ||
| 559 | </table> | ||
| 560 | </section> | ||
| 561 | |||
| 562 | <section id="pixfmt-rgb"> | ||
| 563 | <title>RGB Formats</title> | ||
| 564 | |||
| 565 | &sub-packed-rgb; | ||
| 566 | &sub-sbggr8; | ||
| 567 | &sub-sgbrg8; | ||
| 568 | &sub-sgrbg8; | ||
| 569 | &sub-sbggr16; | ||
| 570 | </section> | ||
| 571 | |||
| 572 | <section id="yuv-formats"> | ||
| 573 | <title>YUV Formats</title> | ||
| 574 | |||
| 575 | <para>YUV is the format native to TV broadcast and composite video | ||
| 576 | signals. It separates the brightness information (Y) from the color | ||
| 577 | information (U and V or Cb and Cr). The color information consists of | ||
| 578 | red and blue <emphasis>color difference</emphasis> signals, this way | ||
| 579 | the green component can be reconstructed by subtracting from the | ||
| 580 | brightness component. See <xref linkend="colorspaces" /> for conversion | ||
| 581 | examples. YUV was chosen because early television would only transmit | ||
| 582 | brightness information. To add color in a way compatible with existing | ||
| 583 | receivers a new signal carrier was added to transmit the color | ||
| 584 | difference signals. Secondary in the YUV format the U and V components | ||
| 585 | usually have lower resolution than the Y component. This is an analog | ||
| 586 | video compression technique taking advantage of a property of the | ||
| 587 | human visual system, being more sensitive to brightness | ||
| 588 | information.</para> | ||
| 589 | |||
| 590 | &sub-packed-yuv; | ||
| 591 | &sub-grey; | ||
| 592 | &sub-y16; | ||
| 593 | &sub-yuyv; | ||
| 594 | &sub-uyvy; | ||
| 595 | &sub-yvyu; | ||
| 596 | &sub-vyuy; | ||
| 597 | &sub-y41p; | ||
| 598 | &sub-yuv420; | ||
| 599 | &sub-yuv410; | ||
| 600 | &sub-yuv422p; | ||
| 601 | &sub-yuv411p; | ||
| 602 | &sub-nv12; | ||
| 603 | &sub-nv16; | ||
| 604 | </section> | ||
| 605 | |||
| 606 | <section> | ||
| 607 | <title>Compressed Formats</title> | ||
| 608 | |||
| 609 | <table pgwide="1" frame="none" id="compressed-formats"> | ||
| 610 | <title>Compressed Image Formats</title> | ||
| 611 | <tgroup cols="3" align="left"> | ||
| 612 | &cs-def; | ||
| 613 | <thead> | ||
| 614 | <row> | ||
| 615 | <entry>Identifier</entry> | ||
| 616 | <entry>Code</entry> | ||
| 617 | <entry>Details</entry> | ||
| 618 | </row> | ||
| 619 | </thead> | ||
| 620 | <tbody valign="top"> | ||
| 621 | <row id="V4L2-PIX-FMT-JPEG"> | ||
| 622 | <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> | ||
| 623 | <entry>'JPEG'</entry> | ||
| 624 | <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, | ||
| 625 | &VIDIOC-S-JPEGCOMP;.</entry> | ||
| 626 | </row> | ||
| 627 | <row id="V4L2-PIX-FMT-MPEG"> | ||
| 628 | <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> | ||
| 629 | <entry>'MPEG'</entry> | ||
| 630 | <entry>MPEG stream. The actual format is determined by | ||
| 631 | extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see | ||
| 632 | <xref linkend="mpeg-control-id" />.</entry> | ||
| 633 | </row> | ||
| 634 | </tbody> | ||
| 635 | </tgroup> | ||
| 636 | </table> | ||
| 637 | </section> | ||
| 638 | |||
| 639 | <section id="pixfmt-reserved"> | ||
| 640 | <title>Reserved Format Identifiers</title> | ||
| 641 | |||
| 642 | <para>These formats are not defined by this specification, they | ||
| 643 | are just listed for reference and to avoid naming conflicts. If you | ||
| 644 | want to register your own format, send an e-mail to the linux-media mailing | ||
| 645 | list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> | ||
| 646 | file. If you want to share your format with other developers add a | ||
| 647 | link to your documentation and send a copy to the linux-media mailing list | ||
| 648 | for inclusion in this section. If you think your format should be listed | ||
| 649 | in a standard format section please make a proposal on the linux-media mailing | ||
| 650 | list.</para> | ||
| 651 | |||
| 652 | <table pgwide="1" frame="none" id="reserved-formats"> | ||
| 653 | <title>Reserved Image Formats</title> | ||
| 654 | <tgroup cols="3" align="left"> | ||
| 655 | &cs-def; | ||
| 656 | <thead> | ||
| 657 | <row> | ||
| 658 | <entry>Identifier</entry> | ||
| 659 | <entry>Code</entry> | ||
| 660 | <entry>Details</entry> | ||
| 661 | </row> | ||
| 662 | </thead> | ||
| 663 | <tbody valign="top"> | ||
| 664 | <row id="V4L2-PIX-FMT-DV"> | ||
| 665 | <entry><constant>V4L2_PIX_FMT_DV</constant></entry> | ||
| 666 | <entry>'dvsd'</entry> | ||
| 667 | <entry>unknown</entry> | ||
| 668 | </row> | ||
| 669 | <row id="V4L2-PIX-FMT-ET61X251"> | ||
| 670 | <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> | ||
| 671 | <entry>'E625'</entry> | ||
| 672 | <entry>Compressed format of the ET61X251 driver.</entry> | ||
| 673 | </row> | ||
| 674 | <row id="V4L2-PIX-FMT-HI240"> | ||
| 675 | <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> | ||
| 676 | <entry>'HI24'</entry> | ||
| 677 | <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> | ||
| 678 | </row> | ||
| 679 | <row id="V4L2-PIX-FMT-HM12"> | ||
| 680 | <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> | ||
| 681 | <entry>'HM12'</entry> | ||
| 682 | <entry><para>YUV 4:2:0 format used by the | ||
| 683 | IVTV driver, <ulink url="http://www.ivtvdriver.org/"> | ||
| 684 | http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the | ||
| 685 | kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> | ||
| 686 | </para></entry> | ||
| 687 | </row> | ||
| 688 | <row id="V4L2-PIX-FMT-SPCA501"> | ||
| 689 | <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> | ||
| 690 | <entry>'S501'</entry> | ||
| 691 | <entry>YUYV per line used by the gspca driver.</entry> | ||
| 692 | </row> | ||
| 693 | <row id="V4L2-PIX-FMT-SPCA505"> | ||
| 694 | <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> | ||
| 695 | <entry>'S505'</entry> | ||
| 696 | <entry>YYUV per line used by the gspca driver.</entry> | ||
| 697 | </row> | ||
| 698 | <row id="V4L2-PIX-FMT-SPCA508"> | ||
| 699 | <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> | ||
| 700 | <entry>'S508'</entry> | ||
| 701 | <entry>YUVY per line used by the gspca driver.</entry> | ||
| 702 | </row> | ||
| 703 | <row id="V4L2-PIX-FMT-SPCA561"> | ||
| 704 | <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> | ||
| 705 | <entry>'S561'</entry> | ||
| 706 | <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> | ||
| 707 | </row> | ||
| 708 | <row id="V4L2-PIX-FMT-SGRBG10"> | ||
| 709 | <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry> | ||
| 710 | <entry>'DA10'</entry> | ||
| 711 | <entry>10 bit raw Bayer, expanded to 16 bits.</entry> | ||
| 712 | </row> | ||
| 713 | <row id="V4L2-PIX-FMT-SGRBG10DPCM8"> | ||
| 714 | <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry> | ||
| 715 | <entry>'DB10'</entry> | ||
| 716 | <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry> | ||
| 717 | </row> | ||
| 718 | <row id="V4L2-PIX-FMT-PAC207"> | ||
| 719 | <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> | ||
| 720 | <entry>'P207'</entry> | ||
| 721 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | ||
| 722 | </row> | ||
| 723 | <row id="V4L2-PIX-FMT-MR97310A"> | ||
| 724 | <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> | ||
| 725 | <entry>'M310'</entry> | ||
| 726 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | ||
| 727 | </row> | ||
| 728 | <row id="V4L2-PIX-FMT-OV511"> | ||
| 729 | <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> | ||
| 730 | <entry>'O511'</entry> | ||
| 731 | <entry>OV511 JPEG format used by the gspca driver.</entry> | ||
| 732 | </row> | ||
| 733 | <row id="V4L2-PIX-FMT-OV518"> | ||
| 734 | <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> | ||
| 735 | <entry>'O518'</entry> | ||
| 736 | <entry>OV518 JPEG format used by the gspca driver.</entry> | ||
| 737 | </row> | ||
| 738 | <row id="V4L2-PIX-FMT-PJPG"> | ||
| 739 | <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> | ||
| 740 | <entry>'PJPG'</entry> | ||
| 741 | <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> | ||
| 742 | </row> | ||
| 743 | <row id="V4L2-PIX-FMT-SQ905C"> | ||
| 744 | <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> | ||
| 745 | <entry>'905C'</entry> | ||
| 746 | <entry>Compressed RGGB bayer format used by the gspca driver.</entry> | ||
| 747 | </row> | ||
| 748 | <row id="V4L2-PIX-FMT-MJPEG"> | ||
| 749 | <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> | ||
| 750 | <entry>'MJPG'</entry> | ||
| 751 | <entry>Compressed format used by the Zoran driver</entry> | ||
| 752 | </row> | ||
| 753 | <row id="V4L2-PIX-FMT-PWC1"> | ||
| 754 | <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> | ||
| 755 | <entry>'PWC1'</entry> | ||
| 756 | <entry>Compressed format of the PWC driver.</entry> | ||
| 757 | </row> | ||
| 758 | <row id="V4L2-PIX-FMT-PWC2"> | ||
| 759 | <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> | ||
| 760 | <entry>'PWC2'</entry> | ||
| 761 | <entry>Compressed format of the PWC driver.</entry> | ||
| 762 | </row> | ||
| 763 | <row id="V4L2-PIX-FMT-SN9C10X"> | ||
| 764 | <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> | ||
| 765 | <entry>'S910'</entry> | ||
| 766 | <entry>Compressed format of the SN9C102 driver.</entry> | ||
| 767 | </row> | ||
| 768 | <row id="V4L2-PIX-FMT-SN9C20X-I420"> | ||
| 769 | <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> | ||
| 770 | <entry>'S920'</entry> | ||
| 771 | <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> | ||
| 772 | </row> | ||
| 773 | <row id="V4L2-PIX-FMT-WNVA"> | ||
| 774 | <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> | ||
| 775 | <entry>'WNVA'</entry> | ||
| 776 | <entry><para>Used by the Winnov Videum driver, <ulink | ||
| 777 | url="http://www.thedirks.org/winnov/"> | ||
| 778 | http://www.thedirks.org/winnov/</ulink></para></entry> | ||
| 779 | </row> | ||
| 780 | <row id="V4L2-PIX-FMT-TM6000"> | ||
| 781 | <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> | ||
| 782 | <entry>'TM60'</entry> | ||
| 783 | <entry><para>Used by Trident tm6000</para></entry> | ||
| 784 | </row> | ||
| 785 | <row id="V4L2-PIX-FMT-YYUV"> | ||
| 786 | <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> | ||
| 787 | <entry>'YYUV'</entry> | ||
| 788 | <entry>unknown</entry> | ||
| 789 | </row> | ||
| 790 | </tbody> | ||
| 791 | </tgroup> | ||
| 792 | </table> | ||
| 793 | </section> | ||
| 794 | |||
| 795 | <!-- | ||
| 796 | Local Variables: | ||
| 797 | mode: sgml | ||
| 798 | sgml-parent-document: "v4l2.sgml" | ||
| 799 | indent-tabs-mode: nil | ||
| 800 | End: | ||
| 801 | --> | ||
diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml new file mode 100644 index 000000000000..73f5eab091f4 --- /dev/null +++ b/Documentation/DocBook/v4l/remote_controllers.xml | |||
| @@ -0,0 +1,175 @@ | |||
| 1 | <title>Remote Controllers</title> | ||
| 2 | <section id="Remote_controllers_Intro"> | ||
| 3 | <title>Introduction</title> | ||
| 4 | |||
| 5 | <para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each | ||
| 6 | manufacturer has their own type of control. It is not rare for the same manufacturer to ship different | ||
| 7 | types of controls, depending on the device.</para> | ||
| 8 | <para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for | ||
| 9 | different devices. This caused the same IR keyname to be mapped completely differently on | ||
| 10 | different IR devices. This resulted that the same IR keyname to be mapped completely different on | ||
| 11 | different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para> | ||
| 12 | <para>This standard should be used by both V4L/DVB drivers and userspace applications</para> | ||
| 13 | <para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para> | ||
| 14 | |||
| 15 | <table pgwide="1" frame="none" id="rc_standard_keymap"> | ||
| 16 | <title>IR default keymapping</title> | ||
| 17 | <tgroup cols="3"> | ||
| 18 | &cs-str; | ||
| 19 | <tbody valign="top"> | ||
| 20 | <row> | ||
| 21 | <entry>Key code</entry> | ||
| 22 | <entry>Meaning</entry> | ||
| 23 | <entry>Key examples on IR</entry> | ||
| 24 | </row> | ||
| 25 | |||
| 26 | <row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row> | ||
| 27 | |||
| 28 | <row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row> | ||
| 29 | <row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row> | ||
| 30 | <row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row> | ||
| 31 | <row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row> | ||
| 32 | <row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row> | ||
| 33 | <row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row> | ||
| 34 | <row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row> | ||
| 35 | <row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row> | ||
| 36 | <row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row> | ||
| 37 | <row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row> | ||
| 38 | |||
| 39 | <row><entry><emphasis role="bold">Movie play control</emphasis></entry></row> | ||
| 40 | |||
| 41 | <row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>>> / FORWARD</entry></row> | ||
| 42 | <row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry><<< / BACK</entry></row> | ||
| 43 | <row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>>>> / FORWARD</entry></row> | ||
| 44 | <row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row> | ||
| 45 | <row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row> | ||
| 46 | <row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry><< / PREV / PREVIOUS</entry></row> | ||
| 47 | <row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row> | ||
| 48 | <row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row> | ||
| 49 | <row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / ></entry></row> | ||
| 50 | <row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row> | ||
| 51 | <row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row> | ||
| 52 | <row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row> | ||
| 53 | <row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row> | ||
| 54 | <row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row> | ||
| 55 | <row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row> | ||
| 56 | <row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row> | ||
| 57 | <row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row> | ||
| 58 | |||
| 59 | <row><entry><emphasis role="bold">Image control</emphasis></entry></row> | ||
| 60 | |||
| 61 | <row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row> | ||
| 62 | <row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row> | ||
| 63 | |||
| 64 | <row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row> | ||
| 65 | <row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row> | ||
| 66 | <row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row> | ||
| 67 | |||
| 68 | <row><entry><emphasis role="bold">Audio control</emphasis></entry></row> | ||
| 69 | |||
| 70 | <row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row> | ||
| 71 | <row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row> | ||
| 72 | <row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row> | ||
| 73 | <row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row> | ||
| 74 | <row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row> | ||
| 75 | <row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row> | ||
| 76 | |||
| 77 | <row><entry><emphasis role="bold">Channel control</emphasis></entry></row> | ||
| 78 | |||
| 79 | <row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row> | ||
| 80 | <row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row> | ||
| 81 | <row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row> | ||
| 82 | <row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row> | ||
| 83 | <row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row> | ||
| 84 | |||
| 85 | <row><entry><emphasis role="bold">Colored keys</emphasis></entry></row> | ||
| 86 | |||
| 87 | <row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row> | ||
| 88 | <row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row> | ||
| 89 | <row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row> | ||
| 90 | <row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row> | ||
| 91 | |||
| 92 | <row><entry><emphasis role="bold">Media selection</emphasis></entry></row> | ||
| 93 | |||
| 94 | <row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row> | ||
| 95 | <row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row> | ||
| 96 | <row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-> ) / CLOSE / OPEN</entry></row> | ||
| 97 | |||
| 98 | <row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row> | ||
| 99 | <row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row> | ||
| 100 | <row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row> | ||
| 101 | <row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row> | ||
| 102 | <row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row> | ||
| 103 | <row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row> | ||
| 104 | <row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row> | ||
| 105 | |||
| 106 | <row><entry><emphasis role="bold">Power control</emphasis></entry></row> | ||
| 107 | |||
| 108 | <row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row> | ||
| 109 | <row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row> | ||
| 110 | <row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row> | ||
| 111 | <row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row> | ||
| 112 | |||
| 113 | <row><entry><emphasis role="bold">Window control</emphasis></entry></row> | ||
| 114 | |||
| 115 | <row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row> | ||
| 116 | <row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row> | ||
| 117 | <row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row> | ||
| 118 | <row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row> | ||
| 119 | <row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row> | ||
| 120 | <row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row> | ||
| 121 | <row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row> | ||
| 122 | <row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row> | ||
| 123 | |||
| 124 | <row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row> | ||
| 125 | |||
| 126 | <row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row> | ||
| 127 | <row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row> | ||
| 128 | <row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row> | ||
| 129 | <row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row> | ||
| 130 | <row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row> | ||
| 131 | <row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row> | ||
| 132 | <row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row> | ||
| 133 | <row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row> | ||
| 134 | <row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row> | ||
| 135 | |||
| 136 | <row><entry><emphasis role="bold">Miscelaneous keys</emphasis></entry></row> | ||
| 137 | |||
| 138 | <row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row> | ||
| 139 | <row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row> | ||
| 140 | |||
| 141 | </tbody> | ||
| 142 | </tgroup> | ||
| 143 | </table> | ||
| 144 | |||
| 145 | <para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para> | ||
| 146 | |||
| 147 | <table pgwide="1" frame="none" id="rc_keymap_notes"> | ||
| 148 | <title>Notes</title> | ||
| 149 | <tgroup cols="1"> | ||
| 150 | &cs-str; | ||
| 151 | <tbody valign="top"> | ||
| 152 | <row> | ||
| 153 | <entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry> | ||
| 154 | </row><row> | ||
| 155 | <entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry> | ||
| 156 | </row><row> | ||
| 157 | <entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry> | ||
| 158 | </row><row> | ||
| 159 | <entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry> | ||
| 160 | </row> | ||
| 161 | </tbody> | ||
| 162 | </tgroup> | ||
| 163 | </table> | ||
| 164 | |||
| 165 | </section> | ||
| 166 | |||
| 167 | <section id="Remote_controllers_table_change"> | ||
| 168 | <title>Changing default Remote Controller mappings</title> | ||
| 169 | <para>The event interface provides two ioctls to be used against | ||
| 170 | the /dev/input/event device, to allow changing the default | ||
| 171 | keymapping.</para> | ||
| 172 | |||
| 173 | <para>This program demonstrates how to replace the keymap tables.</para> | ||
| 174 | &sub-keytable-c; | ||
| 175 | </section> | ||
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml new file mode 100644 index 000000000000..937b4157a5d0 --- /dev/null +++ b/Documentation/DocBook/v4l/v4l2.xml | |||
| @@ -0,0 +1,479 @@ | |||
| 1 | <partinfo> | ||
| 2 | <authorgroup> | ||
| 3 | <author> | ||
| 4 | <firstname>Michael</firstname> | ||
| 5 | <surname>Schimek</surname> | ||
| 6 | <othername role="mi">H</othername> | ||
| 7 | <affiliation> | ||
| 8 | <address> | ||
| 9 | <email>mschimek@gmx.at</email> | ||
| 10 | </address> | ||
| 11 | </affiliation> | ||
| 12 | </author> | ||
| 13 | |||
| 14 | <author> | ||
| 15 | <firstname>Bill</firstname> | ||
| 16 | <surname>Dirks</surname> | ||
| 17 | <!-- Commented until Bill opts in to be spammed. | ||
| 18 | <affiliation> | ||
| 19 | <address> | ||
| 20 | <email>bill@thedirks.org</email> | ||
| 21 | </address> | ||
| 22 | </affiliation> --> | ||
| 23 | <contrib>Original author of the V4L2 API and | ||
| 24 | documentation.</contrib> | ||
| 25 | </author> | ||
| 26 | |||
| 27 | <author> | ||
| 28 | <firstname>Hans</firstname> | ||
| 29 | <surname>Verkuil</surname> | ||
| 30 | <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl, | ||
| 31 | the extended control ioctls and major parts of the sliced VBI | ||
| 32 | API.</contrib> | ||
| 33 | <affiliation> | ||
| 34 | <address> | ||
| 35 | <email>hverkuil@xs4all.nl</email> | ||
| 36 | </address> | ||
| 37 | </affiliation> | ||
| 38 | </author> | ||
| 39 | |||
| 40 | <author> | ||
| 41 | <firstname>Martin</firstname> | ||
| 42 | <surname>Rubli</surname> | ||
| 43 | <!-- | ||
| 44 | <affiliation> | ||
| 45 | <address> | ||
| 46 | <email>martin_rubli@logitech.com</email> | ||
| 47 | </address> | ||
| 48 | </affiliation> --> | ||
| 49 | <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES | ||
| 50 | and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> | ||
| 51 | </author> | ||
| 52 | |||
| 53 | <author> | ||
| 54 | <firstname>Andy</firstname> | ||
| 55 | <surname>Walls</surname> | ||
| 56 | <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV | ||
| 57 | MPEG stream embedded, sliced VBI data format in this specification. | ||
| 58 | </contrib> | ||
| 59 | <affiliation> | ||
| 60 | <address> | ||
| 61 | <email>awalls@radix.net</email> | ||
| 62 | </address> | ||
| 63 | </affiliation> | ||
| 64 | </author> | ||
| 65 | |||
| 66 | <author> | ||
| 67 | <firstname>Mauro</firstname> | ||
| 68 | <surname>Carvalho Chehab</surname> | ||
| 69 | <contrib>Documented libv4l, designed and added v4l2grab example, | ||
| 70 | Remote Controller chapter.</contrib> | ||
| 71 | <affiliation> | ||
| 72 | <address> | ||
| 73 | <email>mchehab@redhat.com</email> | ||
| 74 | </address> | ||
| 75 | </affiliation> | ||
| 76 | </author> | ||
| 77 | </authorgroup> | ||
| 78 | |||
| 79 | <copyright> | ||
| 80 | <year>1999</year> | ||
| 81 | <year>2000</year> | ||
| 82 | <year>2001</year> | ||
| 83 | <year>2002</year> | ||
| 84 | <year>2003</year> | ||
| 85 | <year>2004</year> | ||
| 86 | <year>2005</year> | ||
| 87 | <year>2006</year> | ||
| 88 | <year>2007</year> | ||
| 89 | <year>2008</year> | ||
| 90 | <year>2009</year> | ||
| 91 | <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin | ||
| 92 | Rubli, Andy Walls, Mauro Carvalho Chehab</holder> | ||
| 93 | </copyright> | ||
| 94 | <legalnotice> | ||
| 95 | <para>Except when explicitly stated as GPL, programming examples within | ||
| 96 | this part can be used and distributed without restrictions.</para> | ||
| 97 | </legalnotice> | ||
| 98 | <revhistory> | ||
| 99 | <!-- Put document revisions here, newest first. --> | ||
| 100 | <!-- API revisions (changes and additions of defines, enums, | ||
| 101 | structs, ioctls) must be noted in more detail in the history chapter | ||
| 102 | (compat.sgml), along with the possible impact on existing drivers and | ||
| 103 | applications. --> | ||
| 104 | |||
| 105 | <revision> | ||
| 106 | <revnumber>2.6.32</revnumber> | ||
| 107 | <date>2009-08-31</date> | ||
| 108 | <authorinitials>mcc</authorinitials> | ||
| 109 | <revremark>Now, revisions will match the kernel version where | ||
| 110 | the V4L2 API changes will be used by the Linux Kernel. | ||
| 111 | Also added Remote Controller chapter.</revremark> | ||
| 112 | </revision> | ||
| 113 | |||
| 114 | <revision> | ||
| 115 | <revnumber>0.29</revnumber> | ||
| 116 | <date>2009-08-26</date> | ||
| 117 | <authorinitials>ev</authorinitials> | ||
| 118 | <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> | ||
| 119 | </revision> | ||
| 120 | |||
| 121 | <revision> | ||
| 122 | <revnumber>0.28</revnumber> | ||
| 123 | <date>2009-08-26</date> | ||
| 124 | <authorinitials>gl</authorinitials> | ||
| 125 | <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> | ||
| 126 | </revision> | ||
| 127 | |||
| 128 | <revision> | ||
| 129 | <revnumber>0.27</revnumber> | ||
| 130 | <date>2009-08-15</date> | ||
| 131 | <authorinitials>mcc</authorinitials> | ||
| 132 | <revremark>Added libv4l and Remote Controller documentation; | ||
| 133 | added v4l2grab and keytable application examples.</revremark> | ||
| 134 | </revision> | ||
| 135 | |||
| 136 | <revision> | ||
| 137 | <revnumber>0.26</revnumber> | ||
| 138 | <date>2009-07-23</date> | ||
| 139 | <authorinitials>hv</authorinitials> | ||
| 140 | <revremark>Finalized the RDS capture API. Added modulator and RDS encoder | ||
| 141 | capabilities. Added support for string controls.</revremark> | ||
| 142 | </revision> | ||
| 143 | |||
| 144 | <revision> | ||
| 145 | <revnumber>0.25</revnumber> | ||
| 146 | <date>2009-01-18</date> | ||
| 147 | <authorinitials>hv</authorinitials> | ||
| 148 | <revremark>Added pixel formats VYUY, NV16 and NV61, and changed | ||
| 149 | the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. | ||
| 150 | Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, | ||
| 151 | V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark> | ||
| 152 | </revision> | ||
| 153 | |||
| 154 | <revision> | ||
| 155 | <revnumber>0.24</revnumber> | ||
| 156 | <date>2008-03-04</date> | ||
| 157 | <authorinitials>mhs</authorinitials> | ||
| 158 | <revremark>Added pixel formats Y16 and SBGGR16, new controls | ||
| 159 | and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark> | ||
| 160 | </revision> | ||
| 161 | |||
| 162 | <revision> | ||
| 163 | <revnumber>0.23</revnumber> | ||
| 164 | <date>2007-08-30</date> | ||
| 165 | <authorinitials>mhs</authorinitials> | ||
| 166 | <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER. | ||
| 167 | Clarified the byte order of packed pixel formats.</revremark> | ||
| 168 | </revision> | ||
| 169 | |||
| 170 | <revision> | ||
| 171 | <revnumber>0.22</revnumber> | ||
| 172 | <date>2007-08-29</date> | ||
| 173 | <authorinitials>mhs</authorinitials> | ||
| 174 | <revremark>Added the Video Output Overlay interface, new MPEG | ||
| 175 | controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, | ||
| 176 | VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, | ||
| 177 | VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. | ||
| 178 | Clarifications in the cropping chapter, about RGB pixel formats, the | ||
| 179 | mmap(), poll(), select(), read() and write() functions. Typographical | ||
| 180 | fixes.</revremark> | ||
| 181 | </revision> | ||
| 182 | |||
| 183 | <revision> | ||
| 184 | <revnumber>0.21</revnumber> | ||
| 185 | <date>2006-12-19</date> | ||
| 186 | <authorinitials>mhs</authorinitials> | ||
| 187 | <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark> | ||
| 188 | </revision> | ||
| 189 | |||
| 190 | <revision> | ||
| 191 | <revnumber>0.20</revnumber> | ||
| 192 | <date>2006-11-24</date> | ||
| 193 | <authorinitials>mhs</authorinitials> | ||
| 194 | <revremark>Clarified the purpose of the audioset field in | ||
| 195 | struct v4l2_input and v4l2_output.</revremark> | ||
| 196 | </revision> | ||
| 197 | |||
| 198 | <revision> | ||
| 199 | <revnumber>0.19</revnumber> | ||
| 200 | <date>2006-10-19</date> | ||
| 201 | <authorinitials>mhs</authorinitials> | ||
| 202 | <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark> | ||
| 203 | </revision> | ||
| 204 | |||
| 205 | <revision> | ||
| 206 | <revnumber>0.18</revnumber> | ||
| 207 | <date>2006-10-18</date> | ||
| 208 | <authorinitials>mhs</authorinitials> | ||
| 209 | <revremark>Added the description of extended controls by Hans | ||
| 210 | Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark> | ||
| 211 | </revision> | ||
| 212 | |||
| 213 | <revision> | ||
| 214 | <revnumber>0.17</revnumber> | ||
| 215 | <date>2006-10-12</date> | ||
| 216 | <authorinitials>mhs</authorinitials> | ||
| 217 | <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark> | ||
| 218 | </revision> | ||
| 219 | |||
| 220 | <revision> | ||
| 221 | <revnumber>0.16</revnumber> | ||
| 222 | <date>2006-10-08</date> | ||
| 223 | <authorinitials>mhs</authorinitials> | ||
| 224 | <revremark>VIDIOC_ENUM_FRAMESIZES and | ||
| 225 | VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark> | ||
| 226 | </revision> | ||
| 227 | |||
| 228 | <revision> | ||
| 229 | <revnumber>0.15</revnumber> | ||
| 230 | <date>2006-09-23</date> | ||
| 231 | <authorinitials>mhs</authorinitials> | ||
| 232 | <revremark>Cleaned up the bibliography, added BT.653 and | ||
| 233 | BT.1119. capture.c/start_capturing() for user pointer I/O did not | ||
| 234 | initialize the buffer index. Documented the V4L MPEG and MJPEG | ||
| 235 | VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel | ||
| 236 | formats. See the history chapter for API changes.</revremark> | ||
| 237 | </revision> | ||
| 238 | |||
| 239 | <revision> | ||
| 240 | <revnumber>0.14</revnumber> | ||
| 241 | <date>2006-09-14</date> | ||
| 242 | <authorinitials>mr</authorinitials> | ||
| 243 | <revremark>Added VIDIOC_ENUM_FRAMESIZES and | ||
| 244 | VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of | ||
| 245 | digital devices.</revremark> | ||
| 246 | </revision> | ||
| 247 | |||
| 248 | <revision> | ||
| 249 | <revnumber>0.13</revnumber> | ||
| 250 | <date>2006-04-07</date> | ||
| 251 | <authorinitials>mhs</authorinitials> | ||
| 252 | <revremark>Corrected the description of struct v4l2_window | ||
| 253 | clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 | ||
| 254 | defines.</revremark> | ||
| 255 | </revision> | ||
| 256 | |||
| 257 | <revision> | ||
| 258 | <revnumber>0.12</revnumber> | ||
| 259 | <date>2006-02-03</date> | ||
| 260 | <authorinitials>mhs</authorinitials> | ||
| 261 | <revremark>Corrected the description of struct | ||
| 262 | v4l2_captureparm and v4l2_outputparm.</revremark> | ||
| 263 | </revision> | ||
| 264 | |||
| 265 | <revision> | ||
| 266 | <revnumber>0.11</revnumber> | ||
| 267 | <date>2006-01-27</date> | ||
| 268 | <authorinitials>mhs</authorinitials> | ||
| 269 | <revremark>Improved the description of struct | ||
| 270 | v4l2_tuner.</revremark> | ||
| 271 | </revision> | ||
| 272 | |||
| 273 | <revision> | ||
| 274 | <revnumber>0.10</revnumber> | ||
| 275 | <date>2006-01-10</date> | ||
| 276 | <authorinitials>mhs</authorinitials> | ||
| 277 | <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM | ||
| 278 | clarifications.</revremark> | ||
| 279 | </revision> | ||
| 280 | |||
| 281 | <revision> | ||
| 282 | <revnumber>0.9</revnumber> | ||
| 283 | <date>2005-11-27</date> | ||
| 284 | <authorinitials>mhs</authorinitials> | ||
| 285 | <revremark>Improved the 525 line numbering diagram. Hans | ||
| 286 | Verkuil and I rewrote the sliced VBI section. He also contributed a | ||
| 287 | VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard | ||
| 288 | selection example. Various updates.</revremark> | ||
| 289 | </revision> | ||
| 290 | |||
| 291 | <revision> | ||
| 292 | <revnumber>0.8</revnumber> | ||
| 293 | <date>2004-10-04</date> | ||
| 294 | <authorinitials>mhs</authorinitials> | ||
| 295 | <revremark>Somehow a piece of junk slipped into the capture | ||
| 296 | example, removed.</revremark> | ||
| 297 | </revision> | ||
| 298 | |||
| 299 | <revision> | ||
| 300 | <revnumber>0.7</revnumber> | ||
| 301 | <date>2004-09-19</date> | ||
| 302 | <authorinitials>mhs</authorinitials> | ||
| 303 | <revremark>Fixed video standard selection, control | ||
| 304 | enumeration, downscaling and aspect example. Added read and user | ||
| 305 | pointer i/o to video capture example.</revremark> | ||
| 306 | </revision> | ||
| 307 | |||
| 308 | <revision> | ||
| 309 | <revnumber>0.6</revnumber> | ||
| 310 | <date>2004-08-01</date> | ||
| 311 | <authorinitials>mhs</authorinitials> | ||
| 312 | <revremark>v4l2_buffer changes, added video capture example, | ||
| 313 | various corrections.</revremark> | ||
| 314 | </revision> | ||
| 315 | |||
| 316 | <revision> | ||
| 317 | <revnumber>0.5</revnumber> | ||
| 318 | <date>2003-11-05</date> | ||
| 319 | <authorinitials>mhs</authorinitials> | ||
| 320 | <revremark>Pixel format erratum.</revremark> | ||
| 321 | </revision> | ||
| 322 | |||
| 323 | <revision> | ||
| 324 | <revnumber>0.4</revnumber> | ||
| 325 | <date>2003-09-17</date> | ||
| 326 | <authorinitials>mhs</authorinitials> | ||
| 327 | <revremark>Corrected source and Makefile to generate a PDF. | ||
| 328 | SGML fixes. Added latest API changes. Closed gaps in the history | ||
| 329 | chapter.</revremark> | ||
| 330 | </revision> | ||
| 331 | |||
| 332 | <revision> | ||
| 333 | <revnumber>0.3</revnumber> | ||
| 334 | <date>2003-02-05</date> | ||
| 335 | <authorinitials>mhs</authorinitials> | ||
| 336 | <revremark>Another draft, more corrections.</revremark> | ||
| 337 | </revision> | ||
| 338 | |||
| 339 | <revision> | ||
| 340 | <revnumber>0.2</revnumber> | ||
| 341 | <date>2003-01-15</date> | ||
| 342 | <authorinitials>mhs</authorinitials> | ||
| 343 | <revremark>Second draft, with corrections pointed out by Gerd | ||
| 344 | Knorr.</revremark> | ||
| 345 | </revision> | ||
| 346 | |||
| 347 | <revision> | ||
| 348 | <revnumber>0.1</revnumber> | ||
| 349 | <date>2002-12-01</date> | ||
| 350 | <authorinitials>mhs</authorinitials> | ||
| 351 | <revremark>First draft, based on documentation by Bill Dirks | ||
| 352 | and discussions on the V4L mailing list.</revremark> | ||
| 353 | </revision> | ||
| 354 | </revhistory> | ||
| 355 | </partinfo> | ||
| 356 | |||
| 357 | <title>Video for Linux Two API Specification</title> | ||
| 358 | <subtitle>Revision 2.6.32</subtitle> | ||
| 359 | |||
| 360 | <chapter id="common"> | ||
| 361 | &sub-common; | ||
| 362 | </chapter> | ||
| 363 | |||
| 364 | <chapter id="pixfmt"> | ||
| 365 | &sub-pixfmt; | ||
| 366 | </chapter> | ||
| 367 | |||
| 368 | <chapter id="io"> | ||
| 369 | &sub-io; | ||
| 370 | </chapter> | ||
| 371 | |||
| 372 | <chapter id="devices"> | ||
| 373 | <title>Interfaces</title> | ||
| 374 | |||
| 375 | <section id="capture"> &sub-dev-capture; </section> | ||
| 376 | <section id="overlay"> &sub-dev-overlay; </section> | ||
| 377 | <section id="output"> &sub-dev-output; </section> | ||
| 378 | <section id="osd"> &sub-dev-osd; </section> | ||
| 379 | <section id="codec"> &sub-dev-codec; </section> | ||
| 380 | <section id="effect"> &sub-dev-effect; </section> | ||
| 381 | <section id="raw-vbi"> &sub-dev-raw-vbi; </section> | ||
| 382 | <section id="sliced"> &sub-dev-sliced-vbi; </section> | ||
| 383 | <section id="ttx"> &sub-dev-teletext; </section> | ||
| 384 | <section id="radio"> &sub-dev-radio; </section> | ||
| 385 | <section id="rds"> &sub-dev-rds; </section> | ||
| 386 | </chapter> | ||
| 387 | |||
| 388 | <chapter id="driver"> | ||
| 389 | &sub-driver; | ||
| 390 | </chapter> | ||
| 391 | |||
| 392 | <chapter id="libv4l"> | ||
| 393 | &sub-libv4l; | ||
| 394 | </chapter> | ||
| 395 | |||
| 396 | <chapter id="compat"> | ||
| 397 | &sub-compat; | ||
| 398 | </chapter> | ||
| 399 | |||
| 400 | <appendix id="user-func"> | ||
| 401 | <title>Function Reference</title> | ||
| 402 | |||
| 403 | <!-- Keep this alphabetically sorted. --> | ||
| 404 | |||
| 405 | &sub-close; | ||
| 406 | &sub-ioctl; | ||
| 407 | <!-- All ioctls go here. --> | ||
| 408 | &sub-cropcap; | ||
| 409 | &sub-dbg-g-chip-ident; | ||
| 410 | &sub-dbg-g-register; | ||
| 411 | &sub-encoder-cmd; | ||
| 412 | &sub-enumaudio; | ||
| 413 | &sub-enumaudioout; | ||
| 414 | &sub-enum-fmt; | ||
| 415 | &sub-enum-framesizes; | ||
| 416 | &sub-enum-frameintervals; | ||
| 417 | &sub-enuminput; | ||
| 418 | &sub-enumoutput; | ||
| 419 | &sub-enumstd; | ||
| 420 | &sub-g-audio; | ||
| 421 | &sub-g-audioout; | ||
| 422 | &sub-g-crop; | ||
| 423 | &sub-g-ctrl; | ||
| 424 | &sub-g-enc-index; | ||
| 425 | &sub-g-ext-ctrls; | ||
| 426 | &sub-g-fbuf; | ||
| 427 | &sub-g-fmt; | ||
| 428 | &sub-g-frequency; | ||
| 429 | &sub-g-input; | ||
| 430 | &sub-g-jpegcomp; | ||
| 431 | &sub-g-modulator; | ||
| 432 | &sub-g-output; | ||
| 433 | &sub-g-parm; | ||
| 434 | &sub-g-priority; | ||
| 435 | &sub-g-sliced-vbi-cap; | ||
| 436 | &sub-g-std; | ||
| 437 | &sub-g-tuner; | ||
| 438 | &sub-log-status; | ||
| 439 | &sub-overlay; | ||
| 440 | &sub-qbuf; | ||
| 441 | &sub-querybuf; | ||
| 442 | &sub-querycap; | ||
| 443 | &sub-queryctrl; | ||
| 444 | &sub-querystd; | ||
| 445 | &sub-reqbufs; | ||
| 446 | &sub-s-hw-freq-seek; | ||
| 447 | &sub-streamon; | ||
| 448 | <!-- End of ioctls. --> | ||
| 449 | &sub-mmap; | ||
| 450 | &sub-munmap; | ||
| 451 | &sub-open; | ||
| 452 | &sub-poll; | ||
| 453 | &sub-read; | ||
| 454 | &sub-select; | ||
| 455 | &sub-write; | ||
| 456 | </appendix> | ||
| 457 | |||
| 458 | <appendix id="videodev"> | ||
| 459 | <title>Video For Linux Two Header File</title> | ||
| 460 | &sub-videodev2-h; | ||
| 461 | </appendix> | ||
| 462 | |||
| 463 | <appendix id="capture-example"> | ||
| 464 | <title>Video Capture Example</title> | ||
| 465 | &sub-capture-c; | ||
| 466 | </appendix> | ||
| 467 | |||
| 468 | <appendix id="v4l2grab-example"> | ||
| 469 | <title>Video Grabber example using libv4l</title> | ||
| 470 | <para>This program demonstrates how to grab V4L2 images in ppm format by | ||
| 471 | using libv4l handlers. The advantage is that this grabber can potentially work | ||
| 472 | with any V4L2 driver.</para> | ||
| 473 | &sub-v4l2grab-c; | ||
| 474 | </appendix> | ||
| 475 | |||
| 476 | &sub-media-indices; | ||
| 477 | |||
| 478 | &sub-biblio; | ||
| 479 | |||
diff --git a/Documentation/DocBook/v4l/v4l2grab.c.xml b/Documentation/DocBook/v4l/v4l2grab.c.xml new file mode 100644 index 000000000000..bed12e40be27 --- /dev/null +++ b/Documentation/DocBook/v4l/v4l2grab.c.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* V4L2 video picture grabber | ||
| 3 | Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org> | ||
| 4 | |||
| 5 | This program is free software; you can redistribute it and/or modify | ||
| 6 | it under the terms of the GNU General Public License as published by | ||
| 7 | the Free Software Foundation version 2 of the License. | ||
| 8 | |||
| 9 | This program is distributed in the hope that it will be useful, | ||
| 10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 12 | GNU General Public License for more details. | ||
| 13 | */ | ||
| 14 | |||
| 15 | #include <stdio.h> | ||
| 16 | #include <stdlib.h> | ||
| 17 | #include <string.h> | ||
| 18 | #include <fcntl.h> | ||
| 19 | #include <errno.h> | ||
| 20 | #include <sys/ioctl.h> | ||
| 21 | #include <sys/types.h> | ||
| 22 | #include <sys/time.h> | ||
| 23 | #include <sys/mman.h> | ||
| 24 | #include <linux/videodev2.h> | ||
| 25 | #include "../libv4l/include/libv4l2.h" | ||
| 26 | |||
| 27 | #define CLEAR(x) memset(&(x), 0, sizeof(x)) | ||
| 28 | |||
| 29 | struct buffer { | ||
| 30 | void *start; | ||
| 31 | size_t length; | ||
| 32 | }; | ||
| 33 | |||
| 34 | static void xioctl(int fh, int request, void *arg) | ||
| 35 | { | ||
| 36 | int r; | ||
| 37 | |||
| 38 | do { | ||
| 39 | r = v4l2_ioctl(fh, request, arg); | ||
| 40 | } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); | ||
| 41 | |||
| 42 | if (r == -1) { | ||
| 43 | fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); | ||
| 44 | exit(EXIT_FAILURE); | ||
| 45 | } | ||
| 46 | } | ||
| 47 | |||
| 48 | int main(int argc, char **argv) | ||
| 49 | { | ||
| 50 | struct <link linkend="v4l2-format">v4l2_format</link> fmt; | ||
| 51 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 52 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 53 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 54 | fd_set fds; | ||
| 55 | struct timeval tv; | ||
| 56 | int r, fd = -1; | ||
| 57 | unsigned int i, n_buffers; | ||
| 58 | char *dev_name = "/dev/video0"; | ||
| 59 | char out_name[256]; | ||
| 60 | FILE *fout; | ||
| 61 | struct buffer *buffers; | ||
| 62 | |||
| 63 | fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0); | ||
| 64 | if (fd < 0) { | ||
| 65 | perror("Cannot open device"); | ||
| 66 | exit(EXIT_FAILURE); | ||
| 67 | } | ||
| 68 | |||
| 69 | CLEAR(fmt); | ||
| 70 | fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 71 | fmt.fmt.pix.width = 640; | ||
| 72 | fmt.fmt.pix.height = 480; | ||
| 73 | fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24; | ||
| 74 | fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; | ||
| 75 | xioctl(fd, VIDIOC_S_FMT, &fmt); | ||
| 76 | if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { | ||
| 77 | printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); | ||
| 78 | exit(EXIT_FAILURE); | ||
| 79 | } | ||
| 80 | if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) | ||
| 81 | printf("Warning: driver is sending image at %dx%d\n", | ||
| 82 | fmt.fmt.pix.width, fmt.fmt.pix.height); | ||
| 83 | |||
| 84 | CLEAR(req); | ||
| 85 | req.count = 2; | ||
| 86 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 87 | req.memory = V4L2_MEMORY_MMAP; | ||
| 88 | xioctl(fd, VIDIOC_REQBUFS, &req); | ||
| 89 | |||
| 90 | buffers = calloc(req.count, sizeof(*buffers)); | ||
| 91 | for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { | ||
| 92 | CLEAR(buf); | ||
| 93 | |||
| 94 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 95 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 96 | buf.index = n_buffers; | ||
| 97 | |||
| 98 | xioctl(fd, VIDIOC_QUERYBUF, &buf); | ||
| 99 | |||
| 100 | buffers[n_buffers].length = buf.length; | ||
| 101 | buffers[n_buffers].start = v4l2_mmap(NULL, buf.length, | ||
| 102 | PROT_READ | PROT_WRITE, MAP_SHARED, | ||
| 103 | fd, buf.m.offset); | ||
| 104 | |||
| 105 | if (MAP_FAILED == buffers[n_buffers].start) { | ||
| 106 | perror("mmap"); | ||
| 107 | exit(EXIT_FAILURE); | ||
| 108 | } | ||
| 109 | } | ||
| 110 | |||
| 111 | for (i = 0; i < n_buffers; ++i) { | ||
| 112 | CLEAR(buf); | ||
| 113 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 114 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 115 | buf.index = i; | ||
| 116 | xioctl(fd, VIDIOC_QBUF, &buf); | ||
| 117 | } | ||
| 118 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 119 | |||
| 120 | xioctl(fd, VIDIOC_STREAMON, &type); | ||
| 121 | for (i = 0; i < 20; i++) { | ||
| 122 | do { | ||
| 123 | FD_ZERO(&fds); | ||
| 124 | FD_SET(fd, &fds); | ||
| 125 | |||
| 126 | /* Timeout. */ | ||
| 127 | tv.tv_sec = 2; | ||
| 128 | tv.tv_usec = 0; | ||
| 129 | |||
| 130 | r = select(fd + 1, &fds, NULL, NULL, &tv); | ||
| 131 | } while ((r == -1 && (errno = EINTR))); | ||
| 132 | if (r == -1) { | ||
| 133 | perror("select"); | ||
| 134 | return errno; | ||
| 135 | } | ||
| 136 | |||
| 137 | CLEAR(buf); | ||
| 138 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 139 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 140 | xioctl(fd, VIDIOC_DQBUF, &buf); | ||
| 141 | |||
| 142 | sprintf(out_name, "out%03d.ppm", i); | ||
| 143 | fout = fopen(out_name, "w"); | ||
| 144 | if (!fout) { | ||
| 145 | perror("Cannot open image"); | ||
| 146 | exit(EXIT_FAILURE); | ||
| 147 | } | ||
| 148 | fprintf(fout, "P6\n%d %d 255\n", | ||
| 149 | fmt.fmt.pix.width, fmt.fmt.pix.height); | ||
| 150 | fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); | ||
| 151 | fclose(fout); | ||
| 152 | |||
| 153 | xioctl(fd, VIDIOC_QBUF, &buf); | ||
| 154 | } | ||
| 155 | |||
| 156 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 157 | xioctl(fd, VIDIOC_STREAMOFF, &type); | ||
| 158 | for (i = 0; i < n_buffers; ++i) | ||
| 159 | v4l2_munmap(buffers[i].start, buffers[i].length); | ||
| 160 | v4l2_close(fd); | ||
| 161 | |||
| 162 | return 0; | ||
| 163 | } | ||
| 164 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/vbi_525.gif b/Documentation/DocBook/v4l/vbi_525.gif new file mode 100644 index 000000000000..5580b690d504 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_525.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_525.pdf b/Documentation/DocBook/v4l/vbi_525.pdf new file mode 100644 index 000000000000..9e72c25b208d --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_525.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_625.gif b/Documentation/DocBook/v4l/vbi_625.gif new file mode 100644 index 000000000000..34e3251983c4 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_625.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_625.pdf b/Documentation/DocBook/v4l/vbi_625.pdf new file mode 100644 index 000000000000..765235e33a4d --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_625.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_hsync.gif b/Documentation/DocBook/v4l/vbi_hsync.gif new file mode 100644 index 000000000000..b02434d3b356 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_hsync.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_hsync.pdf b/Documentation/DocBook/v4l/vbi_hsync.pdf new file mode 100644 index 000000000000..200b668189bf --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_hsync.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml new file mode 100644 index 000000000000..97002060ac4f --- /dev/null +++ b/Documentation/DocBook/v4l/videodev2.h.xml | |||
| @@ -0,0 +1,1640 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* | ||
| 3 | * Video for Linux Two header file | ||
| 4 | * | ||
| 5 | * Copyright (C) 1999-2007 the contributors | ||
| 6 | * | ||
| 7 | * This program is free software; you can redistribute it and/or modify | ||
| 8 | * it under the terms of the GNU General Public License as published by | ||
| 9 | * the Free Software Foundation; either version 2 of the License, or | ||
| 10 | * (at your option) any later version. | ||
| 11 | * | ||
| 12 | * This program is distributed in the hope that it will be useful, | ||
| 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 15 | * GNU General Public License for more details. | ||
| 16 | * | ||
| 17 | * Alternatively you can redistribute this file under the terms of the | ||
| 18 | * BSD license as stated below: | ||
| 19 | * | ||
| 20 | * Redistribution and use in source and binary forms, with or without | ||
| 21 | * modification, are permitted provided that the following conditions | ||
| 22 | * are met: | ||
| 23 | * 1. Redistributions of source code must retain the above copyright | ||
| 24 | * notice, this list of conditions and the following disclaimer. | ||
| 25 | * 2. Redistributions in binary form must reproduce the above copyright | ||
| 26 | * notice, this list of conditions and the following disclaimer in | ||
| 27 | * the documentation and/or other materials provided with the | ||
| 28 | * distribution. | ||
| 29 | * 3. The names of its contributors may not be used to endorse or promote | ||
| 30 | * products derived from this software without specific prior written | ||
| 31 | * permission. | ||
| 32 | * | ||
| 33 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
| 34 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
| 35 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
| 36 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | ||
| 37 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
| 38 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED | ||
| 39 | * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | ||
| 40 | * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
| 41 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | ||
| 42 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
| 43 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 44 | * | ||
| 45 | * Header file for v4l or V4L2 drivers and applications | ||
| 46 | * with public API. | ||
| 47 | * All kernel-specific stuff were moved to media/v4l2-dev.h, so | ||
| 48 | * no #if __KERNEL tests are allowed here | ||
| 49 | * | ||
| 50 | * See http://linuxtv.org for more info | ||
| 51 | * | ||
| 52 | * Author: Bill Dirks <bill@thedirks.org> | ||
| 53 | * Justin Schoeman | ||
| 54 | * Hans Verkuil <hverkuil@xs4all.nl> | ||
| 55 | * et al. | ||
| 56 | */ | ||
| 57 | #ifndef __LINUX_VIDEODEV2_H | ||
| 58 | #define __LINUX_VIDEODEV2_H | ||
| 59 | |||
| 60 | #ifdef __KERNEL__ | ||
| 61 | #include <linux/time.h> /* need struct timeval */ | ||
| 62 | #else | ||
| 63 | #include <sys/time.h> | ||
| 64 | #endif | ||
| 65 | #include <linux/compiler.h> | ||
| 66 | #include <linux/ioctl.h> | ||
| 67 | #include <linux/types.h> | ||
| 68 | |||
| 69 | /* | ||
| 70 | * Common stuff for both V4L1 and V4L2 | ||
| 71 | * Moved from videodev.h | ||
| 72 | */ | ||
| 73 | #define VIDEO_MAX_FRAME 32 | ||
| 74 | |||
| 75 | #ifndef __KERNEL__ | ||
| 76 | |||
| 77 | /* These defines are V4L1 specific and should not be used with the V4L2 API! | ||
| 78 | They will be removed from this header in the future. */ | ||
| 79 | |||
| 80 | #define VID_TYPE_CAPTURE 1 /* Can capture */ | ||
| 81 | #define VID_TYPE_TUNER 2 /* Can tune */ | ||
| 82 | #define VID_TYPE_TELETEXT 4 /* Does teletext */ | ||
| 83 | #define VID_TYPE_OVERLAY 8 /* Overlay onto frame buffer */ | ||
| 84 | #define VID_TYPE_CHROMAKEY 16 /* Overlay by chromakey */ | ||
| 85 | #define VID_TYPE_CLIPPING 32 /* Can clip */ | ||
| 86 | #define VID_TYPE_FRAMERAM 64 /* Uses the frame buffer memory */ | ||
| 87 | #define VID_TYPE_SCALES 128 /* Scalable */ | ||
| 88 | #define VID_TYPE_MONOCHROME 256 /* Monochrome only */ | ||
| 89 | #define VID_TYPE_SUBCAPTURE 512 /* Can capture subareas of the image */ | ||
| 90 | #define VID_TYPE_MPEG_DECODER 1024 /* Can decode MPEG streams */ | ||
| 91 | #define VID_TYPE_MPEG_ENCODER 2048 /* Can encode MPEG streams */ | ||
| 92 | #define VID_TYPE_MJPEG_DECODER 4096 /* Can decode MJPEG streams */ | ||
| 93 | #define VID_TYPE_MJPEG_ENCODER 8192 /* Can encode MJPEG streams */ | ||
| 94 | #endif | ||
| 95 | |||
| 96 | /* | ||
| 97 | * M I S C E L L A N E O U S | ||
| 98 | */ | ||
| 99 | |||
| 100 | /* Four-character-code (FOURCC) */ | ||
| 101 | #define v4l2_fourcc(a, b, c, d)\ | ||
| 102 | ((__u32)(a) | ((__u32)(b) << 8) | ((__u32)(c) << 16) | ((__u32)(d) << 24)) | ||
| 103 | |||
| 104 | /* | ||
| 105 | * E N U M S | ||
| 106 | */ | ||
| 107 | enum <link linkend="v4l2-field">v4l2_field</link> { | ||
| 108 | V4L2_FIELD_ANY = 0, /* driver can choose from none, | ||
| 109 | top, bottom, interlaced | ||
| 110 | depending on whatever it thinks | ||
| 111 | is approximate ... */ | ||
| 112 | V4L2_FIELD_NONE = 1, /* this device has no fields ... */ | ||
| 113 | V4L2_FIELD_TOP = 2, /* top field only */ | ||
| 114 | V4L2_FIELD_BOTTOM = 3, /* bottom field only */ | ||
| 115 | V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */ | ||
| 116 | V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one | ||
| 117 | buffer, top-bottom order */ | ||
| 118 | V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */ | ||
| 119 | V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into | ||
| 120 | separate buffers */ | ||
| 121 | V4L2_FIELD_INTERLACED_TB = 8, /* both fields interlaced, top field | ||
| 122 | first and the top field is | ||
| 123 | transmitted first */ | ||
| 124 | V4L2_FIELD_INTERLACED_BT = 9, /* both fields interlaced, top field | ||
| 125 | first and the bottom field is | ||
| 126 | transmitted first */ | ||
| 127 | }; | ||
| 128 | #define V4L2_FIELD_HAS_TOP(field) \ | ||
| 129 | ((field) == V4L2_FIELD_TOP ||\ | ||
| 130 | (field) == V4L2_FIELD_INTERLACED ||\ | ||
| 131 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 132 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 133 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 134 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 135 | #define V4L2_FIELD_HAS_BOTTOM(field) \ | ||
| 136 | ((field) == V4L2_FIELD_BOTTOM ||\ | ||
| 137 | (field) == V4L2_FIELD_INTERLACED ||\ | ||
| 138 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 139 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 140 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 141 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 142 | #define V4L2_FIELD_HAS_BOTH(field) \ | ||
| 143 | ((field) == V4L2_FIELD_INTERLACED ||\ | ||
| 144 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 145 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 146 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 147 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 148 | |||
| 149 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> { | ||
| 150 | V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, | ||
| 151 | V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, | ||
| 152 | V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, | ||
| 153 | V4L2_BUF_TYPE_VBI_CAPTURE = 4, | ||
| 154 | V4L2_BUF_TYPE_VBI_OUTPUT = 5, | ||
| 155 | V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, | ||
| 156 | V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, | ||
| 157 | #if 1 /*KEEP*/ | ||
| 158 | /* Experimental */ | ||
| 159 | V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, | ||
| 160 | #endif | ||
| 161 | V4L2_BUF_TYPE_PRIVATE = 0x80, | ||
| 162 | }; | ||
| 163 | |||
| 164 | enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> { | ||
| 165 | V4L2_CTRL_TYPE_INTEGER = 1, | ||
| 166 | V4L2_CTRL_TYPE_BOOLEAN = 2, | ||
| 167 | V4L2_CTRL_TYPE_MENU = 3, | ||
| 168 | V4L2_CTRL_TYPE_BUTTON = 4, | ||
| 169 | V4L2_CTRL_TYPE_INTEGER64 = 5, | ||
| 170 | V4L2_CTRL_TYPE_CTRL_CLASS = 6, | ||
| 171 | V4L2_CTRL_TYPE_STRING = 7, | ||
| 172 | }; | ||
| 173 | |||
| 174 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> { | ||
| 175 | V4L2_TUNER_RADIO = 1, | ||
| 176 | V4L2_TUNER_ANALOG_TV = 2, | ||
| 177 | V4L2_TUNER_DIGITAL_TV = 3, | ||
| 178 | }; | ||
| 179 | |||
| 180 | enum <link linkend="v4l2-memory">v4l2_memory</link> { | ||
| 181 | V4L2_MEMORY_MMAP = 1, | ||
| 182 | V4L2_MEMORY_USERPTR = 2, | ||
| 183 | V4L2_MEMORY_OVERLAY = 3, | ||
| 184 | }; | ||
| 185 | |||
| 186 | /* see also http://vektor.theorem.ca/graphics/ycbcr/ */ | ||
| 187 | enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> { | ||
| 188 | /* ITU-R 601 -- broadcast NTSC/PAL */ | ||
| 189 | V4L2_COLORSPACE_SMPTE170M = 1, | ||
| 190 | |||
| 191 | /* 1125-Line (US) HDTV */ | ||
| 192 | V4L2_COLORSPACE_SMPTE240M = 2, | ||
| 193 | |||
| 194 | /* HD and modern captures. */ | ||
| 195 | V4L2_COLORSPACE_REC709 = 3, | ||
| 196 | |||
| 197 | /* broken BT878 extents (601, luma range 16-253 instead of 16-235) */ | ||
| 198 | V4L2_COLORSPACE_BT878 = 4, | ||
| 199 | |||
| 200 | /* These should be useful. Assume 601 extents. */ | ||
| 201 | V4L2_COLORSPACE_470_SYSTEM_M = 5, | ||
| 202 | V4L2_COLORSPACE_470_SYSTEM_BG = 6, | ||
| 203 | |||
| 204 | /* I know there will be cameras that send this. So, this is | ||
| 205 | * unspecified chromaticities and full 0-255 on each of the | ||
| 206 | * Y'CbCr components | ||
| 207 | */ | ||
| 208 | V4L2_COLORSPACE_JPEG = 7, | ||
| 209 | |||
| 210 | /* For RGB colourspaces, this is probably a good start. */ | ||
| 211 | V4L2_COLORSPACE_SRGB = 8, | ||
| 212 | }; | ||
| 213 | |||
| 214 | enum <link linkend="v4l2-priority">v4l2_priority</link> { | ||
| 215 | V4L2_PRIORITY_UNSET = 0, /* not initialized */ | ||
| 216 | V4L2_PRIORITY_BACKGROUND = 1, | ||
| 217 | V4L2_PRIORITY_INTERACTIVE = 2, | ||
| 218 | V4L2_PRIORITY_RECORD = 3, | ||
| 219 | V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE, | ||
| 220 | }; | ||
| 221 | |||
| 222 | struct <link linkend="v4l2-rect">v4l2_rect</link> { | ||
| 223 | __s32 left; | ||
| 224 | __s32 top; | ||
| 225 | __s32 width; | ||
| 226 | __s32 height; | ||
| 227 | }; | ||
| 228 | |||
| 229 | struct <link linkend="v4l2-fract">v4l2_fract</link> { | ||
| 230 | __u32 numerator; | ||
| 231 | __u32 denominator; | ||
| 232 | }; | ||
| 233 | |||
| 234 | /* | ||
| 235 | * D R I V E R C A P A B I L I T I E S | ||
| 236 | */ | ||
| 237 | struct <link linkend="v4l2-capability">v4l2_capability</link> { | ||
| 238 | __u8 driver[16]; /* i.e.ie; "bttv" */ | ||
| 239 | __u8 card[32]; /* i.e.ie; "Hauppauge WinTV" */ | ||
| 240 | __u8 bus_info[32]; /* "PCI:" + pci_name(pci_dev) */ | ||
| 241 | __u32 version; /* should use KERNEL_VERSION() */ | ||
| 242 | __u32 capabilities; /* Device capabilities */ | ||
| 243 | __u32 reserved[4]; | ||
| 244 | }; | ||
| 245 | |||
| 246 | /* Values for 'capabilities' field */ | ||
| 247 | #define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */ | ||
| 248 | #define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */ | ||
| 249 | #define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */ | ||
| 250 | #define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a raw VBI capture device */ | ||
| 251 | #define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a raw VBI output device */ | ||
| 252 | #define V4L2_CAP_SLICED_VBI_CAPTURE 0x00000040 /* Is a sliced VBI capture device */ | ||
| 253 | #define V4L2_CAP_SLICED_VBI_OUTPUT 0x00000080 /* Is a sliced VBI output device */ | ||
| 254 | #define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */ | ||
| 255 | #define V4L2_CAP_VIDEO_OUTPUT_OVERLAY 0x00000200 /* Can do video output overlay */ | ||
| 256 | #define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */ | ||
| 257 | #define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */ | ||
| 258 | |||
| 259 | #define V4L2_CAP_TUNER 0x00010000 /* has a tuner */ | ||
| 260 | #define V4L2_CAP_AUDIO 0x00020000 /* has audio support */ | ||
| 261 | #define V4L2_CAP_RADIO 0x00040000 /* is a radio device */ | ||
| 262 | #define V4L2_CAP_MODULATOR 0x00080000 /* has a modulator */ | ||
| 263 | |||
| 264 | #define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */ | ||
| 265 | #define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */ | ||
| 266 | #define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */ | ||
| 267 | |||
| 268 | /* | ||
| 269 | * V I D E O I M A G E F O R M A T | ||
| 270 | */ | ||
| 271 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { | ||
| 272 | __u32 width; | ||
| 273 | __u32 height; | ||
| 274 | __u32 pixelformat; | ||
| 275 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 276 | __u32 bytesperline; /* for padding, zero if unused */ | ||
| 277 | __u32 sizeimage; | ||
| 278 | enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> colorspace; | ||
| 279 | __u32 priv; /* private data, depends on pixelformat */ | ||
| 280 | }; | ||
| 281 | |||
| 282 | /* Pixel format FOURCC depth Description */ | ||
| 283 | |||
| 284 | /* RGB formats */ | ||
| 285 | #define <link linkend="V4L2-PIX-FMT-RGB332">V4L2_PIX_FMT_RGB332</link> v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */ | ||
| 286 | #define <link linkend="V4L2-PIX-FMT-RGB444">V4L2_PIX_FMT_RGB444</link> v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */ | ||
| 287 | #define <link linkend="V4L2-PIX-FMT-RGB555">V4L2_PIX_FMT_RGB555</link> v4l2_fourcc('R', 'G', 'B', 'O') /* 16 RGB-5-5-5 */ | ||
| 288 | #define <link linkend="V4L2-PIX-FMT-RGB565">V4L2_PIX_FMT_RGB565</link> v4l2_fourcc('R', 'G', 'B', 'P') /* 16 RGB-5-6-5 */ | ||
| 289 | #define <link linkend="V4L2-PIX-FMT-RGB555X">V4L2_PIX_FMT_RGB555X</link> v4l2_fourcc('R', 'G', 'B', 'Q') /* 16 RGB-5-5-5 BE */ | ||
| 290 | #define <link linkend="V4L2-PIX-FMT-RGB565X">V4L2_PIX_FMT_RGB565X</link> v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */ | ||
| 291 | #define <link linkend="V4L2-PIX-FMT-BGR24">V4L2_PIX_FMT_BGR24</link> v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */ | ||
| 292 | #define <link linkend="V4L2-PIX-FMT-RGB24">V4L2_PIX_FMT_RGB24</link> v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */ | ||
| 293 | #define <link linkend="V4L2-PIX-FMT-BGR32">V4L2_PIX_FMT_BGR32</link> v4l2_fourcc('B', 'G', 'R', '4') /* 32 BGR-8-8-8-8 */ | ||
| 294 | #define <link linkend="V4L2-PIX-FMT-RGB32">V4L2_PIX_FMT_RGB32</link> v4l2_fourcc('R', 'G', 'B', '4') /* 32 RGB-8-8-8-8 */ | ||
| 295 | |||
| 296 | /* Grey formats */ | ||
| 297 | #define <link linkend="V4L2-PIX-FMT-GREY">V4L2_PIX_FMT_GREY</link> v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */ | ||
| 298 | #define <link linkend="V4L2-PIX-FMT-Y16">V4L2_PIX_FMT_Y16</link> v4l2_fourcc('Y', '1', '6', ' ') /* 16 Greyscale */ | ||
| 299 | |||
| 300 | /* Palette formats */ | ||
| 301 | #define <link linkend="V4L2-PIX-FMT-PAL8">V4L2_PIX_FMT_PAL8</link> v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */ | ||
| 302 | |||
| 303 | /* Luminance+Chrominance formats */ | ||
| 304 | #define <link linkend="V4L2-PIX-FMT-YVU410">V4L2_PIX_FMT_YVU410</link> v4l2_fourcc('Y', 'V', 'U', '9') /* 9 YVU 4:1:0 */ | ||
| 305 | #define <link linkend="V4L2-PIX-FMT-YVU420">V4L2_PIX_FMT_YVU420</link> v4l2_fourcc('Y', 'V', '1', '2') /* 12 YVU 4:2:0 */ | ||
| 306 | #define <link linkend="V4L2-PIX-FMT-YUYV">V4L2_PIX_FMT_YUYV</link> v4l2_fourcc('Y', 'U', 'Y', 'V') /* 16 YUV 4:2:2 */ | ||
| 307 | #define <link linkend="V4L2-PIX-FMT-YYUV">V4L2_PIX_FMT_YYUV</link> v4l2_fourcc('Y', 'Y', 'U', 'V') /* 16 YUV 4:2:2 */ | ||
| 308 | #define <link linkend="V4L2-PIX-FMT-YVYU">V4L2_PIX_FMT_YVYU</link> v4l2_fourcc('Y', 'V', 'Y', 'U') /* 16 YVU 4:2:2 */ | ||
| 309 | #define <link linkend="V4L2-PIX-FMT-UYVY">V4L2_PIX_FMT_UYVY</link> v4l2_fourcc('U', 'Y', 'V', 'Y') /* 16 YUV 4:2:2 */ | ||
| 310 | #define <link linkend="V4L2-PIX-FMT-VYUY">V4L2_PIX_FMT_VYUY</link> v4l2_fourcc('V', 'Y', 'U', 'Y') /* 16 YUV 4:2:2 */ | ||
| 311 | #define <link linkend="V4L2-PIX-FMT-YUV422P">V4L2_PIX_FMT_YUV422P</link> v4l2_fourcc('4', '2', '2', 'P') /* 16 YVU422 planar */ | ||
| 312 | #define <link linkend="V4L2-PIX-FMT-YUV411P">V4L2_PIX_FMT_YUV411P</link> v4l2_fourcc('4', '1', '1', 'P') /* 16 YVU411 planar */ | ||
| 313 | #define <link linkend="V4L2-PIX-FMT-Y41P">V4L2_PIX_FMT_Y41P</link> v4l2_fourcc('Y', '4', '1', 'P') /* 12 YUV 4:1:1 */ | ||
| 314 | #define <link linkend="V4L2-PIX-FMT-YUV444">V4L2_PIX_FMT_YUV444</link> v4l2_fourcc('Y', '4', '4', '4') /* 16 xxxxyyyy uuuuvvvv */ | ||
| 315 | #define <link linkend="V4L2-PIX-FMT-YUV555">V4L2_PIX_FMT_YUV555</link> v4l2_fourcc('Y', 'U', 'V', 'O') /* 16 YUV-5-5-5 */ | ||
| 316 | #define <link linkend="V4L2-PIX-FMT-YUV565">V4L2_PIX_FMT_YUV565</link> v4l2_fourcc('Y', 'U', 'V', 'P') /* 16 YUV-5-6-5 */ | ||
| 317 | #define <link linkend="V4L2-PIX-FMT-YUV32">V4L2_PIX_FMT_YUV32</link> v4l2_fourcc('Y', 'U', 'V', '4') /* 32 YUV-8-8-8-8 */ | ||
| 318 | #define <link linkend="V4L2-PIX-FMT-YUV410">V4L2_PIX_FMT_YUV410</link> v4l2_fourcc('Y', 'U', 'V', '9') /* 9 YUV 4:1:0 */ | ||
| 319 | #define <link linkend="V4L2-PIX-FMT-YUV420">V4L2_PIX_FMT_YUV420</link> v4l2_fourcc('Y', 'U', '1', '2') /* 12 YUV 4:2:0 */ | ||
| 320 | #define <link linkend="V4L2-PIX-FMT-HI240">V4L2_PIX_FMT_HI240</link> v4l2_fourcc('H', 'I', '2', '4') /* 8 8-bit color */ | ||
| 321 | #define <link linkend="V4L2-PIX-FMT-HM12">V4L2_PIX_FMT_HM12</link> v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */ | ||
| 322 | |||
| 323 | /* two planes -- one Y, one Cr + Cb interleaved */ | ||
| 324 | #define <link linkend="V4L2-PIX-FMT-NV12">V4L2_PIX_FMT_NV12</link> v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */ | ||
| 325 | #define <link linkend="V4L2-PIX-FMT-NV21">V4L2_PIX_FMT_NV21</link> v4l2_fourcc('N', 'V', '2', '1') /* 12 Y/CrCb 4:2:0 */ | ||
| 326 | #define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */ | ||
| 327 | #define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */ | ||
| 328 | |||
| 329 | /* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */ | ||
| 330 | #define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */ | ||
| 331 | #define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */ | ||
| 332 | #define <link linkend="V4L2-PIX-FMT-SGRBG8">V4L2_PIX_FMT_SGRBG8</link> v4l2_fourcc('G', 'R', 'B', 'G') /* 8 GRGR.. BGBG.. */ | ||
| 333 | #define <link linkend="V4L2-PIX-FMT-SGRBG10">V4L2_PIX_FMT_SGRBG10</link> v4l2_fourcc('B', 'A', '1', '0') /* 10bit raw bayer */ | ||
| 334 | /* 10bit raw bayer DPCM compressed to 8 bits */ | ||
| 335 | #define <link linkend="V4L2-PIX-FMT-SGRBG10DPCM8">V4L2_PIX_FMT_SGRBG10DPCM8</link> v4l2_fourcc('B', 'D', '1', '0') | ||
| 336 | /* | ||
| 337 | * 10bit raw bayer, expanded to 16 bits | ||
| 338 | * xxxxrrrrrrrrrrxxxxgggggggggg xxxxggggggggggxxxxbbbbbbbbbb... | ||
| 339 | */ | ||
| 340 | #define <link linkend="V4L2-PIX-FMT-SBGGR16">V4L2_PIX_FMT_SBGGR16</link> v4l2_fourcc('B', 'Y', 'R', '2') /* 16 BGBG.. GRGR.. */ | ||
| 341 | |||
| 342 | /* compressed formats */ | ||
| 343 | #define <link linkend="V4L2-PIX-FMT-MJPEG">V4L2_PIX_FMT_MJPEG</link> v4l2_fourcc('M', 'J', 'P', 'G') /* Motion-JPEG */ | ||
| 344 | #define <link linkend="V4L2-PIX-FMT-JPEG">V4L2_PIX_FMT_JPEG</link> v4l2_fourcc('J', 'P', 'E', 'G') /* JFIF JPEG */ | ||
| 345 | #define <link linkend="V4L2-PIX-FMT-DV">V4L2_PIX_FMT_DV</link> v4l2_fourcc('d', 'v', 's', 'd') /* 1394 */ | ||
| 346 | #define <link linkend="V4L2-PIX-FMT-MPEG">V4L2_PIX_FMT_MPEG</link> v4l2_fourcc('M', 'P', 'E', 'G') /* MPEG-1/2/4 */ | ||
| 347 | |||
| 348 | /* Vendor-specific formats */ | ||
| 349 | #define <link linkend="V4L2-PIX-FMT-WNVA">V4L2_PIX_FMT_WNVA</link> v4l2_fourcc('W', 'N', 'V', 'A') /* Winnov hw compress */ | ||
| 350 | #define <link linkend="V4L2-PIX-FMT-SN9C10X">V4L2_PIX_FMT_SN9C10X</link> v4l2_fourcc('S', '9', '1', '0') /* SN9C10x compression */ | ||
| 351 | #define <link linkend="V4L2-PIX-FMT-SN9C20X-I420">V4L2_PIX_FMT_SN9C20X_I420</link> v4l2_fourcc('S', '9', '2', '0') /* SN9C20x YUV 4:2:0 */ | ||
| 352 | #define <link linkend="V4L2-PIX-FMT-PWC1">V4L2_PIX_FMT_PWC1</link> v4l2_fourcc('P', 'W', 'C', '1') /* pwc older webcam */ | ||
| 353 | #define <link linkend="V4L2-PIX-FMT-PWC2">V4L2_PIX_FMT_PWC2</link> v4l2_fourcc('P', 'W', 'C', '2') /* pwc newer webcam */ | ||
| 354 | #define <link linkend="V4L2-PIX-FMT-ET61X251">V4L2_PIX_FMT_ET61X251</link> v4l2_fourcc('E', '6', '2', '5') /* ET61X251 compression */ | ||
| 355 | #define <link linkend="V4L2-PIX-FMT-SPCA501">V4L2_PIX_FMT_SPCA501</link> v4l2_fourcc('S', '5', '0', '1') /* YUYV per line */ | ||
| 356 | #define <link linkend="V4L2-PIX-FMT-SPCA505">V4L2_PIX_FMT_SPCA505</link> v4l2_fourcc('S', '5', '0', '5') /* YYUV per line */ | ||
| 357 | #define <link linkend="V4L2-PIX-FMT-SPCA508">V4L2_PIX_FMT_SPCA508</link> v4l2_fourcc('S', '5', '0', '8') /* YUVY per line */ | ||
| 358 | #define <link linkend="V4L2-PIX-FMT-SPCA561">V4L2_PIX_FMT_SPCA561</link> v4l2_fourcc('S', '5', '6', '1') /* compressed GBRG bayer */ | ||
| 359 | #define <link linkend="V4L2-PIX-FMT-PAC207">V4L2_PIX_FMT_PAC207</link> v4l2_fourcc('P', '2', '0', '7') /* compressed BGGR bayer */ | ||
| 360 | #define <link linkend="V4L2-PIX-FMT-MR97310A">V4L2_PIX_FMT_MR97310A</link> v4l2_fourcc('M', '3', '1', '0') /* compressed BGGR bayer */ | ||
| 361 | #define <link linkend="V4L2-PIX-FMT-SQ905C">V4L2_PIX_FMT_SQ905C</link> v4l2_fourcc('9', '0', '5', 'C') /* compressed RGGB bayer */ | ||
| 362 | #define <link linkend="V4L2-PIX-FMT-PJPG">V4L2_PIX_FMT_PJPG</link> v4l2_fourcc('P', 'J', 'P', 'G') /* Pixart 73xx JPEG */ | ||
| 363 | #define <link linkend="V4L2-PIX-FMT-OV511">V4L2_PIX_FMT_OV511</link> v4l2_fourcc('O', '5', '1', '1') /* ov511 JPEG */ | ||
| 364 | #define <link linkend="V4L2-PIX-FMT-OV518">V4L2_PIX_FMT_OV518</link> v4l2_fourcc('O', '5', '1', '8') /* ov518 JPEG */ | ||
| 365 | #define <link linkend="V4L2-PIX-FMT-TM6000">V4L2_PIX_FMT_TM6000</link> v4l2_fourcc('T', 'M', '6', '0') /* tm5600/tm60x0 */ | ||
| 366 | |||
| 367 | /* | ||
| 368 | * F O R M A T E N U M E R A T I O N | ||
| 369 | */ | ||
| 370 | struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link> { | ||
| 371 | __u32 index; /* Format number */ | ||
| 372 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; /* buffer type */ | ||
| 373 | __u32 flags; | ||
| 374 | __u8 description[32]; /* Description string */ | ||
| 375 | __u32 pixelformat; /* Format fourcc */ | ||
| 376 | __u32 reserved[4]; | ||
| 377 | }; | ||
| 378 | |||
| 379 | #define V4L2_FMT_FLAG_COMPRESSED 0x0001 | ||
| 380 | #define V4L2_FMT_FLAG_EMULATED 0x0002 | ||
| 381 | |||
| 382 | #if 1 /*KEEP*/ | ||
| 383 | /* Experimental Frame Size and frame rate enumeration */ | ||
| 384 | /* | ||
| 385 | * F R A M E S I Z E E N U M E R A T I O N | ||
| 386 | */ | ||
| 387 | enum <link linkend="v4l2-frmsizetypes">v4l2_frmsizetypes</link> { | ||
| 388 | V4L2_FRMSIZE_TYPE_DISCRETE = 1, | ||
| 389 | V4L2_FRMSIZE_TYPE_CONTINUOUS = 2, | ||
| 390 | V4L2_FRMSIZE_TYPE_STEPWISE = 3, | ||
| 391 | }; | ||
| 392 | |||
| 393 | struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> { | ||
| 394 | __u32 width; /* Frame width [pixel] */ | ||
| 395 | __u32 height; /* Frame height [pixel] */ | ||
| 396 | }; | ||
| 397 | |||
| 398 | struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> { | ||
| 399 | __u32 min_width; /* Minimum frame width [pixel] */ | ||
| 400 | __u32 max_width; /* Maximum frame width [pixel] */ | ||
| 401 | __u32 step_width; /* Frame width step size [pixel] */ | ||
| 402 | __u32 min_height; /* Minimum frame height [pixel] */ | ||
| 403 | __u32 max_height; /* Maximum frame height [pixel] */ | ||
| 404 | __u32 step_height; /* Frame height step size [pixel] */ | ||
| 405 | }; | ||
| 406 | |||
| 407 | struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link> { | ||
| 408 | __u32 index; /* Frame size number */ | ||
| 409 | __u32 pixel_format; /* Pixel format */ | ||
| 410 | __u32 type; /* Frame size type the device supports. */ | ||
| 411 | |||
| 412 | union { /* Frame size */ | ||
| 413 | struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> discrete; | ||
| 414 | struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> stepwise; | ||
| 415 | }; | ||
| 416 | |||
| 417 | __u32 reserved[2]; /* Reserved space for future use */ | ||
| 418 | }; | ||
| 419 | |||
| 420 | /* | ||
| 421 | * F R A M E R A T E E N U M E R A T I O N | ||
| 422 | */ | ||
| 423 | enum <link linkend="v4l2-frmivaltypes">v4l2_frmivaltypes</link> { | ||
| 424 | V4L2_FRMIVAL_TYPE_DISCRETE = 1, | ||
| 425 | V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, | ||
| 426 | V4L2_FRMIVAL_TYPE_STEPWISE = 3, | ||
| 427 | }; | ||
| 428 | |||
| 429 | struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> { | ||
| 430 | struct <link linkend="v4l2-fract">v4l2_fract</link> min; /* Minimum frame interval [s] */ | ||
| 431 | struct <link linkend="v4l2-fract">v4l2_fract</link> max; /* Maximum frame interval [s] */ | ||
| 432 | struct <link linkend="v4l2-fract">v4l2_fract</link> step; /* Frame interval step size [s] */ | ||
| 433 | }; | ||
| 434 | |||
| 435 | struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link> { | ||
| 436 | __u32 index; /* Frame format index */ | ||
| 437 | __u32 pixel_format; /* Pixel format */ | ||
| 438 | __u32 width; /* Frame width */ | ||
| 439 | __u32 height; /* Frame height */ | ||
| 440 | __u32 type; /* Frame interval type the device supports. */ | ||
| 441 | |||
| 442 | union { /* Frame interval */ | ||
| 443 | struct <link linkend="v4l2-fract">v4l2_fract</link> discrete; | ||
| 444 | struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> stepwise; | ||
| 445 | }; | ||
| 446 | |||
| 447 | __u32 reserved[2]; /* Reserved space for future use */ | ||
| 448 | }; | ||
| 449 | #endif | ||
| 450 | |||
| 451 | /* | ||
| 452 | * T I M E C O D E | ||
| 453 | */ | ||
| 454 | struct <link linkend="v4l2-timecode">v4l2_timecode</link> { | ||
| 455 | __u32 type; | ||
| 456 | __u32 flags; | ||
| 457 | __u8 frames; | ||
| 458 | __u8 seconds; | ||
| 459 | __u8 minutes; | ||
| 460 | __u8 hours; | ||
| 461 | __u8 userbits[4]; | ||
| 462 | }; | ||
| 463 | |||
| 464 | /* Type */ | ||
| 465 | #define V4L2_TC_TYPE_24FPS 1 | ||
| 466 | #define V4L2_TC_TYPE_25FPS 2 | ||
| 467 | #define V4L2_TC_TYPE_30FPS 3 | ||
| 468 | #define V4L2_TC_TYPE_50FPS 4 | ||
| 469 | #define V4L2_TC_TYPE_60FPS 5 | ||
| 470 | |||
| 471 | /* Flags */ | ||
| 472 | #define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */ | ||
| 473 | #define V4L2_TC_FLAG_COLORFRAME 0x0002 | ||
| 474 | #define V4L2_TC_USERBITS_field 0x000C | ||
| 475 | #define V4L2_TC_USERBITS_USERDEFINED 0x0000 | ||
| 476 | #define V4L2_TC_USERBITS_8BITCHARS 0x0008 | ||
| 477 | /* The above is based on SMPTE timecodes */ | ||
| 478 | |||
| 479 | struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link> { | ||
| 480 | int quality; | ||
| 481 | |||
| 482 | int APPn; /* Number of APP segment to be written, | ||
| 483 | * must be 0..15 */ | ||
| 484 | int APP_len; /* Length of data in JPEG APPn segment */ | ||
| 485 | char APP_data[60]; /* Data in the JPEG APPn segment. */ | ||
| 486 | |||
| 487 | int COM_len; /* Length of data in JPEG COM segment */ | ||
| 488 | char COM_data[60]; /* Data in JPEG COM segment */ | ||
| 489 | |||
| 490 | __u32 jpeg_markers; /* Which markers should go into the JPEG | ||
| 491 | * output. Unless you exactly know what | ||
| 492 | * you do, leave them untouched. | ||
| 493 | * Inluding less markers will make the | ||
| 494 | * resulting code smaller, but there will | ||
| 495 | * be fewer aplications which can read it. | ||
| 496 | * The presence of the APP and COM marker | ||
| 497 | * is influenced by APP_len and COM_len | ||
| 498 | * ONLY, not by this property! */ | ||
| 499 | |||
| 500 | #define V4L2_JPEG_MARKER_DHT (1<<3) /* Define Huffman Tables */ | ||
| 501 | #define V4L2_JPEG_MARKER_DQT (1<<4) /* Define Quantization Tables */ | ||
| 502 | #define V4L2_JPEG_MARKER_DRI (1<<5) /* Define Restart Interval */ | ||
| 503 | #define V4L2_JPEG_MARKER_COM (1<<6) /* Comment segment */ | ||
| 504 | #define V4L2_JPEG_MARKER_APP (1<<7) /* App segment, driver will | ||
| 505 | * allways use APP0 */ | ||
| 506 | }; | ||
| 507 | |||
| 508 | /* | ||
| 509 | * M E M O R Y - M A P P I N G B U F F E R S | ||
| 510 | */ | ||
| 511 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> { | ||
| 512 | __u32 count; | ||
| 513 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 514 | enum <link linkend="v4l2-memory">v4l2_memory</link> memory; | ||
| 515 | __u32 reserved[2]; | ||
| 516 | }; | ||
| 517 | |||
| 518 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> { | ||
| 519 | __u32 index; | ||
| 520 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 521 | __u32 bytesused; | ||
| 522 | __u32 flags; | ||
| 523 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 524 | struct timeval timestamp; | ||
| 525 | struct <link linkend="v4l2-timecode">v4l2_timecode</link> timecode; | ||
| 526 | __u32 sequence; | ||
| 527 | |||
| 528 | /* memory location */ | ||
| 529 | enum <link linkend="v4l2-memory">v4l2_memory</link> memory; | ||
| 530 | union { | ||
| 531 | __u32 offset; | ||
| 532 | unsigned long userptr; | ||
| 533 | } m; | ||
| 534 | __u32 length; | ||
| 535 | __u32 input; | ||
| 536 | __u32 reserved; | ||
| 537 | }; | ||
| 538 | |||
| 539 | /* Flags for 'flags' field */ | ||
| 540 | #define V4L2_BUF_FLAG_MAPPED 0x0001 /* Buffer is mapped (flag) */ | ||
| 541 | #define V4L2_BUF_FLAG_QUEUED 0x0002 /* Buffer is queued for processing */ | ||
| 542 | #define V4L2_BUF_FLAG_DONE 0x0004 /* Buffer is ready */ | ||
| 543 | #define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */ | ||
| 544 | #define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */ | ||
| 545 | #define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */ | ||
| 546 | #define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */ | ||
| 547 | #define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */ | ||
| 548 | |||
| 549 | /* | ||
| 550 | * O V E R L A Y P R E V I E W | ||
| 551 | */ | ||
| 552 | struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link> { | ||
| 553 | __u32 capability; | ||
| 554 | __u32 flags; | ||
| 555 | /* FIXME: in theory we should pass something like PCI device + memory | ||
| 556 | * region + offset instead of some physical address */ | ||
| 557 | void *base; | ||
| 558 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> fmt; | ||
| 559 | }; | ||
| 560 | /* Flags for the 'capability' field. Read only */ | ||
| 561 | #define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001 | ||
| 562 | #define V4L2_FBUF_CAP_CHROMAKEY 0x0002 | ||
| 563 | #define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004 | ||
| 564 | #define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008 | ||
| 565 | #define V4L2_FBUF_CAP_LOCAL_ALPHA 0x0010 | ||
| 566 | #define V4L2_FBUF_CAP_GLOBAL_ALPHA 0x0020 | ||
| 567 | #define V4L2_FBUF_CAP_LOCAL_INV_ALPHA 0x0040 | ||
| 568 | /* Flags for the 'flags' field. */ | ||
| 569 | #define V4L2_FBUF_FLAG_PRIMARY 0x0001 | ||
| 570 | #define V4L2_FBUF_FLAG_OVERLAY 0x0002 | ||
| 571 | #define V4L2_FBUF_FLAG_CHROMAKEY 0x0004 | ||
| 572 | #define V4L2_FBUF_FLAG_LOCAL_ALPHA 0x0008 | ||
| 573 | #define V4L2_FBUF_FLAG_GLOBAL_ALPHA 0x0010 | ||
| 574 | #define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA 0x0020 | ||
| 575 | |||
| 576 | struct <link linkend="v4l2-clip">v4l2_clip</link> { | ||
| 577 | struct <link linkend="v4l2-rect">v4l2_rect</link> c; | ||
| 578 | struct <link linkend="v4l2-clip">v4l2_clip</link> __user *next; | ||
| 579 | }; | ||
| 580 | |||
| 581 | struct <link linkend="v4l2-window">v4l2_window</link> { | ||
| 582 | struct <link linkend="v4l2-rect">v4l2_rect</link> w; | ||
| 583 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 584 | __u32 chromakey; | ||
| 585 | struct <link linkend="v4l2-clip">v4l2_clip</link> __user *clips; | ||
| 586 | __u32 clipcount; | ||
| 587 | void __user *bitmap; | ||
| 588 | __u8 global_alpha; | ||
| 589 | }; | ||
| 590 | |||
| 591 | /* | ||
| 592 | * C A P T U R E P A R A M E T E R S | ||
| 593 | */ | ||
| 594 | struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> { | ||
| 595 | __u32 capability; /* Supported modes */ | ||
| 596 | __u32 capturemode; /* Current mode */ | ||
| 597 | struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in .1us units */ | ||
| 598 | __u32 extendedmode; /* Driver-specific extensions */ | ||
| 599 | __u32 readbuffers; /* # of buffers for read */ | ||
| 600 | __u32 reserved[4]; | ||
| 601 | }; | ||
| 602 | |||
| 603 | /* Flags for 'capability' and 'capturemode' fields */ | ||
| 604 | #define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */ | ||
| 605 | #define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */ | ||
| 606 | |||
| 607 | struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> { | ||
| 608 | __u32 capability; /* Supported modes */ | ||
| 609 | __u32 outputmode; /* Current mode */ | ||
| 610 | struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in seconds */ | ||
| 611 | __u32 extendedmode; /* Driver-specific extensions */ | ||
| 612 | __u32 writebuffers; /* # of buffers for write */ | ||
| 613 | __u32 reserved[4]; | ||
| 614 | }; | ||
| 615 | |||
| 616 | /* | ||
| 617 | * I N P U T I M A G E C R O P P I N G | ||
| 618 | */ | ||
| 619 | struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> { | ||
| 620 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 621 | struct <link linkend="v4l2-rect">v4l2_rect</link> bounds; | ||
| 622 | struct <link linkend="v4l2-rect">v4l2_rect</link> defrect; | ||
| 623 | struct <link linkend="v4l2-fract">v4l2_fract</link> pixelaspect; | ||
| 624 | }; | ||
| 625 | |||
| 626 | struct <link linkend="v4l2-crop">v4l2_crop</link> { | ||
| 627 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 628 | struct <link linkend="v4l2-rect">v4l2_rect</link> c; | ||
| 629 | }; | ||
| 630 | |||
| 631 | /* | ||
| 632 | * A N A L O G V I D E O S T A N D A R D | ||
| 633 | */ | ||
| 634 | |||
| 635 | typedef __u64 v4l2_std_id; | ||
| 636 | |||
| 637 | /* one bit for each */ | ||
| 638 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) | ||
| 639 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) | ||
| 640 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) | ||
| 641 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) | ||
| 642 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) | ||
| 643 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) | ||
| 644 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) | ||
| 645 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) | ||
| 646 | |||
| 647 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) | ||
| 648 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) | ||
| 649 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) | ||
| 650 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) | ||
| 651 | |||
| 652 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) | ||
| 653 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) | ||
| 654 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) | ||
| 655 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) | ||
| 656 | |||
| 657 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) | ||
| 658 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) | ||
| 659 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) | ||
| 660 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) | ||
| 661 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) | ||
| 662 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) | ||
| 663 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) | ||
| 664 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) | ||
| 665 | |||
| 666 | /* ATSC/HDTV */ | ||
| 667 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) | ||
| 668 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) | ||
| 669 | |||
| 670 | /* FIXME: | ||
| 671 | Although std_id is 64 bits, there is an issue on PPC32 architecture that | ||
| 672 | makes switch(__u64) to break. So, there's a hack on v4l2-common.c rounding | ||
| 673 | this value to 32 bits. | ||
| 674 | As, currently, the max value is for V4L2_STD_ATSC_16_VSB (30 bits wide), | ||
| 675 | it should work fine. However, if needed to add more than two standards, | ||
| 676 | v4l2-common.c should be fixed. | ||
| 677 | */ | ||
| 678 | |||
| 679 | /* some merged standards */ | ||
| 680 | #define V4L2_STD_MN (V4L2_STD_PAL_M|V4L2_STD_PAL_N|V4L2_STD_PAL_Nc|V4L2_STD_NTSC) | ||
| 681 | #define V4L2_STD_B (V4L2_STD_PAL_B|V4L2_STD_PAL_B1|V4L2_STD_SECAM_B) | ||
| 682 | #define V4L2_STD_GH (V4L2_STD_PAL_G|V4L2_STD_PAL_H|V4L2_STD_SECAM_G|V4L2_STD_SECAM_H) | ||
| 683 | #define V4L2_STD_DK (V4L2_STD_PAL_DK|V4L2_STD_SECAM_DK) | ||
| 684 | |||
| 685 | /* some common needed stuff */ | ||
| 686 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ | ||
| 687 | V4L2_STD_PAL_B1 |\ | ||
| 688 | V4L2_STD_PAL_G) | ||
| 689 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ | ||
| 690 | V4L2_STD_PAL_D1 |\ | ||
| 691 | V4L2_STD_PAL_K) | ||
| 692 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ | ||
| 693 | V4L2_STD_PAL_DK |\ | ||
| 694 | V4L2_STD_PAL_H |\ | ||
| 695 | V4L2_STD_PAL_I) | ||
| 696 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ | ||
| 697 | V4L2_STD_NTSC_M_JP |\ | ||
| 698 | V4L2_STD_NTSC_M_KR) | ||
| 699 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\ | ||
| 700 | V4L2_STD_SECAM_K |\ | ||
| 701 | V4L2_STD_SECAM_K1) | ||
| 702 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ | ||
| 703 | V4L2_STD_SECAM_G |\ | ||
| 704 | V4L2_STD_SECAM_H |\ | ||
| 705 | V4L2_STD_SECAM_DK |\ | ||
| 706 | V4L2_STD_SECAM_L |\ | ||
| 707 | V4L2_STD_SECAM_LC) | ||
| 708 | |||
| 709 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ | ||
| 710 | V4L2_STD_PAL_60 |\ | ||
| 711 | V4L2_STD_NTSC |\ | ||
| 712 | V4L2_STD_NTSC_443) | ||
| 713 | #define V4L2_STD_625_50 (V4L2_STD_PAL |\ | ||
| 714 | V4L2_STD_PAL_N |\ | ||
| 715 | V4L2_STD_PAL_Nc |\ | ||
| 716 | V4L2_STD_SECAM) | ||
| 717 | #define V4L2_STD_ATSC (V4L2_STD_ATSC_8_VSB |\ | ||
| 718 | V4L2_STD_ATSC_16_VSB) | ||
| 719 | |||
| 720 | #define V4L2_STD_UNKNOWN 0 | ||
| 721 | #define V4L2_STD_ALL (V4L2_STD_525_60 |\ | ||
| 722 | V4L2_STD_625_50) | ||
| 723 | |||
| 724 | struct <link linkend="v4l2-standard">v4l2_standard</link> { | ||
| 725 | __u32 index; | ||
| 726 | v4l2_std_id id; | ||
| 727 | __u8 name[24]; | ||
| 728 | struct <link linkend="v4l2-fract">v4l2_fract</link> frameperiod; /* Frames, not fields */ | ||
| 729 | __u32 framelines; | ||
| 730 | __u32 reserved[4]; | ||
| 731 | }; | ||
| 732 | |||
| 733 | /* | ||
| 734 | * V I D E O I N P U T S | ||
| 735 | */ | ||
| 736 | struct <link linkend="v4l2-input">v4l2_input</link> { | ||
| 737 | __u32 index; /* Which input */ | ||
| 738 | __u8 name[32]; /* Label */ | ||
| 739 | __u32 type; /* Type of input */ | ||
| 740 | __u32 audioset; /* Associated audios (bitfield) */ | ||
| 741 | __u32 tuner; /* Associated tuner */ | ||
| 742 | v4l2_std_id std; | ||
| 743 | __u32 status; | ||
| 744 | __u32 reserved[4]; | ||
| 745 | }; | ||
| 746 | |||
| 747 | /* Values for the 'type' field */ | ||
| 748 | #define V4L2_INPUT_TYPE_TUNER 1 | ||
| 749 | #define V4L2_INPUT_TYPE_CAMERA 2 | ||
| 750 | |||
| 751 | /* field 'status' - general */ | ||
| 752 | #define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */ | ||
| 753 | #define V4L2_IN_ST_NO_SIGNAL 0x00000002 | ||
| 754 | #define V4L2_IN_ST_NO_COLOR 0x00000004 | ||
| 755 | |||
| 756 | /* field 'status' - sensor orientation */ | ||
| 757 | /* If sensor is mounted upside down set both bits */ | ||
| 758 | #define V4L2_IN_ST_HFLIP 0x00000010 /* Frames are flipped horizontally */ | ||
| 759 | #define V4L2_IN_ST_VFLIP 0x00000020 /* Frames are flipped vertically */ | ||
| 760 | |||
| 761 | /* field 'status' - analog */ | ||
| 762 | #define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */ | ||
| 763 | #define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */ | ||
| 764 | |||
| 765 | /* field 'status' - digital */ | ||
| 766 | #define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */ | ||
| 767 | #define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */ | ||
| 768 | #define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */ | ||
| 769 | |||
| 770 | /* field 'status' - VCR and set-top box */ | ||
| 771 | #define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */ | ||
| 772 | #define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */ | ||
| 773 | #define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */ | ||
| 774 | |||
| 775 | /* | ||
| 776 | * V I D E O O U T P U T S | ||
| 777 | */ | ||
| 778 | struct <link linkend="v4l2-output">v4l2_output</link> { | ||
| 779 | __u32 index; /* Which output */ | ||
| 780 | __u8 name[32]; /* Label */ | ||
| 781 | __u32 type; /* Type of output */ | ||
| 782 | __u32 audioset; /* Associated audios (bitfield) */ | ||
| 783 | __u32 modulator; /* Associated modulator */ | ||
| 784 | v4l2_std_id std; | ||
| 785 | __u32 reserved[4]; | ||
| 786 | }; | ||
| 787 | /* Values for the 'type' field */ | ||
| 788 | #define V4L2_OUTPUT_TYPE_MODULATOR 1 | ||
| 789 | #define V4L2_OUTPUT_TYPE_ANALOG 2 | ||
| 790 | #define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3 | ||
| 791 | |||
| 792 | /* | ||
| 793 | * C O N T R O L S | ||
| 794 | */ | ||
| 795 | struct <link linkend="v4l2-control">v4l2_control</link> { | ||
| 796 | __u32 id; | ||
| 797 | __s32 value; | ||
| 798 | }; | ||
| 799 | |||
| 800 | struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> { | ||
| 801 | __u32 id; | ||
| 802 | __u32 size; | ||
| 803 | __u32 reserved2[1]; | ||
| 804 | union { | ||
| 805 | __s32 value; | ||
| 806 | __s64 value64; | ||
| 807 | char *string; | ||
| 808 | }; | ||
| 809 | } __attribute__ ((packed)); | ||
| 810 | |||
| 811 | struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link> { | ||
| 812 | __u32 ctrl_class; | ||
| 813 | __u32 count; | ||
| 814 | __u32 error_idx; | ||
| 815 | __u32 reserved[2]; | ||
| 816 | struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> *controls; | ||
| 817 | }; | ||
| 818 | |||
| 819 | /* Values for ctrl_class field */ | ||
| 820 | #define V4L2_CTRL_CLASS_USER 0x00980000 /* Old-style 'user' controls */ | ||
| 821 | #define V4L2_CTRL_CLASS_MPEG 0x00990000 /* MPEG-compression controls */ | ||
| 822 | #define V4L2_CTRL_CLASS_CAMERA 0x009a0000 /* Camera class controls */ | ||
| 823 | #define V4L2_CTRL_CLASS_FM_TX 0x009b0000 /* FM Modulator control class */ | ||
| 824 | |||
| 825 | #define V4L2_CTRL_ID_MASK (0x0fffffff) | ||
| 826 | #define V4L2_CTRL_ID2CLASS(id) ((id) & 0x0fff0000UL) | ||
| 827 | #define V4L2_CTRL_DRIVER_PRIV(id) (((id) & 0xffff) >= 0x1000) | ||
| 828 | |||
| 829 | /* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */ | ||
| 830 | struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link> { | ||
| 831 | __u32 id; | ||
| 832 | enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> type; | ||
| 833 | __u8 name[32]; /* Whatever */ | ||
| 834 | __s32 minimum; /* Note signedness */ | ||
| 835 | __s32 maximum; | ||
| 836 | __s32 step; | ||
| 837 | __s32 default_value; | ||
| 838 | __u32 flags; | ||
| 839 | __u32 reserved[2]; | ||
| 840 | }; | ||
| 841 | |||
| 842 | /* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */ | ||
| 843 | struct <link linkend="v4l2-querymenu">v4l2_querymenu</link> { | ||
| 844 | __u32 id; | ||
| 845 | __u32 index; | ||
| 846 | __u8 name[32]; /* Whatever */ | ||
| 847 | __u32 reserved; | ||
| 848 | }; | ||
| 849 | |||
| 850 | /* Control flags */ | ||
| 851 | #define V4L2_CTRL_FLAG_DISABLED 0x0001 | ||
| 852 | #define V4L2_CTRL_FLAG_GRABBED 0x0002 | ||
| 853 | #define V4L2_CTRL_FLAG_READ_ONLY 0x0004 | ||
| 854 | #define V4L2_CTRL_FLAG_UPDATE 0x0008 | ||
| 855 | #define V4L2_CTRL_FLAG_INACTIVE 0x0010 | ||
| 856 | #define V4L2_CTRL_FLAG_SLIDER 0x0020 | ||
| 857 | #define V4L2_CTRL_FLAG_WRITE_ONLY 0x0040 | ||
| 858 | |||
| 859 | /* Query flag, to be ORed with the control ID */ | ||
| 860 | #define V4L2_CTRL_FLAG_NEXT_CTRL 0x80000000 | ||
| 861 | |||
| 862 | /* User-class control IDs defined by V4L2 */ | ||
| 863 | #define V4L2_CID_BASE (V4L2_CTRL_CLASS_USER | 0x900) | ||
| 864 | #define V4L2_CID_USER_BASE V4L2_CID_BASE | ||
| 865 | /* IDs reserved for driver specific controls */ | ||
| 866 | #define V4L2_CID_PRIVATE_BASE 0x08000000 | ||
| 867 | |||
| 868 | #define V4L2_CID_USER_CLASS (V4L2_CTRL_CLASS_USER | 1) | ||
| 869 | #define V4L2_CID_BRIGHTNESS (V4L2_CID_BASE+0) | ||
| 870 | #define V4L2_CID_CONTRAST (V4L2_CID_BASE+1) | ||
| 871 | #define V4L2_CID_SATURATION (V4L2_CID_BASE+2) | ||
| 872 | #define V4L2_CID_HUE (V4L2_CID_BASE+3) | ||
| 873 | #define V4L2_CID_AUDIO_VOLUME (V4L2_CID_BASE+5) | ||
| 874 | #define V4L2_CID_AUDIO_BALANCE (V4L2_CID_BASE+6) | ||
| 875 | #define V4L2_CID_AUDIO_BASS (V4L2_CID_BASE+7) | ||
| 876 | #define V4L2_CID_AUDIO_TREBLE (V4L2_CID_BASE+8) | ||
| 877 | #define V4L2_CID_AUDIO_MUTE (V4L2_CID_BASE+9) | ||
| 878 | #define V4L2_CID_AUDIO_LOUDNESS (V4L2_CID_BASE+10) | ||
| 879 | #define V4L2_CID_BLACK_LEVEL (V4L2_CID_BASE+11) /* Deprecated */ | ||
| 880 | #define V4L2_CID_AUTO_WHITE_BALANCE (V4L2_CID_BASE+12) | ||
| 881 | #define V4L2_CID_DO_WHITE_BALANCE (V4L2_CID_BASE+13) | ||
| 882 | #define V4L2_CID_RED_BALANCE (V4L2_CID_BASE+14) | ||
| 883 | #define V4L2_CID_BLUE_BALANCE (V4L2_CID_BASE+15) | ||
| 884 | #define V4L2_CID_GAMMA (V4L2_CID_BASE+16) | ||
| 885 | #define V4L2_CID_WHITENESS (V4L2_CID_GAMMA) /* Deprecated */ | ||
| 886 | #define V4L2_CID_EXPOSURE (V4L2_CID_BASE+17) | ||
| 887 | #define V4L2_CID_AUTOGAIN (V4L2_CID_BASE+18) | ||
| 888 | #define V4L2_CID_GAIN (V4L2_CID_BASE+19) | ||
| 889 | #define V4L2_CID_HFLIP (V4L2_CID_BASE+20) | ||
| 890 | #define V4L2_CID_VFLIP (V4L2_CID_BASE+21) | ||
| 891 | |||
| 892 | /* Deprecated; use V4L2_CID_PAN_RESET and V4L2_CID_TILT_RESET */ | ||
| 893 | #define V4L2_CID_HCENTER (V4L2_CID_BASE+22) | ||
| 894 | #define V4L2_CID_VCENTER (V4L2_CID_BASE+23) | ||
| 895 | |||
| 896 | #define V4L2_CID_POWER_LINE_FREQUENCY (V4L2_CID_BASE+24) | ||
| 897 | enum <link linkend="v4l2-power-line-frequency">v4l2_power_line_frequency</link> { | ||
| 898 | V4L2_CID_POWER_LINE_FREQUENCY_DISABLED = 0, | ||
| 899 | V4L2_CID_POWER_LINE_FREQUENCY_50HZ = 1, | ||
| 900 | V4L2_CID_POWER_LINE_FREQUENCY_60HZ = 2, | ||
| 901 | }; | ||
| 902 | #define V4L2_CID_HUE_AUTO (V4L2_CID_BASE+25) | ||
| 903 | #define V4L2_CID_WHITE_BALANCE_TEMPERATURE (V4L2_CID_BASE+26) | ||
| 904 | #define V4L2_CID_SHARPNESS (V4L2_CID_BASE+27) | ||
| 905 | #define V4L2_CID_BACKLIGHT_COMPENSATION (V4L2_CID_BASE+28) | ||
| 906 | #define V4L2_CID_CHROMA_AGC (V4L2_CID_BASE+29) | ||
| 907 | #define V4L2_CID_COLOR_KILLER (V4L2_CID_BASE+30) | ||
| 908 | #define V4L2_CID_COLORFX (V4L2_CID_BASE+31) | ||
| 909 | enum <link linkend="v4l2-colorfx">v4l2_colorfx</link> { | ||
| 910 | V4L2_COLORFX_NONE = 0, | ||
| 911 | V4L2_COLORFX_BW = 1, | ||
| 912 | V4L2_COLORFX_SEPIA = 2, | ||
| 913 | }; | ||
| 914 | #define V4L2_CID_AUTOBRIGHTNESS (V4L2_CID_BASE+32) | ||
| 915 | #define V4L2_CID_BAND_STOP_FILTER (V4L2_CID_BASE+33) | ||
| 916 | |||
| 917 | /* last CID + 1 */ | ||
| 918 | #define V4L2_CID_LASTP1 (V4L2_CID_BASE+34) | ||
| 919 | |||
| 920 | /* MPEG-class control IDs defined by V4L2 */ | ||
| 921 | #define V4L2_CID_MPEG_BASE (V4L2_CTRL_CLASS_MPEG | 0x900) | ||
| 922 | #define V4L2_CID_MPEG_CLASS (V4L2_CTRL_CLASS_MPEG | 1) | ||
| 923 | |||
| 924 | /* MPEG streams */ | ||
| 925 | #define V4L2_CID_MPEG_STREAM_TYPE (V4L2_CID_MPEG_BASE+0) | ||
| 926 | enum <link linkend="v4l2-mpeg-stream-type">v4l2_mpeg_stream_type</link> { | ||
| 927 | V4L2_MPEG_STREAM_TYPE_MPEG2_PS = 0, /* MPEG-2 program stream */ | ||
| 928 | V4L2_MPEG_STREAM_TYPE_MPEG2_TS = 1, /* MPEG-2 transport stream */ | ||
| 929 | V4L2_MPEG_STREAM_TYPE_MPEG1_SS = 2, /* MPEG-1 system stream */ | ||
| 930 | V4L2_MPEG_STREAM_TYPE_MPEG2_DVD = 3, /* MPEG-2 DVD-compatible stream */ | ||
| 931 | V4L2_MPEG_STREAM_TYPE_MPEG1_VCD = 4, /* MPEG-1 VCD-compatible stream */ | ||
| 932 | V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD = 5, /* MPEG-2 SVCD-compatible stream */ | ||
| 933 | }; | ||
| 934 | #define V4L2_CID_MPEG_STREAM_PID_PMT (V4L2_CID_MPEG_BASE+1) | ||
| 935 | #define V4L2_CID_MPEG_STREAM_PID_AUDIO (V4L2_CID_MPEG_BASE+2) | ||
| 936 | #define V4L2_CID_MPEG_STREAM_PID_VIDEO (V4L2_CID_MPEG_BASE+3) | ||
| 937 | #define V4L2_CID_MPEG_STREAM_PID_PCR (V4L2_CID_MPEG_BASE+4) | ||
| 938 | #define V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (V4L2_CID_MPEG_BASE+5) | ||
| 939 | #define V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (V4L2_CID_MPEG_BASE+6) | ||
| 940 | #define V4L2_CID_MPEG_STREAM_VBI_FMT (V4L2_CID_MPEG_BASE+7) | ||
| 941 | enum <link linkend="v4l2-mpeg-stream-vbi-fmt">v4l2_mpeg_stream_vbi_fmt</link> { | ||
| 942 | V4L2_MPEG_STREAM_VBI_FMT_NONE = 0, /* No VBI in the MPEG stream */ | ||
| 943 | V4L2_MPEG_STREAM_VBI_FMT_IVTV = 1, /* VBI in private packets, IVTV format */ | ||
| 944 | }; | ||
| 945 | |||
| 946 | /* MPEG audio */ | ||
| 947 | #define V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (V4L2_CID_MPEG_BASE+100) | ||
| 948 | enum <link linkend="v4l2-mpeg-audio-sampling-freq">v4l2_mpeg_audio_sampling_freq</link> { | ||
| 949 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100 = 0, | ||
| 950 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000 = 1, | ||
| 951 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000 = 2, | ||
| 952 | }; | ||
| 953 | #define V4L2_CID_MPEG_AUDIO_ENCODING (V4L2_CID_MPEG_BASE+101) | ||
| 954 | enum <link linkend="v4l2-mpeg-audio-encoding">v4l2_mpeg_audio_encoding</link> { | ||
| 955 | V4L2_MPEG_AUDIO_ENCODING_LAYER_1 = 0, | ||
| 956 | V4L2_MPEG_AUDIO_ENCODING_LAYER_2 = 1, | ||
| 957 | V4L2_MPEG_AUDIO_ENCODING_LAYER_3 = 2, | ||
| 958 | V4L2_MPEG_AUDIO_ENCODING_AAC = 3, | ||
| 959 | V4L2_MPEG_AUDIO_ENCODING_AC3 = 4, | ||
| 960 | }; | ||
| 961 | #define V4L2_CID_MPEG_AUDIO_L1_BITRATE (V4L2_CID_MPEG_BASE+102) | ||
| 962 | enum <link linkend="v4l2-mpeg-audio-l1-bitrate">v4l2_mpeg_audio_l1_bitrate</link> { | ||
| 963 | V4L2_MPEG_AUDIO_L1_BITRATE_32K = 0, | ||
| 964 | V4L2_MPEG_AUDIO_L1_BITRATE_64K = 1, | ||
| 965 | V4L2_MPEG_AUDIO_L1_BITRATE_96K = 2, | ||
| 966 | V4L2_MPEG_AUDIO_L1_BITRATE_128K = 3, | ||
| 967 | V4L2_MPEG_AUDIO_L1_BITRATE_160K = 4, | ||
| 968 | V4L2_MPEG_AUDIO_L1_BITRATE_192K = 5, | ||
| 969 | V4L2_MPEG_AUDIO_L1_BITRATE_224K = 6, | ||
| 970 | V4L2_MPEG_AUDIO_L1_BITRATE_256K = 7, | ||
| 971 | V4L2_MPEG_AUDIO_L1_BITRATE_288K = 8, | ||
| 972 | V4L2_MPEG_AUDIO_L1_BITRATE_320K = 9, | ||
| 973 | V4L2_MPEG_AUDIO_L1_BITRATE_352K = 10, | ||
| 974 | V4L2_MPEG_AUDIO_L1_BITRATE_384K = 11, | ||
| 975 | V4L2_MPEG_AUDIO_L1_BITRATE_416K = 12, | ||
| 976 | V4L2_MPEG_AUDIO_L1_BITRATE_448K = 13, | ||
| 977 | }; | ||
| 978 | #define V4L2_CID_MPEG_AUDIO_L2_BITRATE (V4L2_CID_MPEG_BASE+103) | ||
| 979 | enum <link linkend="v4l2-mpeg-audio-l2-bitrate">v4l2_mpeg_audio_l2_bitrate</link> { | ||
| 980 | V4L2_MPEG_AUDIO_L2_BITRATE_32K = 0, | ||
| 981 | V4L2_MPEG_AUDIO_L2_BITRATE_48K = 1, | ||
| 982 | V4L2_MPEG_AUDIO_L2_BITRATE_56K = 2, | ||
| 983 | V4L2_MPEG_AUDIO_L2_BITRATE_64K = 3, | ||
| 984 | V4L2_MPEG_AUDIO_L2_BITRATE_80K = 4, | ||
| 985 | V4L2_MPEG_AUDIO_L2_BITRATE_96K = 5, | ||
| 986 | V4L2_MPEG_AUDIO_L2_BITRATE_112K = 6, | ||
| 987 | V4L2_MPEG_AUDIO_L2_BITRATE_128K = 7, | ||
| 988 | V4L2_MPEG_AUDIO_L2_BITRATE_160K = 8, | ||
| 989 | V4L2_MPEG_AUDIO_L2_BITRATE_192K = 9, | ||
| 990 | V4L2_MPEG_AUDIO_L2_BITRATE_224K = 10, | ||
| 991 | V4L2_MPEG_AUDIO_L2_BITRATE_256K = 11, | ||
| 992 | V4L2_MPEG_AUDIO_L2_BITRATE_320K = 12, | ||
| 993 | V4L2_MPEG_AUDIO_L2_BITRATE_384K = 13, | ||
| 994 | }; | ||
| 995 | #define V4L2_CID_MPEG_AUDIO_L3_BITRATE (V4L2_CID_MPEG_BASE+104) | ||
| 996 | enum <link linkend="v4l2-mpeg-audio-l3-bitrate">v4l2_mpeg_audio_l3_bitrate</link> { | ||
| 997 | V4L2_MPEG_AUDIO_L3_BITRATE_32K = 0, | ||
| 998 | V4L2_MPEG_AUDIO_L3_BITRATE_40K = 1, | ||
| 999 | V4L2_MPEG_AUDIO_L3_BITRATE_48K = 2, | ||
| 1000 | V4L2_MPEG_AUDIO_L3_BITRATE_56K = 3, | ||
| 1001 | V4L2_MPEG_AUDIO_L3_BITRATE_64K = 4, | ||
| 1002 | V4L2_MPEG_AUDIO_L3_BITRATE_80K = 5, | ||
| 1003 | V4L2_MPEG_AUDIO_L3_BITRATE_96K = 6, | ||
| 1004 | V4L2_MPEG_AUDIO_L3_BITRATE_112K = 7, | ||
| 1005 | V4L2_MPEG_AUDIO_L3_BITRATE_128K = 8, | ||
| 1006 | V4L2_MPEG_AUDIO_L3_BITRATE_160K = 9, | ||
| 1007 | V4L2_MPEG_AUDIO_L3_BITRATE_192K = 10, | ||
| 1008 | V4L2_MPEG_AUDIO_L3_BITRATE_224K = 11, | ||
| 1009 | V4L2_MPEG_AUDIO_L3_BITRATE_256K = 12, | ||
| 1010 | V4L2_MPEG_AUDIO_L3_BITRATE_320K = 13, | ||
| 1011 | }; | ||
| 1012 | #define V4L2_CID_MPEG_AUDIO_MODE (V4L2_CID_MPEG_BASE+105) | ||
| 1013 | enum <link linkend="v4l2-mpeg-audio-mode">v4l2_mpeg_audio_mode</link> { | ||
| 1014 | V4L2_MPEG_AUDIO_MODE_STEREO = 0, | ||
| 1015 | V4L2_MPEG_AUDIO_MODE_JOINT_STEREO = 1, | ||
| 1016 | V4L2_MPEG_AUDIO_MODE_DUAL = 2, | ||
| 1017 | V4L2_MPEG_AUDIO_MODE_MONO = 3, | ||
| 1018 | }; | ||
| 1019 | #define V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (V4L2_CID_MPEG_BASE+106) | ||
| 1020 | enum <link linkend="v4l2-mpeg-audio-mode-extension">v4l2_mpeg_audio_mode_extension</link> { | ||
| 1021 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4 = 0, | ||
| 1022 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8 = 1, | ||
| 1023 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12 = 2, | ||
| 1024 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16 = 3, | ||
| 1025 | }; | ||
| 1026 | #define V4L2_CID_MPEG_AUDIO_EMPHASIS (V4L2_CID_MPEG_BASE+107) | ||
| 1027 | enum <link linkend="v4l2-mpeg-audio-emphasis">v4l2_mpeg_audio_emphasis</link> { | ||
| 1028 | V4L2_MPEG_AUDIO_EMPHASIS_NONE = 0, | ||
| 1029 | V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS = 1, | ||
| 1030 | V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17 = 2, | ||
| 1031 | }; | ||
| 1032 | #define V4L2_CID_MPEG_AUDIO_CRC (V4L2_CID_MPEG_BASE+108) | ||
| 1033 | enum <link linkend="v4l2-mpeg-audio-crc">v4l2_mpeg_audio_crc</link> { | ||
| 1034 | V4L2_MPEG_AUDIO_CRC_NONE = 0, | ||
| 1035 | V4L2_MPEG_AUDIO_CRC_CRC16 = 1, | ||
| 1036 | }; | ||
| 1037 | #define V4L2_CID_MPEG_AUDIO_MUTE (V4L2_CID_MPEG_BASE+109) | ||
| 1038 | #define V4L2_CID_MPEG_AUDIO_AAC_BITRATE (V4L2_CID_MPEG_BASE+110) | ||
| 1039 | #define V4L2_CID_MPEG_AUDIO_AC3_BITRATE (V4L2_CID_MPEG_BASE+111) | ||
| 1040 | enum <link linkend="v4l2-mpeg-audio-ac3-bitrate">v4l2_mpeg_audio_ac3_bitrate</link> { | ||
| 1041 | V4L2_MPEG_AUDIO_AC3_BITRATE_32K = 0, | ||
| 1042 | V4L2_MPEG_AUDIO_AC3_BITRATE_40K = 1, | ||
| 1043 | V4L2_MPEG_AUDIO_AC3_BITRATE_48K = 2, | ||
| 1044 | V4L2_MPEG_AUDIO_AC3_BITRATE_56K = 3, | ||
| 1045 | V4L2_MPEG_AUDIO_AC3_BITRATE_64K = 4, | ||
| 1046 | V4L2_MPEG_AUDIO_AC3_BITRATE_80K = 5, | ||
| 1047 | V4L2_MPEG_AUDIO_AC3_BITRATE_96K = 6, | ||
| 1048 | V4L2_MPEG_AUDIO_AC3_BITRATE_112K = 7, | ||
| 1049 | V4L2_MPEG_AUDIO_AC3_BITRATE_128K = 8, | ||
| 1050 | V4L2_MPEG_AUDIO_AC3_BITRATE_160K = 9, | ||
| 1051 | V4L2_MPEG_AUDIO_AC3_BITRATE_192K = 10, | ||
| 1052 | V4L2_MPEG_AUDIO_AC3_BITRATE_224K = 11, | ||
| 1053 | V4L2_MPEG_AUDIO_AC3_BITRATE_256K = 12, | ||
| 1054 | V4L2_MPEG_AUDIO_AC3_BITRATE_320K = 13, | ||
| 1055 | V4L2_MPEG_AUDIO_AC3_BITRATE_384K = 14, | ||
| 1056 | V4L2_MPEG_AUDIO_AC3_BITRATE_448K = 15, | ||
| 1057 | V4L2_MPEG_AUDIO_AC3_BITRATE_512K = 16, | ||
| 1058 | V4L2_MPEG_AUDIO_AC3_BITRATE_576K = 17, | ||
| 1059 | V4L2_MPEG_AUDIO_AC3_BITRATE_640K = 18, | ||
| 1060 | }; | ||
| 1061 | |||
| 1062 | /* MPEG video */ | ||
| 1063 | #define V4L2_CID_MPEG_VIDEO_ENCODING (V4L2_CID_MPEG_BASE+200) | ||
| 1064 | enum <link linkend="v4l2-mpeg-video-encoding">v4l2_mpeg_video_encoding</link> { | ||
| 1065 | V4L2_MPEG_VIDEO_ENCODING_MPEG_1 = 0, | ||
| 1066 | V4L2_MPEG_VIDEO_ENCODING_MPEG_2 = 1, | ||
| 1067 | V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC = 2, | ||
| 1068 | }; | ||
| 1069 | #define V4L2_CID_MPEG_VIDEO_ASPECT (V4L2_CID_MPEG_BASE+201) | ||
| 1070 | enum <link linkend="v4l2-mpeg-video-aspect">v4l2_mpeg_video_aspect</link> { | ||
| 1071 | V4L2_MPEG_VIDEO_ASPECT_1x1 = 0, | ||
| 1072 | V4L2_MPEG_VIDEO_ASPECT_4x3 = 1, | ||
| 1073 | V4L2_MPEG_VIDEO_ASPECT_16x9 = 2, | ||
| 1074 | V4L2_MPEG_VIDEO_ASPECT_221x100 = 3, | ||
| 1075 | }; | ||
| 1076 | #define V4L2_CID_MPEG_VIDEO_B_FRAMES (V4L2_CID_MPEG_BASE+202) | ||
| 1077 | #define V4L2_CID_MPEG_VIDEO_GOP_SIZE (V4L2_CID_MPEG_BASE+203) | ||
| 1078 | #define V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (V4L2_CID_MPEG_BASE+204) | ||
| 1079 | #define V4L2_CID_MPEG_VIDEO_PULLDOWN (V4L2_CID_MPEG_BASE+205) | ||
| 1080 | #define V4L2_CID_MPEG_VIDEO_BITRATE_MODE (V4L2_CID_MPEG_BASE+206) | ||
| 1081 | enum <link linkend="v4l2-mpeg-video-bitrate-mode">v4l2_mpeg_video_bitrate_mode</link> { | ||
| 1082 | V4L2_MPEG_VIDEO_BITRATE_MODE_VBR = 0, | ||
| 1083 | V4L2_MPEG_VIDEO_BITRATE_MODE_CBR = 1, | ||
| 1084 | }; | ||
| 1085 | #define V4L2_CID_MPEG_VIDEO_BITRATE (V4L2_CID_MPEG_BASE+207) | ||
| 1086 | #define V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (V4L2_CID_MPEG_BASE+208) | ||
| 1087 | #define V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (V4L2_CID_MPEG_BASE+209) | ||
| 1088 | #define V4L2_CID_MPEG_VIDEO_MUTE (V4L2_CID_MPEG_BASE+210) | ||
| 1089 | #define V4L2_CID_MPEG_VIDEO_MUTE_YUV (V4L2_CID_MPEG_BASE+211) | ||
| 1090 | |||
| 1091 | /* MPEG-class control IDs specific to the CX2341x driver as defined by V4L2 */ | ||
| 1092 | #define V4L2_CID_MPEG_CX2341X_BASE (V4L2_CTRL_CLASS_MPEG | 0x1000) | ||
| 1093 | #define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+0) | ||
| 1094 | enum <link linkend="v4l2-mpeg-cx2341x-video-spatial-filter-mode">v4l2_mpeg_cx2341x_video_spatial_filter_mode</link> { | ||
| 1095 | V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL = 0, | ||
| 1096 | V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO = 1, | ||
| 1097 | }; | ||
| 1098 | #define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+1) | ||
| 1099 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+2) | ||
| 1100 | enum <link linkend="luma-spatial-filter-type">v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link> { | ||
| 1101 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF = 0, | ||
| 1102 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR = 1, | ||
| 1103 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT = 2, | ||
| 1104 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE = 3, | ||
| 1105 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE = 4, | ||
| 1106 | }; | ||
| 1107 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+3) | ||
| 1108 | enum <link linkend="chroma-spatial-filter-type">v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link> { | ||
| 1109 | V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF = 0, | ||
| 1110 | V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR = 1, | ||
| 1111 | }; | ||
| 1112 | #define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+4) | ||
| 1113 | enum <link linkend="v4l2-mpeg-cx2341x-video-temporal-filter-mode">v4l2_mpeg_cx2341x_video_temporal_filter_mode</link> { | ||
| 1114 | V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL = 0, | ||
| 1115 | V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO = 1, | ||
| 1116 | }; | ||
| 1117 | #define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+5) | ||
| 1118 | #define V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+6) | ||
| 1119 | enum <link linkend="v4l2-mpeg-cx2341x-video-median-filter-type">v4l2_mpeg_cx2341x_video_median_filter_type</link> { | ||
| 1120 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF = 0, | ||
| 1121 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR = 1, | ||
| 1122 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT = 2, | ||
| 1123 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT = 3, | ||
| 1124 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG = 4, | ||
| 1125 | }; | ||
| 1126 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+7) | ||
| 1127 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+8) | ||
| 1128 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+9) | ||
| 1129 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+10) | ||
| 1130 | #define V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (V4L2_CID_MPEG_CX2341X_BASE+11) | ||
| 1131 | |||
| 1132 | /* Camera class control IDs */ | ||
| 1133 | #define V4L2_CID_CAMERA_CLASS_BASE (V4L2_CTRL_CLASS_CAMERA | 0x900) | ||
| 1134 | #define V4L2_CID_CAMERA_CLASS (V4L2_CTRL_CLASS_CAMERA | 1) | ||
| 1135 | |||
| 1136 | #define V4L2_CID_EXPOSURE_AUTO (V4L2_CID_CAMERA_CLASS_BASE+1) | ||
| 1137 | enum <link linkend="v4l2-exposure-auto-type">v4l2_exposure_auto_type</link> { | ||
| 1138 | V4L2_EXPOSURE_AUTO = 0, | ||
| 1139 | V4L2_EXPOSURE_MANUAL = 1, | ||
| 1140 | V4L2_EXPOSURE_SHUTTER_PRIORITY = 2, | ||
| 1141 | V4L2_EXPOSURE_APERTURE_PRIORITY = 3 | ||
| 1142 | }; | ||
| 1143 | #define V4L2_CID_EXPOSURE_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+2) | ||
| 1144 | #define V4L2_CID_EXPOSURE_AUTO_PRIORITY (V4L2_CID_CAMERA_CLASS_BASE+3) | ||
| 1145 | |||
| 1146 | #define V4L2_CID_PAN_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+4) | ||
| 1147 | #define V4L2_CID_TILT_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+5) | ||
| 1148 | #define V4L2_CID_PAN_RESET (V4L2_CID_CAMERA_CLASS_BASE+6) | ||
| 1149 | #define V4L2_CID_TILT_RESET (V4L2_CID_CAMERA_CLASS_BASE+7) | ||
| 1150 | |||
| 1151 | #define V4L2_CID_PAN_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+8) | ||
| 1152 | #define V4L2_CID_TILT_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+9) | ||
| 1153 | |||
| 1154 | #define V4L2_CID_FOCUS_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+10) | ||
| 1155 | #define V4L2_CID_FOCUS_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+11) | ||
| 1156 | #define V4L2_CID_FOCUS_AUTO (V4L2_CID_CAMERA_CLASS_BASE+12) | ||
| 1157 | |||
| 1158 | #define V4L2_CID_ZOOM_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+13) | ||
| 1159 | #define V4L2_CID_ZOOM_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+14) | ||
| 1160 | #define V4L2_CID_ZOOM_CONTINUOUS (V4L2_CID_CAMERA_CLASS_BASE+15) | ||
| 1161 | |||
| 1162 | #define V4L2_CID_PRIVACY (V4L2_CID_CAMERA_CLASS_BASE+16) | ||
| 1163 | |||
| 1164 | /* FM Modulator class control IDs */ | ||
| 1165 | #define V4L2_CID_FM_TX_CLASS_BASE (V4L2_CTRL_CLASS_FM_TX | 0x900) | ||
| 1166 | #define V4L2_CID_FM_TX_CLASS (V4L2_CTRL_CLASS_FM_TX | 1) | ||
| 1167 | |||
| 1168 | #define V4L2_CID_RDS_TX_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 1) | ||
| 1169 | #define V4L2_CID_RDS_TX_PI (V4L2_CID_FM_TX_CLASS_BASE + 2) | ||
| 1170 | #define V4L2_CID_RDS_TX_PTY (V4L2_CID_FM_TX_CLASS_BASE + 3) | ||
| 1171 | #define V4L2_CID_RDS_TX_PS_NAME (V4L2_CID_FM_TX_CLASS_BASE + 5) | ||
| 1172 | #define V4L2_CID_RDS_TX_RADIO_TEXT (V4L2_CID_FM_TX_CLASS_BASE + 6) | ||
| 1173 | |||
| 1174 | #define V4L2_CID_AUDIO_LIMITER_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 64) | ||
| 1175 | #define V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 65) | ||
| 1176 | #define V4L2_CID_AUDIO_LIMITER_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 66) | ||
| 1177 | |||
| 1178 | #define V4L2_CID_AUDIO_COMPRESSION_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 80) | ||
| 1179 | #define V4L2_CID_AUDIO_COMPRESSION_GAIN (V4L2_CID_FM_TX_CLASS_BASE + 81) | ||
| 1180 | #define V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (V4L2_CID_FM_TX_CLASS_BASE + 82) | ||
| 1181 | #define V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (V4L2_CID_FM_TX_CLASS_BASE + 83) | ||
| 1182 | #define V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 84) | ||
| 1183 | |||
| 1184 | #define V4L2_CID_PILOT_TONE_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 96) | ||
| 1185 | #define V4L2_CID_PILOT_TONE_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 97) | ||
| 1186 | #define V4L2_CID_PILOT_TONE_FREQUENCY (V4L2_CID_FM_TX_CLASS_BASE + 98) | ||
| 1187 | |||
| 1188 | #define V4L2_CID_TUNE_PREEMPHASIS (V4L2_CID_FM_TX_CLASS_BASE + 112) | ||
| 1189 | enum <link linkend="v4l2-preemphasis">v4l2_preemphasis</link> { | ||
| 1190 | V4L2_PREEMPHASIS_DISABLED = 0, | ||
| 1191 | V4L2_PREEMPHASIS_50_uS = 1, | ||
| 1192 | V4L2_PREEMPHASIS_75_uS = 2, | ||
| 1193 | }; | ||
| 1194 | #define V4L2_CID_TUNE_POWER_LEVEL (V4L2_CID_FM_TX_CLASS_BASE + 113) | ||
| 1195 | #define V4L2_CID_TUNE_ANTENNA_CAPACITOR (V4L2_CID_FM_TX_CLASS_BASE + 114) | ||
| 1196 | |||
| 1197 | /* | ||
| 1198 | * T U N I N G | ||
| 1199 | */ | ||
| 1200 | struct <link linkend="v4l2-tuner">v4l2_tuner</link> { | ||
| 1201 | __u32 index; | ||
| 1202 | __u8 name[32]; | ||
| 1203 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1204 | __u32 capability; | ||
| 1205 | __u32 rangelow; | ||
| 1206 | __u32 rangehigh; | ||
| 1207 | __u32 rxsubchans; | ||
| 1208 | __u32 audmode; | ||
| 1209 | __s32 signal; | ||
| 1210 | __s32 afc; | ||
| 1211 | __u32 reserved[4]; | ||
| 1212 | }; | ||
| 1213 | |||
| 1214 | struct <link linkend="v4l2-modulator">v4l2_modulator</link> { | ||
| 1215 | __u32 index; | ||
| 1216 | __u8 name[32]; | ||
| 1217 | __u32 capability; | ||
| 1218 | __u32 rangelow; | ||
| 1219 | __u32 rangehigh; | ||
| 1220 | __u32 txsubchans; | ||
| 1221 | __u32 reserved[4]; | ||
| 1222 | }; | ||
| 1223 | |||
| 1224 | /* Flags for the 'capability' field */ | ||
| 1225 | #define V4L2_TUNER_CAP_LOW 0x0001 | ||
| 1226 | #define V4L2_TUNER_CAP_NORM 0x0002 | ||
| 1227 | #define V4L2_TUNER_CAP_STEREO 0x0010 | ||
| 1228 | #define V4L2_TUNER_CAP_LANG2 0x0020 | ||
| 1229 | #define V4L2_TUNER_CAP_SAP 0x0020 | ||
| 1230 | #define V4L2_TUNER_CAP_LANG1 0x0040 | ||
| 1231 | #define V4L2_TUNER_CAP_RDS 0x0080 | ||
| 1232 | |||
| 1233 | /* Flags for the 'rxsubchans' field */ | ||
| 1234 | #define V4L2_TUNER_SUB_MONO 0x0001 | ||
| 1235 | #define V4L2_TUNER_SUB_STEREO 0x0002 | ||
| 1236 | #define V4L2_TUNER_SUB_LANG2 0x0004 | ||
| 1237 | #define V4L2_TUNER_SUB_SAP 0x0004 | ||
| 1238 | #define V4L2_TUNER_SUB_LANG1 0x0008 | ||
| 1239 | #define V4L2_TUNER_SUB_RDS 0x0010 | ||
| 1240 | |||
| 1241 | /* Values for the 'audmode' field */ | ||
| 1242 | #define V4L2_TUNER_MODE_MONO 0x0000 | ||
| 1243 | #define V4L2_TUNER_MODE_STEREO 0x0001 | ||
| 1244 | #define V4L2_TUNER_MODE_LANG2 0x0002 | ||
| 1245 | #define V4L2_TUNER_MODE_SAP 0x0002 | ||
| 1246 | #define V4L2_TUNER_MODE_LANG1 0x0003 | ||
| 1247 | #define V4L2_TUNER_MODE_LANG1_LANG2 0x0004 | ||
| 1248 | |||
| 1249 | struct <link linkend="v4l2-frequency">v4l2_frequency</link> { | ||
| 1250 | __u32 tuner; | ||
| 1251 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1252 | __u32 frequency; | ||
| 1253 | __u32 reserved[8]; | ||
| 1254 | }; | ||
| 1255 | |||
| 1256 | struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link> { | ||
| 1257 | __u32 tuner; | ||
| 1258 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1259 | __u32 seek_upward; | ||
| 1260 | __u32 wrap_around; | ||
| 1261 | __u32 reserved[8]; | ||
| 1262 | }; | ||
| 1263 | |||
| 1264 | /* | ||
| 1265 | * R D S | ||
| 1266 | */ | ||
| 1267 | |||
| 1268 | struct <link linkend="v4l2-rds-data">v4l2_rds_data</link> { | ||
| 1269 | __u8 lsb; | ||
| 1270 | __u8 msb; | ||
| 1271 | __u8 block; | ||
| 1272 | } __attribute__ ((packed)); | ||
| 1273 | |||
| 1274 | #define V4L2_RDS_BLOCK_MSK 0x7 | ||
| 1275 | #define V4L2_RDS_BLOCK_A 0 | ||
| 1276 | #define V4L2_RDS_BLOCK_B 1 | ||
| 1277 | #define V4L2_RDS_BLOCK_C 2 | ||
| 1278 | #define V4L2_RDS_BLOCK_D 3 | ||
| 1279 | #define V4L2_RDS_BLOCK_C_ALT 4 | ||
| 1280 | #define V4L2_RDS_BLOCK_INVALID 7 | ||
| 1281 | |||
| 1282 | #define V4L2_RDS_BLOCK_CORRECTED 0x40 | ||
| 1283 | #define V4L2_RDS_BLOCK_ERROR 0x80 | ||
| 1284 | |||
| 1285 | /* | ||
| 1286 | * A U D I O | ||
| 1287 | */ | ||
| 1288 | struct <link linkend="v4l2-audio">v4l2_audio</link> { | ||
| 1289 | __u32 index; | ||
| 1290 | __u8 name[32]; | ||
| 1291 | __u32 capability; | ||
| 1292 | __u32 mode; | ||
| 1293 | __u32 reserved[2]; | ||
| 1294 | }; | ||
| 1295 | |||
| 1296 | /* Flags for the 'capability' field */ | ||
| 1297 | #define V4L2_AUDCAP_STEREO 0x00001 | ||
| 1298 | #define V4L2_AUDCAP_AVL 0x00002 | ||
| 1299 | |||
| 1300 | /* Flags for the 'mode' field */ | ||
| 1301 | #define V4L2_AUDMODE_AVL 0x00001 | ||
| 1302 | |||
| 1303 | struct <link linkend="v4l2-audioout">v4l2_audioout</link> { | ||
| 1304 | __u32 index; | ||
| 1305 | __u8 name[32]; | ||
| 1306 | __u32 capability; | ||
| 1307 | __u32 mode; | ||
| 1308 | __u32 reserved[2]; | ||
| 1309 | }; | ||
| 1310 | |||
| 1311 | /* | ||
| 1312 | * M P E G S E R V I C E S | ||
| 1313 | * | ||
| 1314 | * NOTE: EXPERIMENTAL API | ||
| 1315 | */ | ||
| 1316 | #if 1 /*KEEP*/ | ||
| 1317 | #define V4L2_ENC_IDX_FRAME_I (0) | ||
| 1318 | #define V4L2_ENC_IDX_FRAME_P (1) | ||
| 1319 | #define V4L2_ENC_IDX_FRAME_B (2) | ||
| 1320 | #define V4L2_ENC_IDX_FRAME_MASK (0xf) | ||
| 1321 | |||
| 1322 | struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> { | ||
| 1323 | __u64 offset; | ||
| 1324 | __u64 pts; | ||
| 1325 | __u32 length; | ||
| 1326 | __u32 flags; | ||
| 1327 | __u32 reserved[2]; | ||
| 1328 | }; | ||
| 1329 | |||
| 1330 | #define V4L2_ENC_IDX_ENTRIES (64) | ||
| 1331 | struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link> { | ||
| 1332 | __u32 entries; | ||
| 1333 | __u32 entries_cap; | ||
| 1334 | __u32 reserved[4]; | ||
| 1335 | struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> entry[V4L2_ENC_IDX_ENTRIES]; | ||
| 1336 | }; | ||
| 1337 | |||
| 1338 | |||
| 1339 | #define V4L2_ENC_CMD_START (0) | ||
| 1340 | #define V4L2_ENC_CMD_STOP (1) | ||
| 1341 | #define V4L2_ENC_CMD_PAUSE (2) | ||
| 1342 | #define V4L2_ENC_CMD_RESUME (3) | ||
| 1343 | |||
| 1344 | /* Flags for V4L2_ENC_CMD_STOP */ | ||
| 1345 | #define V4L2_ENC_CMD_STOP_AT_GOP_END (1 << 0) | ||
| 1346 | |||
| 1347 | struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link> { | ||
| 1348 | __u32 cmd; | ||
| 1349 | __u32 flags; | ||
| 1350 | union { | ||
| 1351 | struct { | ||
| 1352 | __u32 data[8]; | ||
| 1353 | } raw; | ||
| 1354 | }; | ||
| 1355 | }; | ||
| 1356 | |||
| 1357 | #endif | ||
| 1358 | |||
| 1359 | |||
| 1360 | /* | ||
| 1361 | * D A T A S E R V I C E S ( V B I ) | ||
| 1362 | * | ||
| 1363 | * Data services API by Michael Schimek | ||
| 1364 | */ | ||
| 1365 | |||
| 1366 | /* Raw VBI */ | ||
| 1367 | struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> { | ||
| 1368 | __u32 sampling_rate; /* in 1 Hz */ | ||
| 1369 | __u32 offset; | ||
| 1370 | __u32 samples_per_line; | ||
| 1371 | __u32 sample_format; /* V4L2_PIX_FMT_* */ | ||
| 1372 | __s32 start[2]; | ||
| 1373 | __u32 count[2]; | ||
| 1374 | __u32 flags; /* V4L2_VBI_* */ | ||
| 1375 | __u32 reserved[2]; /* must be zero */ | ||
| 1376 | }; | ||
| 1377 | |||
| 1378 | /* VBI flags */ | ||
| 1379 | #define V4L2_VBI_UNSYNC (1 << 0) | ||
| 1380 | #define V4L2_VBI_INTERLACED (1 << 1) | ||
| 1381 | |||
| 1382 | /* Sliced VBI | ||
| 1383 | * | ||
| 1384 | * This implements is a proposal V4L2 API to allow SLICED VBI | ||
| 1385 | * required for some hardware encoders. It should change without | ||
| 1386 | * notice in the definitive implementation. | ||
| 1387 | */ | ||
| 1388 | |||
| 1389 | struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> { | ||
| 1390 | __u16 service_set; | ||
| 1391 | /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field | ||
| 1392 | service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field | ||
| 1393 | (equals frame lines 313-336 for 625 line video | ||
| 1394 | standards, 263-286 for 525 line standards) */ | ||
| 1395 | __u16 service_lines[2][24]; | ||
| 1396 | __u32 io_size; | ||
| 1397 | __u32 reserved[2]; /* must be zero */ | ||
| 1398 | }; | ||
| 1399 | |||
| 1400 | /* Teletext World System Teletext | ||
| 1401 | (WST), defined on ITU-R BT.653-2 */ | ||
| 1402 | #define V4L2_SLICED_TELETEXT_B (0x0001) | ||
| 1403 | /* Video Program System, defined on ETS 300 231*/ | ||
| 1404 | #define V4L2_SLICED_VPS (0x0400) | ||
| 1405 | /* Closed Caption, defined on EIA-608 */ | ||
| 1406 | #define V4L2_SLICED_CAPTION_525 (0x1000) | ||
| 1407 | /* Wide Screen System, defined on ITU-R BT1119.1 */ | ||
| 1408 | #define V4L2_SLICED_WSS_625 (0x4000) | ||
| 1409 | |||
| 1410 | #define V4L2_SLICED_VBI_525 (V4L2_SLICED_CAPTION_525) | ||
| 1411 | #define V4L2_SLICED_VBI_625 (V4L2_SLICED_TELETEXT_B | V4L2_SLICED_VPS | V4L2_SLICED_WSS_625) | ||
| 1412 | |||
| 1413 | struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link> { | ||
| 1414 | __u16 service_set; | ||
| 1415 | /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field | ||
| 1416 | service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field | ||
| 1417 | (equals frame lines 313-336 for 625 line video | ||
| 1418 | standards, 263-286 for 525 line standards) */ | ||
| 1419 | __u16 service_lines[2][24]; | ||
| 1420 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1421 | __u32 reserved[3]; /* must be 0 */ | ||
| 1422 | }; | ||
| 1423 | |||
| 1424 | struct <link linkend="v4l2-sliced-vbi-data">v4l2_sliced_vbi_data</link> { | ||
| 1425 | __u32 id; | ||
| 1426 | __u32 field; /* 0: first field, 1: second field */ | ||
| 1427 | __u32 line; /* 1-23 */ | ||
| 1428 | __u32 reserved; /* must be 0 */ | ||
| 1429 | __u8 data[48]; | ||
| 1430 | }; | ||
| 1431 | |||
| 1432 | /* | ||
| 1433 | * Sliced VBI data inserted into MPEG Streams | ||
| 1434 | */ | ||
| 1435 | |||
| 1436 | /* | ||
| 1437 | * V4L2_MPEG_STREAM_VBI_FMT_IVTV: | ||
| 1438 | * | ||
| 1439 | * Structure of payload contained in an MPEG 2 Private Stream 1 PES Packet in an | ||
| 1440 | * MPEG-2 Program Pack that contains V4L2_MPEG_STREAM_VBI_FMT_IVTV Sliced VBI | ||
| 1441 | * data | ||
| 1442 | * | ||
| 1443 | * Note, the MPEG-2 Program Pack and Private Stream 1 PES packet header | ||
| 1444 | * definitions are not included here. See the MPEG-2 specifications for details | ||
| 1445 | * on these headers. | ||
| 1446 | */ | ||
| 1447 | |||
| 1448 | /* Line type IDs */ | ||
| 1449 | #define V4L2_MPEG_VBI_IVTV_TELETEXT_B (1) | ||
| 1450 | #define V4L2_MPEG_VBI_IVTV_CAPTION_525 (4) | ||
| 1451 | #define V4L2_MPEG_VBI_IVTV_WSS_625 (5) | ||
| 1452 | #define V4L2_MPEG_VBI_IVTV_VPS (7) | ||
| 1453 | |||
| 1454 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> { | ||
| 1455 | __u8 id; /* One of V4L2_MPEG_VBI_IVTV_* above */ | ||
| 1456 | __u8 data[42]; /* Sliced VBI data for the line */ | ||
| 1457 | } __attribute__ ((packed)); | ||
| 1458 | |||
| 1459 | struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> { | ||
| 1460 | __le32 linemask[2]; /* Bitmasks of VBI service lines present */ | ||
| 1461 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[35]; | ||
| 1462 | } __attribute__ ((packed)); | ||
| 1463 | |||
| 1464 | struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> { | ||
| 1465 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[36]; | ||
| 1466 | } __attribute__ ((packed)); | ||
| 1467 | |||
| 1468 | #define V4L2_MPEG_VBI_IVTV_MAGIC0 "itv0" | ||
| 1469 | #define V4L2_MPEG_VBI_IVTV_MAGIC1 "ITV0" | ||
| 1470 | |||
| 1471 | struct <link linkend="v4l2-mpeg-vbi-fmt-ivtv">v4l2_mpeg_vbi_fmt_ivtv</link> { | ||
| 1472 | __u8 magic[4]; | ||
| 1473 | union { | ||
| 1474 | struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> itv0; | ||
| 1475 | struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> ITV0; | ||
| 1476 | }; | ||
| 1477 | } __attribute__ ((packed)); | ||
| 1478 | |||
| 1479 | /* | ||
| 1480 | * A G G R E G A T E S T R U C T U R E S | ||
| 1481 | */ | ||
| 1482 | |||
| 1483 | /* Stream data format | ||
| 1484 | */ | ||
| 1485 | struct <link linkend="v4l2-format">v4l2_format</link> { | ||
| 1486 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1487 | union { | ||
| 1488 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */ | ||
| 1489 | struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */ | ||
| 1490 | struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */ | ||
| 1491 | struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */ | ||
| 1492 | __u8 raw_data[200]; /* user-defined */ | ||
| 1493 | } fmt; | ||
| 1494 | }; | ||
| 1495 | |||
| 1496 | |||
| 1497 | /* Stream type-dependent parameters | ||
| 1498 | */ | ||
| 1499 | struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> { | ||
| 1500 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1501 | union { | ||
| 1502 | struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> capture; | ||
| 1503 | struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> output; | ||
| 1504 | __u8 raw_data[200]; /* user-defined */ | ||
| 1505 | } parm; | ||
| 1506 | }; | ||
| 1507 | |||
| 1508 | /* | ||
| 1509 | * A D V A N C E D D E B U G G I N G | ||
| 1510 | * | ||
| 1511 | * NOTE: EXPERIMENTAL API, NEVER RELY ON THIS IN APPLICATIONS! | ||
| 1512 | * FOR DEBUGGING, TESTING AND INTERNAL USE ONLY! | ||
| 1513 | */ | ||
| 1514 | |||
| 1515 | /* VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER */ | ||
| 1516 | |||
| 1517 | #define V4L2_CHIP_MATCH_HOST 0 /* Match against chip ID on host (0 for the host) */ | ||
| 1518 | #define V4L2_CHIP_MATCH_I2C_DRIVER 1 /* Match against I2C driver name */ | ||
| 1519 | #define V4L2_CHIP_MATCH_I2C_ADDR 2 /* Match against I2C 7-bit address */ | ||
| 1520 | #define V4L2_CHIP_MATCH_AC97 3 /* Match against anciliary AC97 chip */ | ||
| 1521 | |||
| 1522 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> { | ||
| 1523 | __u32 type; /* Match type */ | ||
| 1524 | union { /* Match this chip, meaning determined by type */ | ||
| 1525 | __u32 addr; | ||
| 1526 | char name[32]; | ||
| 1527 | }; | ||
| 1528 | } __attribute__ ((packed)); | ||
| 1529 | |||
| 1530 | struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link> { | ||
| 1531 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match; | ||
| 1532 | __u32 size; /* register size in bytes */ | ||
| 1533 | __u64 reg; | ||
| 1534 | __u64 val; | ||
| 1535 | } __attribute__ ((packed)); | ||
| 1536 | |||
| 1537 | /* VIDIOC_DBG_G_CHIP_IDENT */ | ||
| 1538 | struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { | ||
| 1539 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match; | ||
| 1540 | __u32 ident; /* chip identifier as specified in <media/v4l2-chip-ident.h> */ | ||
| 1541 | __u32 revision; /* chip revision, chip specific */ | ||
| 1542 | } __attribute__ ((packed)); | ||
| 1543 | |||
| 1544 | /* | ||
| 1545 | * I O C T L C O D E S F O R V I D E O D E V I C E S | ||
| 1546 | * | ||
| 1547 | */ | ||
| 1548 | #define VIDIOC_QUERYCAP _IOR('V', 0, struct <link linkend="v4l2-capability">v4l2_capability</link>) | ||
| 1549 | #define VIDIOC_RESERVED _IO('V', 1) | ||
| 1550 | #define VIDIOC_ENUM_FMT _IOWR('V', 2, struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link>) | ||
| 1551 | #define VIDIOC_G_FMT _IOWR('V', 4, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1552 | #define VIDIOC_S_FMT _IOWR('V', 5, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1553 | #define VIDIOC_REQBUFS _IOWR('V', 8, struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link>) | ||
| 1554 | #define VIDIOC_QUERYBUF _IOWR('V', 9, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1555 | #define VIDIOC_G_FBUF _IOR('V', 10, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>) | ||
| 1556 | #define VIDIOC_S_FBUF _IOW('V', 11, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>) | ||
| 1557 | #define VIDIOC_OVERLAY _IOW('V', 14, int) | ||
| 1558 | #define VIDIOC_QBUF _IOWR('V', 15, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1559 | #define VIDIOC_DQBUF _IOWR('V', 17, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1560 | #define VIDIOC_STREAMON _IOW('V', 18, int) | ||
| 1561 | #define VIDIOC_STREAMOFF _IOW('V', 19, int) | ||
| 1562 | #define VIDIOC_G_PARM _IOWR('V', 21, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1563 | #define VIDIOC_S_PARM _IOWR('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1564 | #define VIDIOC_G_STD _IOR('V', 23, v4l2_std_id) | ||
| 1565 | #define VIDIOC_S_STD _IOW('V', 24, v4l2_std_id) | ||
| 1566 | #define VIDIOC_ENUMSTD _IOWR('V', 25, struct <link linkend="v4l2-standard">v4l2_standard</link>) | ||
| 1567 | #define VIDIOC_ENUMINPUT _IOWR('V', 26, struct <link linkend="v4l2-input">v4l2_input</link>) | ||
| 1568 | #define VIDIOC_G_CTRL _IOWR('V', 27, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1569 | #define VIDIOC_S_CTRL _IOWR('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1570 | #define VIDIOC_G_TUNER _IOWR('V', 29, struct <link linkend="v4l2-tuner">v4l2_tuner</link>) | ||
| 1571 | #define VIDIOC_S_TUNER _IOW('V', 30, struct <link linkend="v4l2-tuner">v4l2_tuner</link>) | ||
| 1572 | #define VIDIOC_G_AUDIO _IOR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1573 | #define VIDIOC_S_AUDIO _IOW('V', 34, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1574 | #define VIDIOC_QUERYCTRL _IOWR('V', 36, struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link>) | ||
| 1575 | #define VIDIOC_QUERYMENU _IOWR('V', 37, struct <link linkend="v4l2-querymenu">v4l2_querymenu</link>) | ||
| 1576 | #define VIDIOC_G_INPUT _IOR('V', 38, int) | ||
| 1577 | #define VIDIOC_S_INPUT _IOWR('V', 39, int) | ||
| 1578 | #define VIDIOC_G_OUTPUT _IOR('V', 46, int) | ||
| 1579 | #define VIDIOC_S_OUTPUT _IOWR('V', 47, int) | ||
| 1580 | #define VIDIOC_ENUMOUTPUT _IOWR('V', 48, struct <link linkend="v4l2-output">v4l2_output</link>) | ||
| 1581 | #define VIDIOC_G_AUDOUT _IOR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1582 | #define VIDIOC_S_AUDOUT _IOW('V', 50, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1583 | #define VIDIOC_G_MODULATOR _IOWR('V', 54, struct <link linkend="v4l2-modulator">v4l2_modulator</link>) | ||
| 1584 | #define VIDIOC_S_MODULATOR _IOW('V', 55, struct <link linkend="v4l2-modulator">v4l2_modulator</link>) | ||
| 1585 | #define VIDIOC_G_FREQUENCY _IOWR('V', 56, struct <link linkend="v4l2-frequency">v4l2_frequency</link>) | ||
| 1586 | #define VIDIOC_S_FREQUENCY _IOW('V', 57, struct <link linkend="v4l2-frequency">v4l2_frequency</link>) | ||
| 1587 | #define VIDIOC_CROPCAP _IOWR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>) | ||
| 1588 | #define VIDIOC_G_CROP _IOWR('V', 59, struct <link linkend="v4l2-crop">v4l2_crop</link>) | ||
| 1589 | #define VIDIOC_S_CROP _IOW('V', 60, struct <link linkend="v4l2-crop">v4l2_crop</link>) | ||
| 1590 | #define VIDIOC_G_JPEGCOMP _IOR('V', 61, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>) | ||
| 1591 | #define VIDIOC_S_JPEGCOMP _IOW('V', 62, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>) | ||
| 1592 | #define VIDIOC_QUERYSTD _IOR('V', 63, v4l2_std_id) | ||
| 1593 | #define VIDIOC_TRY_FMT _IOWR('V', 64, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1594 | #define VIDIOC_ENUMAUDIO _IOWR('V', 65, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1595 | #define VIDIOC_ENUMAUDOUT _IOWR('V', 66, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1596 | #define VIDIOC_G_PRIORITY _IOR('V', 67, enum <link linkend="v4l2-priority">v4l2_priority</link>) | ||
| 1597 | #define VIDIOC_S_PRIORITY _IOW('V', 68, enum <link linkend="v4l2-priority">v4l2_priority</link>) | ||
| 1598 | #define VIDIOC_G_SLICED_VBI_CAP _IOWR('V', 69, struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link>) | ||
| 1599 | #define VIDIOC_LOG_STATUS _IO('V', 70) | ||
| 1600 | #define VIDIOC_G_EXT_CTRLS _IOWR('V', 71, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1601 | #define VIDIOC_S_EXT_CTRLS _IOWR('V', 72, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1602 | #define VIDIOC_TRY_EXT_CTRLS _IOWR('V', 73, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1603 | #if 1 /*KEEP*/ | ||
| 1604 | #define VIDIOC_ENUM_FRAMESIZES _IOWR('V', 74, struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link>) | ||
| 1605 | #define VIDIOC_ENUM_FRAMEINTERVALS _IOWR('V', 75, struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link>) | ||
| 1606 | #define VIDIOC_G_ENC_INDEX _IOR('V', 76, struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link>) | ||
| 1607 | #define VIDIOC_ENCODER_CMD _IOWR('V', 77, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>) | ||
| 1608 | #define VIDIOC_TRY_ENCODER_CMD _IOWR('V', 78, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>) | ||
| 1609 | #endif | ||
| 1610 | |||
| 1611 | #if 1 /*KEEP*/ | ||
| 1612 | /* Experimental, meant for debugging, testing and internal use. | ||
| 1613 | Only implemented if CONFIG_VIDEO_ADV_DEBUG is defined. | ||
| 1614 | You must be root to use these ioctls. Never use these in applications! */ | ||
| 1615 | #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>) | ||
| 1616 | #define VIDIOC_DBG_G_REGISTER _IOWR('V', 80, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>) | ||
| 1617 | |||
| 1618 | /* Experimental, meant for debugging, testing and internal use. | ||
| 1619 | Never use this ioctl in applications! */ | ||
| 1620 | #define VIDIOC_DBG_G_CHIP_IDENT _IOWR('V', 81, struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link>) | ||
| 1621 | #endif | ||
| 1622 | |||
| 1623 | #define VIDIOC_S_HW_FREQ_SEEK _IOW('V', 82, struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link>) | ||
| 1624 | /* Reminder: when adding new ioctls please add support for them to | ||
| 1625 | drivers/media/video/v4l2-compat-ioctl32.c as well! */ | ||
| 1626 | |||
| 1627 | #ifdef __OLD_VIDIOC_ | ||
| 1628 | /* for compatibility, will go away some day */ | ||
| 1629 | #define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int) | ||
| 1630 | #define VIDIOC_S_PARM_OLD _IOW('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1631 | #define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1632 | #define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1633 | #define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1634 | #define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>) | ||
| 1635 | #endif | ||
| 1636 | |||
| 1637 | #define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */ | ||
| 1638 | |||
| 1639 | #endif /* __LINUX_VIDEODEV2_H */ | ||
| 1640 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-cropcap.xml b/Documentation/DocBook/v4l/vidioc-cropcap.xml new file mode 100644 index 000000000000..816e90e283c5 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-cropcap.xml | |||
| @@ -0,0 +1,174 @@ | |||
| 1 | <refentry id="vidioc-cropcap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_CROPCAP</refname> | ||
| 9 | <refpurpose>Information about the video cropping and scaling abilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_cropcap | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_CROPCAP</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Applications use this function to query the cropping | ||
| 53 | limits, the pixel aspect of images and to calculate scale factors. | ||
| 54 | They set the <structfield>type</structfield> field of a v4l2_cropcap | ||
| 55 | structure to the respective buffer (stream) type and call the | ||
| 56 | <constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this | ||
| 57 | structure. Drivers fill the rest of the structure. The results are | ||
| 58 | constant except when switching the video standard. Remember this | ||
| 59 | switch can occur implicit when switching the video input or | ||
| 60 | output.</para> | ||
| 61 | |||
| 62 | <table pgwide="1" frame="none" id="v4l2-cropcap"> | ||
| 63 | <title>struct <structname>v4l2_cropcap</structname></title> | ||
| 64 | <tgroup cols="3"> | ||
| 65 | &cs-str; | ||
| 66 | <tbody valign="top"> | ||
| 67 | <row> | ||
| 68 | <entry>&v4l2-buf-type;</entry> | ||
| 69 | <entry><structfield>type</structfield></entry> | ||
| 70 | <entry>Type of the data stream, set by the application. | ||
| 71 | Only these types are valid here: | ||
| 72 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 73 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 74 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 75 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 76 | and higher.</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | ||
| 80 | <entry><structfield>bounds</structfield></entry> | ||
| 81 | <entry>Defines the window within capturing or output is | ||
| 82 | possible, this may exclude for example the horizontal and vertical | ||
| 83 | blanking areas. The cropping rectangle cannot exceed these limits. | ||
| 84 | Width and height are defined in pixels, the driver writer is free to | ||
| 85 | choose origin and units of the coordinate system in the analog | ||
| 86 | domain.</entry> | ||
| 87 | </row> | ||
| 88 | <row> | ||
| 89 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | ||
| 90 | <entry><structfield>defrect</structfield></entry> | ||
| 91 | <entry>Default cropping rectangle, it shall cover the | ||
| 92 | "whole picture". Assuming pixel aspect 1/1 this could be for example a | ||
| 93 | 640 × 480 rectangle for NTSC, a | ||
| 94 | 768 × 576 rectangle for PAL and SECAM centered over | ||
| 95 | the active picture area. The same co-ordinate system as for | ||
| 96 | <structfield>bounds</structfield> is used.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>&v4l2-fract;</entry> | ||
| 100 | <entry><structfield>pixelaspect</structfield></entry> | ||
| 101 | <entry><para>This is the pixel aspect (y / x) when no | ||
| 102 | scaling is applied, the ratio of the actual sampling | ||
| 103 | frequency and the frequency required to get square | ||
| 104 | pixels.</para><para>When cropping coordinates refer to square pixels, | ||
| 105 | the driver sets <structfield>pixelaspect</structfield> to 1/1. Other | ||
| 106 | common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled | ||
| 107 | according to [<xref linkend="itu601" />].</para></entry> | ||
| 108 | </row> | ||
| 109 | </tbody> | ||
| 110 | </tgroup> | ||
| 111 | </table> | ||
| 112 | |||
| 113 | <!-- NB this table is duplicated in the overlay chapter. --> | ||
| 114 | |||
| 115 | <table pgwide="1" frame="none" id="v4l2-rect-crop"> | ||
| 116 | <title>struct <structname>v4l2_rect</structname></title> | ||
| 117 | <tgroup cols="3"> | ||
| 118 | &cs-str; | ||
| 119 | <tbody valign="top"> | ||
| 120 | <row> | ||
| 121 | <entry>__s32</entry> | ||
| 122 | <entry><structfield>left</structfield></entry> | ||
| 123 | <entry>Horizontal offset of the top, left corner of the | ||
| 124 | rectangle, in pixels.</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>__s32</entry> | ||
| 128 | <entry><structfield>top</structfield></entry> | ||
| 129 | <entry>Vertical offset of the top, left corner of the | ||
| 130 | rectangle, in pixels.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>__s32</entry> | ||
| 134 | <entry><structfield>width</structfield></entry> | ||
| 135 | <entry>Width of the rectangle, in pixels.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__s32</entry> | ||
| 139 | <entry><structfield>height</structfield></entry> | ||
| 140 | <entry>Height of the rectangle, in pixels. Width | ||
| 141 | and height cannot be negative, the fields are signed for | ||
| 142 | hysterical reasons. <!-- video4linux-list@redhat.com | ||
| 143 | on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --> | ||
| 144 | </entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </table> | ||
| 149 | </refsect1> | ||
| 150 | |||
| 151 | <refsect1> | ||
| 152 | &return-value; | ||
| 153 | |||
| 154 | <variablelist> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The &v4l2-cropcap; <structfield>type</structfield> is | ||
| 159 | invalid or the ioctl is not supported. This is not permitted for | ||
| 160 | video capture, output and overlay devices, which must support | ||
| 161 | <constant>VIDIOC_CROPCAP</constant>.</para> | ||
| 162 | </listitem> | ||
| 163 | </varlistentry> | ||
| 164 | </variablelist> | ||
| 165 | </refsect1> | ||
| 166 | </refentry> | ||
| 167 | |||
| 168 | <!-- | ||
| 169 | Local Variables: | ||
| 170 | mode: sgml | ||
| 171 | sgml-parent-document: "v4l2.sgml" | ||
| 172 | indent-tabs-mode: nil | ||
| 173 | End: | ||
| 174 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml new file mode 100644 index 000000000000..4a09e203af0f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml | |||
| @@ -0,0 +1,275 @@ | |||
| 1 | <refentry id="vidioc-dbg-g-chip-ident"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_DBG_G_CHIP_IDENT</refname> | ||
| 9 | <refpurpose>Identify the chips on a TV card</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_dbg_chip_ident | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_DBG_G_CHIP_IDENT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <note> | ||
| 53 | <title>Experimental</title> | ||
| 54 | |||
| 55 | <para>This is an <link | ||
| 56 | linkend="experimental">experimental</link> interface and may change in | ||
| 57 | the future.</para> | ||
| 58 | </note> | ||
| 59 | |||
| 60 | <para>For driver debugging purposes this ioctl allows test | ||
| 61 | applications to query the driver about the chips present on the TV | ||
| 62 | card. Regular applications must not use it. When you found a chip | ||
| 63 | specific bug, please contact the linux-media mailing list (&v4l-ml;) | ||
| 64 | so it can be fixed.</para> | ||
| 65 | |||
| 66 | <para>To query the driver applications must initialize the | ||
| 67 | <structfield>match.type</structfield> and | ||
| 68 | <structfield>match.addr</structfield> or <structfield>match.name</structfield> | ||
| 69 | fields of a &v4l2-dbg-chip-ident; | ||
| 70 | and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to | ||
| 71 | this structure. On success the driver stores information about the | ||
| 72 | selected chip in the <structfield>ident</structfield> and | ||
| 73 | <structfield>revision</structfield> fields. On failure the structure | ||
| 74 | remains unchanged.</para> | ||
| 75 | |||
| 76 | <para>When <structfield>match.type</structfield> is | ||
| 77 | <constant>V4L2_CHIP_MATCH_HOST</constant>, | ||
| 78 | <structfield>match.addr</structfield> selects the nth non-&i2c; chip | ||
| 79 | on the TV card. You can enumerate all chips by starting at zero and | ||
| 80 | incrementing <structfield>match.addr</structfield> by one until | ||
| 81 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;. | ||
| 82 | The number zero always selects the host chip, ⪚ the chip connected | ||
| 83 | to the PCI or USB bus.</para> | ||
| 84 | |||
| 85 | <para>When <structfield>match.type</structfield> is | ||
| 86 | <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>, | ||
| 87 | <structfield>match.name</structfield> contains the I2C driver name. | ||
| 88 | For instance | ||
| 89 | <constant>"saa7127"</constant> will match any chip | ||
| 90 | supported by the saa7127 driver, regardless of its &i2c; bus address. | ||
| 91 | When multiple chips supported by the same driver are present, the | ||
| 92 | ioctl will return <constant>V4L2_IDENT_AMBIGUOUS</constant> in the | ||
| 93 | <structfield>ident</structfield> field.</para> | ||
| 94 | |||
| 95 | <para>When <structfield>match.type</structfield> is | ||
| 96 | <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>, | ||
| 97 | <structfield>match.addr</structfield> selects a chip by its 7 bit | ||
| 98 | &i2c; bus address.</para> | ||
| 99 | |||
| 100 | <para>When <structfield>match.type</structfield> is | ||
| 101 | <constant>V4L2_CHIP_MATCH_AC97</constant>, | ||
| 102 | <structfield>match.addr</structfield> selects the nth AC97 chip | ||
| 103 | on the TV card. You can enumerate all chips by starting at zero and | ||
| 104 | incrementing <structfield>match.addr</structfield> by one until | ||
| 105 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.</para> | ||
| 106 | |||
| 107 | <para>On success, the <structfield>ident</structfield> field will | ||
| 108 | contain a chip ID from the Linux | ||
| 109 | <filename>media/v4l2-chip-ident.h</filename> header file, and the | ||
| 110 | <structfield>revision</structfield> field will contain a driver | ||
| 111 | specific value, or zero if no particular revision is associated with | ||
| 112 | this chip.</para> | ||
| 113 | |||
| 114 | <para>When the driver could not identify the selected chip, | ||
| 115 | <structfield>ident</structfield> will contain | ||
| 116 | <constant>V4L2_IDENT_UNKNOWN</constant>. When no chip matched | ||
| 117 | the ioctl will succeed but the | ||
| 118 | <structfield>ident</structfield> field will contain | ||
| 119 | <constant>V4L2_IDENT_NONE</constant>. If multiple chips matched, | ||
| 120 | <structfield>ident</structfield> will contain | ||
| 121 | <constant>V4L2_IDENT_AMBIGUOUS</constant>. In all these cases the | ||
| 122 | <structfield>revision</structfield> field remains unchanged.</para> | ||
| 123 | |||
| 124 | <para>This ioctl is optional, not all drivers may support it. It | ||
| 125 | was introduced in Linux 2.6.21, but the API was changed to the | ||
| 126 | one described here in 2.6.29.</para> | ||
| 127 | |||
| 128 | <para>We recommended the <application>v4l2-dbg</application> | ||
| 129 | utility over calling this ioctl directly. It is available from the | ||
| 130 | LinuxTV v4l-dvb repository; see <ulink | ||
| 131 | url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for | ||
| 132 | access instructions.</para> | ||
| 133 | |||
| 134 | <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| 135 | contains a duplicate of this table. --> | ||
| 136 | <table pgwide="1" frame="none" id="ident-v4l2-dbg-match"> | ||
| 137 | <title>struct <structname>v4l2_dbg_match</structname></title> | ||
| 138 | <tgroup cols="4"> | ||
| 139 | &cs-ustr; | ||
| 140 | <tbody valign="top"> | ||
| 141 | <row> | ||
| 142 | <entry>__u32</entry> | ||
| 143 | <entry><structfield>type</structfield></entry> | ||
| 144 | <entry>See <xref linkend="ident-chip-match-types" /> for a list of | ||
| 145 | possible types.</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>union</entry> | ||
| 149 | <entry>(anonymous)</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry></entry> | ||
| 153 | <entry>__u32</entry> | ||
| 154 | <entry><structfield>addr</structfield></entry> | ||
| 155 | <entry>Match a chip by this number, interpreted according | ||
| 156 | to the <structfield>type</structfield> field.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry></entry> | ||
| 160 | <entry>char</entry> | ||
| 161 | <entry><structfield>name[32]</structfield></entry> | ||
| 162 | <entry>Match a chip by this name, interpreted according | ||
| 163 | to the <structfield>type</structfield> field.</entry> | ||
| 164 | </row> | ||
| 165 | </tbody> | ||
| 166 | </tgroup> | ||
| 167 | </table> | ||
| 168 | |||
| 169 | <table pgwide="1" frame="none" id="v4l2-dbg-chip-ident"> | ||
| 170 | <title>struct <structname>v4l2_dbg_chip_ident</structname></title> | ||
| 171 | <tgroup cols="3"> | ||
| 172 | &cs-str; | ||
| 173 | <tbody valign="top"> | ||
| 174 | <row> | ||
| 175 | <entry>struct v4l2_dbg_match</entry> | ||
| 176 | <entry><structfield>match</structfield></entry> | ||
| 177 | <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry>__u32</entry> | ||
| 181 | <entry><structfield>ident</structfield></entry> | ||
| 182 | <entry>A chip identifier as defined in the Linux | ||
| 183 | <filename>media/v4l2-chip-ident.h</filename> header file, or one of | ||
| 184 | the values from <xref linkend="chip-ids" />.</entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry>__u32</entry> | ||
| 188 | <entry><structfield>revision</structfield></entry> | ||
| 189 | <entry>A chip revision, chip and driver specific.</entry> | ||
| 190 | </row> | ||
| 191 | </tbody> | ||
| 192 | </tgroup> | ||
| 193 | </table> | ||
| 194 | |||
| 195 | <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| 196 | contains a duplicate of this table. --> | ||
| 197 | <table pgwide="1" frame="none" id="ident-chip-match-types"> | ||
| 198 | <title>Chip Match Types</title> | ||
| 199 | <tgroup cols="3"> | ||
| 200 | &cs-def; | ||
| 201 | <tbody valign="top"> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry> | ||
| 204 | <entry>0</entry> | ||
| 205 | <entry>Match the nth chip on the card, zero for the | ||
| 206 | host chip. Does not match &i2c; chips.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry> | ||
| 210 | <entry>1</entry> | ||
| 211 | <entry>Match an &i2c; chip by its driver name.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry> | ||
| 215 | <entry>2</entry> | ||
| 216 | <entry>Match a chip by its 7 bit &i2c; bus address.</entry> | ||
| 217 | </row> | ||
| 218 | <row> | ||
| 219 | <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry> | ||
| 220 | <entry>3</entry> | ||
| 221 | <entry>Match the nth anciliary AC97 chip.</entry> | ||
| 222 | </row> | ||
| 223 | </tbody> | ||
| 224 | </tgroup> | ||
| 225 | </table> | ||
| 226 | |||
| 227 | <!-- This is an anonymous enum in media/v4l2-chip-ident.h. --> | ||
| 228 | <table pgwide="1" frame="none" id="chip-ids"> | ||
| 229 | <title>Chip Identifiers</title> | ||
| 230 | <tgroup cols="3"> | ||
| 231 | &cs-def; | ||
| 232 | <tbody valign="top"> | ||
| 233 | <row> | ||
| 234 | <entry><constant>V4L2_IDENT_NONE</constant></entry> | ||
| 235 | <entry>0</entry> | ||
| 236 | <entry>No chip matched.</entry> | ||
| 237 | </row> | ||
| 238 | <row> | ||
| 239 | <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry> | ||
| 240 | <entry>1</entry> | ||
| 241 | <entry>Multiple chips matched.</entry> | ||
| 242 | </row> | ||
| 243 | <row> | ||
| 244 | <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry> | ||
| 245 | <entry>2</entry> | ||
| 246 | <entry>A chip is present at this address, but the driver | ||
| 247 | could not identify it.</entry> | ||
| 248 | </row> | ||
| 249 | </tbody> | ||
| 250 | </tgroup> | ||
| 251 | </table> | ||
| 252 | </refsect1> | ||
| 253 | |||
| 254 | <refsect1> | ||
| 255 | &return-value; | ||
| 256 | |||
| 257 | <variablelist> | ||
| 258 | <varlistentry> | ||
| 259 | <term><errorcode>EINVAL</errorcode></term> | ||
| 260 | <listitem> | ||
| 261 | <para>The driver does not support this ioctl, or the | ||
| 262 | <structfield>match_type</structfield> is invalid.</para> | ||
| 263 | </listitem> | ||
| 264 | </varlistentry> | ||
| 265 | </variablelist> | ||
| 266 | </refsect1> | ||
| 267 | </refentry> | ||
| 268 | |||
| 269 | <!-- | ||
| 270 | Local Variables: | ||
| 271 | mode: sgml | ||
| 272 | sgml-parent-document: "v4l2.sgml" | ||
| 273 | indent-tabs-mode: nil | ||
| 274 | End: | ||
| 275 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml new file mode 100644 index 000000000000..980c7f3e2fd6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml | |||
| @@ -0,0 +1,275 @@ | |||
| 1 | <refentry id="vidioc-dbg-g-register"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_DBG_G_REGISTER</refname> | ||
| 9 | <refname>VIDIOC_DBG_S_REGISTER</refname> | ||
| 10 | <refpurpose>Read or write hardware registers</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_dbg_register | ||
| 28 | *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para></para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <note> | ||
| 62 | <title>Experimental</title> | ||
| 63 | |||
| 64 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 65 | interface and may change in the future.</para> | ||
| 66 | </note> | ||
| 67 | |||
| 68 | <para>For driver debugging purposes these ioctls allow test | ||
| 69 | applications to access hardware registers directly. Regular | ||
| 70 | applications must not use them.</para> | ||
| 71 | |||
| 72 | <para>Since writing or even reading registers can jeopardize the | ||
| 73 | system security, its stability and damage the hardware, both ioctls | ||
| 74 | require superuser privileges. Additionally the Linux kernel must be | ||
| 75 | compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option | ||
| 76 | to enable these ioctls.</para> | ||
| 77 | |||
| 78 | <para>To write a register applications must initialize all fields | ||
| 79 | of a &v4l2-dbg-register; and call | ||
| 80 | <constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this | ||
| 81 | structure. The <structfield>match.type</structfield> and | ||
| 82 | <structfield>match.addr</structfield> or <structfield>match.name</structfield> | ||
| 83 | fields select a chip on the TV | ||
| 84 | card, the <structfield>reg</structfield> field specifies a register | ||
| 85 | number and the <structfield>val</structfield> field the value to be | ||
| 86 | written into the register.</para> | ||
| 87 | |||
| 88 | <para>To read a register applications must initialize the | ||
| 89 | <structfield>match.type</structfield>, | ||
| 90 | <structfield>match.chip</structfield> or <structfield>match.name</structfield> and | ||
| 91 | <structfield>reg</structfield> fields, and call | ||
| 92 | <constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this | ||
| 93 | structure. On success the driver stores the register value in the | ||
| 94 | <structfield>val</structfield> field. On failure the structure remains | ||
| 95 | unchanged.</para> | ||
| 96 | |||
| 97 | <para>When <structfield>match.type</structfield> is | ||
| 98 | <constant>V4L2_CHIP_MATCH_HOST</constant>, | ||
| 99 | <structfield>match.addr</structfield> selects the nth non-&i2c; chip | ||
| 100 | on the TV card. The number zero always selects the host chip, ⪚ the | ||
| 101 | chip connected to the PCI or USB bus. You can find out which chips are | ||
| 102 | present with the &VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> | ||
| 103 | |||
| 104 | <para>When <structfield>match.type</structfield> is | ||
| 105 | <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>, | ||
| 106 | <structfield>match.name</structfield> contains the I2C driver name. | ||
| 107 | For instance | ||
| 108 | <constant>"saa7127"</constant> will match any chip | ||
| 109 | supported by the saa7127 driver, regardless of its &i2c; bus address. | ||
| 110 | When multiple chips supported by the same driver are present, the | ||
| 111 | effect of these ioctls is undefined. Again with the | ||
| 112 | &VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are | ||
| 113 | present.</para> | ||
| 114 | |||
| 115 | <para>When <structfield>match.type</structfield> is | ||
| 116 | <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>, | ||
| 117 | <structfield>match.addr</structfield> selects a chip by its 7 bit &i2c; | ||
| 118 | bus address.</para> | ||
| 119 | |||
| 120 | <para>When <structfield>match.type</structfield> is | ||
| 121 | <constant>V4L2_CHIP_MATCH_AC97</constant>, | ||
| 122 | <structfield>match.addr</structfield> selects the nth AC97 chip | ||
| 123 | on the TV card.</para> | ||
| 124 | |||
| 125 | <note> | ||
| 126 | <title>Success not guaranteed</title> | ||
| 127 | |||
| 128 | <para>Due to a flaw in the Linux &i2c; bus driver these ioctls may | ||
| 129 | return successfully without actually reading or writing a register. To | ||
| 130 | catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT; | ||
| 131 | call confirming the presence of the selected &i2c; chip.</para> | ||
| 132 | </note> | ||
| 133 | |||
| 134 | <para>These ioctls are optional, not all drivers may support them. | ||
| 135 | However when a driver supports these ioctls it must also support | ||
| 136 | &VIDIOC-DBG-G-CHIP-IDENT;. Conversely it may support | ||
| 137 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> but not these ioctls.</para> | ||
| 138 | |||
| 139 | <para><constant>VIDIOC_DBG_G_REGISTER</constant> and | ||
| 140 | <constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux | ||
| 141 | 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para> | ||
| 142 | |||
| 143 | <para>We recommended the <application>v4l2-dbg</application> | ||
| 144 | utility over calling these ioctls directly. It is available from the | ||
| 145 | LinuxTV v4l-dvb repository; see <ulink | ||
| 146 | url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for | ||
| 147 | access instructions.</para> | ||
| 148 | |||
| 149 | <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml | ||
| 150 | contains a duplicate of this table. --> | ||
| 151 | <table pgwide="1" frame="none" id="v4l2-dbg-match"> | ||
| 152 | <title>struct <structname>v4l2_dbg_match</structname></title> | ||
| 153 | <tgroup cols="4"> | ||
| 154 | &cs-ustr; | ||
| 155 | <tbody valign="top"> | ||
| 156 | <row> | ||
| 157 | <entry>__u32</entry> | ||
| 158 | <entry><structfield>type</structfield></entry> | ||
| 159 | <entry>See <xref linkend="ident-chip-match-types" /> for a list of | ||
| 160 | possible types.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry>union</entry> | ||
| 164 | <entry>(anonymous)</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>__u32</entry> | ||
| 169 | <entry><structfield>addr</structfield></entry> | ||
| 170 | <entry>Match a chip by this number, interpreted according | ||
| 171 | to the <structfield>type</structfield> field.</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>char</entry> | ||
| 176 | <entry><structfield>name[32]</structfield></entry> | ||
| 177 | <entry>Match a chip by this name, interpreted according | ||
| 178 | to the <structfield>type</structfield> field.</entry> | ||
| 179 | </row> | ||
| 180 | </tbody> | ||
| 181 | </tgroup> | ||
| 182 | </table> | ||
| 183 | |||
| 184 | |||
| 185 | <table pgwide="1" frame="none" id="v4l2-dbg-register"> | ||
| 186 | <title>struct <structname>v4l2_dbg_register</structname></title> | ||
| 187 | <tgroup cols="4"> | ||
| 188 | <colspec colname="c1" /> | ||
| 189 | <colspec colname="c2" /> | ||
| 190 | <colspec colname="c4" /> | ||
| 191 | <tbody valign="top"> | ||
| 192 | <row> | ||
| 193 | <entry>struct v4l2_dbg_match</entry> | ||
| 194 | <entry><structfield>match</structfield></entry> | ||
| 195 | <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry>__u64</entry> | ||
| 199 | <entry><structfield>reg</structfield></entry> | ||
| 200 | <entry>A register number.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry>__u64</entry> | ||
| 204 | <entry><structfield>val</structfield></entry> | ||
| 205 | <entry>The value read from, or to be written into the | ||
| 206 | register.</entry> | ||
| 207 | </row> | ||
| 208 | </tbody> | ||
| 209 | </tgroup> | ||
| 210 | </table> | ||
| 211 | |||
| 212 | <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml | ||
| 213 | contains a duplicate of this table. --> | ||
| 214 | <table pgwide="1" frame="none" id="chip-match-types"> | ||
| 215 | <title>Chip Match Types</title> | ||
| 216 | <tgroup cols="3"> | ||
| 217 | &cs-def; | ||
| 218 | <tbody valign="top"> | ||
| 219 | <row> | ||
| 220 | <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry> | ||
| 221 | <entry>0</entry> | ||
| 222 | <entry>Match the nth chip on the card, zero for the | ||
| 223 | host chip. Does not match &i2c; chips.</entry> | ||
| 224 | </row> | ||
| 225 | <row> | ||
| 226 | <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry> | ||
| 227 | <entry>1</entry> | ||
| 228 | <entry>Match an &i2c; chip by its driver name.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry> | ||
| 232 | <entry>2</entry> | ||
| 233 | <entry>Match a chip by its 7 bit &i2c; bus address.</entry> | ||
| 234 | </row> | ||
| 235 | <row> | ||
| 236 | <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry> | ||
| 237 | <entry>3</entry> | ||
| 238 | <entry>Match the nth anciliary AC97 chip.</entry> | ||
| 239 | </row> | ||
| 240 | </tbody> | ||
| 241 | </tgroup> | ||
| 242 | </table> | ||
| 243 | </refsect1> | ||
| 244 | |||
| 245 | <refsect1> | ||
| 246 | &return-value; | ||
| 247 | |||
| 248 | <variablelist> | ||
| 249 | <varlistentry> | ||
| 250 | <term><errorcode>EINVAL</errorcode></term> | ||
| 251 | <listitem> | ||
| 252 | <para>The driver does not support this ioctl, or the kernel | ||
| 253 | was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> | ||
| 254 | option, or the <structfield>match_type</structfield> is invalid, or the | ||
| 255 | selected chip or register does not exist.</para> | ||
| 256 | </listitem> | ||
| 257 | </varlistentry> | ||
| 258 | <varlistentry> | ||
| 259 | <term><errorcode>EPERM</errorcode></term> | ||
| 260 | <listitem> | ||
| 261 | <para>Insufficient permissions. Root privileges are required | ||
| 262 | to execute these ioctls.</para> | ||
| 263 | </listitem> | ||
| 264 | </varlistentry> | ||
| 265 | </variablelist> | ||
| 266 | </refsect1> | ||
| 267 | </refentry> | ||
| 268 | |||
| 269 | <!-- | ||
| 270 | Local Variables: | ||
| 271 | mode: sgml | ||
| 272 | sgml-parent-document: "v4l2.sgml" | ||
| 273 | indent-tabs-mode: nil | ||
| 274 | End: | ||
| 275 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml new file mode 100644 index 000000000000..b0dde943825c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml | |||
| @@ -0,0 +1,204 @@ | |||
| 1 | <refentry id="vidioc-encoder-cmd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENCODER_CMD</refname> | ||
| 9 | <refname>VIDIOC_TRY_ENCODER_CMD</refname> | ||
| 10 | <refpurpose>Execute an encoder command</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <note> | ||
| 53 | <title>Experimental</title> | ||
| 54 | |||
| 55 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 56 | interface and may change in the future.</para> | ||
| 57 | </note> | ||
| 58 | |||
| 59 | <para>These ioctls control an audio/video (usually MPEG-) encoder. | ||
| 60 | <constant>VIDIOC_ENCODER_CMD</constant> sends a command to the | ||
| 61 | encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to | ||
| 62 | try a command without actually executing it.</para> | ||
| 63 | |||
| 64 | <para>To send a command applications must initialize all fields of a | ||
| 65 | &v4l2-encoder-cmd; and call | ||
| 66 | <constant>VIDIOC_ENCODER_CMD</constant> or | ||
| 67 | <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this | ||
| 68 | structure.</para> | ||
| 69 | |||
| 70 | <para>The <structfield>cmd</structfield> field must contain the | ||
| 71 | command code. The <structfield>flags</structfield> field is currently | ||
| 72 | only used by the STOP command and contains one bit: If the | ||
| 73 | <constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, | ||
| 74 | encoding will continue until the end of the current <wordasword>Group | ||
| 75 | Of Pictures</wordasword>, otherwise it will stop immediately.</para> | ||
| 76 | |||
| 77 | <para>A <function>read</function>() call sends a START command to | ||
| 78 | the encoder if it has not been started yet. After a STOP command, | ||
| 79 | <function>read</function>() calls will read the remaining data | ||
| 80 | buffered by the driver. When the buffer is empty, | ||
| 81 | <function>read</function>() will return zero and the next | ||
| 82 | <function>read</function>() call will restart the encoder.</para> | ||
| 83 | |||
| 84 | <para>A <function>close</function>() call sends an immediate STOP | ||
| 85 | to the encoder, and all buffered data is discarded.</para> | ||
| 86 | |||
| 87 | <para>These ioctls are optional, not all drivers may support | ||
| 88 | them. They were introduced in Linux 2.6.21.</para> | ||
| 89 | |||
| 90 | <table pgwide="1" frame="none" id="v4l2-encoder-cmd"> | ||
| 91 | <title>struct <structname>v4l2_encoder_cmd</structname></title> | ||
| 92 | <tgroup cols="3"> | ||
| 93 | &cs-str; | ||
| 94 | <tbody valign="top"> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>cmd</structfield></entry> | ||
| 98 | <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>flags</structfield></entry> | ||
| 103 | <entry>Flags to go with the command, see <xref | ||
| 104 | linkend="encoder-flags" />. If no flags are defined for | ||
| 105 | this command, drivers and applications must set this field to | ||
| 106 | zero.</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>__u32</entry> | ||
| 110 | <entry><structfield>data</structfield>[8]</entry> | ||
| 111 | <entry>Reserved for future extensions. Drivers and | ||
| 112 | applications must set the array to zero.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="encoder-cmds"> | ||
| 119 | <title>Encoder Commands</title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-def; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry><constant>V4L2_ENC_CMD_START</constant></entry> | ||
| 125 | <entry>0</entry> | ||
| 126 | <entry>Start the encoder. When the encoder is already | ||
| 127 | running or paused, this command does nothing. No flags are defined for | ||
| 128 | this command.</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_ENC_CMD_STOP</constant></entry> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>Stop the encoder. When the | ||
| 134 | <constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, | ||
| 135 | encoding will continue until the end of the current <wordasword>Group | ||
| 136 | Of Pictures</wordasword>, otherwise encoding will stop immediately. | ||
| 137 | When the encoder is already stopped, this command does | ||
| 138 | nothing.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry> | ||
| 142 | <entry>2</entry> | ||
| 143 | <entry>Pause the encoder. When the encoder has not been | ||
| 144 | started yet, the driver will return an &EPERM;. When the encoder is | ||
| 145 | already paused, this command does nothing. No flags are defined for | ||
| 146 | this command.</entry> | ||
| 147 | </row> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry> | ||
| 150 | <entry>3</entry> | ||
| 151 | <entry>Resume encoding after a PAUSE command. When the | ||
| 152 | encoder has not been started yet, the driver will return an &EPERM;. | ||
| 153 | When the encoder is already running, this command does nothing. No | ||
| 154 | flags are defined for this command.</entry> | ||
| 155 | </row> | ||
| 156 | </tbody> | ||
| 157 | </tgroup> | ||
| 158 | </table> | ||
| 159 | |||
| 160 | <table pgwide="1" frame="none" id="encoder-flags"> | ||
| 161 | <title>Encoder Command Flags</title> | ||
| 162 | <tgroup cols="3"> | ||
| 163 | &cs-def; | ||
| 164 | <tbody valign="top"> | ||
| 165 | <row> | ||
| 166 | <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry> | ||
| 167 | <entry>0x0001</entry> | ||
| 168 | <entry>Stop encoding at the end of the current <wordasword>Group Of | ||
| 169 | Pictures</wordasword>, rather than immediately.</entry> | ||
| 170 | </row> | ||
| 171 | </tbody> | ||
| 172 | </tgroup> | ||
| 173 | </table> | ||
| 174 | </refsect1> | ||
| 175 | |||
| 176 | <refsect1> | ||
| 177 | &return-value; | ||
| 178 | |||
| 179 | <variablelist> | ||
| 180 | <varlistentry> | ||
| 181 | <term><errorcode>EINVAL</errorcode></term> | ||
| 182 | <listitem> | ||
| 183 | <para>The driver does not support this ioctl, or the | ||
| 184 | <structfield>cmd</structfield> field is invalid.</para> | ||
| 185 | </listitem> | ||
| 186 | </varlistentry> | ||
| 187 | <varlistentry> | ||
| 188 | <term><errorcode>EPERM</errorcode></term> | ||
| 189 | <listitem> | ||
| 190 | <para>The application sent a PAUSE or RESUME command when | ||
| 191 | the encoder was not running.</para> | ||
| 192 | </listitem> | ||
| 193 | </varlistentry> | ||
| 194 | </variablelist> | ||
| 195 | </refsect1> | ||
| 196 | </refentry> | ||
| 197 | |||
| 198 | <!-- | ||
| 199 | Local Variables: | ||
| 200 | mode: sgml | ||
| 201 | sgml-parent-document: "v4l2.sgml" | ||
| 202 | indent-tabs-mode: nil | ||
| 203 | End: | ||
| 204 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml new file mode 100644 index 000000000000..960d44615ca6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <refentry id="vidioc-enum-fmt"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUM_FMT</refname> | ||
| 9 | <refpurpose>Enumerate image formats</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_fmtdesc | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FMT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To enumerate image formats applications initialize the | ||
| 53 | <structfield>type</structfield> and <structfield>index</structfield> | ||
| 54 | field of &v4l2-fmtdesc; and call the | ||
| 55 | <constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this | ||
| 56 | structure. Drivers fill the rest of the structure or return an | ||
| 57 | &EINVAL;. All formats are enumerable by beginning at index zero and | ||
| 58 | incrementing by one until <errorcode>EINVAL</errorcode> is | ||
| 59 | returned.</para> | ||
| 60 | |||
| 61 | <table pgwide="1" frame="none" id="v4l2-fmtdesc"> | ||
| 62 | <title>struct <structname>v4l2_fmtdesc</structname></title> | ||
| 63 | <tgroup cols="3"> | ||
| 64 | &cs-str; | ||
| 65 | <tbody valign="top"> | ||
| 66 | <row> | ||
| 67 | <entry>__u32</entry> | ||
| 68 | <entry><structfield>index</structfield></entry> | ||
| 69 | <entry>Number of the format in the enumeration, set by | ||
| 70 | the application. This is in no way related to the <structfield> | ||
| 71 | pixelformat</structfield> field.</entry> | ||
| 72 | </row> | ||
| 73 | <row> | ||
| 74 | <entry>&v4l2-buf-type;</entry> | ||
| 75 | <entry><structfield>type</structfield></entry> | ||
| 76 | <entry>Type of the data stream, set by the application. | ||
| 77 | Only these types are valid here: | ||
| 78 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 79 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 80 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 81 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 82 | and higher.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__u32</entry> | ||
| 86 | <entry><structfield>flags</structfield></entry> | ||
| 87 | <entry>See <xref linkend="fmtdesc-flags" /></entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>__u8</entry> | ||
| 91 | <entry><structfield>description</structfield>[32]</entry> | ||
| 92 | <entry>Description of the format, a NUL-terminated ASCII | ||
| 93 | string. This information is intended for the user, for example: "YUV | ||
| 94 | 4:2:2".</entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>__u32</entry> | ||
| 98 | <entry><structfield>pixelformat</structfield></entry> | ||
| 99 | <entry>The image format identifier. This is a | ||
| 100 | four character code as computed by the v4l2_fourcc() | ||
| 101 | macro:</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry spanname="hspan"><para><programlisting id="v4l2-fourcc"> | ||
| 105 | #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) | ||
| 106 | </programlisting></para><para>Several image formats are already | ||
| 107 | defined by this specification in <xref linkend="pixfmt" />. Note these | ||
| 108 | codes are not the same as those used in the Windows world.</para></entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 113 | <entry>Reserved for future extensions. Drivers must set | ||
| 114 | the array to zero.</entry> | ||
| 115 | </row> | ||
| 116 | </tbody> | ||
| 117 | </tgroup> | ||
| 118 | </table> | ||
| 119 | |||
| 120 | <table pgwide="1" frame="none" id="fmtdesc-flags"> | ||
| 121 | <title>Image Format Description Flags</title> | ||
| 122 | <tgroup cols="3"> | ||
| 123 | &cs-def; | ||
| 124 | <tbody valign="top"> | ||
| 125 | <row> | ||
| 126 | <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry> | ||
| 127 | <entry>0x0001</entry> | ||
| 128 | <entry>This is a compressed format.</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry> | ||
| 132 | <entry>0x0002</entry> | ||
| 133 | <entry>This format is not native to the device but emulated | ||
| 134 | through software (usually libv4l2), where possible try to use a native format | ||
| 135 | instead for better performance.</entry> | ||
| 136 | </row> | ||
| 137 | </tbody> | ||
| 138 | </tgroup> | ||
| 139 | </table> | ||
| 140 | </refsect1> | ||
| 141 | |||
| 142 | <refsect1> | ||
| 143 | &return-value; | ||
| 144 | |||
| 145 | <variablelist> | ||
| 146 | <varlistentry> | ||
| 147 | <term><errorcode>EINVAL</errorcode></term> | ||
| 148 | <listitem> | ||
| 149 | <para>The &v4l2-fmtdesc; <structfield>type</structfield> | ||
| 150 | is not supported or the <structfield>index</structfield> is out of | ||
| 151 | bounds.</para> | ||
| 152 | </listitem> | ||
| 153 | </varlistentry> | ||
| 154 | </variablelist> | ||
| 155 | </refsect1> | ||
| 156 | </refentry> | ||
| 157 | |||
| 158 | <!-- | ||
| 159 | Local Variables: | ||
| 160 | mode: sgml | ||
| 161 | sgml-parent-document: "v4l2.sgml" | ||
| 162 | indent-tabs-mode: nil | ||
| 163 | End: | ||
| 164 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml new file mode 100644 index 000000000000..3c216e113a54 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml | |||
| @@ -0,0 +1,270 @@ | |||
| 1 | <refentry id="vidioc-enum-frameintervals"> | ||
| 2 | |||
| 3 | <refmeta> | ||
| 4 | <refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_ENUM_FRAMEINTERVALS</refname> | ||
| 10 | <refpurpose>Enumerate frame intervals</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_frmivalenum *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FRAMEINTERVALS</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para>Pointer to a &v4l2-frmivalenum; structure that | ||
| 44 | contains a pixel format and size and receives a frame interval.</para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>This ioctl allows applications to enumerate all frame | ||
| 54 | intervals that the device supports for the given pixel format and | ||
| 55 | frame size.</para> | ||
| 56 | <para>The supported pixel formats and frame sizes can be obtained | ||
| 57 | by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES; | ||
| 58 | functions.</para> | ||
| 59 | <para>The return value and the content of the | ||
| 60 | <structfield>v4l2_frmivalenum.type</structfield> field depend on the | ||
| 61 | type of frame intervals the device supports. Here are the semantics of | ||
| 62 | the function for the different cases:</para> | ||
| 63 | <itemizedlist> | ||
| 64 | <listitem> | ||
| 65 | <para><emphasis role="bold">Discrete:</emphasis> The function | ||
| 66 | returns success if the given index value (zero-based) is valid. The | ||
| 67 | application should increase the index by one for each call until | ||
| 68 | <constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type` | ||
| 69 | field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the | ||
| 70 | union only the `discrete` member is valid.</para> | ||
| 71 | </listitem> | ||
| 72 | <listitem> | ||
| 73 | <para><emphasis role="bold">Step-wise:</emphasis> The function | ||
| 74 | returns success if the given index value is zero and | ||
| 75 | <constant>EINVAL</constant> for any other index value. The | ||
| 76 | <structfield>v4l2_frmivalenum.type</structfield> field is set to | ||
| 77 | <constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the | ||
| 78 | union only the <structfield>stepwise</structfield> member is | ||
| 79 | valid.</para> | ||
| 80 | </listitem> | ||
| 81 | <listitem> | ||
| 82 | <para><emphasis role="bold">Continuous:</emphasis> This is a | ||
| 83 | special case of the step-wise type above. The function returns success | ||
| 84 | if the given index value is zero and <constant>EINVAL</constant> for | ||
| 85 | any other index value. The | ||
| 86 | <structfield>v4l2_frmivalenum.type</structfield> field is set to | ||
| 87 | <constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of | ||
| 88 | the union only the <structfield>stepwise</structfield> member is valid | ||
| 89 | and the <structfield>step</structfield> value is set to 1.</para> | ||
| 90 | </listitem> | ||
| 91 | </itemizedlist> | ||
| 92 | |||
| 93 | <para>When the application calls the function with index zero, it | ||
| 94 | must check the <structfield>type</structfield> field to determine the | ||
| 95 | type of frame interval enumeration the device supports. Only for the | ||
| 96 | <constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make | ||
| 97 | sense to increase the index value to receive more frame | ||
| 98 | intervals.</para> | ||
| 99 | <para>Note that the order in which the frame intervals are | ||
| 100 | returned has no special meaning. In particular does it not say | ||
| 101 | anything about potential default frame intervals.</para> | ||
| 102 | <para>Applications can assume that the enumeration data does not | ||
| 103 | change without any interaction from the application itself. This means | ||
| 104 | that the enumeration data is consistent if the application does not | ||
| 105 | perform any other ioctl calls while it runs the frame interval | ||
| 106 | enumeration.</para> | ||
| 107 | </refsect1> | ||
| 108 | |||
| 109 | <refsect1> | ||
| 110 | <title>Notes</title> | ||
| 111 | |||
| 112 | <itemizedlist> | ||
| 113 | <listitem> | ||
| 114 | <para><emphasis role="bold">Frame intervals and frame | ||
| 115 | rates:</emphasis> The V4L2 API uses frame intervals instead of frame | ||
| 116 | rates. Given the frame interval the frame rate can be computed as | ||
| 117 | follows:<screen>frame_rate = 1 / frame_interval</screen></para> | ||
| 118 | </listitem> | ||
| 119 | </itemizedlist> | ||
| 120 | |||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | <title>Structs</title> | ||
| 125 | |||
| 126 | <para>In the structs below, <emphasis>IN</emphasis> denotes a | ||
| 127 | value that has to be filled in by the application, | ||
| 128 | <emphasis>OUT</emphasis> denotes values that the driver fills in. The | ||
| 129 | application should zero out all members except for the | ||
| 130 | <emphasis>IN</emphasis> fields.</para> | ||
| 131 | |||
| 132 | <table pgwide="1" frame="none" id="v4l2-frmival-stepwise"> | ||
| 133 | <title>struct <structname>v4l2_frmival_stepwise</structname></title> | ||
| 134 | <tgroup cols="3"> | ||
| 135 | &cs-str; | ||
| 136 | <tbody valign="top"> | ||
| 137 | <row> | ||
| 138 | <entry>&v4l2-fract;</entry> | ||
| 139 | <entry><structfield>min</structfield></entry> | ||
| 140 | <entry>Minimum frame interval [s].</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry>&v4l2-fract;</entry> | ||
| 144 | <entry><structfield>max</structfield></entry> | ||
| 145 | <entry>Maximum frame interval [s].</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>&v4l2-fract;</entry> | ||
| 149 | <entry><structfield>step</structfield></entry> | ||
| 150 | <entry>Frame interval step size [s].</entry> | ||
| 151 | </row> | ||
| 152 | </tbody> | ||
| 153 | </tgroup> | ||
| 154 | </table> | ||
| 155 | |||
| 156 | <table pgwide="1" frame="none" id="v4l2-frmivalenum"> | ||
| 157 | <title>struct <structname>v4l2_frmivalenum</structname></title> | ||
| 158 | <tgroup cols="4"> | ||
| 159 | <colspec colname="c1" /> | ||
| 160 | <colspec colname="c2" /> | ||
| 161 | <colspec colname="c3" /> | ||
| 162 | <colspec colname="c4" /> | ||
| 163 | <tbody valign="top"> | ||
| 164 | <row> | ||
| 165 | <entry>__u32</entry> | ||
| 166 | <entry><structfield>index</structfield></entry> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>IN: Index of the given frame interval in the | ||
| 169 | enumeration.</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry>__u32</entry> | ||
| 173 | <entry><structfield>pixel_format</structfield></entry> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>IN: Pixel format for which the frame intervals are | ||
| 176 | enumerated.</entry> | ||
| 177 | </row> | ||
| 178 | <row> | ||
| 179 | <entry>__u32</entry> | ||
| 180 | <entry><structfield>width</structfield></entry> | ||
| 181 | <entry></entry> | ||
| 182 | <entry>IN: Frame width for which the frame intervals are | ||
| 183 | enumerated.</entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry>__u32</entry> | ||
| 187 | <entry><structfield>height</structfield></entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry>IN: Frame height for which the frame intervals are | ||
| 190 | enumerated.</entry> | ||
| 191 | </row> | ||
| 192 | <row> | ||
| 193 | <entry>__u32</entry> | ||
| 194 | <entry><structfield>type</structfield></entry> | ||
| 195 | <entry></entry> | ||
| 196 | <entry>OUT: Frame interval type the device supports.</entry> | ||
| 197 | </row> | ||
| 198 | <row> | ||
| 199 | <entry>union</entry> | ||
| 200 | <entry></entry> | ||
| 201 | <entry></entry> | ||
| 202 | <entry>OUT: Frame interval with the given index.</entry> | ||
| 203 | </row> | ||
| 204 | <row> | ||
| 205 | <entry></entry> | ||
| 206 | <entry>&v4l2-fract;</entry> | ||
| 207 | <entry><structfield>discrete</structfield></entry> | ||
| 208 | <entry>Frame interval [s].</entry> | ||
| 209 | </row> | ||
| 210 | <row> | ||
| 211 | <entry></entry> | ||
| 212 | <entry>&v4l2-frmival-stepwise;</entry> | ||
| 213 | <entry><structfield>stepwise</structfield></entry> | ||
| 214 | <entry></entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry>__u32</entry> | ||
| 218 | <entry><structfield>reserved[2]</structfield></entry> | ||
| 219 | <entry></entry> | ||
| 220 | <entry>Reserved space for future use.</entry> | ||
| 221 | </row> | ||
| 222 | </tbody> | ||
| 223 | </tgroup> | ||
| 224 | </table> | ||
| 225 | </refsect1> | ||
| 226 | |||
| 227 | <refsect1> | ||
| 228 | <title>Enums</title> | ||
| 229 | |||
| 230 | <table pgwide="1" frame="none" id="v4l2-frmivaltypes"> | ||
| 231 | <title>enum <structname>v4l2_frmivaltypes</structname></title> | ||
| 232 | <tgroup cols="3"> | ||
| 233 | &cs-def; | ||
| 234 | <tbody valign="top"> | ||
| 235 | <row> | ||
| 236 | <entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry> | ||
| 237 | <entry>1</entry> | ||
| 238 | <entry>Discrete frame interval.</entry> | ||
| 239 | </row> | ||
| 240 | <row> | ||
| 241 | <entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry> | ||
| 242 | <entry>2</entry> | ||
| 243 | <entry>Continuous frame interval.</entry> | ||
| 244 | </row> | ||
| 245 | <row> | ||
| 246 | <entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry> | ||
| 247 | <entry>3</entry> | ||
| 248 | <entry>Step-wise defined frame interval.</entry> | ||
| 249 | </row> | ||
| 250 | </tbody> | ||
| 251 | </tgroup> | ||
| 252 | </table> | ||
| 253 | </refsect1> | ||
| 254 | |||
| 255 | <refsect1> | ||
| 256 | &return-value; | ||
| 257 | |||
| 258 | <para>See the description section above for a list of return | ||
| 259 | values that <varname>errno</varname> can have.</para> | ||
| 260 | </refsect1> | ||
| 261 | |||
| 262 | </refentry> | ||
| 263 | |||
| 264 | <!-- | ||
| 265 | Local Variables: | ||
| 266 | mode: sgml | ||
| 267 | sgml-parent-document: "v4l2.sgml" | ||
| 268 | indent-tabs-mode: nil | ||
| 269 | End: | ||
| 270 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml new file mode 100644 index 000000000000..6afa4542c818 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml | |||
| @@ -0,0 +1,282 @@ | |||
| 1 | <refentry id="vidioc-enum-framesizes"> | ||
| 2 | |||
| 3 | <refmeta> | ||
| 4 | <refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_ENUM_FRAMESIZES</refname> | ||
| 10 | <refpurpose>Enumerate frame sizes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_frmsizeenum *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FRAMESIZES</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para>Pointer to a &v4l2-frmsizeenum; that contains an index | ||
| 44 | and pixel format and receives a frame width and height.</para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <note> | ||
| 54 | <title>Experimental</title> | ||
| 55 | |||
| 56 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 57 | interface and may change in the future.</para> | ||
| 58 | </note> | ||
| 59 | |||
| 60 | <para>This ioctl allows applications to enumerate all frame sizes | ||
| 61 | (&ie; width and height in pixels) that the device supports for the | ||
| 62 | given pixel format.</para> | ||
| 63 | <para>The supported pixel formats can be obtained by using the | ||
| 64 | &VIDIOC-ENUM-FMT; function.</para> | ||
| 65 | <para>The return value and the content of the | ||
| 66 | <structfield>v4l2_frmsizeenum.type</structfield> field depend on the | ||
| 67 | type of frame sizes the device supports. Here are the semantics of the | ||
| 68 | function for the different cases:</para> | ||
| 69 | |||
| 70 | <itemizedlist> | ||
| 71 | <listitem> | ||
| 72 | <para><emphasis role="bold">Discrete:</emphasis> The function | ||
| 73 | returns success if the given index value (zero-based) is valid. The | ||
| 74 | application should increase the index by one for each call until | ||
| 75 | <constant>EINVAL</constant> is returned. The | ||
| 76 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 77 | <constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the | ||
| 78 | union only the <structfield>discrete</structfield> member is | ||
| 79 | valid.</para> | ||
| 80 | </listitem> | ||
| 81 | <listitem> | ||
| 82 | <para><emphasis role="bold">Step-wise:</emphasis> The function | ||
| 83 | returns success if the given index value is zero and | ||
| 84 | <constant>EINVAL</constant> for any other index value. The | ||
| 85 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 86 | <constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the | ||
| 87 | union only the <structfield>stepwise</structfield> member is | ||
| 88 | valid.</para> | ||
| 89 | </listitem> | ||
| 90 | <listitem> | ||
| 91 | <para><emphasis role="bold">Continuous:</emphasis> This is a | ||
| 92 | special case of the step-wise type above. The function returns success | ||
| 93 | if the given index value is zero and <constant>EINVAL</constant> for | ||
| 94 | any other index value. The | ||
| 95 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 96 | <constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of | ||
| 97 | the union only the <structfield>stepwise</structfield> member is valid | ||
| 98 | and the <structfield>step_width</structfield> and | ||
| 99 | <structfield>step_height</structfield> values are set to 1.</para> | ||
| 100 | </listitem> | ||
| 101 | </itemizedlist> | ||
| 102 | |||
| 103 | <para>When the application calls the function with index zero, it | ||
| 104 | must check the <structfield>type</structfield> field to determine the | ||
| 105 | type of frame size enumeration the device supports. Only for the | ||
| 106 | <constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make | ||
| 107 | sense to increase the index value to receive more frame sizes.</para> | ||
| 108 | <para>Note that the order in which the frame sizes are returned | ||
| 109 | has no special meaning. In particular does it not say anything about | ||
| 110 | potential default format sizes.</para> | ||
| 111 | <para>Applications can assume that the enumeration data does not | ||
| 112 | change without any interaction from the application itself. This means | ||
| 113 | that the enumeration data is consistent if the application does not | ||
| 114 | perform any other ioctl calls while it runs the frame size | ||
| 115 | enumeration.</para> | ||
| 116 | </refsect1> | ||
| 117 | |||
| 118 | <refsect1> | ||
| 119 | <title>Structs</title> | ||
| 120 | |||
| 121 | <para>In the structs below, <emphasis>IN</emphasis> denotes a | ||
| 122 | value that has to be filled in by the application, | ||
| 123 | <emphasis>OUT</emphasis> denotes values that the driver fills in. The | ||
| 124 | application should zero out all members except for the | ||
| 125 | <emphasis>IN</emphasis> fields.</para> | ||
| 126 | |||
| 127 | <table pgwide="1" frame="none" id="v4l2-frmsize-discrete"> | ||
| 128 | <title>struct <structname>v4l2_frmsize_discrete</structname></title> | ||
| 129 | <tgroup cols="3"> | ||
| 130 | &cs-str; | ||
| 131 | <tbody valign="top"> | ||
| 132 | <row> | ||
| 133 | <entry>__u32</entry> | ||
| 134 | <entry><structfield>width</structfield></entry> | ||
| 135 | <entry>Width of the frame [pixel].</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__u32</entry> | ||
| 139 | <entry><structfield>height</structfield></entry> | ||
| 140 | <entry>Height of the frame [pixel].</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </table> | ||
| 145 | |||
| 146 | <table pgwide="1" frame="none" id="v4l2-frmsize-stepwise"> | ||
| 147 | <title>struct <structname>v4l2_frmsize_stepwise</structname></title> | ||
| 148 | <tgroup cols="3"> | ||
| 149 | &cs-str; | ||
| 150 | <tbody valign="top"> | ||
| 151 | <row> | ||
| 152 | <entry>__u32</entry> | ||
| 153 | <entry><structfield>min_width</structfield></entry> | ||
| 154 | <entry>Minimum frame width [pixel].</entry> | ||
| 155 | </row> | ||
| 156 | <row> | ||
| 157 | <entry>__u32</entry> | ||
| 158 | <entry><structfield>max_width</structfield></entry> | ||
| 159 | <entry>Maximum frame width [pixel].</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry>__u32</entry> | ||
| 163 | <entry><structfield>step_width</structfield></entry> | ||
| 164 | <entry>Frame width step size [pixel].</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry>__u32</entry> | ||
| 168 | <entry><structfield>min_height</structfield></entry> | ||
| 169 | <entry>Minimum frame height [pixel].</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry>__u32</entry> | ||
| 173 | <entry><structfield>max_height</structfield></entry> | ||
| 174 | <entry>Maximum frame height [pixel].</entry> | ||
| 175 | </row> | ||
| 176 | <row> | ||
| 177 | <entry>__u32</entry> | ||
| 178 | <entry><structfield>step_height</structfield></entry> | ||
| 179 | <entry>Frame height step size [pixel].</entry> | ||
| 180 | </row> | ||
| 181 | </tbody> | ||
| 182 | </tgroup> | ||
| 183 | </table> | ||
| 184 | |||
| 185 | <table pgwide="1" frame="none" id="v4l2-frmsizeenum"> | ||
| 186 | <title>struct <structname>v4l2_frmsizeenum</structname></title> | ||
| 187 | <tgroup cols="4"> | ||
| 188 | <colspec colname="c1" /> | ||
| 189 | <colspec colname="c2" /> | ||
| 190 | <colspec colname="c3" /> | ||
| 191 | <colspec colname="c4" /> | ||
| 192 | <tbody valign="top"> | ||
| 193 | <row> | ||
| 194 | <entry>__u32</entry> | ||
| 195 | <entry><structfield>index</structfield></entry> | ||
| 196 | <entry></entry> | ||
| 197 | <entry>IN: Index of the given frame size in the enumeration.</entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry>__u32</entry> | ||
| 201 | <entry><structfield>pixel_format</structfield></entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>IN: Pixel format for which the frame sizes are enumerated.</entry> | ||
| 204 | </row> | ||
| 205 | <row> | ||
| 206 | <entry>__u32</entry> | ||
| 207 | <entry><structfield>type</structfield></entry> | ||
| 208 | <entry></entry> | ||
| 209 | <entry>OUT: Frame size type the device supports.</entry> | ||
| 210 | </row> | ||
| 211 | <row> | ||
| 212 | <entry>union</entry> | ||
| 213 | <entry></entry> | ||
| 214 | <entry></entry> | ||
| 215 | <entry>OUT: Frame size with the given index.</entry> | ||
| 216 | </row> | ||
| 217 | <row> | ||
| 218 | <entry></entry> | ||
| 219 | <entry>&v4l2-frmsize-discrete;</entry> | ||
| 220 | <entry><structfield>discrete</structfield></entry> | ||
| 221 | <entry></entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry></entry> | ||
| 225 | <entry>&v4l2-frmsize-stepwise;</entry> | ||
| 226 | <entry><structfield>stepwise</structfield></entry> | ||
| 227 | <entry></entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u32</entry> | ||
| 231 | <entry><structfield>reserved[2]</structfield></entry> | ||
| 232 | <entry></entry> | ||
| 233 | <entry>Reserved space for future use.</entry> | ||
| 234 | </row> | ||
| 235 | </tbody> | ||
| 236 | </tgroup> | ||
| 237 | </table> | ||
| 238 | </refsect1> | ||
| 239 | |||
| 240 | <refsect1> | ||
| 241 | <title>Enums</title> | ||
| 242 | |||
| 243 | <table pgwide="1" frame="none" id="v4l2-frmsizetypes"> | ||
| 244 | <title>enum <structname>v4l2_frmsizetypes</structname></title> | ||
| 245 | <tgroup cols="3"> | ||
| 246 | &cs-def; | ||
| 247 | <tbody valign="top"> | ||
| 248 | <row> | ||
| 249 | <entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry> | ||
| 250 | <entry>1</entry> | ||
| 251 | <entry>Discrete frame size.</entry> | ||
| 252 | </row> | ||
| 253 | <row> | ||
| 254 | <entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry> | ||
| 255 | <entry>2</entry> | ||
| 256 | <entry>Continuous frame size.</entry> | ||
| 257 | </row> | ||
| 258 | <row> | ||
| 259 | <entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry> | ||
| 260 | <entry>3</entry> | ||
| 261 | <entry>Step-wise defined frame size.</entry> | ||
| 262 | </row> | ||
| 263 | </tbody> | ||
| 264 | </tgroup> | ||
| 265 | </table> | ||
| 266 | </refsect1> | ||
| 267 | |||
| 268 | <refsect1> | ||
| 269 | &return-value; | ||
| 270 | |||
| 271 | <para>See the description section above for a list of return | ||
| 272 | values that <varname>errno</varname> can have.</para> | ||
| 273 | </refsect1> | ||
| 274 | </refentry> | ||
| 275 | |||
| 276 | <!-- | ||
| 277 | Local Variables: | ||
| 278 | mode: sgml | ||
| 279 | sgml-parent-document: "v4l2.sgml" | ||
| 280 | indent-tabs-mode: nil | ||
| 281 | End: | ||
| 282 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/v4l/vidioc-enumaudio.xml new file mode 100644 index 000000000000..9ae8f2d3a96f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumaudio.xml | |||
| @@ -0,0 +1,86 @@ | |||
| 1 | <refentry id="vidioc-enumaudio"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMAUDIO</refname> | ||
| 9 | <refpurpose>Enumerate audio inputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMAUDIO</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of an audio input applications | ||
| 52 | initialize the <structfield>index</structfield> field and zero out the | ||
| 53 | <structfield>reserved</structfield> array of a &v4l2-audio; | ||
| 54 | and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer | ||
| 55 | to this structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all audio | ||
| 57 | inputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <para>See <xref linkend="vidioc-g-audio" /> for a description of | ||
| 61 | &v4l2-audio;.</para> | ||
| 62 | </refsect1> | ||
| 63 | |||
| 64 | <refsect1> | ||
| 65 | &return-value; | ||
| 66 | |||
| 67 | <variablelist> | ||
| 68 | <varlistentry> | ||
| 69 | <term><errorcode>EINVAL</errorcode></term> | ||
| 70 | <listitem> | ||
| 71 | <para>The number of the audio input is out of bounds, or | ||
| 72 | there are no audio inputs at all and this ioctl is not | ||
| 73 | supported.</para> | ||
| 74 | </listitem> | ||
| 75 | </varlistentry> | ||
| 76 | </variablelist> | ||
| 77 | </refsect1> | ||
| 78 | </refentry> | ||
| 79 | |||
| 80 | <!-- | ||
| 81 | Local Variables: | ||
| 82 | mode: sgml | ||
| 83 | sgml-parent-document: "v4l2.sgml" | ||
| 84 | indent-tabs-mode: nil | ||
| 85 | End: | ||
| 86 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/v4l/vidioc-enumaudioout.xml new file mode 100644 index 000000000000..d3d7c0ab17b8 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumaudioout.xml | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | <refentry id="vidioc-enumaudioout"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMAUDOUT</refname> | ||
| 9 | <refpurpose>Enumerate audio outputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMAUDOUT</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of an audio output applications | ||
| 52 | initialize the <structfield>index</structfield> field and zero out the | ||
| 53 | <structfield>reserved</structfield> array of a &v4l2-audioout; and | ||
| 54 | call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer | ||
| 55 | to this structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all audio | ||
| 57 | outputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <para>Note connectors on a TV card to loop back the received audio | ||
| 61 | signal to a sound card are not audio outputs in this sense.</para> | ||
| 62 | |||
| 63 | <para>See <xref linkend="vidioc-g-audioout" /> for a description of | ||
| 64 | &v4l2-audioout;.</para> | ||
| 65 | </refsect1> | ||
| 66 | |||
| 67 | <refsect1> | ||
| 68 | &return-value; | ||
| 69 | |||
| 70 | <variablelist> | ||
| 71 | <varlistentry> | ||
| 72 | <term><errorcode>EINVAL</errorcode></term> | ||
| 73 | <listitem> | ||
| 74 | <para>The number of the audio output is out of bounds, or | ||
| 75 | there are no audio outputs at all and this ioctl is not | ||
| 76 | supported.</para> | ||
| 77 | </listitem> | ||
| 78 | </varlistentry> | ||
| 79 | </variablelist> | ||
| 80 | </refsect1> | ||
| 81 | </refentry> | ||
| 82 | |||
| 83 | <!-- | ||
| 84 | Local Variables: | ||
| 85 | mode: sgml | ||
| 86 | sgml-parent-document: "v4l2.sgml" | ||
| 87 | indent-tabs-mode: nil | ||
| 88 | End: | ||
| 89 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enuminput.xml b/Documentation/DocBook/v4l/vidioc-enuminput.xml new file mode 100644 index 000000000000..414856b82473 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enuminput.xml | |||
| @@ -0,0 +1,287 @@ | |||
| 1 | <refentry id="vidioc-enuminput"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMINPUT</refname> | ||
| 9 | <refpurpose>Enumerate video inputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_input | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUMINPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the attributes of a video input applications | ||
| 53 | initialize the <structfield>index</structfield> field of &v4l2-input; | ||
| 54 | and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a | ||
| 55 | pointer to this structure. Drivers fill the rest of the structure or | ||
| 56 | return an &EINVAL; when the index is out of bounds. To enumerate all | ||
| 57 | inputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <table frame="none" pgwide="1" id="v4l2-input"> | ||
| 61 | <title>struct <structname>v4l2_input</structname></title> | ||
| 62 | <tgroup cols="3"> | ||
| 63 | &cs-str; | ||
| 64 | <tbody valign="top"> | ||
| 65 | <row> | ||
| 66 | <entry>__u32</entry> | ||
| 67 | <entry><structfield>index</structfield></entry> | ||
| 68 | <entry>Identifies the input, set by the | ||
| 69 | application.</entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>__u8</entry> | ||
| 73 | <entry><structfield>name</structfield>[32]</entry> | ||
| 74 | <entry>Name of the video input, a NUL-terminated ASCII | ||
| 75 | string, for example: "Vin (Composite 2)". This information is intended | ||
| 76 | for the user, preferably the connector label on the device itself.</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>__u32</entry> | ||
| 80 | <entry><structfield>type</structfield></entry> | ||
| 81 | <entry>Type of the input, see <xref | ||
| 82 | linkend="input-type" />.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__u32</entry> | ||
| 86 | <entry><structfield>audioset</structfield></entry> | ||
| 87 | <entry><para>Drivers can enumerate up to 32 video and | ||
| 88 | audio inputs. This field shows which audio inputs were selectable as | ||
| 89 | audio source if this was the currently selected video input. It is a | ||
| 90 | bit mask. The LSB corresponds to audio input 0, the MSB to input 31. | ||
| 91 | Any number of bits can be set, or none.</para><para>When the driver | ||
| 92 | does not enumerate audio inputs no bits must be set. Applications | ||
| 93 | shall not interpret this as lack of audio support. Some drivers | ||
| 94 | automatically select audio sources and do not enumerate them since | ||
| 95 | there is no choice anyway.</para><para>For details on audio inputs and | ||
| 96 | how to select the current input see <xref | ||
| 97 | linkend="audio" />.</para></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>__u32</entry> | ||
| 101 | <entry><structfield>tuner</structfield></entry> | ||
| 102 | <entry>Capture devices can have zero or more tuners (RF | ||
| 103 | demodulators). When the <structfield>type</structfield> is set to | ||
| 104 | <constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and | ||
| 105 | this field identifies the tuner. It corresponds to | ||
| 106 | &v4l2-tuner; field <structfield>index</structfield>. For details on | ||
| 107 | tuners see <xref linkend="tuner" />.</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>&v4l2-std-id;</entry> | ||
| 111 | <entry><structfield>std</structfield></entry> | ||
| 112 | <entry>Every video input supports one or more different | ||
| 113 | video standards. This field is a set of all supported standards. For | ||
| 114 | details on video standards and how to switch see <xref | ||
| 115 | linkend="standard" />.</entry> | ||
| 116 | </row> | ||
| 117 | <row> | ||
| 118 | <entry>__u32</entry> | ||
| 119 | <entry><structfield>status</structfield></entry> | ||
| 120 | <entry>This field provides status information about the | ||
| 121 | input. See <xref linkend="input-status" /> for flags. | ||
| 122 | With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the | ||
| 123 | current input.</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>__u32</entry> | ||
| 127 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 128 | <entry>Reserved for future extensions. Drivers must set | ||
| 129 | the array to zero.</entry> | ||
| 130 | </row> | ||
| 131 | </tbody> | ||
| 132 | </tgroup> | ||
| 133 | </table> | ||
| 134 | |||
| 135 | <table frame="none" pgwide="1" id="input-type"> | ||
| 136 | <title>Input Types</title> | ||
| 137 | <tgroup cols="3"> | ||
| 138 | &cs-def; | ||
| 139 | <tbody valign="top"> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> | ||
| 142 | <entry>1</entry> | ||
| 143 | <entry>This input uses a tuner (RF demodulator).</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> | ||
| 147 | <entry>2</entry> | ||
| 148 | <entry>Analog baseband input, for example CVBS / | ||
| 149 | Composite Video, S-Video, RGB.</entry> | ||
| 150 | </row> | ||
| 151 | </tbody> | ||
| 152 | </tgroup> | ||
| 153 | </table> | ||
| 154 | |||
| 155 | <!-- Status flags based on proposal by Mark McClelland, | ||
| 156 | video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re: | ||
| 157 | v4l2 api". "Why are some of them inverted? So that the driver doesn't | ||
| 158 | have to lie about the status in cases where it can't tell one way or | ||
| 159 | the other. Plus, a status of zero would generally mean that everything | ||
| 160 | is OK." --> | ||
| 161 | |||
| 162 | <table frame="none" pgwide="1" id="input-status"> | ||
| 163 | <title>Input Status Flags</title> | ||
| 164 | <tgroup cols="3"> | ||
| 165 | <colspec colname="c1" /> | ||
| 166 | <colspec colname="c2" align="center" /> | ||
| 167 | <colspec colname="c3" /> | ||
| 168 | <spanspec namest="c1" nameend="c3" spanname="hspan" | ||
| 169 | align="left" /> | ||
| 170 | <tbody valign="top"> | ||
| 171 | <row> | ||
| 172 | <entry spanname="hspan">General</entry> | ||
| 173 | </row> | ||
| 174 | <row> | ||
| 175 | <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry> | ||
| 176 | <entry>0x00000001</entry> | ||
| 177 | <entry>Attached device is off.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry> | ||
| 181 | <entry>0x00000002</entry> | ||
| 182 | <entry></entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry> | ||
| 186 | <entry>0x00000004</entry> | ||
| 187 | <entry>The hardware supports color decoding, but does not | ||
| 188 | detect color modulation in the signal.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry spanname="hspan">Sensor Orientation</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry><constant>V4L2_IN_ST_HFLIP</constant></entry> | ||
| 195 | <entry>0x00000010</entry> | ||
| 196 | <entry>The input is connected to a device that produces a signal | ||
| 197 | that is flipped horizontally and does not correct this before passing the | ||
| 198 | signal to userspace.</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry><constant>V4L2_IN_ST_VFLIP</constant></entry> | ||
| 202 | <entry>0x00000020</entry> | ||
| 203 | <entry>The input is connected to a device that produces a signal | ||
| 204 | that is flipped vertically and does not correct this before passing the | ||
| 205 | signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry> | ||
| 206 | </row> | ||
| 207 | <row> | ||
| 208 | <entry spanname="hspan">Analog Video</entry> | ||
| 209 | </row> | ||
| 210 | <row> | ||
| 211 | <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry> | ||
| 212 | <entry>0x00000100</entry> | ||
| 213 | <entry>No horizontal sync lock.</entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry> | ||
| 217 | <entry>0x00000200</entry> | ||
| 218 | <entry>A color killer circuit automatically disables color | ||
| 219 | decoding when it detects no color modulation. When this flag is set | ||
| 220 | the color killer is enabled <emphasis>and</emphasis> has shut off | ||
| 221 | color decoding.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry spanname="hspan">Digital Video</entry> | ||
| 225 | </row> | ||
| 226 | <row> | ||
| 227 | <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry> | ||
| 228 | <entry>0x00010000</entry> | ||
| 229 | <entry>No synchronization lock.</entry> | ||
| 230 | </row> | ||
| 231 | <row> | ||
| 232 | <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry> | ||
| 233 | <entry>0x00020000</entry> | ||
| 234 | <entry>No equalizer lock.</entry> | ||
| 235 | </row> | ||
| 236 | <row> | ||
| 237 | <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry> | ||
| 238 | <entry>0x00040000</entry> | ||
| 239 | <entry>Carrier recovery failed.</entry> | ||
| 240 | </row> | ||
| 241 | <row> | ||
| 242 | <entry spanname="hspan">VCR and Set-Top Box</entry> | ||
| 243 | </row> | ||
| 244 | <row> | ||
| 245 | <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry> | ||
| 246 | <entry>0x01000000</entry> | ||
| 247 | <entry>Macrovision is an analog copy prevention system | ||
| 248 | mangling the video signal to confuse video recorders. When this | ||
| 249 | flag is set Macrovision has been detected.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry> | ||
| 253 | <entry>0x02000000</entry> | ||
| 254 | <entry>Conditional access denied.</entry> | ||
| 255 | </row> | ||
| 256 | <row> | ||
| 257 | <entry><constant>V4L2_IN_ST_VTR</constant></entry> | ||
| 258 | <entry>0x04000000</entry> | ||
| 259 | <entry>VTR time constant. [?]</entry> | ||
| 260 | </row> | ||
| 261 | </tbody> | ||
| 262 | </tgroup> | ||
| 263 | </table> | ||
| 264 | </refsect1> | ||
| 265 | |||
| 266 | <refsect1> | ||
| 267 | &return-value; | ||
| 268 | |||
| 269 | <variablelist> | ||
| 270 | <varlistentry> | ||
| 271 | <term><errorcode>EINVAL</errorcode></term> | ||
| 272 | <listitem> | ||
| 273 | <para>The &v4l2-input; <structfield>index</structfield> is | ||
| 274 | out of bounds.</para> | ||
| 275 | </listitem> | ||
| 276 | </varlistentry> | ||
| 277 | </variablelist> | ||
| 278 | </refsect1> | ||
| 279 | </refentry> | ||
| 280 | |||
| 281 | <!-- | ||
| 282 | Local Variables: | ||
| 283 | mode: sgml | ||
| 284 | sgml-parent-document: "v4l2.sgml" | ||
| 285 | indent-tabs-mode: nil | ||
| 286 | End: | ||
| 287 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/v4l/vidioc-enumoutput.xml new file mode 100644 index 000000000000..e8d16dcd50cf --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumoutput.xml | |||
| @@ -0,0 +1,172 @@ | |||
| 1 | <refentry id="vidioc-enumoutput"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMOUTPUT</refname> | ||
| 9 | <refpurpose>Enumerate video outputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_output *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMOUTPUT</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of a video outputs applications | ||
| 52 | initialize the <structfield>index</structfield> field of &v4l2-output; | ||
| 53 | and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a | ||
| 54 | pointer to this structure. Drivers fill the rest of the structure or | ||
| 55 | return an &EINVAL; when the index is out of bounds. To enumerate all | ||
| 56 | outputs applications shall begin at index zero, incrementing by one | ||
| 57 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 58 | |||
| 59 | <table frame="none" pgwide="1" id="v4l2-output"> | ||
| 60 | <title>struct <structname>v4l2_output</structname></title> | ||
| 61 | <tgroup cols="3"> | ||
| 62 | &cs-str; | ||
| 63 | <tbody valign="top"> | ||
| 64 | <row> | ||
| 65 | <entry>__u32</entry> | ||
| 66 | <entry><structfield>index</structfield></entry> | ||
| 67 | <entry>Identifies the output, set by the | ||
| 68 | application.</entry> | ||
| 69 | </row> | ||
| 70 | <row> | ||
| 71 | <entry>__u8</entry> | ||
| 72 | <entry><structfield>name</structfield>[32]</entry> | ||
| 73 | <entry>Name of the video output, a NUL-terminated ASCII | ||
| 74 | string, for example: "Vout". This information is intended for the | ||
| 75 | user, preferably the connector label on the device itself.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>__u32</entry> | ||
| 79 | <entry><structfield>type</structfield></entry> | ||
| 80 | <entry>Type of the output, see <xref | ||
| 81 | linkend="output-type" />.</entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry>__u32</entry> | ||
| 85 | <entry><structfield>audioset</structfield></entry> | ||
| 86 | <entry><para>Drivers can enumerate up to 32 video and | ||
| 87 | audio outputs. This field shows which audio outputs were | ||
| 88 | selectable as the current output if this was the currently selected | ||
| 89 | video output. It is a bit mask. The LSB corresponds to audio output 0, | ||
| 90 | the MSB to output 31. Any number of bits can be set, or | ||
| 91 | none.</para><para>When the driver does not enumerate audio outputs no | ||
| 92 | bits must be set. Applications shall not interpret this as lack of | ||
| 93 | audio support. Drivers may automatically select audio outputs without | ||
| 94 | enumerating them.</para><para>For details on audio outputs and how to | ||
| 95 | select the current output see <xref linkend="audio" />.</para></entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>__u32</entry> | ||
| 99 | <entry><structfield>modulator</structfield></entry> | ||
| 100 | <entry>Output devices can have zero or more RF modulators. | ||
| 101 | When the <structfield>type</structfield> is | ||
| 102 | <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF | ||
| 103 | connector and this field identifies the modulator. It corresponds to | ||
| 104 | &v4l2-modulator; field <structfield>index</structfield>. For details | ||
| 105 | on modulators see <xref linkend="tuner" />.</entry> | ||
| 106 | </row> | ||
| 107 | <row> | ||
| 108 | <entry>&v4l2-std-id;</entry> | ||
| 109 | <entry><structfield>std</structfield></entry> | ||
| 110 | <entry>Every video output supports one or more different | ||
| 111 | video standards. This field is a set of all supported standards. For | ||
| 112 | details on video standards and how to switch see <xref | ||
| 113 | linkend="standard" />.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry>__u32</entry> | ||
| 117 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 118 | <entry>Reserved for future extensions. Drivers must set | ||
| 119 | the array to zero.</entry> | ||
| 120 | </row> | ||
| 121 | </tbody> | ||
| 122 | </tgroup> | ||
| 123 | </table> | ||
| 124 | |||
| 125 | <table frame="none" pgwide="1" id="output-type"> | ||
| 126 | <title>Output Type</title> | ||
| 127 | <tgroup cols="3"> | ||
| 128 | &cs-def; | ||
| 129 | <tbody valign="top"> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>This output is an analog TV modulator.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry> | ||
| 137 | <entry>2</entry> | ||
| 138 | <entry>Analog baseband output, for example Composite / | ||
| 139 | CVBS, S-Video, RGB.</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry> | ||
| 143 | <entry>3</entry> | ||
| 144 | <entry>[?]</entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </table> | ||
| 149 | |||
| 150 | </refsect1> | ||
| 151 | <refsect1> | ||
| 152 | &return-value; | ||
| 153 | |||
| 154 | <variablelist> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The &v4l2-output; <structfield>index</structfield> | ||
| 159 | is out of bounds.</para> | ||
| 160 | </listitem> | ||
| 161 | </varlistentry> | ||
| 162 | </variablelist> | ||
| 163 | </refsect1> | ||
| 164 | </refentry> | ||
| 165 | |||
| 166 | <!-- | ||
| 167 | Local Variables: | ||
| 168 | mode: sgml | ||
| 169 | sgml-parent-document: "v4l2.sgml" | ||
| 170 | indent-tabs-mode: nil | ||
| 171 | End: | ||
| 172 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumstd.xml b/Documentation/DocBook/v4l/vidioc-enumstd.xml new file mode 100644 index 000000000000..95803fe2c8e4 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumstd.xml | |||
| @@ -0,0 +1,391 @@ | |||
| 1 | <refentry id="vidioc-enumstd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMSTD</refname> | ||
| 9 | <refpurpose>Enumerate supported video standards</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_standard *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMSTD</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of a video standard, | ||
| 52 | especially a custom (driver defined) one, applications initialize the | ||
| 53 | <structfield>index</structfield> field of &v4l2-standard; and call the | ||
| 54 | <constant>VIDIOC_ENUMSTD</constant> ioctl with a pointer to this | ||
| 55 | structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all standards | ||
| 57 | applications shall begin at index zero, incrementing by one until the | ||
| 58 | driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a | ||
| 59 | different set of standards after switching the video input or | ||
| 60 | output.<footnote> | ||
| 61 | <para>The supported standards may overlap and we need an | ||
| 62 | unambiguous set to find the current standard returned by | ||
| 63 | <constant>VIDIOC_G_STD</constant>.</para> | ||
| 64 | </footnote></para> | ||
| 65 | |||
| 66 | <table pgwide="1" frame="none" id="v4l2-standard"> | ||
| 67 | <title>struct <structname>v4l2_standard</structname></title> | ||
| 68 | <tgroup cols="3"> | ||
| 69 | &cs-str; | ||
| 70 | <tbody valign="top"> | ||
| 71 | <row> | ||
| 72 | <entry>__u32</entry> | ||
| 73 | <entry><structfield>index</structfield></entry> | ||
| 74 | <entry>Number of the video standard, set by the | ||
| 75 | application.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>&v4l2-std-id;</entry> | ||
| 79 | <entry><structfield>id</structfield></entry> | ||
| 80 | <entry>The bits in this field identify the standard as | ||
| 81 | one of the common standards listed in <xref linkend="v4l2-std-id" />, | ||
| 82 | or if bits 32 to 63 are set as custom standards. Multiple bits can be | ||
| 83 | set if the hardware does not distinguish between these standards, | ||
| 84 | however separate indices do not indicate the opposite. The | ||
| 85 | <structfield>id</structfield> must be unique. No other enumerated | ||
| 86 | <structname>v4l2_standard</structname> structure, for this input or | ||
| 87 | output anyway, can contain the same set of bits.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>__u8</entry> | ||
| 91 | <entry><structfield>name</structfield>[24]</entry> | ||
| 92 | <entry>Name of the standard, a NUL-terminated ASCII | ||
| 93 | string, for example: "PAL-B/G", "NTSC Japan". This information is | ||
| 94 | intended for the user.</entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>&v4l2-fract;</entry> | ||
| 98 | <entry><structfield>frameperiod</structfield></entry> | ||
| 99 | <entry>The frame period (not field period) is numerator | ||
| 100 | / denominator. For example M/NTSC has a frame period of 1001 / | ||
| 101 | 30000 seconds.</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>__u32</entry> | ||
| 105 | <entry><structfield>framelines</structfield></entry> | ||
| 106 | <entry>Total lines per frame including blanking, | ||
| 107 | e. g. 625 for B/PAL.</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>__u32</entry> | ||
| 111 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 112 | <entry>Reserved for future extensions. Drivers must set | ||
| 113 | the array to zero.</entry> | ||
| 114 | </row> | ||
| 115 | </tbody> | ||
| 116 | </tgroup> | ||
| 117 | </table> | ||
| 118 | |||
| 119 | <table pgwide="1" frame="none" id="v4l2-fract"> | ||
| 120 | <title>struct <structname>v4l2_fract</structname></title> | ||
| 121 | <tgroup cols="3"> | ||
| 122 | &cs-str; | ||
| 123 | <tbody valign="top"> | ||
| 124 | <row> | ||
| 125 | <entry>__u32</entry> | ||
| 126 | <entry><structfield>numerator</structfield></entry> | ||
| 127 | <entry></entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry>__u32</entry> | ||
| 131 | <entry><structfield>denominator</structfield></entry> | ||
| 132 | <entry></entry> | ||
| 133 | </row> | ||
| 134 | </tbody> | ||
| 135 | </tgroup> | ||
| 136 | </table> | ||
| 137 | |||
| 138 | <table pgwide="1" frame="none" id="v4l2-std-id"> | ||
| 139 | <title>typedef <structname>v4l2_std_id</structname></title> | ||
| 140 | <tgroup cols="3"> | ||
| 141 | &cs-str; | ||
| 142 | <tbody valign="top"> | ||
| 143 | <row> | ||
| 144 | <entry>__u64</entry> | ||
| 145 | <entry><structfield>v4l2_std_id</structfield></entry> | ||
| 146 | <entry>This type is a set, each bit representing another | ||
| 147 | video standard as listed below and in <xref | ||
| 148 | linkend="video-standards" />. The 32 most significant bits are reserved | ||
| 149 | for custom (driver defined) video standards.</entry> | ||
| 150 | </row> | ||
| 151 | </tbody> | ||
| 152 | </tgroup> | ||
| 153 | </table> | ||
| 154 | |||
| 155 | <para><programlisting> | ||
| 156 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) | ||
| 157 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) | ||
| 158 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) | ||
| 159 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) | ||
| 160 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) | ||
| 161 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) | ||
| 162 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) | ||
| 163 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) | ||
| 164 | |||
| 165 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) | ||
| 166 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) | ||
| 167 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) | ||
| 168 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) | ||
| 169 | </programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is | ||
| 170 | a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color | ||
| 171 | modulation with a 4.43 MHz color subcarrier. Some PAL video recorders | ||
| 172 | can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic | ||
| 173 | PAL TV.</para><para><programlisting> | ||
| 174 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) | ||
| 175 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) | ||
| 176 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) | ||
| 177 | </programlisting></para><para><constant>V4L2_STD_NTSC_443</constant> | ||
| 178 | is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC | ||
| 179 | color modulation with a 4.43 MHz color | ||
| 180 | subcarrier.</para><para><programlisting> | ||
| 181 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) | ||
| 182 | |||
| 183 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) | ||
| 184 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) | ||
| 185 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) | ||
| 186 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) | ||
| 187 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) | ||
| 188 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) | ||
| 189 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) | ||
| 190 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) | ||
| 191 | |||
| 192 | /* ATSC/HDTV */ | ||
| 193 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) | ||
| 194 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) | ||
| 195 | </programlisting></para><para><!-- ATSC proposal by Mark McClelland, | ||
| 196 | video4linux-list@redhat.com on 17 Oct 2002 | ||
| 197 | --><constant>V4L2_STD_ATSC_8_VSB</constant> and | ||
| 198 | <constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital | ||
| 199 | TV standards. Presently the V4L2 API does not support digital TV. See | ||
| 200 | also the Linux DVB API at <ulink | ||
| 201 | url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> | ||
| 202 | <para><programlisting> | ||
| 203 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ | ||
| 204 | V4L2_STD_PAL_B1 |\ | ||
| 205 | V4L2_STD_PAL_G) | ||
| 206 | #define V4L2_STD_B (V4L2_STD_PAL_B |\ | ||
| 207 | V4L2_STD_PAL_B1 |\ | ||
| 208 | V4L2_STD_SECAM_B) | ||
| 209 | #define V4L2_STD_GH (V4L2_STD_PAL_G |\ | ||
| 210 | V4L2_STD_PAL_H |\ | ||
| 211 | V4L2_STD_SECAM_G |\ | ||
| 212 | V4L2_STD_SECAM_H) | ||
| 213 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ | ||
| 214 | V4L2_STD_PAL_D1 |\ | ||
| 215 | V4L2_STD_PAL_K) | ||
| 216 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ | ||
| 217 | V4L2_STD_PAL_DK |\ | ||
| 218 | V4L2_STD_PAL_H |\ | ||
| 219 | V4L2_STD_PAL_I) | ||
| 220 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ | ||
| 221 | V4L2_STD_NTSC_M_JP |\ | ||
| 222 | V4L2_STD_NTSC_M_KR) | ||
| 223 | #define V4L2_STD_MN (V4L2_STD_PAL_M |\ | ||
| 224 | V4L2_STD_PAL_N |\ | ||
| 225 | V4L2_STD_PAL_Nc |\ | ||
| 226 | V4L2_STD_NTSC) | ||
| 227 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\ | ||
| 228 | V4L2_STD_SECAM_K |\ | ||
| 229 | V4L2_STD_SECAM_K1) | ||
| 230 | #define V4L2_STD_DK (V4L2_STD_PAL_DK |\ | ||
| 231 | V4L2_STD_SECAM_DK) | ||
| 232 | |||
| 233 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ | ||
| 234 | V4L2_STD_SECAM_G |\ | ||
| 235 | V4L2_STD_SECAM_H |\ | ||
| 236 | V4L2_STD_SECAM_DK |\ | ||
| 237 | V4L2_STD_SECAM_L |\ | ||
| 238 | V4L2_STD_SECAM_LC) | ||
| 239 | |||
| 240 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ | ||
| 241 | V4L2_STD_PAL_60 |\ | ||
| 242 | V4L2_STD_NTSC |\ | ||
| 243 | V4L2_STD_NTSC_443) | ||
| 244 | #define V4L2_STD_625_50 (V4L2_STD_PAL |\ | ||
| 245 | V4L2_STD_PAL_N |\ | ||
| 246 | V4L2_STD_PAL_Nc |\ | ||
| 247 | V4L2_STD_SECAM) | ||
| 248 | |||
| 249 | #define V4L2_STD_UNKNOWN 0 | ||
| 250 | #define V4L2_STD_ALL (V4L2_STD_525_60 |\ | ||
| 251 | V4L2_STD_625_50) | ||
| 252 | </programlisting></para> | ||
| 253 | |||
| 254 | <table pgwide="1" id="video-standards" orient="land"> | ||
| 255 | <title>Video Standards (based on [<xref linkend="itu470" />])</title> | ||
| 256 | <tgroup cols="12" colsep="1" rowsep="1" align="center"> | ||
| 257 | <colspec colname="c1" align="left" /> | ||
| 258 | <colspec colname="c2" /> | ||
| 259 | <colspec colname="c3" /> | ||
| 260 | <colspec colname="c4" /> | ||
| 261 | <colspec colname="c5" /> | ||
| 262 | <colspec colnum="7" colname="c7" /> | ||
| 263 | <colspec colnum="9" colname="c9" /> | ||
| 264 | <colspec colnum="12" colname="c12" /> | ||
| 265 | <spanspec namest="c2" nameend="c3" spanname="m" align="center" /> | ||
| 266 | <spanspec namest="c4" nameend="c12" spanname="x" align="center" /> | ||
| 267 | <spanspec namest="c5" nameend="c7" spanname="b" align="center" /> | ||
| 268 | <spanspec namest="c9" nameend="c12" spanname="s" align="center" /> | ||
| 269 | <thead> | ||
| 270 | <row> | ||
| 271 | <entry>Characteristics</entry> | ||
| 272 | <entry><para>M/NTSC<footnote><para>Japan uses a standard | ||
| 273 | similar to M/NTSC | ||
| 274 | (V4L2_STD_NTSC_M_JP).</para></footnote></para></entry> | ||
| 275 | <entry>M/PAL</entry> | ||
| 276 | <entry><para>N/PAL<footnote><para> The values in | ||
| 277 | brackets apply to the combination N/PAL a.k.a. | ||
| 278 | N<subscript>C</subscript> used in Argentina | ||
| 279 | (V4L2_STD_PAL_Nc).</para></footnote></para></entry> | ||
| 280 | <entry align="center">B, B1, G/PAL</entry> | ||
| 281 | <entry align="center">D, D1, K/PAL</entry> | ||
| 282 | <entry align="center">H/PAL</entry> | ||
| 283 | <entry align="center">I/PAL</entry> | ||
| 284 | <entry align="center">B, G/SECAM</entry> | ||
| 285 | <entry align="center">D, K/SECAM</entry> | ||
| 286 | <entry align="center">K1/SECAM</entry> | ||
| 287 | <entry align="center">L/SECAM</entry> | ||
| 288 | </row> | ||
| 289 | </thead> | ||
| 290 | <tbody valign="top"> | ||
| 291 | <row> | ||
| 292 | <entry>Frame lines</entry> | ||
| 293 | <entry spanname="m">525</entry> | ||
| 294 | <entry spanname="x">625</entry> | ||
| 295 | </row> | ||
| 296 | <row> | ||
| 297 | <entry>Frame period (s)</entry> | ||
| 298 | <entry spanname="m">1001/30000</entry> | ||
| 299 | <entry spanname="x">1/25</entry> | ||
| 300 | </row> | ||
| 301 | <row> | ||
| 302 | <entry>Chrominance sub-carrier frequency (Hz)</entry> | ||
| 303 | <entry>3579545 ± 10</entry> | ||
| 304 | <entry>3579611.49 ± 10</entry> | ||
| 305 | <entry>4433618.75 ± 5 (3582056.25 | ||
| 306 | ± 5)</entry> | ||
| 307 | <entry spanname="b">4433618.75 ± 5</entry> | ||
| 308 | <entry>4433618.75 ± 1</entry> | ||
| 309 | <entry spanname="s">f<subscript>OR</subscript> = | ||
| 310 | 4406250 ± 2000, f<subscript>OB</subscript> = 4250000 | ||
| 311 | ± 2000</entry> | ||
| 312 | </row> | ||
| 313 | <row> | ||
| 314 | <entry>Nominal radio-frequency channel bandwidth | ||
| 315 | (MHz)</entry> | ||
| 316 | <entry>6</entry> | ||
| 317 | <entry>6</entry> | ||
| 318 | <entry>6</entry> | ||
| 319 | <entry>B: 7; B1, G: 8</entry> | ||
| 320 | <entry>8</entry> | ||
| 321 | <entry>8</entry> | ||
| 322 | <entry>8</entry> | ||
| 323 | <entry>8</entry> | ||
| 324 | <entry>8</entry> | ||
| 325 | <entry>8</entry> | ||
| 326 | <entry>8</entry> | ||
| 327 | </row> | ||
| 328 | <row> | ||
| 329 | <entry>Sound carrier relative to vision carrier | ||
| 330 | (MHz)</entry> | ||
| 331 | <entry>+ 4.5</entry> | ||
| 332 | <entry>+ 4.5</entry> | ||
| 333 | <entry>+ 4.5</entry> | ||
| 334 | <entry><para>+ 5.5 ± 0.001 | ||
| 335 | <footnote><para>In the Federal Republic of Germany, Austria, Italy, | ||
| 336 | the Netherlands, Slovakia and Switzerland a system of two sound | ||
| 337 | carriers is used, the frequency of the second carrier being | ||
| 338 | 242.1875 kHz above the frequency of the first sound carrier. For | ||
| 339 | stereophonic sound transmissions a similar system is used in | ||
| 340 | Australia.</para></footnote> <footnote><para>New Zealand uses a sound | ||
| 341 | carrier displaced 5.4996 ± 0.0005 MHz from the vision | ||
| 342 | carrier.</para></footnote> <footnote><para>In Denmark, Finland, New | ||
| 343 | Zealand, Sweden and Spain a system of two sound carriers is used. In | ||
| 344 | Iceland, Norway and Poland the same system is being introduced. The | ||
| 345 | second carrier is 5.85 MHz above the vision carrier and is DQPSK | ||
| 346 | modulated with 728 kbit/s sound and data multiplex. (NICAM | ||
| 347 | system)</para></footnote> <footnote><para>In the United Kingdom, a | ||
| 348 | system of two sound carriers is used. The second sound carrier is | ||
| 349 | 6.552 MHz above the vision carrier and is DQPSK modulated with a | ||
| 350 | 728 kbit/s sound and data multiplex able to carry two sound | ||
| 351 | channels. (NICAM system)</para></footnote></para></entry> | ||
| 352 | <entry>+ 6.5 ± 0.001</entry> | ||
| 353 | <entry>+ 5.5</entry> | ||
| 354 | <entry>+ 5.9996 ± 0.0005</entry> | ||
| 355 | <entry>+ 5.5 ± 0.001</entry> | ||
| 356 | <entry>+ 6.5 ± 0.001</entry> | ||
| 357 | <entry>+ 6.5</entry> | ||
| 358 | <entry><para>+ 6.5 <footnote><para>In France, a | ||
| 359 | digital carrier 5.85 MHz away from the vision carrier may be used in | ||
| 360 | addition to the main sound carrier. It is modulated in differentially | ||
| 361 | encoded QPSK with a 728 kbit/s sound and data multiplexer capable of | ||
| 362 | carrying two sound channels. (NICAM | ||
| 363 | system)</para></footnote></para></entry> | ||
| 364 | </row> | ||
| 365 | </tbody> | ||
| 366 | </tgroup> | ||
| 367 | </table> | ||
| 368 | </refsect1> | ||
| 369 | |||
| 370 | <refsect1> | ||
| 371 | &return-value; | ||
| 372 | |||
| 373 | <variablelist> | ||
| 374 | <varlistentry> | ||
| 375 | <term><errorcode>EINVAL</errorcode></term> | ||
| 376 | <listitem> | ||
| 377 | <para>The &v4l2-standard; <structfield>index</structfield> | ||
| 378 | is out of bounds.</para> | ||
| 379 | </listitem> | ||
| 380 | </varlistentry> | ||
| 381 | </variablelist> | ||
| 382 | </refsect1> | ||
| 383 | </refentry> | ||
| 384 | |||
| 385 | <!-- | ||
| 386 | Local Variables: | ||
| 387 | mode: sgml | ||
| 388 | sgml-parent-document: "v4l2.sgml" | ||
| 389 | indent-tabs-mode: nil | ||
| 390 | End: | ||
| 391 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-audio.xml b/Documentation/DocBook/v4l/vidioc-g-audio.xml new file mode 100644 index 000000000000..65361a8c2b05 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-audio.xml | |||
| @@ -0,0 +1,188 @@ | |||
| 1 | <refentry id="vidioc-g-audio"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_AUDIO</refname> | ||
| 9 | <refname>VIDIOC_S_AUDIO</refname> | ||
| 10 | <refpurpose>Query or select the current audio input and its | ||
| 11 | attributes</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para></para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <para>To query the current audio input applications zero out the | ||
| 62 | <structfield>reserved</structfield> array of a &v4l2-audio; | ||
| 63 | and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer | ||
| 64 | to this structure. Drivers fill the rest of the structure or return an | ||
| 65 | &EINVAL; when the device has no audio inputs, or none which combine | ||
| 66 | with the current video input.</para> | ||
| 67 | |||
| 68 | <para>Audio inputs have one writable property, the audio mode. To | ||
| 69 | select the current audio input <emphasis>and</emphasis> change the | ||
| 70 | audio mode, applications initialize the | ||
| 71 | <structfield>index</structfield> and <structfield>mode</structfield> | ||
| 72 | fields, and the | ||
| 73 | <structfield>reserved</structfield> array of a | ||
| 74 | <structname>v4l2_audio</structname> structure and call the | ||
| 75 | <constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a | ||
| 76 | different audio mode if the request cannot be satisfied. However, this | ||
| 77 | is a write-only ioctl, it does not return the actual new audio | ||
| 78 | mode.</para> | ||
| 79 | |||
| 80 | <table pgwide="1" frame="none" id="v4l2-audio"> | ||
| 81 | <title>struct <structname>v4l2_audio</structname></title> | ||
| 82 | <tgroup cols="3"> | ||
| 83 | &cs-str; | ||
| 84 | <tbody valign="top"> | ||
| 85 | <row> | ||
| 86 | <entry>__u32</entry> | ||
| 87 | <entry><structfield>index</structfield></entry> | ||
| 88 | <entry>Identifies the audio input, set by the | ||
| 89 | driver or application.</entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>__u8</entry> | ||
| 93 | <entry><structfield>name</structfield>[32]</entry> | ||
| 94 | <entry>Name of the audio input, a NUL-terminated ASCII | ||
| 95 | string, for example: "Line In". This information is intended for the | ||
| 96 | user, preferably the connector label on the device itself.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>__u32</entry> | ||
| 100 | <entry><structfield>capability</structfield></entry> | ||
| 101 | <entry>Audio capability flags, see <xref | ||
| 102 | linkend="audio-capability" />.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>__u32</entry> | ||
| 106 | <entry><structfield>mode</structfield></entry> | ||
| 107 | <entry>Audio mode flags set by drivers and applications (on | ||
| 108 | <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 113 | <entry>Reserved for future extensions. Drivers and | ||
| 114 | applications must set the array to zero.</entry> | ||
| 115 | </row> | ||
| 116 | </tbody> | ||
| 117 | </tgroup> | ||
| 118 | </table> | ||
| 119 | |||
| 120 | <table pgwide="1" frame="none" id="audio-capability"> | ||
| 121 | <title>Audio Capability Flags</title> | ||
| 122 | <tgroup cols="3"> | ||
| 123 | &cs-def; | ||
| 124 | <tbody valign="top"> | ||
| 125 | <row> | ||
| 126 | <entry><constant>V4L2_AUDCAP_STEREO</constant></entry> | ||
| 127 | <entry>0x00001</entry> | ||
| 128 | <entry>This is a stereo input. The flag is intended to | ||
| 129 | automatically disable stereo recording etc. when the signal is always | ||
| 130 | monaural. The API provides no means to detect if stereo is | ||
| 131 | <emphasis>received</emphasis>, unless the audio input belongs to a | ||
| 132 | tuner.</entry> | ||
| 133 | </row> | ||
| 134 | <row> | ||
| 135 | <entry><constant>V4L2_AUDCAP_AVL</constant></entry> | ||
| 136 | <entry>0x00002</entry> | ||
| 137 | <entry>Automatic Volume Level mode is supported.</entry> | ||
| 138 | </row> | ||
| 139 | </tbody> | ||
| 140 | </tgroup> | ||
| 141 | </table> | ||
| 142 | |||
| 143 | <table pgwide="1" frame="none" id="audio-mode"> | ||
| 144 | <title>Audio Mode Flags</title> | ||
| 145 | <tgroup cols="3"> | ||
| 146 | &cs-def; | ||
| 147 | <tbody valign="top"> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_AUDMODE_AVL</constant></entry> | ||
| 150 | <entry>0x00001</entry> | ||
| 151 | <entry>AVL mode is on.</entry> | ||
| 152 | </row> | ||
| 153 | </tbody> | ||
| 154 | </tgroup> | ||
| 155 | </table> | ||
| 156 | </refsect1> | ||
| 157 | |||
| 158 | <refsect1> | ||
| 159 | &return-value; | ||
| 160 | |||
| 161 | <variablelist> | ||
| 162 | <varlistentry> | ||
| 163 | <term><errorcode>EINVAL</errorcode></term> | ||
| 164 | <listitem> | ||
| 165 | <para>No audio inputs combine with the current video input, | ||
| 166 | or the number of the selected audio input is out of bounds or it does | ||
| 167 | not combine, or there are no audio inputs at all and the ioctl is not | ||
| 168 | supported.</para> | ||
| 169 | </listitem> | ||
| 170 | </varlistentry> | ||
| 171 | <varlistentry> | ||
| 172 | <term><errorcode>EBUSY</errorcode></term> | ||
| 173 | <listitem> | ||
| 174 | <para>I/O is in progress, the input cannot be | ||
| 175 | switched.</para> | ||
| 176 | </listitem> | ||
| 177 | </varlistentry> | ||
| 178 | </variablelist> | ||
| 179 | </refsect1> | ||
| 180 | </refentry> | ||
| 181 | |||
| 182 | <!-- | ||
| 183 | Local Variables: | ||
| 184 | mode: sgml | ||
| 185 | sgml-parent-document: "v4l2.sgml" | ||
| 186 | indent-tabs-mode: nil | ||
| 187 | End: | ||
| 188 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/v4l/vidioc-g-audioout.xml new file mode 100644 index 000000000000..3632730c5c6e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-audioout.xml | |||
| @@ -0,0 +1,154 @@ | |||
| 1 | <refentry id="vidioc-g-audioout"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_AUDOUT</refname> | ||
| 9 | <refname>VIDIOC_S_AUDOUT</refname> | ||
| 10 | <refpurpose>Query or select the current audio output</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the current audio output applications zero out the | ||
| 61 | <structfield>reserved</structfield> array of a &v4l2-audioout; and | ||
| 62 | call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer | ||
| 63 | to this structure. Drivers fill the rest of the structure or return an | ||
| 64 | &EINVAL; when the device has no audio inputs, or none which combine | ||
| 65 | with the current video output.</para> | ||
| 66 | |||
| 67 | <para>Audio outputs have no writable properties. Nevertheless, to | ||
| 68 | select the current audio output applications can initialize the | ||
| 69 | <structfield>index</structfield> field and | ||
| 70 | <structfield>reserved</structfield> array (which in the future may | ||
| 71 | contain writable properties) of a | ||
| 72 | <structname>v4l2_audioout</structname> structure and call the | ||
| 73 | <constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the | ||
| 74 | requested output or return the &EINVAL; when the index is out of | ||
| 75 | bounds. This is a write-only ioctl, it does not return the current | ||
| 76 | audio output attributes as <constant>VIDIOC_G_AUDOUT</constant> | ||
| 77 | does.</para> | ||
| 78 | |||
| 79 | <para>Note connectors on a TV card to loop back the received audio | ||
| 80 | signal to a sound card are not audio outputs in this sense.</para> | ||
| 81 | |||
| 82 | <table pgwide="1" frame="none" id="v4l2-audioout"> | ||
| 83 | <title>struct <structname>v4l2_audioout</structname></title> | ||
| 84 | <tgroup cols="3"> | ||
| 85 | &cs-str; | ||
| 86 | <tbody valign="top"> | ||
| 87 | <row> | ||
| 88 | <entry>__u32</entry> | ||
| 89 | <entry><structfield>index</structfield></entry> | ||
| 90 | <entry>Identifies the audio output, set by the | ||
| 91 | driver or application.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>__u8</entry> | ||
| 95 | <entry><structfield>name</structfield>[32]</entry> | ||
| 96 | <entry>Name of the audio output, a NUL-terminated ASCII | ||
| 97 | string, for example: "Line Out". This information is intended for the | ||
| 98 | user, preferably the connector label on the device itself.</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>capability</structfield></entry> | ||
| 103 | <entry>Audio capability flags, none defined yet. Drivers | ||
| 104 | must set this field to zero.</entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry>__u32</entry> | ||
| 108 | <entry><structfield>mode</structfield></entry> | ||
| 109 | <entry>Audio mode, none defined yet. Drivers and | ||
| 110 | applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this | ||
| 111 | field to zero.</entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>__u32</entry> | ||
| 115 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 116 | <entry>Reserved for future extensions. Drivers and | ||
| 117 | applications must set the array to zero.</entry> | ||
| 118 | </row> | ||
| 119 | </tbody> | ||
| 120 | </tgroup> | ||
| 121 | </table> | ||
| 122 | </refsect1> | ||
| 123 | |||
| 124 | <refsect1> | ||
| 125 | &return-value; | ||
| 126 | |||
| 127 | <variablelist> | ||
| 128 | <varlistentry> | ||
| 129 | <term><errorcode>EINVAL</errorcode></term> | ||
| 130 | <listitem> | ||
| 131 | <para>No audio outputs combine with the current video | ||
| 132 | output, or the number of the selected audio output is out of bounds or | ||
| 133 | it does not combine, or there are no audio outputs at all and the | ||
| 134 | ioctl is not supported.</para> | ||
| 135 | </listitem> | ||
| 136 | </varlistentry> | ||
| 137 | <varlistentry> | ||
| 138 | <term><errorcode>EBUSY</errorcode></term> | ||
| 139 | <listitem> | ||
| 140 | <para>I/O is in progress, the output cannot be | ||
| 141 | switched.</para> | ||
| 142 | </listitem> | ||
| 143 | </varlistentry> | ||
| 144 | </variablelist> | ||
| 145 | </refsect1> | ||
| 146 | </refentry> | ||
| 147 | |||
| 148 | <!-- | ||
| 149 | Local Variables: | ||
| 150 | mode: sgml | ||
| 151 | sgml-parent-document: "v4l2.sgml" | ||
| 152 | indent-tabs-mode: nil | ||
| 153 | End: | ||
| 154 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-crop.xml b/Documentation/DocBook/v4l/vidioc-g-crop.xml new file mode 100644 index 000000000000..d235b1dedbed --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-crop.xml | |||
| @@ -0,0 +1,143 @@ | |||
| 1 | <refentry id="vidioc-g-crop"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_CROP</refname> | ||
| 9 | <refname>VIDIOC_S_CROP</refname> | ||
| 10 | <refpurpose>Get or set the current cropping rectangle</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_crop *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_crop *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_CROP, VIDIOC_S_CROP</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the cropping rectangle size and position | ||
| 61 | applications set the <structfield>type</structfield> field of a | ||
| 62 | <structname>v4l2_crop</structname> structure to the respective buffer | ||
| 63 | (stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl | ||
| 64 | with a pointer to this structure. The driver fills the rest of the | ||
| 65 | structure or returns the &EINVAL; if cropping is not supported.</para> | ||
| 66 | |||
| 67 | <para>To change the cropping rectangle applications initialize the | ||
| 68 | <structfield>type</structfield> and &v4l2-rect; substructure named | ||
| 69 | <structfield>c</structfield> of a v4l2_crop structure and call the | ||
| 70 | <constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this | ||
| 71 | structure.</para> | ||
| 72 | |||
| 73 | <para>The driver first adjusts the requested dimensions against | ||
| 74 | hardware limits, &ie; the bounds given by the capture/output window, | ||
| 75 | and it rounds to the closest possible values of horizontal and | ||
| 76 | vertical offset, width and height. In particular the driver must round | ||
| 77 | the vertical offset of the cropping rectangle to frame lines modulo | ||
| 78 | two, such that the field order cannot be confused.</para> | ||
| 79 | |||
| 80 | <para>Second the driver adjusts the image size (the opposite | ||
| 81 | rectangle of the scaling process, source or target depending on the | ||
| 82 | data direction) to the closest size possible while maintaining the | ||
| 83 | current horizontal and vertical scaling factor.</para> | ||
| 84 | |||
| 85 | <para>Finally the driver programs the hardware with the actual | ||
| 86 | cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a | ||
| 87 | write-only ioctl, it does not return the actual parameters. To query | ||
| 88 | them applications must call <constant>VIDIOC_G_CROP</constant> and | ||
| 89 | &VIDIOC-G-FMT;. When the parameters are unsuitable the application may | ||
| 90 | modify the cropping or image parameters and repeat the cycle until | ||
| 91 | satisfactory parameters have been negotiated.</para> | ||
| 92 | |||
| 93 | <para>When cropping is not supported then no parameters are | ||
| 94 | changed and <constant>VIDIOC_S_CROP</constant> returns the | ||
| 95 | &EINVAL;.</para> | ||
| 96 | |||
| 97 | <table pgwide="1" frame="none" id="v4l2-crop"> | ||
| 98 | <title>struct <structname>v4l2_crop</structname></title> | ||
| 99 | <tgroup cols="3"> | ||
| 100 | &cs-str; | ||
| 101 | <tbody valign="top"> | ||
| 102 | <row> | ||
| 103 | <entry>&v4l2-buf-type;</entry> | ||
| 104 | <entry><structfield>type</structfield></entry> | ||
| 105 | <entry>Type of the data stream, set by the application. | ||
| 106 | Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 107 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 108 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 109 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 110 | and higher.</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry>&v4l2-rect;</entry> | ||
| 114 | <entry><structfield>c</structfield></entry> | ||
| 115 | <entry>Cropping rectangle. The same co-ordinate system as | ||
| 116 | for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry> | ||
| 117 | </row> | ||
| 118 | </tbody> | ||
| 119 | </tgroup> | ||
| 120 | </table> | ||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | &return-value; | ||
| 125 | |||
| 126 | <variablelist> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EINVAL</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>Cropping is not supported.</para> | ||
| 131 | </listitem> | ||
| 132 | </varlistentry> | ||
| 133 | </variablelist> | ||
| 134 | </refsect1> | ||
| 135 | </refentry> | ||
| 136 | |||
| 137 | <!-- | ||
| 138 | Local Variables: | ||
| 139 | mode: sgml | ||
| 140 | sgml-parent-document: "v4l2.sgml" | ||
| 141 | indent-tabs-mode: nil | ||
| 142 | End: | ||
| 143 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/v4l/vidioc-g-ctrl.xml new file mode 100644 index 000000000000..8b5e6ff7f3df --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-ctrl.xml | |||
| @@ -0,0 +1,130 @@ | |||
| 1 | <refentry id="vidioc-g-ctrl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_CTRL</refname> | ||
| 9 | <refname>VIDIOC_S_CTRL</refname> | ||
| 10 | <refpurpose>Get or set the value of a control</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_control | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | </refsynopsisdiv> | ||
| 24 | |||
| 25 | <refsect1> | ||
| 26 | <title>Arguments</title> | ||
| 27 | |||
| 28 | <variablelist> | ||
| 29 | <varlistentry> | ||
| 30 | <term><parameter>fd</parameter></term> | ||
| 31 | <listitem> | ||
| 32 | <para>&fd;</para> | ||
| 33 | </listitem> | ||
| 34 | </varlistentry> | ||
| 35 | <varlistentry> | ||
| 36 | <term><parameter>request</parameter></term> | ||
| 37 | <listitem> | ||
| 38 | <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para> | ||
| 39 | </listitem> | ||
| 40 | </varlistentry> | ||
| 41 | <varlistentry> | ||
| 42 | <term><parameter>argp</parameter></term> | ||
| 43 | <listitem> | ||
| 44 | <para></para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>To get the current value of a control applications | ||
| 54 | initialize the <structfield>id</structfield> field of a struct | ||
| 55 | <structname>v4l2_control</structname> and call the | ||
| 56 | <constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this | ||
| 57 | structure. To change the value of a control applications initialize | ||
| 58 | the <structfield>id</structfield> and <structfield>value</structfield> | ||
| 59 | fields of a struct <structname>v4l2_control</structname> and call the | ||
| 60 | <constant>VIDIOC_S_CTRL</constant> ioctl.</para> | ||
| 61 | |||
| 62 | <para>When the <structfield>id</structfield> is invalid drivers | ||
| 63 | return an &EINVAL;. When the <structfield>value</structfield> is out | ||
| 64 | of bounds drivers can choose to take the closest valid value or return | ||
| 65 | an &ERANGE;, whatever seems more appropriate. However, | ||
| 66 | <constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not | ||
| 67 | return the actual new value.</para> | ||
| 68 | |||
| 69 | <para>These ioctls work only with user controls. For other | ||
| 70 | control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or | ||
| 71 | &VIDIOC-TRY-EXT-CTRLS; must be used.</para> | ||
| 72 | |||
| 73 | <table pgwide="1" frame="none" id="v4l2-control"> | ||
| 74 | <title>struct <structname>v4l2_control</structname></title> | ||
| 75 | <tgroup cols="3"> | ||
| 76 | &cs-str; | ||
| 77 | <tbody valign="top"> | ||
| 78 | <row> | ||
| 79 | <entry>__u32</entry> | ||
| 80 | <entry><structfield>id</structfield></entry> | ||
| 81 | <entry>Identifies the control, set by the | ||
| 82 | application.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__s32</entry> | ||
| 86 | <entry><structfield>value</structfield></entry> | ||
| 87 | <entry>New value or current value.</entry> | ||
| 88 | </row> | ||
| 89 | </tbody> | ||
| 90 | </tgroup> | ||
| 91 | </table> | ||
| 92 | </refsect1> | ||
| 93 | |||
| 94 | <refsect1> | ||
| 95 | &return-value; | ||
| 96 | |||
| 97 | <variablelist> | ||
| 98 | <varlistentry> | ||
| 99 | <term><errorcode>EINVAL</errorcode></term> | ||
| 100 | <listitem> | ||
| 101 | <para>The &v4l2-control; <structfield>id</structfield> is | ||
| 102 | invalid.</para> | ||
| 103 | </listitem> | ||
| 104 | </varlistentry> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>ERANGE</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The &v4l2-control; <structfield>value</structfield> | ||
| 109 | is out of bounds.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | <varlistentry> | ||
| 113 | <term><errorcode>EBUSY</errorcode></term> | ||
| 114 | <listitem> | ||
| 115 | <para>The control is temporarily not changeable, possibly | ||
| 116 | because another applications took over control of the device function | ||
| 117 | this control belongs to.</para> | ||
| 118 | </listitem> | ||
| 119 | </varlistentry> | ||
| 120 | </variablelist> | ||
| 121 | </refsect1> | ||
| 122 | </refentry> | ||
| 123 | |||
| 124 | <!-- | ||
| 125 | Local Variables: | ||
| 126 | mode: sgml | ||
| 127 | sgml-parent-document: "v4l2.sgml" | ||
| 128 | indent-tabs-mode: nil | ||
| 129 | End: | ||
| 130 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/v4l/vidioc-g-enc-index.xml new file mode 100644 index 000000000000..9f242e4b2948 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-enc-index.xml | |||
| @@ -0,0 +1,213 @@ | |||
| 1 | <refentry id="vidioc-g-enc-index"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_ENC_INDEX</refname> | ||
| 9 | <refpurpose>Get meta data about a compressed video stream</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_enc_idx *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_G_ENC_INDEX</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <note> | ||
| 52 | <title>Experimental</title> | ||
| 53 | |||
| 54 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 55 | interface and may change in the future.</para> | ||
| 56 | </note> | ||
| 57 | |||
| 58 | <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides | ||
| 59 | meta data about a compressed video stream the same or another | ||
| 60 | application currently reads from the driver, which is useful for | ||
| 61 | random access into the stream without decoding it.</para> | ||
| 62 | |||
| 63 | <para>To read the data applications must call | ||
| 64 | <constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a | ||
| 65 | &v4l2-enc-idx;. On success the driver fills the | ||
| 66 | <structfield>entry</structfield> array, stores the number of elements | ||
| 67 | written in the <structfield>entries</structfield> field, and | ||
| 68 | initializes the <structfield>entries_cap</structfield> field.</para> | ||
| 69 | |||
| 70 | <para>Each element of the <structfield>entry</structfield> array | ||
| 71 | contains meta data about one picture. A | ||
| 72 | <constant>VIDIOC_G_ENC_INDEX</constant> call reads up to | ||
| 73 | <constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver | ||
| 74 | buffer, which can hold up to <structfield>entries_cap</structfield> | ||
| 75 | entries. This number can be lower or higher than | ||
| 76 | <constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the | ||
| 77 | application fails to read the meta data in time the oldest entries | ||
| 78 | will be lost. When the buffer is empty or no capturing/encoding is in | ||
| 79 | progress, <structfield>entries</structfield> will be zero.</para> | ||
| 80 | |||
| 81 | <para>Currently this ioctl is only defined for MPEG-2 program | ||
| 82 | streams and video elementary streams.</para> | ||
| 83 | |||
| 84 | <table pgwide="1" frame="none" id="v4l2-enc-idx"> | ||
| 85 | <title>struct <structname>v4l2_enc_idx</structname></title> | ||
| 86 | <tgroup cols="3"> | ||
| 87 | &cs-str; | ||
| 88 | <tbody valign="top"> | ||
| 89 | <row> | ||
| 90 | <entry>__u32</entry> | ||
| 91 | <entry><structfield>entries</structfield></entry> | ||
| 92 | <entry>The number of entries the driver stored in the | ||
| 93 | <structfield>entry</structfield> array.</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>entries_cap</structfield></entry> | ||
| 98 | <entry>The number of entries the driver can | ||
| 99 | buffer. Must be greater than zero.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u32</entry> | ||
| 103 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 104 | <entry spanname="hspan">Reserved for future extensions. | ||
| 105 | Drivers must set the array to zero.</entry> | ||
| 106 | </row> | ||
| 107 | <row> | ||
| 108 | <entry>&v4l2-enc-idx-entry;</entry> | ||
| 109 | <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry> | ||
| 110 | <entry>Meta data about a compressed video stream. Each | ||
| 111 | element of the array corresponds to one picture, sorted in ascending | ||
| 112 | order by their <structfield>offset</structfield>.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="v4l2-enc-idx-entry"> | ||
| 119 | <title>struct <structname>v4l2_enc_idx_entry</structname></title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-str; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry>__u64</entry> | ||
| 125 | <entry><structfield>offset</structfield></entry> | ||
| 126 | <entry>The offset in bytes from the beginning of the | ||
| 127 | compressed video stream to the beginning of this picture, that is a | ||
| 128 | <wordasword>PES packet header</wordasword> as defined in <xref | ||
| 129 | linkend="mpeg2part1" /> or a <wordasword>picture | ||
| 130 | header</wordasword> as defined in <xref linkend="mpeg2part2" />. When | ||
| 131 | the encoder is stopped, the driver resets the offset to zero.</entry> | ||
| 132 | </row> | ||
| 133 | <row> | ||
| 134 | <entry>__u64</entry> | ||
| 135 | <entry><structfield>pts</structfield></entry> | ||
| 136 | <entry>The 33 bit <wordasword>Presentation Time | ||
| 137 | Stamp</wordasword> of this picture as defined in <xref | ||
| 138 | linkend="mpeg2part1" />.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry>__u32</entry> | ||
| 142 | <entry><structfield>length</structfield></entry> | ||
| 143 | <entry>The length of this picture in bytes.</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry>__u32</entry> | ||
| 147 | <entry><structfield>flags</structfield></entry> | ||
| 148 | <entry>Flags containing the coding type of this picture, see <xref | ||
| 149 | linkend="enc-idx-flags" />.</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry>__u32</entry> | ||
| 153 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 154 | <entry>Reserved for future extensions. | ||
| 155 | Drivers must set the array to zero.</entry> | ||
| 156 | </row> | ||
| 157 | </tbody> | ||
| 158 | </tgroup> | ||
| 159 | </table> | ||
| 160 | |||
| 161 | <table pgwide="1" frame="none" id="enc-idx-flags"> | ||
| 162 | <title>Index Entry Flags</title> | ||
| 163 | <tgroup cols="3"> | ||
| 164 | &cs-def; | ||
| 165 | <tbody valign="top"> | ||
| 166 | <row> | ||
| 167 | <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry> | ||
| 168 | <entry>0x00</entry> | ||
| 169 | <entry>This is an Intra-coded picture.</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry> | ||
| 173 | <entry>0x01</entry> | ||
| 174 | <entry>This is a Predictive-coded picture.</entry> | ||
| 175 | </row> | ||
| 176 | <row> | ||
| 177 | <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry> | ||
| 178 | <entry>0x02</entry> | ||
| 179 | <entry>This is a Bidirectionally predictive-coded | ||
| 180 | picture.</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry> | ||
| 184 | <entry>0x0F</entry> | ||
| 185 | <entry><wordasword>AND</wordasword> the flags field with | ||
| 186 | this mask to obtain the picture coding type.</entry> | ||
| 187 | </row> | ||
| 188 | </tbody> | ||
| 189 | </tgroup> | ||
| 190 | </table> | ||
| 191 | </refsect1> | ||
| 192 | |||
| 193 | <refsect1> | ||
| 194 | &return-value; | ||
| 195 | |||
| 196 | <variablelist> | ||
| 197 | <varlistentry> | ||
| 198 | <term><errorcode>EINVAL</errorcode></term> | ||
| 199 | <listitem> | ||
| 200 | <para>The driver does not support this ioctl.</para> | ||
| 201 | </listitem> | ||
| 202 | </varlistentry> | ||
| 203 | </variablelist> | ||
| 204 | </refsect1> | ||
| 205 | </refentry> | ||
| 206 | |||
| 207 | <!-- | ||
| 208 | Local Variables: | ||
| 209 | mode: sgml | ||
| 210 | sgml-parent-document: "v4l2.sgml" | ||
| 211 | indent-tabs-mode: nil | ||
| 212 | End: | ||
| 213 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml new file mode 100644 index 000000000000..3aa7f8f9ff0c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml | |||
| @@ -0,0 +1,307 @@ | |||
| 1 | <refentry id="vidioc-g-ext-ctrls"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, | ||
| 4 | VIDIOC_TRY_EXT_CTRLS</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_G_EXT_CTRLS</refname> | ||
| 10 | <refname>VIDIOC_S_EXT_CTRLS</refname> | ||
| 11 | <refname>VIDIOC_TRY_EXT_CTRLS</refname> | ||
| 12 | <refpurpose>Get or set the value of several controls, try control | ||
| 13 | values</refpurpose> | ||
| 14 | </refnamediv> | ||
| 15 | |||
| 16 | <refsynopsisdiv> | ||
| 17 | <funcsynopsis> | ||
| 18 | <funcprototype> | ||
| 19 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 20 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 21 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 22 | <paramdef>struct v4l2_ext_controls | ||
| 23 | *<parameter>argp</parameter></paramdef> | ||
| 24 | </funcprototype> | ||
| 25 | </funcsynopsis> | ||
| 26 | </refsynopsisdiv> | ||
| 27 | |||
| 28 | <refsect1> | ||
| 29 | <title>Arguments</title> | ||
| 30 | |||
| 31 | <variablelist> | ||
| 32 | <varlistentry> | ||
| 33 | <term><parameter>fd</parameter></term> | ||
| 34 | <listitem> | ||
| 35 | <para>&fd;</para> | ||
| 36 | </listitem> | ||
| 37 | </varlistentry> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>request</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, | ||
| 42 | VIDIOC_TRY_EXT_CTRLS</para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | <varlistentry> | ||
| 46 | <term><parameter>argp</parameter></term> | ||
| 47 | <listitem> | ||
| 48 | <para></para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | </variablelist> | ||
| 52 | </refsect1> | ||
| 53 | |||
| 54 | <refsect1> | ||
| 55 | <title>Description</title> | ||
| 56 | |||
| 57 | <para>These ioctls allow the caller to get or set multiple | ||
| 58 | controls atomically. Control IDs are grouped into control classes (see | ||
| 59 | <xref linkend="ctrl-class" />) and all controls in the control array | ||
| 60 | must belong to the same control class.</para> | ||
| 61 | |||
| 62 | <para>Applications must always fill in the | ||
| 63 | <structfield>count</structfield>, | ||
| 64 | <structfield>ctrl_class</structfield>, | ||
| 65 | <structfield>controls</structfield> and | ||
| 66 | <structfield>reserved</structfield> fields of &v4l2-ext-controls;, and | ||
| 67 | initialize the &v4l2-ext-control; array pointed to by the | ||
| 68 | <structfield>controls</structfield> fields.</para> | ||
| 69 | |||
| 70 | <para>To get the current value of a set of controls applications | ||
| 71 | initialize the <structfield>id</structfield>, | ||
| 72 | <structfield>size</structfield> and <structfield>reserved2</structfield> fields | ||
| 73 | of each &v4l2-ext-control; and call the | ||
| 74 | <constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls | ||
| 75 | must also set the <structfield>string</structfield> field.</para> | ||
| 76 | |||
| 77 | <para>If the <structfield>size</structfield> is too small to | ||
| 78 | receive the control result (only relevant for pointer-type controls | ||
| 79 | like strings), then the driver will set <structfield>size</structfield> | ||
| 80 | to a valid value and return an &ENOSPC;. You should re-allocate the | ||
| 81 | string memory to this new size and try again. It is possible that the | ||
| 82 | same issue occurs again if the string has grown in the meantime. It is | ||
| 83 | recommended to call &VIDIOC-QUERYCTRL; first and use | ||
| 84 | <structfield>maximum</structfield>+1 as the new <structfield>size</structfield> | ||
| 85 | value. It is guaranteed that that is sufficient memory. | ||
| 86 | </para> | ||
| 87 | |||
| 88 | <para>To change the value of a set of controls applications | ||
| 89 | initialize the <structfield>id</structfield>, <structfield>size</structfield>, | ||
| 90 | <structfield>reserved2</structfield> and | ||
| 91 | <structfield>value/string</structfield> fields of each &v4l2-ext-control; and | ||
| 92 | call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls | ||
| 93 | will only be set if <emphasis>all</emphasis> control values are | ||
| 94 | valid.</para> | ||
| 95 | |||
| 96 | <para>To check if a set of controls have correct values applications | ||
| 97 | initialize the <structfield>id</structfield>, <structfield>size</structfield>, | ||
| 98 | <structfield>reserved2</structfield> and | ||
| 99 | <structfield>value/string</structfield> fields of each &v4l2-ext-control; and | ||
| 100 | call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to | ||
| 101 | the driver whether wrong values are automatically adjusted to a valid | ||
| 102 | value or if an error is returned.</para> | ||
| 103 | |||
| 104 | <para>When the <structfield>id</structfield> or | ||
| 105 | <structfield>ctrl_class</structfield> is invalid drivers return an | ||
| 106 | &EINVAL;. When the value is out of bounds drivers can choose to take | ||
| 107 | the closest valid value or return an &ERANGE;, whatever seems more | ||
| 108 | appropriate. In the first case the new value is set in | ||
| 109 | &v4l2-ext-control;.</para> | ||
| 110 | |||
| 111 | <para>The driver will only set/get these controls if all control | ||
| 112 | values are correct. This prevents the situation where only some of the | ||
| 113 | controls were set/get. Only low-level errors (⪚ a failed i2c | ||
| 114 | command) can still cause this situation.</para> | ||
| 115 | |||
| 116 | <table pgwide="1" frame="none" id="v4l2-ext-control"> | ||
| 117 | <title>struct <structname>v4l2_ext_control</structname></title> | ||
| 118 | <tgroup cols="4"> | ||
| 119 | &cs-ustr; | ||
| 120 | <tbody valign="top"> | ||
| 121 | <row> | ||
| 122 | <entry>__u32</entry> | ||
| 123 | <entry><structfield>id</structfield></entry> | ||
| 124 | <entry></entry> | ||
| 125 | <entry>Identifies the control, set by the | ||
| 126 | application.</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>__u32</entry> | ||
| 130 | <entry><structfield>size</structfield></entry> | ||
| 131 | <entry></entry> | ||
| 132 | <entry>The total size in bytes of the payload of this | ||
| 133 | control. This is normally 0, but for pointer controls this should be | ||
| 134 | set to the size of the memory containing the payload, or that will | ||
| 135 | receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds | ||
| 136 | that this value is less than is required to store | ||
| 137 | the payload result, then it is set to a value large enough to store the | ||
| 138 | payload result and ENOSPC is returned. Note that for string controls | ||
| 139 | this <structfield>size</structfield> field should not be confused with the length of the string. | ||
| 140 | This field refers to the size of the memory that contains the string. | ||
| 141 | The actual <emphasis>length</emphasis> of the string may well be much smaller. | ||
| 142 | </entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry>__u32</entry> | ||
| 146 | <entry><structfield>reserved2</structfield>[1]</entry> | ||
| 147 | <entry></entry> | ||
| 148 | <entry>Reserved for future extensions. Drivers and | ||
| 149 | applications must set the array to zero.</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry>union</entry> | ||
| 153 | <entry>(anonymous)</entry> | ||
| 154 | </row> | ||
| 155 | <row> | ||
| 156 | <entry></entry> | ||
| 157 | <entry>__s32</entry> | ||
| 158 | <entry><structfield>value</structfield></entry> | ||
| 159 | <entry>New value or current value.</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry></entry> | ||
| 163 | <entry>__s64</entry> | ||
| 164 | <entry><structfield>value64</structfield></entry> | ||
| 165 | <entry>New value or current value.</entry> | ||
| 166 | </row> | ||
| 167 | <row> | ||
| 168 | <entry></entry> | ||
| 169 | <entry>char *</entry> | ||
| 170 | <entry><structfield>string</structfield></entry> | ||
| 171 | <entry>A pointer to a string.</entry> | ||
| 172 | </row> | ||
| 173 | </tbody> | ||
| 174 | </tgroup> | ||
| 175 | </table> | ||
| 176 | |||
| 177 | <table pgwide="1" frame="none" id="v4l2-ext-controls"> | ||
| 178 | <title>struct <structname>v4l2_ext_controls</structname></title> | ||
| 179 | <tgroup cols="3"> | ||
| 180 | &cs-str; | ||
| 181 | <tbody valign="top"> | ||
| 182 | <row> | ||
| 183 | <entry>__u32</entry> | ||
| 184 | <entry><structfield>ctrl_class</structfield></entry> | ||
| 185 | <entry>The control class to which all controls belong, see | ||
| 186 | <xref linkend="ctrl-class" />.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry>__u32</entry> | ||
| 190 | <entry><structfield>count</structfield></entry> | ||
| 191 | <entry>The number of controls in the controls array. May | ||
| 192 | also be zero.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry>__u32</entry> | ||
| 196 | <entry><structfield>error_idx</structfield></entry> | ||
| 197 | <entry>Set by the driver in case of an error. It is the | ||
| 198 | index of the control causing the error or equal to 'count' when the | ||
| 199 | error is not associated with a particular control. Undefined when the | ||
| 200 | ioctl returns 0 (success).</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry>__u32</entry> | ||
| 204 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 205 | <entry>Reserved for future extensions. Drivers and | ||
| 206 | applications must set the array to zero.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry>&v4l2-ext-control; *</entry> | ||
| 210 | <entry><structfield>controls</structfield></entry> | ||
| 211 | <entry>Pointer to an array of | ||
| 212 | <structfield>count</structfield> v4l2_ext_control structures. Ignored | ||
| 213 | if <structfield>count</structfield> equals zero.</entry> | ||
| 214 | </row> | ||
| 215 | </tbody> | ||
| 216 | </tgroup> | ||
| 217 | </table> | ||
| 218 | |||
| 219 | <table pgwide="1" frame="none" id="ctrl-class"> | ||
| 220 | <title>Control classes</title> | ||
| 221 | <tgroup cols="3"> | ||
| 222 | &cs-def; | ||
| 223 | <tbody valign="top"> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry> | ||
| 226 | <entry>0x980000</entry> | ||
| 227 | <entry>The class containing user controls. These controls | ||
| 228 | are described in <xref linkend="control" />. All controls that can be set | ||
| 229 | using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this | ||
| 230 | class.</entry> | ||
| 231 | </row> | ||
| 232 | <row> | ||
| 233 | <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> | ||
| 234 | <entry>0x990000</entry> | ||
| 235 | <entry>The class containing MPEG compression controls. | ||
| 236 | These controls are described in <xref | ||
| 237 | linkend="mpeg-controls" />.</entry> | ||
| 238 | </row> | ||
| 239 | <row> | ||
| 240 | <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> | ||
| 241 | <entry>0x9a0000</entry> | ||
| 242 | <entry>The class containing camera controls. | ||
| 243 | These controls are described in <xref | ||
| 244 | linkend="camera-controls" />.</entry> | ||
| 245 | </row> | ||
| 246 | <row> | ||
| 247 | <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> | ||
| 248 | <entry>0x9b0000</entry> | ||
| 249 | <entry>The class containing FM Transmitter (FM TX) controls. | ||
| 250 | These controls are described in <xref | ||
| 251 | linkend="fm-tx-controls" />.</entry> | ||
| 252 | </row> | ||
| 253 | </tbody> | ||
| 254 | </tgroup> | ||
| 255 | </table> | ||
| 256 | |||
| 257 | </refsect1> | ||
| 258 | |||
| 259 | <refsect1> | ||
| 260 | &return-value; | ||
| 261 | |||
| 262 | <variablelist> | ||
| 263 | <varlistentry> | ||
| 264 | <term><errorcode>EINVAL</errorcode></term> | ||
| 265 | <listitem> | ||
| 266 | <para>The &v4l2-ext-control; <structfield>id</structfield> | ||
| 267 | is invalid or the &v4l2-ext-controls; | ||
| 268 | <structfield>ctrl_class</structfield> is invalid. This error code is | ||
| 269 | also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and | ||
| 270 | <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more | ||
| 271 | control values are in conflict.</para> | ||
| 272 | </listitem> | ||
| 273 | </varlistentry> | ||
| 274 | <varlistentry> | ||
| 275 | <term><errorcode>ERANGE</errorcode></term> | ||
| 276 | <listitem> | ||
| 277 | <para>The &v4l2-ext-control; <structfield>value</structfield> | ||
| 278 | is out of bounds.</para> | ||
| 279 | </listitem> | ||
| 280 | </varlistentry> | ||
| 281 | <varlistentry> | ||
| 282 | <term><errorcode>EBUSY</errorcode></term> | ||
| 283 | <listitem> | ||
| 284 | <para>The control is temporarily not changeable, possibly | ||
| 285 | because another applications took over control of the device function | ||
| 286 | this control belongs to.</para> | ||
| 287 | </listitem> | ||
| 288 | </varlistentry> | ||
| 289 | <varlistentry> | ||
| 290 | <term><errorcode>ENOSPC</errorcode></term> | ||
| 291 | <listitem> | ||
| 292 | <para>The space reserved for the control's payload is insufficient. | ||
| 293 | The field <structfield>size</structfield> is set to a value that is enough | ||
| 294 | to store the payload and this error code is returned.</para> | ||
| 295 | </listitem> | ||
| 296 | </varlistentry> | ||
| 297 | </variablelist> | ||
| 298 | </refsect1> | ||
| 299 | </refentry> | ||
| 300 | |||
| 301 | <!-- | ||
| 302 | Local Variables: | ||
| 303 | mode: sgml | ||
| 304 | sgml-parent-document: "v4l2.sgml" | ||
| 305 | indent-tabs-mode: nil | ||
| 306 | End: | ||
| 307 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml new file mode 100644 index 000000000000..f7017062656e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml | |||
| @@ -0,0 +1,456 @@ | |||
| 1 | <refentry id="vidioc-g-fbuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_FBUF</refname> | ||
| 9 | <refname>VIDIOC_S_FBUF</refname> | ||
| 10 | <refpurpose>Get or set frame buffer overlay parameters</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and | ||
| 61 | <constant>VIDIOC_S_FBUF</constant> ioctl to get and set the | ||
| 62 | framebuffer parameters for a <link linkend="overlay">Video | ||
| 63 | Overlay</link> or <link linkend="osd">Video Output Overlay</link> | ||
| 64 | (OSD). The type of overlay is implied by the device type (capture or | ||
| 65 | output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl. | ||
| 66 | One <filename>/dev/videoN</filename> device must not support both | ||
| 67 | kinds of overlay.</para> | ||
| 68 | |||
| 69 | <para>The V4L2 API distinguishes destructive and non-destructive | ||
| 70 | overlays. A destructive overlay copies captured video images into the | ||
| 71 | video memory of a graphics card. A non-destructive overlay blends | ||
| 72 | video images into a VGA signal or graphics into a video signal. | ||
| 73 | <wordasword>Video Output Overlays</wordasword> are always | ||
| 74 | non-destructive.</para> | ||
| 75 | |||
| 76 | <para>To get the current parameters applications call the | ||
| 77 | <constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a | ||
| 78 | <structname>v4l2_framebuffer</structname> structure. The driver fills | ||
| 79 | all fields of the structure or returns an &EINVAL; when overlays are | ||
| 80 | not supported.</para> | ||
| 81 | |||
| 82 | <para>To set the parameters for a <wordasword>Video Output | ||
| 83 | Overlay</wordasword>, applications must initialize the | ||
| 84 | <structfield>flags</structfield> field of a struct | ||
| 85 | <structname>v4l2_framebuffer</structname>. Since the framebuffer is | ||
| 86 | implemented on the TV card all other parameters are determined by the | ||
| 87 | driver. When an application calls <constant>VIDIOC_S_FBUF</constant> | ||
| 88 | with a pointer to this structure, the driver prepares for the overlay | ||
| 89 | and returns the framebuffer parameters as | ||
| 90 | <constant>VIDIOC_G_FBUF</constant> does, or it returns an error | ||
| 91 | code.</para> | ||
| 92 | |||
| 93 | <para>To set the parameters for a <wordasword>non-destructive | ||
| 94 | Video Overlay</wordasword>, applications must initialize the | ||
| 95 | <structfield>flags</structfield> field, the | ||
| 96 | <structfield>fmt</structfield> substructure, and call | ||
| 97 | <constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the | ||
| 98 | overlay and returns the framebuffer parameters as | ||
| 99 | <constant>VIDIOC_G_FBUF</constant> does, or it returns an error | ||
| 100 | code.</para> | ||
| 101 | |||
| 102 | <para>For a <wordasword>destructive Video Overlay</wordasword> | ||
| 103 | applications must additionally provide a | ||
| 104 | <structfield>base</structfield> address. Setting up a DMA to a | ||
| 105 | random memory location can jeopardize the system security, its | ||
| 106 | stability or even damage the hardware, therefore only the superuser | ||
| 107 | can set the parameters for a destructive video overlay.</para> | ||
| 108 | |||
| 109 | <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.--> | ||
| 110 | |||
| 111 | <table pgwide="1" frame="none" id="v4l2-framebuffer"> | ||
| 112 | <title>struct <structname>v4l2_framebuffer</structname></title> | ||
| 113 | <tgroup cols="4"> | ||
| 114 | &cs-ustr; | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>capability</structfield></entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Overlay capability flags set by the driver, see | ||
| 121 | <xref linkend="framebuffer-cap" />.</entry> | ||
| 122 | </row> | ||
| 123 | <row> | ||
| 124 | <entry>__u32</entry> | ||
| 125 | <entry><structfield>flags</structfield></entry> | ||
| 126 | <entry></entry> | ||
| 127 | <entry>Overlay control flags set by application and | ||
| 128 | driver, see <xref linkend="framebuffer-flags" /></entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry>void *</entry> | ||
| 132 | <entry><structfield>base</structfield></entry> | ||
| 133 | <entry></entry> | ||
| 134 | <entry>Physical base address of the framebuffer, | ||
| 135 | that is the address of the pixel in the top left corner of the | ||
| 136 | framebuffer.<footnote><para>A physical base address may not suit all | ||
| 137 | platforms. GK notes in theory we should pass something like PCI device | ||
| 138 | + memory region + offset instead. If you encounter problems please | ||
| 139 | discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry></entry> | ||
| 143 | <entry></entry> | ||
| 144 | <entry></entry> | ||
| 145 | <entry>This field is irrelevant to | ||
| 146 | <wordasword>non-destructive Video Overlays</wordasword>. For | ||
| 147 | <wordasword>destructive Video Overlays</wordasword> applications must | ||
| 148 | provide a base address. The driver may accept only base addresses | ||
| 149 | which are a multiple of two, four or eight bytes. For | ||
| 150 | <wordasword>Video Output Overlays</wordasword> the driver must return | ||
| 151 | a valid base address, so applications can find the corresponding Linux | ||
| 152 | framebuffer device (see <xref linkend="osd" />).</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry>&v4l2-pix-format;</entry> | ||
| 156 | <entry><structfield>fmt</structfield></entry> | ||
| 157 | <entry></entry> | ||
| 158 | <entry>Layout of the frame buffer. The | ||
| 159 | <structname>v4l2_pix_format</structname> structure is defined in <xref | ||
| 160 | linkend="pixfmt" />, for clarification the fields and acceptable values | ||
| 161 | are listed below:</entry> | ||
| 162 | </row> | ||
| 163 | <row> | ||
| 164 | <entry></entry> | ||
| 165 | <entry>__u32</entry> | ||
| 166 | <entry><structfield>width</structfield></entry> | ||
| 167 | <entry>Width of the frame buffer in pixels.</entry> | ||
| 168 | </row> | ||
| 169 | <row> | ||
| 170 | <entry></entry> | ||
| 171 | <entry>__u32</entry> | ||
| 172 | <entry><structfield>height</structfield></entry> | ||
| 173 | <entry>Height of the frame buffer in pixels.</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry></entry> | ||
| 177 | <entry>__u32</entry> | ||
| 178 | <entry><structfield>pixelformat</structfield></entry> | ||
| 179 | <entry>The pixel format of the | ||
| 180 | framebuffer.</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry></entry> | ||
| 184 | <entry></entry> | ||
| 185 | <entry></entry> | ||
| 186 | <entry>For <wordasword>non-destructive Video | ||
| 187 | Overlays</wordasword> this field only defines a format for the | ||
| 188 | &v4l2-window; <structfield>chromakey</structfield> field.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry></entry> | ||
| 192 | <entry></entry> | ||
| 193 | <entry></entry> | ||
| 194 | <entry>For <wordasword>destructive Video | ||
| 195 | Overlays</wordasword> applications must initialize this field. For | ||
| 196 | <wordasword>Video Output Overlays</wordasword> the driver must return | ||
| 197 | a valid format.</entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry></entry> | ||
| 201 | <entry></entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>Usually this is an RGB format (for example | ||
| 204 | <link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>) | ||
| 205 | but YUV formats (only packed YUV formats when chroma keying is used, | ||
| 206 | not including <constant>V4L2_PIX_FMT_YUYV</constant> and | ||
| 207 | <constant>V4L2_PIX_FMT_UYVY</constant>) and the | ||
| 208 | <constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The | ||
| 209 | behavior of the driver when an application requests a compressed | ||
| 210 | format is undefined. See <xref linkend="pixfmt" /> for information on | ||
| 211 | pixel formats.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry></entry> | ||
| 215 | <entry>&v4l2-field;</entry> | ||
| 216 | <entry><structfield>field</structfield></entry> | ||
| 217 | <entry>Drivers and applications shall ignore this field. | ||
| 218 | If applicable, the field order is selected with the &VIDIOC-S-FMT; | ||
| 219 | ioctl, using the <structfield>field</structfield> field of | ||
| 220 | &v4l2-window;.</entry> | ||
| 221 | </row> | ||
| 222 | <row> | ||
| 223 | <entry></entry> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>bytesperline</structfield></entry> | ||
| 226 | <entry>Distance in bytes between the leftmost pixels in | ||
| 227 | two adjacent lines.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry spanname="hspan"><para>This field is irrelevant to | ||
| 231 | <wordasword>non-destructive Video | ||
| 232 | Overlays</wordasword>.</para><para>For <wordasword>destructive Video | ||
| 233 | Overlays</wordasword> both applications and drivers can set this field | ||
| 234 | to request padding bytes at the end of each line. Drivers however may | ||
| 235 | ignore the requested value, returning <structfield>width</structfield> | ||
| 236 | times bytes-per-pixel or a larger value required by the hardware. That | ||
| 237 | implies applications can just set this field to zero to get a | ||
| 238 | reasonable default.</para><para>For <wordasword>Video Output | ||
| 239 | Overlays</wordasword> the driver must return a valid | ||
| 240 | value.</para><para>Video hardware may access padding bytes, therefore | ||
| 241 | they must reside in accessible memory. Consider for example the case | ||
| 242 | where padding bytes after the last line of an image cross a system | ||
| 243 | page boundary. Capture devices may write padding bytes, the value is | ||
| 244 | undefined. Output devices ignore the contents of padding | ||
| 245 | bytes.</para><para>When the image format is planar the | ||
| 246 | <structfield>bytesperline</structfield> value applies to the largest | ||
| 247 | plane and is divided by the same factor as the | ||
| 248 | <structfield>width</structfield> field for any smaller planes. For | ||
| 249 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many | ||
| 250 | padding bytes following each line as the Y plane. To avoid ambiguities | ||
| 251 | drivers must return a <structfield>bytesperline</structfield> value | ||
| 252 | rounded up to a multiple of the scale factor.</para></entry> | ||
| 253 | </row> | ||
| 254 | <row> | ||
| 255 | <entry></entry> | ||
| 256 | <entry>__u32</entry> | ||
| 257 | <entry><structfield>sizeimage</structfield></entry> | ||
| 258 | <entry><para>This field is irrelevant to | ||
| 259 | <wordasword>non-destructive Video Overlays</wordasword>. For | ||
| 260 | <wordasword>destructive Video Overlays</wordasword> applications must | ||
| 261 | initialize this field. For <wordasword>Video Output | ||
| 262 | Overlays</wordasword> the driver must return a valid | ||
| 263 | format.</para><para>Together with <structfield>base</structfield> it | ||
| 264 | defines the framebuffer memory accessible by the | ||
| 265 | driver.</para></entry> | ||
| 266 | </row> | ||
| 267 | <row> | ||
| 268 | <entry></entry> | ||
| 269 | <entry>&v4l2-colorspace;</entry> | ||
| 270 | <entry><structfield>colorspace</structfield></entry> | ||
| 271 | <entry>This information supplements the | ||
| 272 | <structfield>pixelformat</structfield> and must be set by the driver, | ||
| 273 | see <xref linkend="colorspaces" />.</entry> | ||
| 274 | </row> | ||
| 275 | <row> | ||
| 276 | <entry></entry> | ||
| 277 | <entry>__u32</entry> | ||
| 278 | <entry><structfield>priv</structfield></entry> | ||
| 279 | <entry>Reserved for additional information about custom | ||
| 280 | (driver defined) formats. When not used drivers and applications must | ||
| 281 | set this field to zero.</entry> | ||
| 282 | </row> | ||
| 283 | </tbody> | ||
| 284 | </tgroup> | ||
| 285 | </table> | ||
| 286 | |||
| 287 | <table pgwide="1" frame="none" id="framebuffer-cap"> | ||
| 288 | <title>Frame Buffer Capability Flags</title> | ||
| 289 | <tgroup cols="3"> | ||
| 290 | &cs-def; | ||
| 291 | <tbody valign="top"> | ||
| 292 | <row> | ||
| 293 | <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry> | ||
| 294 | <entry>0x0001</entry> | ||
| 295 | <entry>The device is capable of non-destructive overlays. | ||
| 296 | When the driver clears this flag, only destructive overlays are | ||
| 297 | supported. There are no drivers yet which support both destructive and | ||
| 298 | non-destructive overlays.</entry> | ||
| 299 | </row> | ||
| 300 | <row> | ||
| 301 | <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> | ||
| 302 | <entry>0x0002</entry> | ||
| 303 | <entry>The device supports clipping by chroma-keying the | ||
| 304 | images. That is, image pixels replace pixels in the VGA or video | ||
| 305 | signal only where the latter assume a certain color. Chroma-keying | ||
| 306 | makes no sense for destructive overlays.</entry> | ||
| 307 | </row> | ||
| 308 | <row> | ||
| 309 | <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry> | ||
| 310 | <entry>0x0004</entry> | ||
| 311 | <entry>The device supports clipping using a list of clip | ||
| 312 | rectangles.</entry> | ||
| 313 | </row> | ||
| 314 | <row> | ||
| 315 | <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry> | ||
| 316 | <entry>0x0008</entry> | ||
| 317 | <entry>The device supports clipping using a bit mask.</entry> | ||
| 318 | </row> | ||
| 319 | <row> | ||
| 320 | <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry> | ||
| 321 | <entry>0x0010</entry> | ||
| 322 | <entry>The device supports clipping/blending using the | ||
| 323 | alpha channel of the framebuffer or VGA signal. Alpha blending makes | ||
| 324 | no sense for destructive overlays.</entry> | ||
| 325 | </row> | ||
| 326 | <row> | ||
| 327 | <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry> | ||
| 328 | <entry>0x0020</entry> | ||
| 329 | <entry>The device supports alpha blending using a global | ||
| 330 | alpha value. Alpha blending makes no sense for destructive overlays.</entry> | ||
| 331 | </row> | ||
| 332 | <row> | ||
| 333 | <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry> | ||
| 334 | <entry>0x0040</entry> | ||
| 335 | <entry>The device supports clipping/blending using the | ||
| 336 | inverted alpha channel of the framebuffer or VGA signal. Alpha | ||
| 337 | blending makes no sense for destructive overlays.</entry> | ||
| 338 | </row> | ||
| 339 | </tbody> | ||
| 340 | </tgroup> | ||
| 341 | </table> | ||
| 342 | |||
| 343 | <table pgwide="1" frame="none" id="framebuffer-flags"> | ||
| 344 | <title>Frame Buffer Flags</title> | ||
| 345 | <tgroup cols="3"> | ||
| 346 | &cs-def; | ||
| 347 | <tbody valign="top"> | ||
| 348 | <row> | ||
| 349 | <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry> | ||
| 350 | <entry>0x0001</entry> | ||
| 351 | <entry>The framebuffer is the primary graphics surface. | ||
| 352 | In other words, the overlay is destructive. [?]</entry> | ||
| 353 | </row> | ||
| 354 | <row> | ||
| 355 | <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry> | ||
| 356 | <entry>0x0002</entry> | ||
| 357 | <entry>The frame buffer is an overlay surface the same | ||
| 358 | size as the capture. [?]</entry> | ||
| 359 | </row> | ||
| 360 | <row> | ||
| 361 | <entry spanname="hspan">The purpose of | ||
| 362 | <constant>V4L2_FBUF_FLAG_PRIMARY</constant> and | ||
| 363 | <constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear. | ||
| 364 | Most drivers seem to ignore these flags. For compatibility with the | ||
| 365 | <wordasword>bttv</wordasword> driver applications should set the | ||
| 366 | <constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry> | ||
| 367 | </row> | ||
| 368 | <row> | ||
| 369 | <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry> | ||
| 370 | <entry>0x0004</entry> | ||
| 371 | <entry>Use chroma-keying. The chroma-key color is | ||
| 372 | determined by the <structfield>chromakey</structfield> field of | ||
| 373 | &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 374 | linkend="overlay" /> | ||
| 375 | and | ||
| 376 | <xref linkend="osd" />.</entry> | ||
| 377 | </row> | ||
| 378 | <row> | ||
| 379 | <entry spanname="hspan">There are no flags to enable | ||
| 380 | clipping using a list of clip rectangles or a bitmap. These methods | ||
| 381 | are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 382 | linkend="overlay" /> and <xref linkend="osd" />.</entry> | ||
| 383 | </row> | ||
| 384 | <row> | ||
| 385 | <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry> | ||
| 386 | <entry>0x0008</entry> | ||
| 387 | <entry>Use the alpha channel of the framebuffer to clip or | ||
| 388 | blend framebuffer pixels with video images. The blend | ||
| 389 | function is: output = framebuffer pixel * alpha + video pixel * (1 - | ||
| 390 | alpha). The actual alpha depth depends on the framebuffer pixel | ||
| 391 | format.</entry> | ||
| 392 | </row> | ||
| 393 | <row> | ||
| 394 | <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry> | ||
| 395 | <entry>0x0010</entry> | ||
| 396 | <entry>Use a global alpha value to blend the framebuffer | ||
| 397 | with video images. The blend function is: output = (framebuffer pixel | ||
| 398 | * alpha + video pixel * (255 - alpha)) / 255. The alpha value is | ||
| 399 | determined by the <structfield>global_alpha</structfield> field of | ||
| 400 | &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 401 | linkend="overlay" /> | ||
| 402 | and <xref linkend="osd" />.</entry> | ||
| 403 | </row> | ||
| 404 | <row> | ||
| 405 | <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry> | ||
| 406 | <entry>0x0020</entry> | ||
| 407 | <entry>Like | ||
| 408 | <constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel | ||
| 409 | of the framebuffer to clip or blend framebuffer pixels with video | ||
| 410 | images, but with an inverted alpha value. The blend function is: | ||
| 411 | output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The | ||
| 412 | actual alpha depth depends on the framebuffer pixel format.</entry> | ||
| 413 | </row> | ||
| 414 | </tbody> | ||
| 415 | </tgroup> | ||
| 416 | </table> | ||
| 417 | </refsect1> | ||
| 418 | |||
| 419 | <refsect1> | ||
| 420 | &return-value; | ||
| 421 | |||
| 422 | <variablelist> | ||
| 423 | <varlistentry> | ||
| 424 | <term><errorcode>EPERM</errorcode></term> | ||
| 425 | <listitem> | ||
| 426 | <para><constant>VIDIOC_S_FBUF</constant> can only be called | ||
| 427 | by a privileged user to negotiate the parameters for a destructive | ||
| 428 | overlay.</para> | ||
| 429 | </listitem> | ||
| 430 | </varlistentry> | ||
| 431 | <varlistentry> | ||
| 432 | <term><errorcode>EBUSY</errorcode></term> | ||
| 433 | <listitem> | ||
| 434 | <para>The framebuffer parameters cannot be changed at this | ||
| 435 | time because overlay is already enabled, or capturing is enabled | ||
| 436 | and the hardware cannot capture and overlay simultaneously.</para> | ||
| 437 | </listitem> | ||
| 438 | </varlistentry> | ||
| 439 | <varlistentry> | ||
| 440 | <term><errorcode>EINVAL</errorcode></term> | ||
| 441 | <listitem> | ||
| 442 | <para>The ioctl is not supported or the | ||
| 443 | <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para> | ||
| 444 | </listitem> | ||
| 445 | </varlistentry> | ||
| 446 | </variablelist> | ||
| 447 | </refsect1> | ||
| 448 | </refentry> | ||
| 449 | |||
| 450 | <!-- | ||
| 451 | Local Variables: | ||
| 452 | mode: sgml | ||
| 453 | sgml-parent-document: "v4l2.sgml" | ||
| 454 | indent-tabs-mode: nil | ||
| 455 | End: | ||
| 456 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml new file mode 100644 index 000000000000..7c7d1b72c40d --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml | |||
| @@ -0,0 +1,201 @@ | |||
| 1 | <refentry id="vidioc-g-fmt"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, | ||
| 4 | VIDIOC_TRY_FMT</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_G_FMT</refname> | ||
| 10 | <refname>VIDIOC_S_FMT</refname> | ||
| 11 | <refname>VIDIOC_TRY_FMT</refname> | ||
| 12 | <refpurpose>Get or set the data format, try a format</refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | |||
| 15 | <refsynopsisdiv> | ||
| 16 | <funcsynopsis> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 19 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 20 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 21 | <paramdef>struct v4l2_format | ||
| 22 | *<parameter>argp</parameter></paramdef> | ||
| 23 | </funcprototype> | ||
| 24 | </funcsynopsis> | ||
| 25 | </refsynopsisdiv> | ||
| 26 | |||
| 27 | <refsect1> | ||
| 28 | <title>Arguments</title> | ||
| 29 | |||
| 30 | <variablelist> | ||
| 31 | <varlistentry> | ||
| 32 | <term><parameter>fd</parameter></term> | ||
| 33 | <listitem> | ||
| 34 | <para>&fd;</para> | ||
| 35 | </listitem> | ||
| 36 | </varlistentry> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>request</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>argp</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para></para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | </variablelist> | ||
| 50 | </refsect1> | ||
| 51 | |||
| 52 | <refsect1> | ||
| 53 | <title>Description</title> | ||
| 54 | |||
| 55 | <para>These ioctls are used to negotiate the format of data | ||
| 56 | (typically image format) exchanged between driver and | ||
| 57 | application.</para> | ||
| 58 | |||
| 59 | <para>To query the current parameters applications set the | ||
| 60 | <structfield>type</structfield> field of a struct | ||
| 61 | <structname>v4l2_format</structname> to the respective buffer (stream) | ||
| 62 | type. For example video capture devices use | ||
| 63 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application | ||
| 64 | calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to | ||
| 65 | this structure the driver fills the respective member of the | ||
| 66 | <structfield>fmt</structfield> union. In case of video capture devices | ||
| 67 | that is the &v4l2-pix-format; <structfield>pix</structfield> member. | ||
| 68 | When the requested buffer type is not supported drivers return an | ||
| 69 | &EINVAL;.</para> | ||
| 70 | |||
| 71 | <para>To change the current format parameters applications | ||
| 72 | initialize the <structfield>type</structfield> field and all | ||
| 73 | fields of the respective <structfield>fmt</structfield> | ||
| 74 | union member. For details see the documentation of the various devices | ||
| 75 | types in <xref linkend="devices" />. Good practice is to query the | ||
| 76 | current parameters first, and to | ||
| 77 | modify only those parameters not suitable for the application. When | ||
| 78 | the application calls the <constant>VIDIOC_S_FMT</constant> ioctl | ||
| 79 | with a pointer to a <structname>v4l2_format</structname> structure | ||
| 80 | the driver checks | ||
| 81 | and adjusts the parameters against hardware abilities. Drivers | ||
| 82 | should not return an error code unless the input is ambiguous, this is | ||
| 83 | a mechanism to fathom device capabilities and to approach parameters | ||
| 84 | acceptable for both the application and driver. On success the driver | ||
| 85 | may program the hardware, allocate resources and generally prepare for | ||
| 86 | data exchange. | ||
| 87 | Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the | ||
| 88 | current format parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 89 | Very simple, inflexible devices may even ignore all input and always | ||
| 90 | return the default parameters. However all V4L2 devices exchanging | ||
| 91 | data with the application must implement the | ||
| 92 | <constant>VIDIOC_G_FMT</constant> and | ||
| 93 | <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer | ||
| 94 | type is not supported drivers return an &EINVAL; on a | ||
| 95 | <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in | ||
| 96 | progress or the resource is not available for other reasons drivers | ||
| 97 | return the &EBUSY;.</para> | ||
| 98 | |||
| 99 | <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent | ||
| 100 | to <constant>VIDIOC_S_FMT</constant> with one exception: it does not | ||
| 101 | change driver state. It can also be called at any time, never | ||
| 102 | returning <errorcode>EBUSY</errorcode>. This function is provided to | ||
| 103 | negotiate parameters, to learn about hardware limitations, without | ||
| 104 | disabling I/O or possibly time consuming hardware preparations. | ||
| 105 | Although strongly recommended drivers are not required to implement | ||
| 106 | this ioctl.</para> | ||
| 107 | |||
| 108 | <table pgwide="1" frame="none" id="v4l2-format"> | ||
| 109 | <title>struct <structname>v4l2_format</structname></title> | ||
| 110 | <tgroup cols="4"> | ||
| 111 | <colspec colname="c1" /> | ||
| 112 | <colspec colname="c2" /> | ||
| 113 | <colspec colname="c3" /> | ||
| 114 | <colspec colname="c4" /> | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>&v4l2-buf-type;</entry> | ||
| 118 | <entry><structfield>type</structfield></entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Type of the data stream, see <xref | ||
| 121 | linkend="v4l2-buf-type" />.</entry> | ||
| 122 | </row> | ||
| 123 | <row> | ||
| 124 | <entry>union</entry> | ||
| 125 | <entry><structfield>fmt</structfield></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry></entry> | ||
| 129 | <entry>&v4l2-pix-format;</entry> | ||
| 130 | <entry><structfield>pix</structfield></entry> | ||
| 131 | <entry>Definition of an image format, see <xref | ||
| 132 | linkend="pixfmt" />, used by video capture and output | ||
| 133 | devices.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry></entry> | ||
| 137 | <entry>&v4l2-window;</entry> | ||
| 138 | <entry><structfield>win</structfield></entry> | ||
| 139 | <entry>Definition of an overlaid image, see <xref | ||
| 140 | linkend="overlay" />, used by video overlay devices.</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry></entry> | ||
| 144 | <entry>&v4l2-vbi-format;</entry> | ||
| 145 | <entry><structfield>vbi</structfield></entry> | ||
| 146 | <entry>Raw VBI capture or output parameters. This is | ||
| 147 | discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI | ||
| 148 | capture and output devices.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry></entry> | ||
| 152 | <entry>&v4l2-sliced-vbi-format;</entry> | ||
| 153 | <entry><structfield>sliced</structfield></entry> | ||
| 154 | <entry>Sliced VBI capture or output parameters. See | ||
| 155 | <xref linkend="sliced" /> for details. Used by sliced VBI | ||
| 156 | capture and output devices.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry></entry> | ||
| 160 | <entry>__u8</entry> | ||
| 161 | <entry><structfield>raw_data</structfield>[200]</entry> | ||
| 162 | <entry>Place holder for future extensions and custom | ||
| 163 | (driver defined) formats with <structfield>type</structfield> | ||
| 164 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> | ||
| 165 | </row> | ||
| 166 | </tbody> | ||
| 167 | </tgroup> | ||
| 168 | </table> | ||
| 169 | </refsect1> | ||
| 170 | |||
| 171 | <refsect1> | ||
| 172 | &return-value; | ||
| 173 | |||
| 174 | <variablelist> | ||
| 175 | <varlistentry> | ||
| 176 | <term><errorcode>EBUSY</errorcode></term> | ||
| 177 | <listitem> | ||
| 178 | <para>The data format cannot be changed at this | ||
| 179 | time, for example because I/O is already in progress.</para> | ||
| 180 | </listitem> | ||
| 181 | </varlistentry> | ||
| 182 | <varlistentry> | ||
| 183 | <term><errorcode>EINVAL</errorcode></term> | ||
| 184 | <listitem> | ||
| 185 | <para>The &v4l2-format; <structfield>type</structfield> | ||
| 186 | field is invalid, the requested buffer type not supported, or | ||
| 187 | <constant>VIDIOC_TRY_FMT</constant> was called and is not | ||
| 188 | supported with this buffer type.</para> | ||
| 189 | </listitem> | ||
| 190 | </varlistentry> | ||
| 191 | </variablelist> | ||
| 192 | </refsect1> | ||
| 193 | </refentry> | ||
| 194 | |||
| 195 | <!-- | ||
| 196 | Local Variables: | ||
| 197 | mode: sgml | ||
| 198 | sgml-parent-document: "v4l2.sgml" | ||
| 199 | indent-tabs-mode: nil | ||
| 200 | End: | ||
| 201 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/v4l/vidioc-g-frequency.xml new file mode 100644 index 000000000000..062d72069090 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-frequency.xml | |||
| @@ -0,0 +1,145 @@ | |||
| 1 | <refentry id="vidioc-g-frequency"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_FREQUENCY</refname> | ||
| 9 | <refname>VIDIOC_S_FREQUENCY</refname> | ||
| 10 | <refpurpose>Get or set tuner or modulator radio | ||
| 11 | frequency</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>struct v4l2_frequency | ||
| 21 | *<parameter>argp</parameter></paramdef> | ||
| 22 | </funcprototype> | ||
| 23 | </funcsynopsis> | ||
| 24 | <funcsynopsis> | ||
| 25 | <funcprototype> | ||
| 26 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 27 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 28 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 29 | <paramdef>const struct v4l2_frequency | ||
| 30 | *<parameter>argp</parameter></paramdef> | ||
| 31 | </funcprototype> | ||
| 32 | </funcsynopsis> | ||
| 33 | </refsynopsisdiv> | ||
| 34 | |||
| 35 | <refsect1> | ||
| 36 | <title>Arguments</title> | ||
| 37 | |||
| 38 | <variablelist> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>fd</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para>&fd;</para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | <varlistentry> | ||
| 46 | <term><parameter>request</parameter></term> | ||
| 47 | <listitem> | ||
| 48 | <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | <varlistentry> | ||
| 52 | <term><parameter>argp</parameter></term> | ||
| 53 | <listitem> | ||
| 54 | <para></para> | ||
| 55 | </listitem> | ||
| 56 | </varlistentry> | ||
| 57 | </variablelist> | ||
| 58 | </refsect1> | ||
| 59 | |||
| 60 | <refsect1> | ||
| 61 | <title>Description</title> | ||
| 62 | |||
| 63 | <para>To get the current tuner or modulator radio frequency | ||
| 64 | applications set the <structfield>tuner</structfield> field of a | ||
| 65 | &v4l2-frequency; to the respective tuner or modulator number (only | ||
| 66 | input devices have tuners, only output devices have modulators), zero | ||
| 67 | out the <structfield>reserved</structfield> array and | ||
| 68 | call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer | ||
| 69 | to this structure. The driver stores the current frequency in the | ||
| 70 | <structfield>frequency</structfield> field.</para> | ||
| 71 | |||
| 72 | <para>To change the current tuner or modulator radio frequency | ||
| 73 | applications initialize the <structfield>tuner</structfield>, | ||
| 74 | <structfield>type</structfield> and | ||
| 75 | <structfield>frequency</structfield> fields, and the | ||
| 76 | <structfield>reserved</structfield> array of a &v4l2-frequency; and | ||
| 77 | call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer | ||
| 78 | to this structure. When the requested frequency is not possible the | ||
| 79 | driver assumes the closest possible value. However | ||
| 80 | <constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does | ||
| 81 | not return the actual new frequency.</para> | ||
| 82 | |||
| 83 | <table pgwide="1" frame="none" id="v4l2-frequency"> | ||
| 84 | <title>struct <structname>v4l2_frequency</structname></title> | ||
| 85 | <tgroup cols="3"> | ||
| 86 | &cs-str; | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry>__u32</entry> | ||
| 90 | <entry><structfield>tuner</structfield></entry> | ||
| 91 | <entry>The tuner or modulator index number. This is the | ||
| 92 | same value as in the &v4l2-input; <structfield>tuner</structfield> | ||
| 93 | field and the &v4l2-tuner; <structfield>index</structfield> field, or | ||
| 94 | the &v4l2-output; <structfield>modulator</structfield> field and the | ||
| 95 | &v4l2-modulator; <structfield>index</structfield> field.</entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>&v4l2-tuner-type;</entry> | ||
| 99 | <entry><structfield>type</structfield></entry> | ||
| 100 | <entry>The tuner type. This is the same value as in the | ||
| 101 | &v4l2-tuner; <structfield>type</structfield> field. The field is not | ||
| 102 | applicable to modulators, &ie; ignored by drivers.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>__u32</entry> | ||
| 106 | <entry><structfield>frequency</structfield></entry> | ||
| 107 | <entry>Tuning frequency in units of 62.5 kHz, or if the | ||
| 108 | &v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag | ||
| 109 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 110 | Hz.</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry>__u32</entry> | ||
| 114 | <entry><structfield>reserved</structfield>[8]</entry> | ||
| 115 | <entry>Reserved for future extensions. Drivers and | ||
| 116 | applications must set the array to zero.</entry> | ||
| 117 | </row> | ||
| 118 | </tbody> | ||
| 119 | </tgroup> | ||
| 120 | </table> | ||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | &return-value; | ||
| 125 | |||
| 126 | <variablelist> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EINVAL</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>The <structfield>tuner</structfield> index is out of | ||
| 131 | bounds or the value in the <structfield>type</structfield> field is | ||
| 132 | wrong.</para> | ||
| 133 | </listitem> | ||
| 134 | </varlistentry> | ||
| 135 | </variablelist> | ||
| 136 | </refsect1> | ||
| 137 | </refentry> | ||
| 138 | |||
| 139 | <!-- | ||
| 140 | Local Variables: | ||
| 141 | mode: sgml | ||
| 142 | sgml-parent-document: "v4l2.sgml" | ||
| 143 | indent-tabs-mode: nil | ||
| 144 | End: | ||
| 145 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-input.xml b/Documentation/DocBook/v4l/vidioc-g-input.xml new file mode 100644 index 000000000000..ed076e92760d --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-input.xml | |||
| @@ -0,0 +1,100 @@ | |||
| 1 | <refentry id="vidioc-g-input"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_INPUT</refname> | ||
| 9 | <refname>VIDIOC_S_INPUT</refname> | ||
| 10 | <refpurpose>Query or select the current video input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_INPUT, VIDIOC_S_INPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the current video input applications call the | ||
| 53 | <constant>VIDIOC_G_INPUT</constant> ioctl with a pointer to an integer | ||
| 54 | where the driver stores the number of the input, as in the | ||
| 55 | &v4l2-input; <structfield>index</structfield> field. This ioctl will | ||
| 56 | fail only when there are no video inputs, returning | ||
| 57 | <errorcode>EINVAL</errorcode>.</para> | ||
| 58 | |||
| 59 | <para>To select a video input applications store the number of the | ||
| 60 | desired input in an integer and call the | ||
| 61 | <constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this | ||
| 62 | integer. Side effects are possible. For example inputs may support | ||
| 63 | different video standards, so the driver may implicitly switch the | ||
| 64 | current standard. It is good practice to select an input before | ||
| 65 | querying or negotiating any other parameters.</para> | ||
| 66 | |||
| 67 | <para>Information about video inputs is available using the | ||
| 68 | &VIDIOC-ENUMINPUT; ioctl.</para> | ||
| 69 | </refsect1> | ||
| 70 | |||
| 71 | <refsect1> | ||
| 72 | &return-value; | ||
| 73 | |||
| 74 | <variablelist> | ||
| 75 | <varlistentry> | ||
| 76 | <term><errorcode>EINVAL</errorcode></term> | ||
| 77 | <listitem> | ||
| 78 | <para>The number of the video input is out of bounds, or | ||
| 79 | there are no video inputs at all and this ioctl is not | ||
| 80 | supported.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBUSY</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>I/O is in progress, the input cannot be | ||
| 87 | switched.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | </variablelist> | ||
| 91 | </refsect1> | ||
| 92 | </refentry> | ||
| 93 | |||
| 94 | <!-- | ||
| 95 | Local Variables: | ||
| 96 | mode: sgml | ||
| 97 | sgml-parent-document: "v4l2.sgml" | ||
| 98 | indent-tabs-mode: nil | ||
| 99 | End: | ||
| 100 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml new file mode 100644 index 000000000000..77394b287411 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml | |||
| @@ -0,0 +1,180 @@ | |||
| 1 | <refentry id="vidioc-g-jpegcomp"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_JPEGCOMP</refname> | ||
| 9 | <refname>VIDIOC_S_JPEGCOMP</refname> | ||
| 10 | <refpurpose></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_jpegcompression *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const v4l2_jpegcompression *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>[to do]</para> | ||
| 61 | |||
| 62 | <para>Ronald Bultje elaborates:</para> | ||
| 63 | |||
| 64 | <!-- See video4linux-list@redhat.com on 16 Oct 2002, subject | ||
| 65 | "Re: [V4L] Re: v4l2 api / Zoran v4l2_jpegcompression" --> | ||
| 66 | |||
| 67 | <para>APP is some application-specific information. The | ||
| 68 | application can set it itself, and it'll be stored in the JPEG-encoded | ||
| 69 | fields (eg; interlacing information for in an AVI or so). COM is the | ||
| 70 | same, but it's comments, like 'encoded by me' or so.</para> | ||
| 71 | |||
| 72 | <para>jpeg_markers describes whether the huffman tables, | ||
| 73 | quantization tables and the restart interval information (all | ||
| 74 | JPEG-specific stuff) should be stored in the JPEG-encoded fields. | ||
| 75 | These define how the JPEG field is encoded. If you omit them, | ||
| 76 | applications assume you've used standard encoding. You usually do want | ||
| 77 | to add them.</para> | ||
| 78 | |||
| 79 | <!-- NB VIDIOC_S_JPEGCOMP is w/o. --> | ||
| 80 | |||
| 81 | <table pgwide="1" frame="none" id="v4l2-jpegcompression"> | ||
| 82 | <title>struct <structname>v4l2_jpegcompression</structname></title> | ||
| 83 | <tgroup cols="3"> | ||
| 84 | &cs-str; | ||
| 85 | <tbody valign="top"> | ||
| 86 | <row> | ||
| 87 | <entry>int</entry> | ||
| 88 | <entry><structfield>quality</structfield></entry> | ||
| 89 | <entry></entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>int</entry> | ||
| 93 | <entry><structfield>APPn</structfield></entry> | ||
| 94 | <entry></entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>int</entry> | ||
| 98 | <entry><structfield>APP_len</structfield></entry> | ||
| 99 | <entry></entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>char</entry> | ||
| 103 | <entry><structfield>APP_data</structfield>[60]</entry> | ||
| 104 | <entry></entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry>int</entry> | ||
| 108 | <entry><structfield>COM_len</structfield></entry> | ||
| 109 | <entry></entry> | ||
| 110 | </row> | ||
| 111 | <row> | ||
| 112 | <entry>char</entry> | ||
| 113 | <entry><structfield>COM_data</structfield>[60]</entry> | ||
| 114 | <entry></entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>jpeg_markers</structfield></entry> | ||
| 119 | <entry>See <xref linkend="jpeg-markers" />.</entry> | ||
| 120 | </row> | ||
| 121 | </tbody> | ||
| 122 | </tgroup> | ||
| 123 | </table> | ||
| 124 | |||
| 125 | <table pgwide="1" frame="none" id="jpeg-markers"> | ||
| 126 | <title>JPEG Markers Flags</title> | ||
| 127 | <tgroup cols="3"> | ||
| 128 | &cs-def; | ||
| 129 | <tbody valign="top"> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_JPEG_MARKER_DHT</constant></entry> | ||
| 132 | <entry>(1<<3)</entry> | ||
| 133 | <entry>Define Huffman Tables</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry> | ||
| 137 | <entry>(1<<4)</entry> | ||
| 138 | <entry>Define Quantization Tables</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry> | ||
| 142 | <entry>(1<<5)</entry> | ||
| 143 | <entry>Define Restart Interval</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry> | ||
| 147 | <entry>(1<<6)</entry> | ||
| 148 | <entry>Comment segment</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry> | ||
| 152 | <entry>(1<<7)</entry> | ||
| 153 | <entry>App segment, driver will always use APP0</entry> | ||
| 154 | </row> | ||
| 155 | </tbody> | ||
| 156 | </tgroup> | ||
| 157 | </table> | ||
| 158 | </refsect1> | ||
| 159 | |||
| 160 | <refsect1> | ||
| 161 | &return-value; | ||
| 162 | |||
| 163 | <variablelist> | ||
| 164 | <varlistentry> | ||
| 165 | <term><errorcode>EINVAL</errorcode></term> | ||
| 166 | <listitem> | ||
| 167 | <para>This ioctl is not supported.</para> | ||
| 168 | </listitem> | ||
| 169 | </varlistentry> | ||
| 170 | </variablelist> | ||
| 171 | </refsect1> | ||
| 172 | </refentry> | ||
| 173 | |||
| 174 | <!-- | ||
| 175 | Local Variables: | ||
| 176 | mode: sgml | ||
| 177 | sgml-parent-document: "v4l2.sgml" | ||
| 178 | indent-tabs-mode: nil | ||
| 179 | End: | ||
| 180 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/v4l/vidioc-g-modulator.xml new file mode 100644 index 000000000000..15ce660f0f5a --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-modulator.xml | |||
| @@ -0,0 +1,246 @@ | |||
| 1 | <refentry id="vidioc-g-modulator"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_MODULATOR</refname> | ||
| 9 | <refname>VIDIOC_S_MODULATOR</refname> | ||
| 10 | <refpurpose>Get or set modulator attributes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_modulator | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_modulator | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query the attributes of a modulator applications initialize | ||
| 63 | the <structfield>index</structfield> field and zero out the | ||
| 64 | <structfield>reserved</structfield> array of a &v4l2-modulator; and | ||
| 65 | call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer | ||
| 66 | to this structure. Drivers fill the rest of the structure or return an | ||
| 67 | &EINVAL; when the index is out of bounds. To enumerate all modulators | ||
| 68 | applications shall begin at index zero, incrementing by one until the | ||
| 69 | driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 70 | |||
| 71 | <para>Modulators have two writable properties, an audio | ||
| 72 | modulation set and the radio frequency. To change the modulated audio | ||
| 73 | subprograms, applications initialize the <structfield>index | ||
| 74 | </structfield> and <structfield>txsubchans</structfield> fields and the | ||
| 75 | <structfield>reserved</structfield> array and call the | ||
| 76 | <constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a | ||
| 77 | different audio modulation if the request cannot be satisfied. However | ||
| 78 | this is a write-only ioctl, it does not return the actual audio | ||
| 79 | modulation selected.</para> | ||
| 80 | |||
| 81 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | ||
| 82 | is available.</para> | ||
| 83 | |||
| 84 | <table pgwide="1" frame="none" id="v4l2-modulator"> | ||
| 85 | <title>struct <structname>v4l2_modulator</structname></title> | ||
| 86 | <tgroup cols="3"> | ||
| 87 | &cs-str; | ||
| 88 | <tbody valign="top"> | ||
| 89 | <row> | ||
| 90 | <entry>__u32</entry> | ||
| 91 | <entry><structfield>index</structfield></entry> | ||
| 92 | <entry>Identifies the modulator, set by the | ||
| 93 | application.</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>__u8</entry> | ||
| 97 | <entry><structfield>name</structfield>[32]</entry> | ||
| 98 | <entry>Name of the modulator, a NUL-terminated ASCII | ||
| 99 | string. This information is intended for the user.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u32</entry> | ||
| 103 | <entry><structfield>capability</structfield></entry> | ||
| 104 | <entry>Modulator capability flags. No flags are defined | ||
| 105 | for this field, the tuner flags in &v4l2-tuner; | ||
| 106 | are used accordingly. The audio flags indicate the ability | ||
| 107 | to encode audio subprograms. They will <emphasis>not</emphasis> | ||
| 108 | change for example with the current video standard.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>rangelow</structfield></entry> | ||
| 113 | <entry>The lowest tunable frequency in units of 62.5 | ||
| 114 | KHz, or if the <structfield>capability</structfield> flag | ||
| 115 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 116 | Hz.</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry>__u32</entry> | ||
| 120 | <entry><structfield>rangehigh</structfield></entry> | ||
| 121 | <entry>The highest tunable frequency in units of 62.5 | ||
| 122 | KHz, or if the <structfield>capability</structfield> flag | ||
| 123 | <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>txsubchans</structfield></entry> | ||
| 129 | <entry>With this field applications can determine how | ||
| 130 | audio sub-carriers shall be modulated. It contains a set of flags as | ||
| 131 | defined in <xref linkend="modulator-txsubchans" />. Note the tuner | ||
| 132 | <structfield>rxsubchans</structfield> flags are reused, but the | ||
| 133 | semantics are different. Video output devices are assumed to have an | ||
| 134 | analog or PCM audio input with 1-3 channels. The | ||
| 135 | <structfield>txsubchans</structfield> flags select one or more | ||
| 136 | channels for modulation, together with some audio subprogram | ||
| 137 | indicator, for example a stereo pilot tone.</entry> | ||
| 138 | </row> | ||
| 139 | <row> | ||
| 140 | <entry>__u32</entry> | ||
| 141 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 142 | <entry>Reserved for future extensions. Drivers and | ||
| 143 | applications must set the array to zero.</entry> | ||
| 144 | </row> | ||
| 145 | </tbody> | ||
| 146 | </tgroup> | ||
| 147 | </table> | ||
| 148 | |||
| 149 | <table pgwide="1" frame="none" id="modulator-txsubchans"> | ||
| 150 | <title>Modulator Audio Transmission Flags</title> | ||
| 151 | <tgroup cols="3"> | ||
| 152 | &cs-def; | ||
| 153 | <tbody valign="top"> | ||
| 154 | <row> | ||
| 155 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 156 | <entry>0x0001</entry> | ||
| 157 | <entry>Modulate channel 1 as mono audio, when the input | ||
| 158 | has more channels, a down-mix of channel 1 and 2. This flag does not | ||
| 159 | combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
| 160 | <constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | ||
| 164 | <entry>0x0002</entry> | ||
| 165 | <entry>Modulate channel 1 and 2 as left and right | ||
| 166 | channel of a stereo audio signal. When the input has only one channel | ||
| 167 | or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also | ||
| 168 | set, channel 1 is encoded as left and right channel. This flag does | ||
| 169 | not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
| 170 | <constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not | ||
| 171 | support stereo audio it shall fall back to mono.</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | ||
| 175 | <entry>0x0008</entry> | ||
| 176 | <entry>Modulate channel 1 and 2 as primary and secondary | ||
| 177 | language of a bilingual audio signal. When the input has only one | ||
| 178 | channel it is used for both languages. It is not possible to encode | ||
| 179 | the primary or secondary language only. This flag does not combine | ||
| 180 | with <constant>V4L2_TUNER_SUB_MONO</constant>, | ||
| 181 | <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
| 182 | <constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not | ||
| 183 | support the respective audio matrix, or the current video standard | ||
| 184 | does not permit bilingual audio the | ||
| 185 | <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; | ||
| 186 | and the driver shall fall back to mono or stereo mode.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | ||
| 190 | <entry>0x0004</entry> | ||
| 191 | <entry>Same effect as | ||
| 192 | <constant>V4L2_TUNER_SUB_SAP</constant>.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | ||
| 196 | <entry>0x0004</entry> | ||
| 197 | <entry>When combined with <constant>V4L2_TUNER_SUB_MONO | ||
| 198 | </constant> the first channel is encoded as mono audio, the last | ||
| 199 | channel as Second Audio Program. When the input has only one channel | ||
| 200 | it is used for both audio tracks. When the input has three channels | ||
| 201 | the mono track is a down-mix of channel 1 and 2. When combined with | ||
| 202 | <constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are | ||
| 203 | encoded as left and right stereo audio, channel 3 as Second Audio | ||
| 204 | Program. When the input has only two channels, the first is encoded as | ||
| 205 | left and right channel and the second as SAP. When the input has only | ||
| 206 | one channel it is used for all audio tracks. It is not possible to | ||
| 207 | encode a Second Audio Program only. This flag must combine with | ||
| 208 | <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
| 209 | <constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not | ||
| 210 | support the respective audio matrix, or the current video standard | ||
| 211 | does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl | ||
| 212 | shall return an &EINVAL; and driver shall fall back to mono or stereo | ||
| 213 | mode.</entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | ||
| 217 | <entry>0x0010</entry> | ||
| 218 | <entry>Enable the RDS encoder for a radio FM transmitter.</entry> | ||
| 219 | </row> | ||
| 220 | </tbody> | ||
| 221 | </tgroup> | ||
| 222 | </table> | ||
| 223 | </refsect1> | ||
| 224 | |||
| 225 | <refsect1> | ||
| 226 | &return-value; | ||
| 227 | |||
| 228 | <variablelist> | ||
| 229 | <varlistentry> | ||
| 230 | <term><errorcode>EINVAL</errorcode></term> | ||
| 231 | <listitem> | ||
| 232 | <para>The &v4l2-modulator; | ||
| 233 | <structfield>index</structfield> is out of bounds.</para> | ||
| 234 | </listitem> | ||
| 235 | </varlistentry> | ||
| 236 | </variablelist> | ||
| 237 | </refsect1> | ||
| 238 | </refentry> | ||
| 239 | |||
| 240 | <!-- | ||
| 241 | Local Variables: | ||
| 242 | mode: sgml | ||
| 243 | sgml-parent-document: "v4l2.sgml" | ||
| 244 | indent-tabs-mode: nil | ||
| 245 | End: | ||
| 246 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-output.xml b/Documentation/DocBook/v4l/vidioc-g-output.xml new file mode 100644 index 000000000000..3ea8c0ed812e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-output.xml | |||
| @@ -0,0 +1,100 @@ | |||
| 1 | <refentry id="vidioc-g-output"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_OUTPUT</refname> | ||
| 9 | <refname>VIDIOC_S_OUTPUT</refname> | ||
| 10 | <refpurpose>Query or select the current video output</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the current video output applications call the | ||
| 53 | <constant>VIDIOC_G_OUTPUT</constant> ioctl with a pointer to an integer | ||
| 54 | where the driver stores the number of the output, as in the | ||
| 55 | &v4l2-output; <structfield>index</structfield> field. This ioctl | ||
| 56 | will fail only when there are no video outputs, returning the | ||
| 57 | &EINVAL;.</para> | ||
| 58 | |||
| 59 | <para>To select a video output applications store the number of the | ||
| 60 | desired output in an integer and call the | ||
| 61 | <constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer. | ||
| 62 | Side effects are possible. For example outputs may support different | ||
| 63 | video standards, so the driver may implicitly switch the current | ||
| 64 | standard. It is good practice to select an output before querying or | ||
| 65 | negotiating any other parameters.</para> | ||
| 66 | |||
| 67 | <para>Information about video outputs is available using the | ||
| 68 | &VIDIOC-ENUMOUTPUT; ioctl.</para> | ||
| 69 | </refsect1> | ||
| 70 | |||
| 71 | <refsect1> | ||
| 72 | &return-value; | ||
| 73 | |||
| 74 | <variablelist> | ||
| 75 | <varlistentry> | ||
| 76 | <term><errorcode>EINVAL</errorcode></term> | ||
| 77 | <listitem> | ||
| 78 | <para>The number of the video output is out of bounds, or | ||
| 79 | there are no video outputs at all and this ioctl is not | ||
| 80 | supported.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBUSY</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>I/O is in progress, the output cannot be | ||
| 87 | switched.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | </variablelist> | ||
| 91 | </refsect1> | ||
| 92 | </refentry> | ||
| 93 | |||
| 94 | <!-- | ||
| 95 | Local Variables: | ||
| 96 | mode: sgml | ||
| 97 | sgml-parent-document: "v4l2.sgml" | ||
| 98 | indent-tabs-mode: nil | ||
| 99 | End: | ||
| 100 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-parm.xml b/Documentation/DocBook/v4l/vidioc-g-parm.xml new file mode 100644 index 000000000000..78332d365ce9 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-parm.xml | |||
| @@ -0,0 +1,332 @@ | |||
| 1 | <refentry id="vidioc-g-parm"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_PARM</refname> | ||
| 9 | <refname>VIDIOC_S_PARM</refname> | ||
| 10 | <refpurpose>Get or set streaming parameters</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The current video standard determines a nominal number of | ||
| 53 | frames per second. If less than this number of frames is to be | ||
| 54 | captured or output, applications can request frame skipping or | ||
| 55 | duplicating on the driver side. This is especially useful when using | ||
| 56 | the <function>read()</function> or <function>write()</function>, which | ||
| 57 | are not augmented by timestamps or sequence counters, and to avoid | ||
| 58 | unneccessary data copying.</para> | ||
| 59 | |||
| 60 | <para>Further these ioctls can be used to determine the number of | ||
| 61 | buffers used internally by a driver in read/write mode. For | ||
| 62 | implications see the section discussing the &func-read; | ||
| 63 | function.</para> | ||
| 64 | |||
| 65 | <para>To get and set the streaming parameters applications call | ||
| 66 | the <constant>VIDIOC_G_PARM</constant> and | ||
| 67 | <constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a | ||
| 68 | pointer to a struct <structname>v4l2_streamparm</structname> which | ||
| 69 | contains a union holding separate parameters for input and output | ||
| 70 | devices.</para> | ||
| 71 | |||
| 72 | <table pgwide="1" frame="none" id="v4l2-streamparm"> | ||
| 73 | <title>struct <structname>v4l2_streamparm</structname></title> | ||
| 74 | <tgroup cols="4"> | ||
| 75 | &cs-ustr; | ||
| 76 | <tbody valign="top"> | ||
| 77 | <row> | ||
| 78 | <entry>&v4l2-buf-type;</entry> | ||
| 79 | <entry><structfield>type</structfield></entry> | ||
| 80 | <entry></entry> | ||
| 81 | <entry>The buffer (stream) type, same as &v4l2-format; | ||
| 82 | <structfield>type</structfield>, set by the application.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>union</entry> | ||
| 86 | <entry><structfield>parm</structfield></entry> | ||
| 87 | <entry></entry> | ||
| 88 | <entry></entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry></entry> | ||
| 92 | <entry>&v4l2-captureparm;</entry> | ||
| 93 | <entry><structfield>capture</structfield></entry> | ||
| 94 | <entry>Parameters for capture devices, used when | ||
| 95 | <structfield>type</structfield> is | ||
| 96 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry>&v4l2-outputparm;</entry> | ||
| 101 | <entry><structfield>output</structfield></entry> | ||
| 102 | <entry>Parameters for output devices, used when | ||
| 103 | <structfield>type</structfield> is | ||
| 104 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry></entry> | ||
| 108 | <entry>__u8</entry> | ||
| 109 | <entry><structfield>raw_data</structfield>[200]</entry> | ||
| 110 | <entry>A place holder for future extensions and custom | ||
| 111 | (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and | ||
| 112 | higher.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="v4l2-captureparm"> | ||
| 119 | <title>struct <structname>v4l2_captureparm</structname></title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-str; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry>__u32</entry> | ||
| 125 | <entry><structfield>capability</structfield></entry> | ||
| 126 | <entry>See <xref linkend="parm-caps" />.</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>__u32</entry> | ||
| 130 | <entry><structfield>capturemode</structfield></entry> | ||
| 131 | <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> | ||
| 132 | </row> | ||
| 133 | <row> | ||
| 134 | <entry>&v4l2-fract;</entry> | ||
| 135 | <entry><structfield>timeperframe</structfield></entry> | ||
| 136 | <entry><para>This is is the desired period between | ||
| 137 | successive frames captured by the driver, in seconds. The | ||
| 138 | field is intended to skip frames on the driver side, saving I/O | ||
| 139 | bandwidth.</para><para>Applications store here the desired frame | ||
| 140 | period, drivers return the actual frame period, which must be greater | ||
| 141 | or equal to the nominal frame period determined by the current video | ||
| 142 | standard (&v4l2-standard; <structfield>frameperiod</structfield> | ||
| 143 | field). Changing the video standard (also implicitly by switching the | ||
| 144 | video input) may reset this parameter to the nominal frame period. To | ||
| 145 | reset manually applications can just set this field to | ||
| 146 | zero.</para><para>Drivers support this function only when they set the | ||
| 147 | <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the | ||
| 148 | <structfield>capability</structfield> field.</para></entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry>__u32</entry> | ||
| 152 | <entry><structfield>extendedmode</structfield></entry> | ||
| 153 | <entry>Custom (driver specific) streaming parameters. When | ||
| 154 | unused, applications and drivers must set this field to zero. | ||
| 155 | Applications using this field should check the driver name and | ||
| 156 | version, see <xref linkend="querycap" />.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>readbuffers</structfield></entry> | ||
| 161 | <entry>Applications set this field to the desired number | ||
| 162 | of buffers used internally by the driver in &func-read; mode. Drivers | ||
| 163 | return the actual number of buffers. When an application requests zero | ||
| 164 | buffers, drivers should just return the current setting rather than | ||
| 165 | the minimum or an error code. For details see <xref | ||
| 166 | linkend="rw" />.</entry> | ||
| 167 | </row> | ||
| 168 | <row> | ||
| 169 | <entry>__u32</entry> | ||
| 170 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 171 | <entry>Reserved for future extensions. Drivers and | ||
| 172 | applications must set the array to zero.</entry> | ||
| 173 | </row> | ||
| 174 | </tbody> | ||
| 175 | </tgroup> | ||
| 176 | </table> | ||
| 177 | |||
| 178 | <table pgwide="1" frame="none" id="v4l2-outputparm"> | ||
| 179 | <title>struct <structname>v4l2_outputparm</structname></title> | ||
| 180 | <tgroup cols="3"> | ||
| 181 | &cs-str; | ||
| 182 | <tbody valign="top"> | ||
| 183 | <row> | ||
| 184 | <entry>__u32</entry> | ||
| 185 | <entry><structfield>capability</structfield></entry> | ||
| 186 | <entry>See <xref linkend="parm-caps" />.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry>__u32</entry> | ||
| 190 | <entry><structfield>outputmode</structfield></entry> | ||
| 191 | <entry>Set by drivers and applications, see <xref | ||
| 192 | linkend="parm-flags" />.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry>&v4l2-fract;</entry> | ||
| 196 | <entry><structfield>timeperframe</structfield></entry> | ||
| 197 | <entry>This is is the desired period between | ||
| 198 | successive frames output by the driver, in seconds.</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry spanname="hspan"><para>The field is intended to | ||
| 202 | repeat frames on the driver side in &func-write; mode (in streaming | ||
| 203 | mode timestamps can be used to throttle the output), saving I/O | ||
| 204 | bandwidth.</para><para>Applications store here the desired frame | ||
| 205 | period, drivers return the actual frame period, which must be greater | ||
| 206 | or equal to the nominal frame period determined by the current video | ||
| 207 | standard (&v4l2-standard; <structfield>frameperiod</structfield> | ||
| 208 | field). Changing the video standard (also implicitly by switching the | ||
| 209 | video output) may reset this parameter to the nominal frame period. To | ||
| 210 | reset manually applications can just set this field to | ||
| 211 | zero.</para><para>Drivers support this function only when they set the | ||
| 212 | <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the | ||
| 213 | <structfield>capability</structfield> field.</para></entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry>__u32</entry> | ||
| 217 | <entry><structfield>extendedmode</structfield></entry> | ||
| 218 | <entry>Custom (driver specific) streaming parameters. When | ||
| 219 | unused, applications and drivers must set this field to zero. | ||
| 220 | Applications using this field should check the driver name and | ||
| 221 | version, see <xref linkend="querycap" />.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>writebuffers</structfield></entry> | ||
| 226 | <entry>Applications set this field to the desired number | ||
| 227 | of buffers used internally by the driver in | ||
| 228 | <function>write()</function> mode. Drivers return the actual number of | ||
| 229 | buffers. When an application requests zero buffers, drivers should | ||
| 230 | just return the current setting rather than the minimum or an error | ||
| 231 | code. For details see <xref linkend="rw" />.</entry> | ||
| 232 | </row> | ||
| 233 | <row> | ||
| 234 | <entry>__u32</entry> | ||
| 235 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 236 | <entry>Reserved for future extensions. Drivers and | ||
| 237 | applications must set the array to zero.</entry> | ||
| 238 | </row> | ||
| 239 | </tbody> | ||
| 240 | </tgroup> | ||
| 241 | </table> | ||
| 242 | |||
| 243 | <table pgwide="1" frame="none" id="parm-caps"> | ||
| 244 | <title>Streaming Parameters Capabilites</title> | ||
| 245 | <tgroup cols="3"> | ||
| 246 | &cs-def; | ||
| 247 | <tbody valign="top"> | ||
| 248 | <row> | ||
| 249 | <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry> | ||
| 250 | <entry>0x1000</entry> | ||
| 251 | <entry>The frame skipping/repeating controlled by the | ||
| 252 | <structfield>timeperframe</structfield> field is supported.</entry> | ||
| 253 | </row> | ||
| 254 | </tbody> | ||
| 255 | </tgroup> | ||
| 256 | </table> | ||
| 257 | |||
| 258 | <table pgwide="1" frame="none" id="parm-flags"> | ||
| 259 | <title>Capture Parameters Flags</title> | ||
| 260 | <tgroup cols="3"> | ||
| 261 | &cs-def; | ||
| 262 | <tbody valign="top"> | ||
| 263 | <row> | ||
| 264 | <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry> | ||
| 265 | <entry>0x0001</entry> | ||
| 266 | <entry><para>High quality imaging mode. High quality mode | ||
| 267 | is intended for still imaging applications. The idea is to get the | ||
| 268 | best possible image quality that the hardware can deliver. It is not | ||
| 269 | defined how the driver writer may achieve that; it will depend on the | ||
| 270 | hardware and the ingenuity of the driver writer. High quality mode is | ||
| 271 | a different mode from the the regular motion video capture modes. In | ||
| 272 | high quality mode:<itemizedlist> | ||
| 273 | <listitem> | ||
| 274 | <para>The driver may be able to capture higher | ||
| 275 | resolutions than for motion capture.</para> | ||
| 276 | </listitem> | ||
| 277 | <listitem> | ||
| 278 | <para>The driver may support fewer pixel formats | ||
| 279 | than motion capture (eg; true color).</para> | ||
| 280 | </listitem> | ||
| 281 | <listitem> | ||
| 282 | <para>The driver may capture and arithmetically | ||
| 283 | combine multiple successive fields or frames to remove color edge | ||
| 284 | artifacts and reduce the noise in the video data. | ||
| 285 | </para> | ||
| 286 | </listitem> | ||
| 287 | <listitem> | ||
| 288 | <para>The driver may capture images in slices like | ||
| 289 | a scanner in order to handle larger format images than would otherwise | ||
| 290 | be possible. </para> | ||
| 291 | </listitem> | ||
| 292 | <listitem> | ||
| 293 | <para>An image capture operation may be | ||
| 294 | significantly slower than motion capture. </para> | ||
| 295 | </listitem> | ||
| 296 | <listitem> | ||
| 297 | <para>Moving objects in the image might have | ||
| 298 | excessive motion blur. </para> | ||
| 299 | </listitem> | ||
| 300 | <listitem> | ||
| 301 | <para>Capture might only work through the | ||
| 302 | <function>read()</function> call.</para> | ||
| 303 | </listitem> | ||
| 304 | </itemizedlist></para></entry> | ||
| 305 | </row> | ||
| 306 | </tbody> | ||
| 307 | </tgroup> | ||
| 308 | </table> | ||
| 309 | |||
| 310 | </refsect1> | ||
| 311 | |||
| 312 | <refsect1> | ||
| 313 | &return-value; | ||
| 314 | |||
| 315 | <variablelist> | ||
| 316 | <varlistentry> | ||
| 317 | <term><errorcode>EINVAL</errorcode></term> | ||
| 318 | <listitem> | ||
| 319 | <para>This ioctl is not supported.</para> | ||
| 320 | </listitem> | ||
| 321 | </varlistentry> | ||
| 322 | </variablelist> | ||
| 323 | </refsect1> | ||
| 324 | </refentry> | ||
| 325 | |||
| 326 | <!-- | ||
| 327 | Local Variables: | ||
| 328 | mode: sgml | ||
| 329 | sgml-parent-document: "v4l2.sgml" | ||
| 330 | indent-tabs-mode: nil | ||
| 331 | End: | ||
| 332 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-priority.xml b/Documentation/DocBook/v4l/vidioc-g-priority.xml new file mode 100644 index 000000000000..5fb001978645 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-priority.xml | |||
| @@ -0,0 +1,144 @@ | |||
| 1 | <refentry id="vidioc-g-priority"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_PRIORITY</refname> | ||
| 9 | <refname>VIDIOC_S_PRIORITY</refname> | ||
| 10 | <refpurpose>Query or request the access priority associated with a | ||
| 11 | file descriptor</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para>Pointer to an enum v4l2_priority type.</para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <para>To query the current access priority | ||
| 62 | applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl | ||
| 63 | with a pointer to an enum v4l2_priority variable where the driver stores | ||
| 64 | the current priority.</para> | ||
| 65 | |||
| 66 | <para>To request an access priority applications store the | ||
| 67 | desired priority in an enum v4l2_priority variable and call | ||
| 68 | <constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this | ||
| 69 | variable.</para> | ||
| 70 | |||
| 71 | <table frame="none" pgwide="1" id="v4l2-priority"> | ||
| 72 | <title>enum v4l2_priority</title> | ||
| 73 | <tgroup cols="3"> | ||
| 74 | &cs-def; | ||
| 75 | <tbody valign="top"> | ||
| 76 | <row> | ||
| 77 | <entry><constant>V4L2_PRIORITY_UNSET</constant></entry> | ||
| 78 | <entry>0</entry> | ||
| 79 | <entry></entry> | ||
| 80 | </row> | ||
| 81 | <row> | ||
| 82 | <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry> | ||
| 83 | <entry>1</entry> | ||
| 84 | <entry>Lowest priority, usually applications running in | ||
| 85 | background, for example monitoring VBI transmissions. A proxy | ||
| 86 | application running in user space will be necessary if multiple | ||
| 87 | applications want to read from a device at this priority.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry> | ||
| 91 | <entry>2</entry> | ||
| 92 | <entry></entry> | ||
| 93 | </row> | ||
| 94 | <row> | ||
| 95 | <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry> | ||
| 96 | <entry>2</entry> | ||
| 97 | <entry>Medium priority, usually applications started and | ||
| 98 | interactively controlled by the user. For example TV viewers, Teletext | ||
| 99 | browsers, or just "panel" applications to change the channel or video | ||
| 100 | controls. This is the default priority unless an application requests | ||
| 101 | another.</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry><constant>V4L2_PRIORITY_RECORD</constant></entry> | ||
| 105 | <entry>3</entry> | ||
| 106 | <entry>Highest priority. Only one file descriptor can have | ||
| 107 | this priority, it blocks any other fd from changing device properties. | ||
| 108 | Usually applications which must not be interrupted, like video | ||
| 109 | recording.</entry> | ||
| 110 | </row> | ||
| 111 | </tbody> | ||
| 112 | </tgroup> | ||
| 113 | </table> | ||
| 114 | </refsect1> | ||
| 115 | |||
| 116 | <refsect1> | ||
| 117 | &return-value; | ||
| 118 | |||
| 119 | <variablelist> | ||
| 120 | <varlistentry> | ||
| 121 | <term><errorcode>EINVAL</errorcode></term> | ||
| 122 | <listitem> | ||
| 123 | <para>The requested priority value is invalid, or the | ||
| 124 | driver does not support access priorities.</para> | ||
| 125 | </listitem> | ||
| 126 | </varlistentry> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EBUSY</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>Another application already requested higher | ||
| 131 | priority.</para> | ||
| 132 | </listitem> | ||
| 133 | </varlistentry> | ||
| 134 | </variablelist> | ||
| 135 | </refsect1> | ||
| 136 | </refentry> | ||
| 137 | |||
| 138 | <!-- | ||
| 139 | Local Variables: | ||
| 140 | mode: sgml | ||
| 141 | sgml-parent-document: "v4l2.sgml" | ||
| 142 | indent-tabs-mode: nil | ||
| 143 | End: | ||
| 144 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml new file mode 100644 index 000000000000..10e721b17374 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml | |||
| @@ -0,0 +1,264 @@ | |||
| 1 | <refentry id="vidioc-g-sliced-vbi-cap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_SLICED_VBI_CAP</refname> | ||
| 9 | <refpurpose>Query sliced VBI capabilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_G_SLICED_VBI_CAP</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To find out which data services are supported by a sliced | ||
| 52 | VBI capture or output device, applications initialize the | ||
| 53 | <structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;, | ||
| 54 | clear the <structfield>reserved</structfield> array and | ||
| 55 | call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The | ||
| 56 | driver fills in the remaining fields or returns an &EINVAL; if the | ||
| 57 | sliced VBI API is unsupported or <structfield>type</structfield> | ||
| 58 | is invalid.</para> | ||
| 59 | |||
| 60 | <para>Note the <structfield>type</structfield> field was added, | ||
| 61 | and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para> | ||
| 62 | |||
| 63 | <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap"> | ||
| 64 | <title>struct <structname>v4l2_sliced_vbi_cap</structname></title> | ||
| 65 | <tgroup cols="5"> | ||
| 66 | <colspec colname="c1" colwidth="3*" /> | ||
| 67 | <colspec colname="c2" colwidth="3*" /> | ||
| 68 | <colspec colname="c3" colwidth="2*" /> | ||
| 69 | <colspec colname="c4" colwidth="2*" /> | ||
| 70 | <colspec colname="c5" colwidth="2*" /> | ||
| 71 | <spanspec spanname="hspan" namest="c3" nameend="c5" /> | ||
| 72 | <tbody valign="top"> | ||
| 73 | <row> | ||
| 74 | <entry>__u16</entry> | ||
| 75 | <entry><structfield>service_set</structfield></entry> | ||
| 76 | <entry spanname="hspan">A set of all data services | ||
| 77 | supported by the driver. Equal to the union of all elements of the | ||
| 78 | <structfield>service_lines </structfield> array.</entry> | ||
| 79 | </row> | ||
| 80 | <row> | ||
| 81 | <entry>__u16</entry> | ||
| 82 | <entry><structfield>service_lines</structfield>[2][24]</entry> | ||
| 83 | <entry spanname="hspan">Each element of this array | ||
| 84 | contains a set of data services the hardware can look for or insert | ||
| 85 | into a particular scan line. Data services are defined in <xref | ||
| 86 | linkend="vbi-services" />. Array indices map to ITU-R | ||
| 87 | line numbers (see also <xref | ||
| 88 | linkend="vbi-525" /> and <xref | ||
| 89 | linkend="vbi-625" />) as follows:</entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry></entry> | ||
| 93 | <entry></entry> | ||
| 94 | <entry>Element</entry> | ||
| 95 | <entry>525 line systems</entry> | ||
| 96 | <entry>625 line systems</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry></entry> | ||
| 101 | <entry><structfield>service_lines</structfield>[0][1]</entry> | ||
| 102 | <entry align="center">1</entry> | ||
| 103 | <entry align="center">1</entry> | ||
| 104 | </row> | ||
| 105 | <row> | ||
| 106 | <entry></entry> | ||
| 107 | <entry></entry> | ||
| 108 | <entry><structfield>service_lines</structfield>[0][23]</entry> | ||
| 109 | <entry align="center">23</entry> | ||
| 110 | <entry align="center">23</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry></entry> | ||
| 114 | <entry></entry> | ||
| 115 | <entry><structfield>service_lines</structfield>[1][1]</entry> | ||
| 116 | <entry align="center">264</entry> | ||
| 117 | <entry align="center">314</entry> | ||
| 118 | </row> | ||
| 119 | <row> | ||
| 120 | <entry></entry> | ||
| 121 | <entry></entry> | ||
| 122 | <entry><structfield>service_lines</structfield>[1][23]</entry> | ||
| 123 | <entry align="center">286</entry> | ||
| 124 | <entry align="center">336</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry></entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry></entry> | ||
| 131 | <entry></entry> | ||
| 132 | <entry spanname="hspan">The number of VBI lines the | ||
| 133 | hardware can capture or output per frame, or the number of services it | ||
| 134 | can identify on a given line may be limited. For example on PAL line | ||
| 135 | 16 the hardware may be able to look for a VPS or Teletext signal, but | ||
| 136 | not both at the same time. Applications can learn about these limits | ||
| 137 | using the &VIDIOC-S-FMT; ioctl as described in <xref | ||
| 138 | linkend="sliced" />.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry></entry> | ||
| 142 | </row> | ||
| 143 | <row> | ||
| 144 | <entry></entry> | ||
| 145 | <entry></entry> | ||
| 146 | <entry spanname="hspan">Drivers must set | ||
| 147 | <structfield>service_lines</structfield>[0][0] and | ||
| 148 | <structfield>service_lines</structfield>[1][0] to zero.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry>&v4l2-buf-type;</entry> | ||
| 152 | <entry><structfield>type</structfield></entry> | ||
| 153 | <entry>Type of the data stream, see <xref | ||
| 154 | linkend="v4l2-buf-type" />. Should be | ||
| 155 | <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or | ||
| 156 | <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>reserved</structfield>[3]</entry> | ||
| 161 | <entry spanname="hspan">This array is reserved for future | ||
| 162 | extensions. Applications and drivers must set it to zero.</entry> | ||
| 163 | </row> | ||
| 164 | </tbody> | ||
| 165 | </tgroup> | ||
| 166 | </table> | ||
| 167 | |||
| 168 | <!-- See also dev-sliced-vbi.sgml --> | ||
| 169 | <table pgwide="1" frame="none" id="vbi-services"> | ||
| 170 | <title>Sliced VBI services</title> | ||
| 171 | <tgroup cols="5"> | ||
| 172 | <colspec colname="c1" colwidth="2*" /> | ||
| 173 | <colspec colname="c2" colwidth="1*" /> | ||
| 174 | <colspec colname="c3" colwidth="1*" /> | ||
| 175 | <colspec colname="c4" colwidth="2*" /> | ||
| 176 | <colspec colname="c5" colwidth="2*" /> | ||
| 177 | <spanspec spanname='rlp' namest='c3' nameend='c5' /> | ||
| 178 | <thead> | ||
| 179 | <row> | ||
| 180 | <entry>Symbol</entry> | ||
| 181 | <entry>Value</entry> | ||
| 182 | <entry>Reference</entry> | ||
| 183 | <entry>Lines, usually</entry> | ||
| 184 | <entry>Payload</entry> | ||
| 185 | </row> | ||
| 186 | </thead> | ||
| 187 | <tbody valign="top"> | ||
| 188 | <row> | ||
| 189 | <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext | ||
| 190 | System B)</entry> | ||
| 191 | <entry>0x0001</entry> | ||
| 192 | <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> | ||
| 193 | <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> | ||
| 194 | <entry>Last 42 of the 45 byte Teletext packet, that is | ||
| 195 | without clock run-in and framing code, lsb first transmitted.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry><constant>V4L2_SLICED_VPS</constant></entry> | ||
| 199 | <entry>0x0400</entry> | ||
| 200 | <entry><xref linkend="ets300231" /></entry> | ||
| 201 | <entry>PAL line 16</entry> | ||
| 202 | <entry>Byte number 3 to 15 according to Figure 9 of | ||
| 203 | ETS 300 231, lsb first transmitted.</entry> | ||
| 204 | </row> | ||
| 205 | <row> | ||
| 206 | <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> | ||
| 207 | <entry>0x1000</entry> | ||
| 208 | <entry><xref linkend="eia608" /></entry> | ||
| 209 | <entry>NTSC line 21, 284 (second field 21)</entry> | ||
| 210 | <entry>Two bytes in transmission order, including parity | ||
| 211 | bit, lsb first transmitted.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry><constant>V4L2_SLICED_WSS_625</constant></entry> | ||
| 215 | <entry>0x4000</entry> | ||
| 216 | <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry> | ||
| 217 | <entry>PAL/SECAM line 23</entry> | ||
| 218 | <entry><screen> | ||
| 219 | Byte 0 1 | ||
| 220 | msb lsb msb lsb | ||
| 221 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | ||
| 222 | </screen></entry> | ||
| 223 | </row> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_SLICED_VBI_525</constant></entry> | ||
| 226 | <entry>0x1000</entry> | ||
| 227 | <entry spanname="rlp">Set of services applicable to 525 | ||
| 228 | line systems.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_SLICED_VBI_625</constant></entry> | ||
| 232 | <entry>0x4401</entry> | ||
| 233 | <entry spanname="rlp">Set of services applicable to 625 | ||
| 234 | line systems.</entry> | ||
| 235 | </row> | ||
| 236 | </tbody> | ||
| 237 | </tgroup> | ||
| 238 | </table> | ||
| 239 | |||
| 240 | </refsect1> | ||
| 241 | |||
| 242 | <refsect1> | ||
| 243 | &return-value; | ||
| 244 | |||
| 245 | <variablelist> | ||
| 246 | <varlistentry> | ||
| 247 | <term><errorcode>EINVAL</errorcode></term> | ||
| 248 | <listitem> | ||
| 249 | <para>The device does not support sliced VBI capturing or | ||
| 250 | output, or the value in the <structfield>type</structfield> field is | ||
| 251 | wrong.</para> | ||
| 252 | </listitem> | ||
| 253 | </varlistentry> | ||
| 254 | </variablelist> | ||
| 255 | </refsect1> | ||
| 256 | </refentry> | ||
| 257 | |||
| 258 | <!-- | ||
| 259 | Local Variables: | ||
| 260 | mode: sgml | ||
| 261 | sgml-parent-document: "v4l2.sgml" | ||
| 262 | indent-tabs-mode: nil | ||
| 263 | End: | ||
| 264 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-std.xml b/Documentation/DocBook/v4l/vidioc-g-std.xml new file mode 100644 index 000000000000..b6f5d267e856 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-std.xml | |||
| @@ -0,0 +1,99 @@ | |||
| 1 | <refentry id="vidioc-g-std"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_STD, VIDIOC_S_STD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_STD</refname> | ||
| 9 | <refname>VIDIOC_S_STD</refname> | ||
| 10 | <refpurpose>Query or select the video standard of the current input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_std_id | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const v4l2_std_id | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_STD, VIDIOC_S_STD</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query and select the current video standard applications | ||
| 63 | use the <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant> ioctls which take a pointer to a | ||
| 64 | &v4l2-std-id; type as argument. <constant>VIDIOC_G_STD</constant> can | ||
| 65 | return a single flag or a set of flags as in &v4l2-standard; field | ||
| 66 | <structfield>id</structfield>. The flags must be unambiguous such | ||
| 67 | that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para> | ||
| 68 | |||
| 69 | <para><constant>VIDIOC_S_STD</constant> accepts one or more | ||
| 70 | flags, being a write-only ioctl it does not return the actual new standard as | ||
| 71 | <constant>VIDIOC_G_STD</constant> does. When no flags are given or | ||
| 72 | the current input does not support the requested standard the driver | ||
| 73 | returns an &EINVAL;. When the standard set is ambiguous drivers may | ||
| 74 | return <errorcode>EINVAL</errorcode> or choose any of the requested | ||
| 75 | standards.</para> | ||
| 76 | </refsect1> | ||
| 77 | |||
| 78 | <refsect1> | ||
| 79 | &return-value; | ||
| 80 | |||
| 81 | <variablelist> | ||
| 82 | <varlistentry> | ||
| 83 | <term><errorcode>EINVAL</errorcode></term> | ||
| 84 | <listitem> | ||
| 85 | <para>This ioctl is not supported, or the | ||
| 86 | <constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para> | ||
| 87 | </listitem> | ||
| 88 | </varlistentry> | ||
| 89 | </variablelist> | ||
| 90 | </refsect1> | ||
| 91 | </refentry> | ||
| 92 | |||
| 93 | <!-- | ||
| 94 | Local Variables: | ||
| 95 | mode: sgml | ||
| 96 | sgml-parent-document: "v4l2.sgml" | ||
| 97 | indent-tabs-mode: nil | ||
| 98 | End: | ||
| 99 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/v4l/vidioc-g-tuner.xml new file mode 100644 index 000000000000..bd98c734c06b --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-tuner.xml | |||
| @@ -0,0 +1,535 @@ | |||
| 1 | <refentry id="vidioc-g-tuner"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_TUNER</refname> | ||
| 9 | <refname>VIDIOC_S_TUNER</refname> | ||
| 10 | <refpurpose>Get or set tuner attributes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_tuner | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_tuner | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query the attributes of a tuner applications initialize the | ||
| 63 | <structfield>index</structfield> field and zero out the | ||
| 64 | <structfield>reserved</structfield> array of a &v4l2-tuner; and call the | ||
| 65 | <constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this | ||
| 66 | structure. Drivers fill the rest of the structure or return an | ||
| 67 | &EINVAL; when the index is out of bounds. To enumerate all tuners | ||
| 68 | applications shall begin at index zero, incrementing by one until the | ||
| 69 | driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 70 | |||
| 71 | <para>Tuners have two writable properties, the audio mode and | ||
| 72 | the radio frequency. To change the audio mode, applications initialize | ||
| 73 | the <structfield>index</structfield>, | ||
| 74 | <structfield>audmode</structfield> and | ||
| 75 | <structfield>reserved</structfield> fields and call the | ||
| 76 | <constant>VIDIOC_S_TUNER</constant> ioctl. This will | ||
| 77 | <emphasis>not</emphasis> change the current tuner, which is determined | ||
| 78 | by the current video input. Drivers may choose a different audio mode | ||
| 79 | if the requested mode is invalid or unsupported. Since this is a | ||
| 80 | <!-- FIXME -->write-only ioctl, it does not return the actually | ||
| 81 | selected audio mode.</para> | ||
| 82 | |||
| 83 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | ||
| 84 | is available.</para> | ||
| 85 | |||
| 86 | <table pgwide="1" frame="none" id="v4l2-tuner"> | ||
| 87 | <title>struct <structname>v4l2_tuner</structname></title> | ||
| 88 | <tgroup cols="3"> | ||
| 89 | <colspec colname="c1" colwidth="1*" /> | ||
| 90 | <colspec colname="c2" colwidth="1*" /> | ||
| 91 | <colspec colname="c3" colwidth="1*" /> | ||
| 92 | <colspec colname="c4" colwidth="1*" /> | ||
| 93 | <spanspec spanname="hspan" namest="c3" nameend="c4" /> | ||
| 94 | <tbody valign="top"> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>index</structfield></entry> | ||
| 98 | <entry spanname="hspan">Identifies the tuner, set by the | ||
| 99 | application.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u8</entry> | ||
| 103 | <entry><structfield>name</structfield>[32]</entry> | ||
| 104 | <entry spanname="hspan"><para>Name of the tuner, a | ||
| 105 | NUL-terminated ASCII string. This information is intended for the | ||
| 106 | user.<!-- FIXME Video inputs already have a name, the purpose of this | ||
| 107 | field is not quite clear.--></para></entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>&v4l2-tuner-type;</entry> | ||
| 111 | <entry><structfield>type</structfield></entry> | ||
| 112 | <entry spanname="hspan">Type of the tuner, see <xref | ||
| 113 | linkend="v4l2-tuner-type" />.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry>__u32</entry> | ||
| 117 | <entry><structfield>capability</structfield></entry> | ||
| 118 | <entry spanname="hspan"><para>Tuner capability flags, see | ||
| 119 | <xref linkend="tuner-capability" />. Audio flags indicate the ability | ||
| 120 | to decode audio subprograms. They will <emphasis>not</emphasis> | ||
| 121 | change, for example with the current video standard.</para><para>When | ||
| 122 | the structure refers to a radio tuner only the | ||
| 123 | <constant>V4L2_TUNER_CAP_LOW</constant>, | ||
| 124 | <constant>V4L2_TUNER_CAP_STEREO</constant> and | ||
| 125 | <constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>__u32</entry> | ||
| 129 | <entry><structfield>rangelow</structfield></entry> | ||
| 130 | <entry spanname="hspan">The lowest tunable frequency in | ||
| 131 | units of 62.5 kHz, or if the <structfield>capability</structfield> | ||
| 132 | flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 133 | Hz.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>__u32</entry> | ||
| 137 | <entry><structfield>rangehigh</structfield></entry> | ||
| 138 | <entry spanname="hspan">The highest tunable frequency in | ||
| 139 | units of 62.5 kHz, or if the <structfield>capability</structfield> | ||
| 140 | flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 141 | Hz.</entry> | ||
| 142 | </row> | ||
| 143 | <row> | ||
| 144 | <entry>__u32</entry> | ||
| 145 | <entry><structfield>rxsubchans</structfield></entry> | ||
| 146 | <entry spanname="hspan"><para>Some tuners or audio | ||
| 147 | decoders can determine the received audio subprograms by analyzing | ||
| 148 | audio carriers, pilot tones or other indicators. To pass this | ||
| 149 | information drivers set flags defined in <xref | ||
| 150 | linkend="tuner-rxsubchans" /> in this field. For | ||
| 151 | example:</para></entry> | ||
| 152 | </row> | ||
| 153 | <row> | ||
| 154 | <entry></entry> | ||
| 155 | <entry></entry> | ||
| 156 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 157 | <entry>receiving mono audio</entry> | ||
| 158 | </row> | ||
| 159 | <row> | ||
| 160 | <entry></entry> | ||
| 161 | <entry></entry> | ||
| 162 | <entry><constant>STEREO | SAP</constant></entry> | ||
| 163 | <entry>receiving stereo audio and a secondary audio | ||
| 164 | program</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry></entry> | ||
| 168 | <entry></entry> | ||
| 169 | <entry><constant>MONO | STEREO</constant></entry> | ||
| 170 | <entry>receiving mono or stereo audio, the hardware cannot | ||
| 171 | distinguish</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry></entry> | ||
| 175 | <entry></entry> | ||
| 176 | <entry><constant>LANG1 | LANG2</constant></entry> | ||
| 177 | <entry>receiving bilingual audio</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry></entry> | ||
| 181 | <entry></entry> | ||
| 182 | <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry> | ||
| 183 | <entry>receiving mono, stereo or bilingual | ||
| 184 | audio</entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry></entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry spanname="hspan"><para>When the | ||
| 190 | <constant>V4L2_TUNER_CAP_STEREO</constant>, | ||
| 191 | <constant>_LANG1</constant>, <constant>_LANG2</constant> or | ||
| 192 | <constant>_SAP</constant> flag is cleared in the | ||
| 193 | <structfield>capability</structfield> field, the corresponding | ||
| 194 | <constant>V4L2_TUNER_SUB_</constant> flag must not be set | ||
| 195 | here.</para><para>This field is valid only if this is the tuner of the | ||
| 196 | current video input, or when the structure refers to a radio | ||
| 197 | tuner.</para></entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry>__u32</entry> | ||
| 201 | <entry><structfield>audmode</structfield></entry> | ||
| 202 | <entry spanname="hspan"><para>The selected audio mode, see | ||
| 203 | <xref linkend="tuner-audmode" /> for valid values. The audio mode does | ||
| 204 | not affect audio subprogram detection, and like a <link | ||
| 205 | linkend="control">control</link> it does not automatically change | ||
| 206 | unless the requested mode is invalid or unsupported. See <xref | ||
| 207 | linkend="tuner-matrix" /> for possible results when | ||
| 208 | the selected and received audio programs do not | ||
| 209 | match.</para><para>Currently this is the only field of struct | ||
| 210 | <structname>v4l2_tuner</structname> applications can | ||
| 211 | change.</para></entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry>__u32</entry> | ||
| 215 | <entry><structfield>signal</structfield></entry> | ||
| 216 | <entry spanname="hspan">The signal strength if known, ranging | ||
| 217 | from 0 to 65535. Higher values indicate a better signal.</entry> | ||
| 218 | </row> | ||
| 219 | <row> | ||
| 220 | <entry>__s32</entry> | ||
| 221 | <entry><structfield>afc</structfield></entry> | ||
| 222 | <entry spanname="hspan">Automatic frequency control: When the | ||
| 223 | <structfield>afc</structfield> value is negative, the frequency is too | ||
| 224 | low, when positive too high.<!-- FIXME need example what to do when it never | ||
| 225 | settles at zero, &ie; range is what? --></entry> | ||
| 226 | </row> | ||
| 227 | <row> | ||
| 228 | <entry>__u32</entry> | ||
| 229 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 230 | <entry spanname="hspan">Reserved for future extensions. Drivers and | ||
| 231 | applications must set the array to zero.</entry> | ||
| 232 | </row> | ||
| 233 | </tbody> | ||
| 234 | </tgroup> | ||
| 235 | </table> | ||
| 236 | |||
| 237 | <table pgwide="1" frame="none" id="v4l2-tuner-type"> | ||
| 238 | <title>enum v4l2_tuner_type</title> | ||
| 239 | <tgroup cols="3"> | ||
| 240 | &cs-def; | ||
| 241 | <tbody valign="top"> | ||
| 242 | <row> | ||
| 243 | <entry><constant>V4L2_TUNER_RADIO</constant></entry> | ||
| 244 | <entry>1</entry> | ||
| 245 | <entry></entry> | ||
| 246 | </row> | ||
| 247 | <row> | ||
| 248 | <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry> | ||
| 249 | <entry>2</entry> | ||
| 250 | <entry></entry> | ||
| 251 | </row> | ||
| 252 | </tbody> | ||
| 253 | </tgroup> | ||
| 254 | </table> | ||
| 255 | |||
| 256 | <table pgwide="1" frame="none" id="tuner-capability"> | ||
| 257 | <title>Tuner and Modulator Capability Flags</title> | ||
| 258 | <tgroup cols="3"> | ||
| 259 | &cs-def; | ||
| 260 | <tbody valign="top"> | ||
| 261 | <row> | ||
| 262 | <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry> | ||
| 263 | <entry>0x0001</entry> | ||
| 264 | <entry>When set, tuning frequencies are expressed in units of | ||
| 265 | 62.5 Hz, otherwise in units of 62.5 kHz.</entry> | ||
| 266 | </row> | ||
| 267 | <row> | ||
| 268 | <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry> | ||
| 269 | <entry>0x0002</entry> | ||
| 270 | <entry>This is a multi-standard tuner; the video standard | ||
| 271 | can or must be switched. (B/G PAL tuners for example are typically not | ||
| 272 | considered multi-standard because the video standard is automatically | ||
| 273 | determined from the frequency band.) The set of supported video | ||
| 274 | standards is available from the &v4l2-input; pointing to this tuner, | ||
| 275 | see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only | ||
| 276 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 277 | </row> | ||
| 278 | <row> | ||
| 279 | <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry> | ||
| 280 | <entry>0x0010</entry> | ||
| 281 | <entry>Stereo audio reception is supported.</entry> | ||
| 282 | </row> | ||
| 283 | <row> | ||
| 284 | <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry> | ||
| 285 | <entry>0x0040</entry> | ||
| 286 | <entry>Reception of the primary language of a bilingual | ||
| 287 | audio program is supported. Bilingual audio is a feature of | ||
| 288 | two-channel systems, transmitting the primary language monaural on the | ||
| 289 | main audio carrier and a secondary language monaural on a second | ||
| 290 | carrier. Only | ||
| 291 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 292 | </row> | ||
| 293 | <row> | ||
| 294 | <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry> | ||
| 295 | <entry>0x0020</entry> | ||
| 296 | <entry>Reception of the secondary language of a bilingual | ||
| 297 | audio program is supported. Only | ||
| 298 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 299 | </row> | ||
| 300 | <row> | ||
| 301 | <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry> | ||
| 302 | <entry>0x0020</entry> | ||
| 303 | <entry><para>Reception of a secondary audio program is | ||
| 304 | supported. This is a feature of the BTSC system which accompanies the | ||
| 305 | NTSC video standard. Two audio carriers are available for mono or | ||
| 306 | stereo transmissions of a primary language, and an independent third | ||
| 307 | carrier for a monaural secondary language. Only | ||
| 308 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the | ||
| 309 | <constant>V4L2_TUNER_CAP_LANG2</constant> and | ||
| 310 | <constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms. | ||
| 311 | <constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner | ||
| 312 | supports the <constant>V4L2_STD_NTSC_M</constant> video | ||
| 313 | standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> | ||
| 314 | </row> | ||
| 315 | <row> | ||
| 316 | <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry> | ||
| 317 | <entry>0x0080</entry> | ||
| 318 | <entry>RDS capture is supported. This capability is only valid for | ||
| 319 | radio tuners.</entry> | ||
| 320 | </row> | ||
| 321 | </tbody> | ||
| 322 | </tgroup> | ||
| 323 | </table> | ||
| 324 | |||
| 325 | <table pgwide="1" frame="none" id="tuner-rxsubchans"> | ||
| 326 | <title>Tuner Audio Reception Flags</title> | ||
| 327 | <tgroup cols="3"> | ||
| 328 | &cs-def; | ||
| 329 | <tbody valign="top"> | ||
| 330 | <row> | ||
| 331 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 332 | <entry>0x0001</entry> | ||
| 333 | <entry>The tuner receives a mono audio signal.</entry> | ||
| 334 | </row> | ||
| 335 | <row> | ||
| 336 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | ||
| 337 | <entry>0x0002</entry> | ||
| 338 | <entry>The tuner receives a stereo audio signal.</entry> | ||
| 339 | </row> | ||
| 340 | <row> | ||
| 341 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | ||
| 342 | <entry>0x0008</entry> | ||
| 343 | <entry>The tuner receives the primary language of a | ||
| 344 | bilingual audio signal. Drivers must clear this flag when the current | ||
| 345 | video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> | ||
| 346 | </row> | ||
| 347 | <row> | ||
| 348 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | ||
| 349 | <entry>0x0004</entry> | ||
| 350 | <entry>The tuner receives the secondary language of a | ||
| 351 | bilingual audio signal (or a second audio program).</entry> | ||
| 352 | </row> | ||
| 353 | <row> | ||
| 354 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | ||
| 355 | <entry>0x0004</entry> | ||
| 356 | <entry>The tuner receives a Second Audio Program. Note the | ||
| 357 | <constant>V4L2_TUNER_SUB_LANG2</constant> and | ||
| 358 | <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The | ||
| 359 | <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the | ||
| 360 | current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> | ||
| 361 | </row> | ||
| 362 | <row> | ||
| 363 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | ||
| 364 | <entry>0x0010</entry> | ||
| 365 | <entry>The tuner receives an RDS channel.</entry> | ||
| 366 | </row> | ||
| 367 | </tbody> | ||
| 368 | </tgroup> | ||
| 369 | </table> | ||
| 370 | |||
| 371 | <table pgwide="1" frame="none" id="tuner-audmode"> | ||
| 372 | <title>Tuner Audio Modes</title> | ||
| 373 | <tgroup cols="3"> | ||
| 374 | &cs-def; | ||
| 375 | <tbody valign="top"> | ||
| 376 | <row> | ||
| 377 | <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry> | ||
| 378 | <entry>0</entry> | ||
| 379 | <entry>Play mono audio. When the tuner receives a stereo | ||
| 380 | signal this a down-mix of the left and right channel. When the tuner | ||
| 381 | receives a bilingual or SAP signal this mode selects the primary | ||
| 382 | language.</entry> | ||
| 383 | </row> | ||
| 384 | <row> | ||
| 385 | <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry> | ||
| 386 | <entry>1</entry> | ||
| 387 | <entry><para>Play stereo audio. When the tuner receives | ||
| 388 | bilingual audio it may play different languages on the left and right | ||
| 389 | channel or the primary language is played on both channels.</para><para>Playing | ||
| 390 | different languages in this mode is | ||
| 391 | deprecated. New drivers should do this only in | ||
| 392 | <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner | ||
| 393 | receives no stereo signal or does not support stereo reception the | ||
| 394 | driver shall fall back to <constant>MODE_MONO</constant>.</para></entry> | ||
| 395 | </row> | ||
| 396 | <row> | ||
| 397 | <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry> | ||
| 398 | <entry>3</entry> | ||
| 399 | <entry>Play the primary language, mono or stereo. Only | ||
| 400 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 401 | mode.</entry> | ||
| 402 | </row> | ||
| 403 | <row> | ||
| 404 | <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry> | ||
| 405 | <entry>2</entry> | ||
| 406 | <entry>Play the secondary language, mono. When the tuner | ||
| 407 | receives no bilingual audio or SAP, or their reception is not | ||
| 408 | supported the driver shall fall back to mono or stereo mode. Only | ||
| 409 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 410 | mode.</entry> | ||
| 411 | </row> | ||
| 412 | <row> | ||
| 413 | <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry> | ||
| 414 | <entry>2</entry> | ||
| 415 | <entry>Play the Second Audio Program. When the tuner | ||
| 416 | receives no bilingual audio or SAP, or their reception is not | ||
| 417 | supported the driver shall fall back to mono or stereo mode. Only | ||
| 418 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode. | ||
| 419 | Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and | ||
| 420 | <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry> | ||
| 421 | </row> | ||
| 422 | <row> | ||
| 423 | <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry> | ||
| 424 | <entry>4</entry> | ||
| 425 | <entry>Play the primary language on the left channel, the | ||
| 426 | secondary language on the right channel. When the tuner receives no | ||
| 427 | bilingual audio or SAP, it shall fall back to | ||
| 428 | <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>. | ||
| 429 | Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 430 | mode.</entry> | ||
| 431 | </row> | ||
| 432 | </tbody> | ||
| 433 | </tgroup> | ||
| 434 | </table> | ||
| 435 | |||
| 436 | <table pgwide="1" frame="all" id="tuner-matrix"> | ||
| 437 | <title>Tuner Audio Matrix</title> | ||
| 438 | <tgroup cols="6" align="center"> | ||
| 439 | <colspec align="left" /> | ||
| 440 | <colspec colname="c2" colwidth="1*" /> | ||
| 441 | <colspec colwidth="1*" /> | ||
| 442 | <colspec colwidth="1*" /> | ||
| 443 | <colspec colnum="6" colname="c6" colwidth="1*" /> | ||
| 444 | <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" /> | ||
| 445 | <thead> | ||
| 446 | <row> | ||
| 447 | <entry></entry> | ||
| 448 | <entry spanname="hspan">Selected | ||
| 449 | <constant>V4L2_TUNER_MODE_</constant></entry> | ||
| 450 | </row> | ||
| 451 | <row> | ||
| 452 | <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry> | ||
| 453 | <entry><constant>MONO</constant></entry> | ||
| 454 | <entry><constant>STEREO</constant></entry> | ||
| 455 | <entry><constant>LANG1</constant></entry> | ||
| 456 | <entry><constant>LANG2 = SAP</constant></entry> | ||
| 457 | <entry><constant>LANG1_LANG2</constant><footnote><para>This | ||
| 458 | mode has been added in Linux 2.6.17 and may not be supported by older | ||
| 459 | drivers.</para></footnote></entry> | ||
| 460 | </row> | ||
| 461 | </thead> | ||
| 462 | <tbody valign="top"> | ||
| 463 | <row> | ||
| 464 | <entry><constant>MONO</constant></entry> | ||
| 465 | <entry>Mono</entry> | ||
| 466 | <entry>Mono/Mono</entry> | ||
| 467 | <entry>Mono</entry> | ||
| 468 | <entry>Mono</entry> | ||
| 469 | <entry>Mono/Mono</entry> | ||
| 470 | </row> | ||
| 471 | <row> | ||
| 472 | <entry><constant>MONO | SAP</constant></entry> | ||
| 473 | <entry>Mono</entry> | ||
| 474 | <entry>Mono/Mono</entry> | ||
| 475 | <entry>Mono</entry> | ||
| 476 | <entry>SAP</entry> | ||
| 477 | <entry>Mono/SAP (preferred) or Mono/Mono</entry> | ||
| 478 | </row> | ||
| 479 | <row> | ||
| 480 | <entry><constant>STEREO</constant></entry> | ||
| 481 | <entry>L+R</entry> | ||
| 482 | <entry>L/R</entry> | ||
| 483 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 484 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 485 | <entry>L/R (preferred) or L+R/L+R</entry> | ||
| 486 | </row> | ||
| 487 | <row> | ||
| 488 | <entry><constant>STEREO | SAP</constant></entry> | ||
| 489 | <entry>L+R</entry> | ||
| 490 | <entry>L/R</entry> | ||
| 491 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 492 | <entry>SAP</entry> | ||
| 493 | <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry> | ||
| 494 | </row> | ||
| 495 | <row> | ||
| 496 | <entry><constant>LANG1 | LANG2</constant></entry> | ||
| 497 | <entry>Language 1</entry> | ||
| 498 | <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of | ||
| 499 | both languages in <constant>MODE_STEREO</constant> is deprecated. In | ||
| 500 | the future drivers should produce only the primary language in this | ||
| 501 | mode. Applications should request | ||
| 502 | <constant>MODE_LANG1_LANG2</constant> to record both languages or a | ||
| 503 | stereo signal.</para></footnote>) or | ||
| 504 | Lang1/Lang1</entry> | ||
| 505 | <entry>Language 1</entry> | ||
| 506 | <entry>Language 2</entry> | ||
| 507 | <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry> | ||
| 508 | </row> | ||
| 509 | </tbody> | ||
| 510 | </tgroup> | ||
| 511 | </table> | ||
| 512 | </refsect1> | ||
| 513 | |||
| 514 | <refsect1> | ||
| 515 | &return-value; | ||
| 516 | |||
| 517 | <variablelist> | ||
| 518 | <varlistentry> | ||
| 519 | <term><errorcode>EINVAL</errorcode></term> | ||
| 520 | <listitem> | ||
| 521 | <para>The &v4l2-tuner; <structfield>index</structfield> is | ||
| 522 | out of bounds.</para> | ||
| 523 | </listitem> | ||
| 524 | </varlistentry> | ||
| 525 | </variablelist> | ||
| 526 | </refsect1> | ||
| 527 | </refentry> | ||
| 528 | |||
| 529 | <!-- | ||
| 530 | Local Variables: | ||
| 531 | mode: sgml | ||
| 532 | sgml-parent-document: "v4l2.sgml" | ||
| 533 | indent-tabs-mode: nil | ||
| 534 | End: | ||
| 535 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-log-status.xml b/Documentation/DocBook/v4l/vidioc-log-status.xml new file mode 100644 index 000000000000..2634b7c88b58 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-log-status.xml | |||
| @@ -0,0 +1,58 @@ | |||
| 1 | <refentry id="vidioc-log-status"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_LOG_STATUS</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_LOG_STATUS</refname> | ||
| 9 | <refpurpose>Log driver status information</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | </funcprototype> | ||
| 19 | </funcsynopsis> | ||
| 20 | </refsynopsisdiv> | ||
| 21 | |||
| 22 | <refsect1> | ||
| 23 | <title>Description</title> | ||
| 24 | |||
| 25 | <para>As the video/audio devices become more complicated it | ||
| 26 | becomes harder to debug problems. When this ioctl is called the driver | ||
| 27 | will output the current device status to the kernel log. This is | ||
| 28 | particular useful when dealing with problems like no sound, no video | ||
| 29 | and incorrectly tuned channels. Also many modern devices autodetect | ||
| 30 | video and audio standards and this ioctl will report what the device | ||
| 31 | thinks what the standard is. Mismatches may give an indication where | ||
| 32 | the problem is.</para> | ||
| 33 | |||
| 34 | <para>This ioctl is optional and not all drivers support it. It | ||
| 35 | was introduced in Linux 2.6.15.</para> | ||
| 36 | </refsect1> | ||
| 37 | |||
| 38 | <refsect1> | ||
| 39 | &return-value; | ||
| 40 | |||
| 41 | <variablelist> | ||
| 42 | <varlistentry> | ||
| 43 | <term><errorcode>EINVAL</errorcode></term> | ||
| 44 | <listitem> | ||
| 45 | <para>The driver does not support this ioctl.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | </refentry> | ||
| 51 | |||
| 52 | <!-- | ||
| 53 | Local Variables: | ||
| 54 | mode: sgml | ||
| 55 | sgml-parent-document: "v4l2.sgml" | ||
| 56 | indent-tabs-mode: nil | ||
| 57 | End: | ||
| 58 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-overlay.xml b/Documentation/DocBook/v4l/vidioc-overlay.xml new file mode 100644 index 000000000000..1036c582cc15 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-overlay.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="vidioc-overlay"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_OVERLAY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_OVERLAY</refname> | ||
| 9 | <refpurpose>Start or stop video overlay</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>const int *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_OVERLAY</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is part of the <link linkend="overlay">video | ||
| 52 | overlay</link> I/O method. Applications call | ||
| 53 | <constant>VIDIOC_OVERLAY</constant> to start or stop the | ||
| 54 | overlay. It takes a pointer to an integer which must be set to | ||
| 55 | zero by the application to stop overlay, to one to start.</para> | ||
| 56 | |||
| 57 | <para>Drivers do not support &VIDIOC-STREAMON; or | ||
| 58 | &VIDIOC-STREAMOFF; with <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> | ||
| 59 | </refsect1> | ||
| 60 | |||
| 61 | <refsect1> | ||
| 62 | &return-value; | ||
| 63 | |||
| 64 | <variablelist> | ||
| 65 | <varlistentry> | ||
| 66 | <term><errorcode>EINVAL</errorcode></term> | ||
| 67 | <listitem> | ||
| 68 | <para>Video overlay is not supported, or the | ||
| 69 | parameters have not been set up. See <xref | ||
| 70 | linkend="overlay" /> for the necessary steps.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml new file mode 100644 index 000000000000..187081778154 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml | |||
| @@ -0,0 +1,168 @@ | |||
| 1 | <refentry id="vidioc-qbuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QBUF</refname> | ||
| 9 | <refname>VIDIOC_DQBUF</refname> | ||
| 10 | <refpurpose>Exchange a buffer with the driver</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_QBUF, VIDIOC_DQBUF</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Applications call the <constant>VIDIOC_QBUF</constant> ioctl | ||
| 53 | to enqueue an empty (capturing) or filled (output) buffer in the | ||
| 54 | driver's incoming queue. The semantics depend on the selected I/O | ||
| 55 | method.</para> | ||
| 56 | |||
| 57 | <para>To enqueue a <link linkend="mmap">memory mapped</link> | ||
| 58 | buffer applications set the <structfield>type</structfield> field of a | ||
| 59 | &v4l2-buffer; to the same buffer type as previously &v4l2-format; | ||
| 60 | <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 61 | <structfield>type</structfield>, the <structfield>memory</structfield> | ||
| 62 | field to <constant>V4L2_MEMORY_MMAP</constant> and the | ||
| 63 | <structfield>index</structfield> field. Valid index numbers range from | ||
| 64 | zero to the number of buffers allocated with &VIDIOC-REQBUFS; | ||
| 65 | (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The | ||
| 66 | contents of the struct <structname>v4l2_buffer</structname> returned | ||
| 67 | by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is | ||
| 68 | intended for output (<structfield>type</structfield> is | ||
| 69 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or | ||
| 70 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also | ||
| 71 | initialize the <structfield>bytesused</structfield>, | ||
| 72 | <structfield>field</structfield> and | ||
| 73 | <structfield>timestamp</structfield> fields. See <xref | ||
| 74 | linkend="buffer" /> for details. When | ||
| 75 | <constant>VIDIOC_QBUF</constant> is called with a pointer to this | ||
| 76 | structure the driver sets the | ||
| 77 | <constant>V4L2_BUF_FLAG_MAPPED</constant> and | ||
| 78 | <constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the | ||
| 79 | <constant>V4L2_BUF_FLAG_DONE</constant> flag in the | ||
| 80 | <structfield>flags</structfield> field, or it returns an | ||
| 81 | &EINVAL;.</para> | ||
| 82 | |||
| 83 | <para>To enqueue a <link linkend="userp">user pointer</link> | ||
| 84 | buffer applications set the <structfield>type</structfield> field of a | ||
| 85 | &v4l2-buffer; to the same buffer type as previously &v4l2-format; | ||
| 86 | <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 87 | <structfield>type</structfield>, the <structfield>memory</structfield> | ||
| 88 | field to <constant>V4L2_MEMORY_USERPTR</constant> and the | ||
| 89 | <structfield>m.userptr</structfield> field to the address of the | ||
| 90 | buffer and <structfield>length</structfield> to its size. When the | ||
| 91 | buffer is intended for output additional fields must be set as above. | ||
| 92 | When <constant>VIDIOC_QBUF</constant> is called with a pointer to this | ||
| 93 | structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> | ||
| 94 | flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and | ||
| 95 | <constant>V4L2_BUF_FLAG_DONE</constant> flags in the | ||
| 96 | <structfield>flags</structfield> field, or it returns an error code. | ||
| 97 | This ioctl locks the memory pages of the buffer in physical memory, | ||
| 98 | they cannot be swapped out to disk. Buffers remain locked until | ||
| 99 | dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are | ||
| 100 | called, or until the device is closed.</para> | ||
| 101 | |||
| 102 | <para>Applications call the <constant>VIDIOC_DQBUF</constant> | ||
| 103 | ioctl to dequeue a filled (capturing) or displayed (output) buffer | ||
| 104 | from the driver's outgoing queue. They just set the | ||
| 105 | <structfield>type</structfield> and <structfield>memory</structfield> | ||
| 106 | fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> | ||
| 107 | is called with a pointer to this structure the driver fills the | ||
| 108 | remaining fields or returns an error code.</para> | ||
| 109 | |||
| 110 | <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no | ||
| 111 | buffer is in the outgoing queue. When the | ||
| 112 | <constant>O_NONBLOCK</constant> flag was given to the &func-open; | ||
| 113 | function, <constant>VIDIOC_DQBUF</constant> returns immediately | ||
| 114 | with an &EAGAIN; when no buffer is available.</para> | ||
| 115 | |||
| 116 | <para>The <structname>v4l2_buffer</structname> structure is | ||
| 117 | specified in <xref linkend="buffer" />.</para> | ||
| 118 | </refsect1> | ||
| 119 | |||
| 120 | <refsect1> | ||
| 121 | &return-value; | ||
| 122 | |||
| 123 | <variablelist> | ||
| 124 | <varlistentry> | ||
| 125 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 126 | <listitem> | ||
| 127 | <para>Non-blocking I/O has been selected using | ||
| 128 | <constant>O_NONBLOCK</constant> and no buffer was in the outgoing | ||
| 129 | queue.</para> | ||
| 130 | </listitem> | ||
| 131 | </varlistentry> | ||
| 132 | <varlistentry> | ||
| 133 | <term><errorcode>EINVAL</errorcode></term> | ||
| 134 | <listitem> | ||
| 135 | <para>The buffer <structfield>type</structfield> is not | ||
| 136 | supported, or the <structfield>index</structfield> is out of bounds, | ||
| 137 | or no buffers have been allocated yet, or the | ||
| 138 | <structfield>userptr</structfield> or | ||
| 139 | <structfield>length</structfield> are invalid.</para> | ||
| 140 | </listitem> | ||
| 141 | </varlistentry> | ||
| 142 | <varlistentry> | ||
| 143 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 144 | <listitem> | ||
| 145 | <para>Not enough physical or virtual memory was available to | ||
| 146 | enqueue a user pointer buffer.</para> | ||
| 147 | </listitem> | ||
| 148 | </varlistentry> | ||
| 149 | <varlistentry> | ||
| 150 | <term><errorcode>EIO</errorcode></term> | ||
| 151 | <listitem> | ||
| 152 | <para><constant>VIDIOC_DQBUF</constant> failed due to an | ||
| 153 | internal error. Can also indicate temporary problems like signal | ||
| 154 | loss. Note the driver might dequeue an (empty) buffer despite | ||
| 155 | returning an error, or even stop capturing.</para> | ||
| 156 | </listitem> | ||
| 157 | </varlistentry> | ||
| 158 | </variablelist> | ||
| 159 | </refsect1> | ||
| 160 | </refentry> | ||
| 161 | |||
| 162 | <!-- | ||
| 163 | Local Variables: | ||
| 164 | mode: sgml | ||
| 165 | sgml-parent-document: "v4l2.sgml" | ||
| 166 | indent-tabs-mode: nil | ||
| 167 | End: | ||
| 168 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml new file mode 100644 index 000000000000..d834993e6191 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml | |||
| @@ -0,0 +1,103 @@ | |||
| 1 | <refentry id="vidioc-querybuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYBUF</refname> | ||
| 9 | <refpurpose>Query the status of a buffer</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_QUERYBUF</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is part of the <link linkend="mmap">memory | ||
| 52 | mapping</link> I/O method. It can be used to query the status of a | ||
| 53 | buffer at any time after buffers have been allocated with the | ||
| 54 | &VIDIOC-REQBUFS; ioctl.</para> | ||
| 55 | |||
| 56 | <para>Applications set the <structfield>type</structfield> field | ||
| 57 | of a &v4l2-buffer; to the same buffer type as previously | ||
| 58 | &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 59 | <structfield>type</structfield>, and the <structfield>index</structfield> | ||
| 60 | field. Valid index numbers range from zero | ||
| 61 | to the number of buffers allocated with &VIDIOC-REQBUFS; | ||
| 62 | (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. | ||
| 63 | After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to | ||
| 64 | this structure drivers return an error code or fill the rest of | ||
| 65 | the structure.</para> | ||
| 66 | |||
| 67 | <para>In the <structfield>flags</structfield> field the | ||
| 68 | <constant>V4L2_BUF_FLAG_MAPPED</constant>, | ||
| 69 | <constant>V4L2_BUF_FLAG_QUEUED</constant> and | ||
| 70 | <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The | ||
| 71 | <structfield>memory</structfield> field will be set to | ||
| 72 | <constant>V4L2_MEMORY_MMAP</constant>, the <structfield>m.offset</structfield> | ||
| 73 | contains the offset of the buffer from the start of the device memory, | ||
| 74 | the <structfield>length</structfield> field its size. The driver may | ||
| 75 | or may not set the remaining fields and flags, they are meaningless in | ||
| 76 | this context.</para> | ||
| 77 | |||
| 78 | <para>The <structname>v4l2_buffer</structname> structure is | ||
| 79 | specified in <xref linkend="buffer" />.</para> | ||
| 80 | </refsect1> | ||
| 81 | |||
| 82 | <refsect1> | ||
| 83 | &return-value; | ||
| 84 | |||
| 85 | <variablelist> | ||
| 86 | <varlistentry> | ||
| 87 | <term><errorcode>EINVAL</errorcode></term> | ||
| 88 | <listitem> | ||
| 89 | <para>The buffer <structfield>type</structfield> is not | ||
| 90 | supported, or the <structfield>index</structfield> is out of bounds.</para> | ||
| 91 | </listitem> | ||
| 92 | </varlistentry> | ||
| 93 | </variablelist> | ||
| 94 | </refsect1> | ||
| 95 | </refentry> | ||
| 96 | |||
| 97 | <!-- | ||
| 98 | Local Variables: | ||
| 99 | mode: sgml | ||
| 100 | sgml-parent-document: "v4l2.sgml" | ||
| 101 | indent-tabs-mode: nil | ||
| 102 | End: | ||
| 103 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml new file mode 100644 index 000000000000..6ab7e25b31b6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querycap.xml | |||
| @@ -0,0 +1,284 @@ | |||
| 1 | <refentry id="vidioc-querycap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYCAP</refname> | ||
| 9 | <refpurpose>Query device capabilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_QUERYCAP</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>All V4L2 devices support the | ||
| 52 | <constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify | ||
| 53 | kernel devices compatible with this specification and to obtain | ||
| 54 | information about driver and hardware capabilities. The ioctl takes a | ||
| 55 | pointer to a &v4l2-capability; which is filled by the driver. When the | ||
| 56 | driver is not compatible with this specification the ioctl returns an | ||
| 57 | &EINVAL;.</para> | ||
| 58 | |||
| 59 | <table pgwide="1" frame="none" id="v4l2-capability"> | ||
| 60 | <title>struct <structname>v4l2_capability</structname></title> | ||
| 61 | <tgroup cols="3"> | ||
| 62 | &cs-str; | ||
| 63 | <tbody valign="top"> | ||
| 64 | <row> | ||
| 65 | <entry>__u8</entry> | ||
| 66 | <entry><structfield>driver</structfield>[16]</entry> | ||
| 67 | <entry><para>Name of the driver, a unique NUL-terminated | ||
| 68 | ASCII string. For example: "bttv". Driver specific applications can | ||
| 69 | use this information to verify the driver identity. It is also useful | ||
| 70 | to work around known bugs, or to identify drivers in error reports. | ||
| 71 | The driver version is stored in the <structfield>version</structfield> | ||
| 72 | field.</para><para>Storing strings in fixed sized arrays is bad | ||
| 73 | practice but unavoidable here. Drivers and applications should take | ||
| 74 | precautions to never read or write beyond the end of the array and to | ||
| 75 | make sure the strings are properly NUL-terminated.</para></entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>__u8</entry> | ||
| 79 | <entry><structfield>card</structfield>[32]</entry> | ||
| 80 | <entry>Name of the device, a NUL-terminated ASCII string. | ||
| 81 | For example: "Yoyodyne TV/FM". One driver may support different brands | ||
| 82 | or models of video hardware. This information is intended for users, | ||
| 83 | for example in a menu of available devices. Since multiple TV cards of | ||
| 84 | the same brand may be installed which are supported by the same | ||
| 85 | driver, this name should be combined with the character device file | ||
| 86 | name (⪚ <filename>/dev/video2</filename>) or the | ||
| 87 | <structfield>bus_info</structfield> string to avoid | ||
| 88 | ambiguities.</entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry>__u8</entry> | ||
| 92 | <entry><structfield>bus_info</structfield>[32]</entry> | ||
| 93 | <entry>Location of the device in the system, a | ||
| 94 | NUL-terminated ASCII string. For example: "PCI Slot 4". This | ||
| 95 | information is intended for users, to distinguish multiple | ||
| 96 | identical devices. If no such information is available the field may | ||
| 97 | simply count the devices controlled by the driver, or contain the | ||
| 98 | empty string (<structfield>bus_info</structfield>[0] = 0).<!-- XXX pci_dev->slot_name example --></entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>version</structfield></entry> | ||
| 103 | <entry><para>Version number of the driver. Together with | ||
| 104 | the <structfield>driver</structfield> field this identifies a | ||
| 105 | particular driver. The version number is formatted using the | ||
| 106 | <constant>KERNEL_VERSION()</constant> macro:</para></entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry spanname="hspan"><para> | ||
| 110 | <programlisting> | ||
| 111 | #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) | ||
| 112 | |||
| 113 | __u32 version = KERNEL_VERSION(0, 8, 1); | ||
| 114 | |||
| 115 | printf ("Version: %u.%u.%u\n", | ||
| 116 | (version >> 16) & 0xFF, | ||
| 117 | (version >> 8) & 0xFF, | ||
| 118 | version & 0xFF); | ||
| 119 | </programlisting></para></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>__u32</entry> | ||
| 123 | <entry><structfield>capabilities</structfield></entry> | ||
| 124 | <entry>Device capabilities, see <xref | ||
| 125 | linkend="device-capabilities" />.</entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>__u32</entry> | ||
| 129 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 130 | <entry>Reserved for future extensions. Drivers must set | ||
| 131 | this array to zero.</entry> | ||
| 132 | </row> | ||
| 133 | </tbody> | ||
| 134 | </tgroup> | ||
| 135 | </table> | ||
| 136 | |||
| 137 | <table pgwide="1" frame="none" id="device-capabilities"> | ||
| 138 | <title>Device Capabilities Flags</title> | ||
| 139 | <tgroup cols="3"> | ||
| 140 | &cs-def; | ||
| 141 | <tbody valign="top"> | ||
| 142 | <row> | ||
| 143 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> | ||
| 144 | <entry>0x00000001</entry> | ||
| 145 | <entry>The device supports the <link | ||
| 146 | linkend="capture">Video Capture</link> interface.</entry> | ||
| 147 | </row> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> | ||
| 150 | <entry>0x00000002</entry> | ||
| 151 | <entry>The device supports the <link | ||
| 152 | linkend="output">Video Output</link> interface.</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> | ||
| 156 | <entry>0x00000004</entry> | ||
| 157 | <entry>The device supports the <link | ||
| 158 | linkend="overlay">Video Overlay</link> interface. A video overlay device | ||
| 159 | typically stores captured images directly in the video memory of a | ||
| 160 | graphics card, with hardware clipping and scaling.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> | ||
| 164 | <entry>0x00000010</entry> | ||
| 165 | <entry>The device supports the <link linkend="raw-vbi">Raw | ||
| 166 | VBI Capture</link> interface, providing Teletext and Closed Caption | ||
| 167 | data.</entry> | ||
| 168 | </row> | ||
| 169 | <row> | ||
| 170 | <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry> | ||
| 171 | <entry>0x00000020</entry> | ||
| 172 | <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry> | ||
| 173 | </row> | ||
| 174 | <row> | ||
| 175 | <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry> | ||
| 176 | <entry>0x00000040</entry> | ||
| 177 | <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry> | ||
| 181 | <entry>0x00000080</entry> | ||
| 182 | <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> | ||
| 186 | <entry>0x00000100</entry> | ||
| 187 | <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry> | ||
| 188 | </row> | ||
| 189 | <row> | ||
| 190 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> | ||
| 191 | <entry>0x00000200</entry> | ||
| 192 | <entry>The device supports the <link linkend="osd">Video | ||
| 193 | Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video | ||
| 194 | Overlay</wordasword> interface, this is a secondary function of video | ||
| 195 | output devices and overlays an image onto an outgoing video signal. | ||
| 196 | When the driver sets this flag, it must clear the | ||
| 197 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice | ||
| 198 | versa.<footnote><para>The &v4l2-framebuffer; lacks an | ||
| 199 | &v4l2-buf-type; field, therefore the type of overlay is implied by the | ||
| 200 | driver capabilities.</para></footnote></entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry> | ||
| 204 | <entry>0x00000400</entry> | ||
| 205 | <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for | ||
| 206 | hardware frequency seeking.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_CAP_TUNER</constant></entry> | ||
| 210 | <entry>0x00010000</entry> | ||
| 211 | <entry>The device has some sort of tuner to | ||
| 212 | receive RF-modulated video signals. For more information about | ||
| 213 | tuner programming see | ||
| 214 | <xref linkend="tuner" />.</entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry><constant>V4L2_CAP_AUDIO</constant></entry> | ||
| 218 | <entry>0x00020000</entry> | ||
| 219 | <entry>The device has audio inputs or outputs. It may or | ||
| 220 | may not support audio recording or playback, in PCM or compressed | ||
| 221 | formats. PCM audio support must be implemented as ALSA or OSS | ||
| 222 | interface. For more information on audio inputs and outputs see <xref | ||
| 223 | linkend="audio" />.</entry> | ||
| 224 | </row> | ||
| 225 | <row> | ||
| 226 | <entry><constant>V4L2_CAP_RADIO</constant></entry> | ||
| 227 | <entry>0x00040000</entry> | ||
| 228 | <entry>This is a radio receiver.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_CAP_MODULATOR</constant></entry> | ||
| 232 | <entry>0x00080000</entry> | ||
| 233 | <entry>The device has some sort of modulator to | ||
| 234 | emit RF-modulated video/audio signals. For more information about | ||
| 235 | modulator programming see | ||
| 236 | <xref linkend="tuner" />.</entry> | ||
| 237 | </row> | ||
| 238 | <row> | ||
| 239 | <entry><constant>V4L2_CAP_READWRITE</constant></entry> | ||
| 240 | <entry>0x01000000</entry> | ||
| 241 | <entry>The device supports the <link | ||
| 242 | linkend="rw">read()</link> and/or <link linkend="rw">write()</link> | ||
| 243 | I/O methods.</entry> | ||
| 244 | </row> | ||
| 245 | <row> | ||
| 246 | <entry><constant>V4L2_CAP_ASYNCIO</constant></entry> | ||
| 247 | <entry>0x02000000</entry> | ||
| 248 | <entry>The device supports the <link | ||
| 249 | linkend="async">asynchronous</link> I/O methods.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_CAP_STREAMING</constant></entry> | ||
| 253 | <entry>0x04000000</entry> | ||
| 254 | <entry>The device supports the <link | ||
| 255 | linkend="mmap">streaming</link> I/O method.</entry> | ||
| 256 | </row> | ||
| 257 | </tbody> | ||
| 258 | </tgroup> | ||
| 259 | </table> | ||
| 260 | </refsect1> | ||
| 261 | |||
| 262 | <refsect1> | ||
| 263 | &return-value; | ||
| 264 | |||
| 265 | <variablelist> | ||
| 266 | <varlistentry> | ||
| 267 | <term><errorcode>EINVAL</errorcode></term> | ||
| 268 | <listitem> | ||
| 269 | <para>The device is not compatible with this | ||
| 270 | specification.</para> | ||
| 271 | </listitem> | ||
| 272 | </varlistentry> | ||
| 273 | </variablelist> | ||
| 274 | </refsect1> | ||
| 275 | </refentry> | ||
| 276 | |||
| 277 | <!-- | ||
| 278 | Local Variables: | ||
| 279 | mode: sgml | ||
| 280 | sgml-parent-document: "v4l2.sgml" | ||
| 281 | indent-tabs-mode: nil | ||
| 282 | End: | ||
| 283 | --> | ||
| 284 | |||
diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml new file mode 100644 index 000000000000..4876ff1a1a04 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml | |||
| @@ -0,0 +1,428 @@ | |||
| 1 | <refentry id="vidioc-queryctrl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYCTRL</refname> | ||
| 9 | <refname>VIDIOC_QUERYMENU</refname> | ||
| 10 | <refpurpose>Enumerate controls and menu control items</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the attributes of a control applications set the | ||
| 61 | <structfield>id</structfield> field of a &v4l2-queryctrl; and call the | ||
| 62 | <constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this | ||
| 63 | structure. The driver fills the rest of the structure or returns an | ||
| 64 | &EINVAL; when the <structfield>id</structfield> is invalid.</para> | ||
| 65 | |||
| 66 | <para>It is possible to enumerate controls by calling | ||
| 67 | <constant>VIDIOC_QUERYCTRL</constant> with successive | ||
| 68 | <structfield>id</structfield> values starting from | ||
| 69 | <constant>V4L2_CID_BASE</constant> up to and exclusive | ||
| 70 | <constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return | ||
| 71 | <errorcode>EINVAL</errorcode> if a control in this range is not | ||
| 72 | supported. Further applications can enumerate private controls, which | ||
| 73 | are not defined in this specification, by starting at | ||
| 74 | <constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing | ||
| 75 | <structfield>id</structfield> until the driver returns | ||
| 76 | <errorcode>EINVAL</errorcode>.</para> | ||
| 77 | |||
| 78 | <para>In both cases, when the driver sets the | ||
| 79 | <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the | ||
| 80 | <structfield>flags</structfield> field this control is permanently | ||
| 81 | disabled and should be ignored by the application.<footnote> | ||
| 82 | <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was | ||
| 83 | intended for two purposes: Drivers can skip predefined controls not | ||
| 84 | supported by the hardware (although returning EINVAL would do as | ||
| 85 | well), or disable predefined and private controls after hardware | ||
| 86 | detection without the trouble of reordering control arrays and indices | ||
| 87 | (EINVAL cannot be used to skip private controls because it would | ||
| 88 | prematurely end the enumeration).</para></footnote></para> | ||
| 89 | |||
| 90 | <para>When the application ORs <structfield>id</structfield> with | ||
| 91 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the | ||
| 92 | next supported control, or <errorcode>EINVAL</errorcode> if there is | ||
| 93 | none. Drivers which do not support this flag yet always return | ||
| 94 | <errorcode>EINVAL</errorcode>.</para> | ||
| 95 | |||
| 96 | <para>Additional information is required for menu controls: the | ||
| 97 | names of the menu items. To query them applications set the | ||
| 98 | <structfield>id</structfield> and <structfield>index</structfield> | ||
| 99 | fields of &v4l2-querymenu; and call the | ||
| 100 | <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this | ||
| 101 | structure. The driver fills the rest of the structure or returns an | ||
| 102 | &EINVAL; when the <structfield>id</structfield> or | ||
| 103 | <structfield>index</structfield> is invalid. Menu items are enumerated | ||
| 104 | by calling <constant>VIDIOC_QUERYMENU</constant> with successive | ||
| 105 | <structfield>index</structfield> values from &v4l2-queryctrl; | ||
| 106 | <structfield>minimum</structfield> (0) to | ||
| 107 | <structfield>maximum</structfield>, inclusive.</para> | ||
| 108 | |||
| 109 | <para>See also the examples in <xref linkend="control" />.</para> | ||
| 110 | |||
| 111 | <table pgwide="1" frame="none" id="v4l2-queryctrl"> | ||
| 112 | <title>struct <structname>v4l2_queryctrl</structname></title> | ||
| 113 | <tgroup cols="3"> | ||
| 114 | &cs-str; | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>id</structfield></entry> | ||
| 119 | <entry>Identifies the control, set by the application. See | ||
| 120 | <xref linkend="control-id" /> for predefined IDs. When the ID is ORed | ||
| 121 | with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns | ||
| 122 | the first control with a higher ID. Drivers which do not support this | ||
| 123 | flag yet always return an &EINVAL;.</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>&v4l2-ctrl-type;</entry> | ||
| 127 | <entry><structfield>type</structfield></entry> | ||
| 128 | <entry>Type of control, see <xref | ||
| 129 | linkend="v4l2-ctrl-type" />.</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>__u8</entry> | ||
| 133 | <entry><structfield>name</structfield>[32]</entry> | ||
| 134 | <entry>Name of the control, a NUL-terminated ASCII | ||
| 135 | string. This information is intended for the user.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__s32</entry> | ||
| 139 | <entry><structfield>minimum</structfield></entry> | ||
| 140 | <entry>Minimum value, inclusive. This field gives a lower | ||
| 141 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | ||
| 142 | lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. | ||
| 143 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value | ||
| 144 | gives the minimum length of the string. This length <emphasis>does not include the terminating | ||
| 145 | zero</emphasis>. It may not be valid for any other type of control, including | ||
| 146 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | ||
| 147 | signed value.</entry> | ||
| 148 | </row> | ||
| 149 | <row> | ||
| 150 | <entry>__s32</entry> | ||
| 151 | <entry><structfield>maximum</structfield></entry> | ||
| 152 | <entry>Maximum value, inclusive. This field gives an upper | ||
| 153 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | ||
| 154 | highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> | ||
| 155 | controls. | ||
| 156 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value | ||
| 157 | gives the maximum length of the string. This length <emphasis>does not include the terminating | ||
| 158 | zero</emphasis>. It may not be valid for any other type of control, including | ||
| 159 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | ||
| 160 | signed value.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry>__s32</entry> | ||
| 164 | <entry><structfield>step</structfield></entry> | ||
| 165 | <entry><para>This field gives a step size for | ||
| 166 | <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For | ||
| 167 | <constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to | ||
| 168 | the string length that has to be a multiple of this step size. | ||
| 169 | It may not be valid for any other type of control, including | ||
| 170 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> | ||
| 171 | controls.</para><para>Generally drivers should not scale hardware | ||
| 172 | control values. It may be necessary for example when the | ||
| 173 | <structfield>name</structfield> or <structfield>id</structfield> imply | ||
| 174 | a particular unit and the hardware actually accepts only multiples of | ||
| 175 | said unit. If so, drivers must take care values are properly rounded | ||
| 176 | when scaling, such that errors will not accumulate on repeated | ||
| 177 | read-write cycles.</para><para>This field gives the smallest change of | ||
| 178 | an integer control actually affecting hardware. Often the information | ||
| 179 | is needed when the user can change controls by keyboard or GUI | ||
| 180 | buttons, rather than a slider. When for example a hardware register | ||
| 181 | accepts values 0-511 and the driver reports 0-65535, step should be | ||
| 182 | 128.</para><para>Note that although signed, the step value is supposed to | ||
| 183 | be always positive.</para></entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry>__s32</entry> | ||
| 187 | <entry><structfield>default_value</structfield></entry> | ||
| 188 | <entry>The default value of a | ||
| 189 | <constant>V4L2_CTRL_TYPE_INTEGER</constant>, | ||
| 190 | <constant>_BOOLEAN</constant> or <constant>_MENU</constant> control. | ||
| 191 | Not valid for other types of controls. Drivers reset controls only | ||
| 192 | when the driver is loaded, not later, in particular not when the | ||
| 193 | func-open; is called.</entry> | ||
| 194 | </row> | ||
| 195 | <row> | ||
| 196 | <entry>__u32</entry> | ||
| 197 | <entry><structfield>flags</structfield></entry> | ||
| 198 | <entry>Control flags, see <xref | ||
| 199 | linkend="control-flags" />.</entry> | ||
| 200 | </row> | ||
| 201 | <row> | ||
| 202 | <entry>__u32</entry> | ||
| 203 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 204 | <entry>Reserved for future extensions. Drivers must set | ||
| 205 | the array to zero.</entry> | ||
| 206 | </row> | ||
| 207 | </tbody> | ||
| 208 | </tgroup> | ||
| 209 | </table> | ||
| 210 | |||
| 211 | <table pgwide="1" frame="none" id="v4l2-querymenu"> | ||
| 212 | <title>struct <structname>v4l2_querymenu</structname></title> | ||
| 213 | <tgroup cols="3"> | ||
| 214 | &cs-str; | ||
| 215 | <tbody valign="top"> | ||
| 216 | <row> | ||
| 217 | <entry>__u32</entry> | ||
| 218 | <entry><structfield>id</structfield></entry> | ||
| 219 | <entry>Identifies the control, set by the application | ||
| 220 | from the respective &v4l2-queryctrl; | ||
| 221 | <structfield>id</structfield>.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>index</structfield></entry> | ||
| 226 | <entry>Index of the menu item, starting at zero, set by | ||
| 227 | the application.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u8</entry> | ||
| 231 | <entry><structfield>name</structfield>[32]</entry> | ||
| 232 | <entry>Name of the menu item, a NUL-terminated ASCII | ||
| 233 | string. This information is intended for the user.</entry> | ||
| 234 | </row> | ||
| 235 | <row> | ||
| 236 | <entry>__u32</entry> | ||
| 237 | <entry><structfield>reserved</structfield></entry> | ||
| 238 | <entry>Reserved for future extensions. Drivers must set | ||
| 239 | the array to zero.</entry> | ||
| 240 | </row> | ||
| 241 | </tbody> | ||
| 242 | </tgroup> | ||
| 243 | </table> | ||
| 244 | |||
| 245 | <table pgwide="1" frame="none" id="v4l2-ctrl-type"> | ||
| 246 | <title>enum v4l2_ctrl_type</title> | ||
| 247 | <tgroup cols="5" align="left"> | ||
| 248 | <colspec colwidth="30*" /> | ||
| 249 | <colspec colwidth="5*" align="center" /> | ||
| 250 | <colspec colwidth="5*" align="center" /> | ||
| 251 | <colspec colwidth="5*" align="center" /> | ||
| 252 | <colspec colwidth="55*" /> | ||
| 253 | <thead> | ||
| 254 | <row> | ||
| 255 | <entry>Type</entry> | ||
| 256 | <entry><structfield>minimum</structfield></entry> | ||
| 257 | <entry><structfield>step</structfield></entry> | ||
| 258 | <entry><structfield>maximum</structfield></entry> | ||
| 259 | <entry>Description</entry> | ||
| 260 | </row> | ||
| 261 | </thead> | ||
| 262 | <tbody valign="top"> | ||
| 263 | <row> | ||
| 264 | <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry> | ||
| 265 | <entry>any</entry> | ||
| 266 | <entry>any</entry> | ||
| 267 | <entry>any</entry> | ||
| 268 | <entry>An integer-valued control ranging from minimum to | ||
| 269 | maximum inclusive. The step value indicates the increment between | ||
| 270 | values which are actually different on the hardware.</entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> | ||
| 274 | <entry>0</entry> | ||
| 275 | <entry>1</entry> | ||
| 276 | <entry>1</entry> | ||
| 277 | <entry>A boolean-valued control. Zero corresponds to | ||
| 278 | "disabled", and one means "enabled".</entry> | ||
| 279 | </row> | ||
| 280 | <row> | ||
| 281 | <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> | ||
| 282 | <entry>0</entry> | ||
| 283 | <entry>1</entry> | ||
| 284 | <entry>N-1</entry> | ||
| 285 | <entry>The control has a menu of N choices. The names of | ||
| 286 | the menu items can be enumerated with the | ||
| 287 | <constant>VIDIOC_QUERYMENU</constant> ioctl.</entry> | ||
| 288 | </row> | ||
| 289 | <row> | ||
| 290 | <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry> | ||
| 291 | <entry>0</entry> | ||
| 292 | <entry>0</entry> | ||
| 293 | <entry>0</entry> | ||
| 294 | <entry>A control which performs an action when set. | ||
| 295 | Drivers must ignore the value passed with | ||
| 296 | <constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a | ||
| 297 | <constant>VIDIOC_G_CTRL</constant> attempt.</entry> | ||
| 298 | </row> | ||
| 299 | <row> | ||
| 300 | <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> | ||
| 301 | <entry>n/a</entry> | ||
| 302 | <entry>n/a</entry> | ||
| 303 | <entry>n/a</entry> | ||
| 304 | <entry>A 64-bit integer valued control. Minimum, maximum | ||
| 305 | and step size cannot be queried.</entry> | ||
| 306 | </row> | ||
| 307 | <row> | ||
| 308 | <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> | ||
| 309 | <entry>≥ 0</entry> | ||
| 310 | <entry>≥ 1</entry> | ||
| 311 | <entry>≥ 0</entry> | ||
| 312 | <entry>The minimum and maximum string lengths. The step size | ||
| 313 | means that the string must be (minimum + N * step) characters long for | ||
| 314 | N ≥ 0. These lengths do not include the terminating zero, so in order to | ||
| 315 | pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the | ||
| 316 | <structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can | ||
| 317 | set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. | ||
| 318 | Which character encoding is used will depend on the string control itself and | ||
| 319 | should be part of the control documentation.</entry> | ||
| 320 | </row> | ||
| 321 | <row> | ||
| 322 | <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> | ||
| 323 | <entry>n/a</entry> | ||
| 324 | <entry>n/a</entry> | ||
| 325 | <entry>n/a</entry> | ||
| 326 | <entry>This is not a control. When | ||
| 327 | <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID | ||
| 328 | equal to a control class code (see <xref linkend="ctrl-class" />), the | ||
| 329 | ioctl returns the name of the control class and this control type. | ||
| 330 | Older drivers which do not support this feature return an | ||
| 331 | &EINVAL;.</entry> | ||
| 332 | </row> | ||
| 333 | </tbody> | ||
| 334 | </tgroup> | ||
| 335 | </table> | ||
| 336 | |||
| 337 | <table pgwide="1" frame="none" id="control-flags"> | ||
| 338 | <title>Control Flags</title> | ||
| 339 | <tgroup cols="3"> | ||
| 340 | &cs-def; | ||
| 341 | <tbody valign="top"> | ||
| 342 | <row> | ||
| 343 | <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry> | ||
| 344 | <entry>0x0001</entry> | ||
| 345 | <entry>This control is permanently disabled and should be | ||
| 346 | ignored by the application. Any attempt to change the control will | ||
| 347 | result in an &EINVAL;.</entry> | ||
| 348 | </row> | ||
| 349 | <row> | ||
| 350 | <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry> | ||
| 351 | <entry>0x0002</entry> | ||
| 352 | <entry>This control is temporarily unchangeable, for | ||
| 353 | example because another application took over control of the | ||
| 354 | respective resource. Such controls may be displayed specially in a | ||
| 355 | user interface. Attempts to change the control may result in an | ||
| 356 | &EBUSY;.</entry> | ||
| 357 | </row> | ||
| 358 | <row> | ||
| 359 | <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry> | ||
| 360 | <entry>0x0004</entry> | ||
| 361 | <entry>This control is permanently readable only. Any | ||
| 362 | attempt to change the control will result in an &EINVAL;.</entry> | ||
| 363 | </row> | ||
| 364 | <row> | ||
| 365 | <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry> | ||
| 366 | <entry>0x0008</entry> | ||
| 367 | <entry>A hint that changing this control may affect the | ||
| 368 | value of other controls within the same control class. Applications | ||
| 369 | should update their user interface accordingly.</entry> | ||
| 370 | </row> | ||
| 371 | <row> | ||
| 372 | <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry> | ||
| 373 | <entry>0x0010</entry> | ||
| 374 | <entry>This control is not applicable to the current | ||
| 375 | configuration and should be displayed accordingly in a user interface. | ||
| 376 | For example the flag may be set on a MPEG audio level 2 bitrate | ||
| 377 | control when MPEG audio encoding level 1 was selected with another | ||
| 378 | control.</entry> | ||
| 379 | </row> | ||
| 380 | <row> | ||
| 381 | <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry> | ||
| 382 | <entry>0x0020</entry> | ||
| 383 | <entry>A hint that this control is best represented as a | ||
| 384 | slider-like element in a user interface.</entry> | ||
| 385 | </row> | ||
| 386 | <row> | ||
| 387 | <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry> | ||
| 388 | <entry>0x0040</entry> | ||
| 389 | <entry>This control is permanently writable only. Any | ||
| 390 | attempt to read the control will result in an &EACCES; error code. This | ||
| 391 | flag is typically present for relative controls or action controls where | ||
| 392 | writing a value will cause the device to carry out a given action | ||
| 393 | (⪚ motor control) but no meaningful value can be returned.</entry> | ||
| 394 | </row> | ||
| 395 | </tbody> | ||
| 396 | </tgroup> | ||
| 397 | </table> | ||
| 398 | </refsect1> | ||
| 399 | |||
| 400 | <refsect1> | ||
| 401 | &return-value; | ||
| 402 | |||
| 403 | <variablelist> | ||
| 404 | <varlistentry> | ||
| 405 | <term><errorcode>EINVAL</errorcode></term> | ||
| 406 | <listitem> | ||
| 407 | <para>The &v4l2-queryctrl; <structfield>id</structfield> | ||
| 408 | is invalid. The &v4l2-querymenu; <structfield>id</structfield> or | ||
| 409 | <structfield>index</structfield> is invalid.</para> | ||
| 410 | </listitem> | ||
| 411 | </varlistentry> | ||
| 412 | <varlistentry> | ||
| 413 | <term><errorcode>EACCES</errorcode></term> | ||
| 414 | <listitem> | ||
| 415 | <para>An attempt was made to read a write-only control.</para> | ||
| 416 | </listitem> | ||
| 417 | </varlistentry> | ||
| 418 | </variablelist> | ||
| 419 | </refsect1> | ||
| 420 | </refentry> | ||
| 421 | |||
| 422 | <!-- | ||
| 423 | Local Variables: | ||
| 424 | mode: sgml | ||
| 425 | sgml-parent-document: "v4l2.sgml" | ||
| 426 | indent-tabs-mode: nil | ||
| 427 | End: | ||
| 428 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querystd.xml b/Documentation/DocBook/v4l/vidioc-querystd.xml new file mode 100644 index 000000000000..b5a7ff934486 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querystd.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="vidioc-querystd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYSTD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYSTD</refname> | ||
| 9 | <refpurpose>Sense the video standard received by the current | ||
| 10 | input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_std_id *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_QUERYSTD</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The hardware may be able to detect the current video | ||
| 53 | standard automatically. To do so, applications call <constant> | ||
| 54 | VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The | ||
| 55 | driver stores here a set of candidates, this can be a single flag or a | ||
| 56 | set of supported standards if for example the hardware can only | ||
| 57 | distinguish between 50 and 60 Hz systems. When detection is not | ||
| 58 | possible or fails, the set must contain all standards supported by the | ||
| 59 | current video input or output.</para> | ||
| 60 | |||
| 61 | </refsect1> | ||
| 62 | |||
| 63 | <refsect1> | ||
| 64 | &return-value; | ||
| 65 | |||
| 66 | <variablelist> | ||
| 67 | <varlistentry> | ||
| 68 | <term><errorcode>EINVAL</errorcode></term> | ||
| 69 | <listitem> | ||
| 70 | <para>This ioctl is not supported.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml new file mode 100644 index 000000000000..bab38084454f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml | |||
| @@ -0,0 +1,160 @@ | |||
| 1 | <refentry id="vidioc-reqbufs"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_REQBUFS</refname> | ||
| 9 | <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_REQBUFS</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is used to initiate <link linkend="mmap">memory | ||
| 52 | mapped</link> or <link linkend="userp">user pointer</link> | ||
| 53 | I/O. Memory mapped buffers are located in device memory and must be | ||
| 54 | allocated with this ioctl before they can be mapped into the | ||
| 55 | application's address space. User buffers are allocated by | ||
| 56 | applications themselves, and this ioctl is merely used to switch the | ||
| 57 | driver into user pointer I/O mode.</para> | ||
| 58 | |||
| 59 | <para>To allocate device buffers applications initialize three | ||
| 60 | fields of a <structname>v4l2_requestbuffers</structname> structure. | ||
| 61 | They set the <structfield>type</structfield> field to the respective | ||
| 62 | stream or buffer type, the <structfield>count</structfield> field to | ||
| 63 | the desired number of buffers, and <structfield>memory</structfield> | ||
| 64 | must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl | ||
| 65 | is called with a pointer to this structure the driver attempts to | ||
| 66 | allocate the requested number of buffers and stores the actual number | ||
| 67 | allocated in the <structfield>count</structfield> field. It can be | ||
| 68 | smaller than the number requested, even zero, when the driver runs out | ||
| 69 | of free memory. A larger number is possible when the driver requires | ||
| 70 | more buffers to function correctly.<footnote> | ||
| 71 | <para>For example video output requires at least two buffers, | ||
| 72 | one displayed and one filled by the application.</para> | ||
| 73 | </footnote> When memory mapping I/O is not supported the ioctl | ||
| 74 | returns an &EINVAL;.</para> | ||
| 75 | |||
| 76 | <para>Applications can call <constant>VIDIOC_REQBUFS</constant> | ||
| 77 | again to change the number of buffers, however this cannot succeed | ||
| 78 | when any buffers are still mapped. A <structfield>count</structfield> | ||
| 79 | value of zero frees all buffers, after aborting or finishing any DMA | ||
| 80 | in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no | ||
| 81 | reason why munmap()ping one or even all buffers must imply | ||
| 82 | streamoff.--></para> | ||
| 83 | |||
| 84 | <para>To negotiate user pointer I/O, applications initialize only | ||
| 85 | the <structfield>type</structfield> field and set | ||
| 86 | <structfield>memory</structfield> to | ||
| 87 | <constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called | ||
| 88 | with a pointer to this structure the driver prepares for user pointer | ||
| 89 | I/O, when this I/O method is not supported the ioctl returns an | ||
| 90 | &EINVAL;.</para> | ||
| 91 | |||
| 92 | <table pgwide="1" frame="none" id="v4l2-requestbuffers"> | ||
| 93 | <title>struct <structname>v4l2_requestbuffers</structname></title> | ||
| 94 | <tgroup cols="3"> | ||
| 95 | &cs-str; | ||
| 96 | <tbody valign="top"> | ||
| 97 | <row> | ||
| 98 | <entry>__u32</entry> | ||
| 99 | <entry><structfield>count</structfield></entry> | ||
| 100 | <entry>The number of buffers requested or granted. This | ||
| 101 | field is only used when <structfield>memory</structfield> is set to | ||
| 102 | <constant>V4L2_MEMORY_MMAP</constant>.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>&v4l2-buf-type;</entry> | ||
| 106 | <entry><structfield>type</structfield></entry> | ||
| 107 | <entry>Type of the stream or buffers, this is the same | ||
| 108 | as the &v4l2-format; <structfield>type</structfield> field. See <xref | ||
| 109 | linkend="v4l2-buf-type" /> for valid values.</entry> | ||
| 110 | </row> | ||
| 111 | <row> | ||
| 112 | <entry>&v4l2-memory;</entry> | ||
| 113 | <entry><structfield>memory</structfield></entry> | ||
| 114 | <entry>Applications set this field to | ||
| 115 | <constant>V4L2_MEMORY_MMAP</constant> or | ||
| 116 | <constant>V4L2_MEMORY_USERPTR</constant>.</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry>__u32</entry> | ||
| 120 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 121 | <entry>A place holder for future extensions and custom | ||
| 122 | (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and | ||
| 123 | higher.</entry> | ||
| 124 | </row> | ||
| 125 | </tbody> | ||
| 126 | </tgroup> | ||
| 127 | </table> | ||
| 128 | </refsect1> | ||
| 129 | |||
| 130 | <refsect1> | ||
| 131 | &return-value; | ||
| 132 | |||
| 133 | <variablelist> | ||
| 134 | <varlistentry> | ||
| 135 | <term><errorcode>EBUSY</errorcode></term> | ||
| 136 | <listitem> | ||
| 137 | <para>The driver supports multiple opens and I/O is already | ||
| 138 | in progress, or reallocation of buffers was attempted although one or | ||
| 139 | more are still mapped.</para> | ||
| 140 | </listitem> | ||
| 141 | </varlistentry> | ||
| 142 | <varlistentry> | ||
| 143 | <term><errorcode>EINVAL</errorcode></term> | ||
| 144 | <listitem> | ||
| 145 | <para>The buffer type (<structfield>type</structfield> field) or the | ||
| 146 | requested I/O method (<structfield>memory</structfield>) is not | ||
| 147 | supported.</para> | ||
| 148 | </listitem> | ||
| 149 | </varlistentry> | ||
| 150 | </variablelist> | ||
| 151 | </refsect1> | ||
| 152 | </refentry> | ||
| 153 | |||
| 154 | <!-- | ||
| 155 | Local Variables: | ||
| 156 | mode: sgml | ||
| 157 | sgml-parent-document: "v4l2.sgml" | ||
| 158 | indent-tabs-mode: nil | ||
| 159 | End: | ||
| 160 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml new file mode 100644 index 000000000000..14b3ec7ed75b --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml | |||
| @@ -0,0 +1,129 @@ | |||
| 1 | <refentry id="vidioc-s-hw-freq-seek"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_S_HW_FREQ_SEEK</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_S_HW_FREQ_SEEK</refname> | ||
| 9 | <refpurpose>Perform a hardware frequency seek</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_hw_freq_seek | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_S_HW_FREQ_SEEK</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Start a hardware frequency seek from the current frequency. | ||
| 53 | To do this applications initialize the <structfield>tuner</structfield>, | ||
| 54 | <structfield>type</structfield>, <structfield>seek_upward</structfield> and | ||
| 55 | <structfield>wrap_around</structfield> fields, and zero out the | ||
| 56 | <structfield>reserved</structfield> array of a &v4l2-hw-freq-seek; and | ||
| 57 | call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer | ||
| 58 | to this structure.</para> | ||
| 59 | |||
| 60 | <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para> | ||
| 61 | |||
| 62 | <table pgwide="1" frame="none" id="v4l2-hw-freq-seek"> | ||
| 63 | <title>struct <structname>v4l2_hw_freq_seek</structname></title> | ||
| 64 | <tgroup cols="3"> | ||
| 65 | &cs-str; | ||
| 66 | <tbody valign="top"> | ||
| 67 | <row> | ||
| 68 | <entry>__u32</entry> | ||
| 69 | <entry><structfield>tuner</structfield></entry> | ||
| 70 | <entry>The tuner index number. This is the | ||
| 71 | same value as in the &v4l2-input; <structfield>tuner</structfield> | ||
| 72 | field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>&v4l2-tuner-type;</entry> | ||
| 76 | <entry><structfield>type</structfield></entry> | ||
| 77 | <entry>The tuner type. This is the same value as in the | ||
| 78 | &v4l2-tuner; <structfield>type</structfield> field.</entry> | ||
| 79 | </row> | ||
| 80 | <row> | ||
| 81 | <entry>__u32</entry> | ||
| 82 | <entry><structfield>seek_upward</structfield></entry> | ||
| 83 | <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry> | ||
| 84 | </row> | ||
| 85 | <row> | ||
| 86 | <entry>__u32</entry> | ||
| 87 | <entry><structfield>wrap_around</structfield></entry> | ||
| 88 | <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.</entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry>__u32</entry> | ||
| 92 | <entry><structfield>reserved</structfield>[8]</entry> | ||
| 93 | <entry>Reserved for future extensions. Drivers and | ||
| 94 | applications must set the array to zero.</entry> | ||
| 95 | </row> | ||
| 96 | </tbody> | ||
| 97 | </tgroup> | ||
| 98 | </table> | ||
| 99 | </refsect1> | ||
| 100 | |||
| 101 | <refsect1> | ||
| 102 | &return-value; | ||
| 103 | |||
| 104 | <variablelist> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>EINVAL</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The <structfield>tuner</structfield> index is out of | ||
| 109 | bounds or the value in the <structfield>type</structfield> field is | ||
| 110 | wrong.</para> | ||
| 111 | </listitem> | ||
| 112 | </varlistentry> | ||
| 113 | <varlistentry> | ||
| 114 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 115 | <listitem> | ||
| 116 | <para>The ioctl timed-out. Try again.</para> | ||
| 117 | </listitem> | ||
| 118 | </varlistentry> | ||
| 119 | </variablelist> | ||
| 120 | </refsect1> | ||
| 121 | </refentry> | ||
| 122 | |||
| 123 | <!-- | ||
| 124 | Local Variables: | ||
| 125 | mode: sgml | ||
| 126 | sgml-parent-document: "v4l2.sgml" | ||
| 127 | indent-tabs-mode: nil | ||
| 128 | End: | ||
| 129 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml new file mode 100644 index 000000000000..e42bff1f2c0a --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-streamon.xml | |||
| @@ -0,0 +1,106 @@ | |||
| 1 | <refentry id="vidioc-streamon"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_STREAMON</refname> | ||
| 9 | <refname>VIDIOC_STREAMOFF</refname> | ||
| 10 | <refpurpose>Start or stop streaming I/O</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>const int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_STREAMON, VIDIOC_STREAMOFF</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The <constant>VIDIOC_STREAMON</constant> and | ||
| 53 | <constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture | ||
| 54 | or output process during streaming (<link linkend="mmap">memory | ||
| 55 | mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para> | ||
| 56 | |||
| 57 | <para>Specifically the capture hardware is disabled and no input | ||
| 58 | buffers are filled (if there are any empty buffers in the incoming | ||
| 59 | queue) until <constant>VIDIOC_STREAMON</constant> has been called. | ||
| 60 | Accordingly the output hardware is disabled, no video signal is | ||
| 61 | produced until <constant>VIDIOC_STREAMON</constant> has been called. | ||
| 62 | The ioctl will succeed only when at least one output buffer is in the | ||
| 63 | incoming queue.</para> | ||
| 64 | |||
| 65 | <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of | ||
| 66 | aborting or finishing any DMA in progress, unlocks any user pointer | ||
| 67 | buffers locked in physical memory, and it removes all buffers from the | ||
| 68 | incoming and outgoing queues. That means all images captured but not | ||
| 69 | dequeued yet will be lost, likewise all images enqueued for output but | ||
| 70 | not transmitted yet. I/O returns to the same state as after calling | ||
| 71 | &VIDIOC-REQBUFS; and can be restarted accordingly.</para> | ||
| 72 | |||
| 73 | <para>Both ioctls take a pointer to an integer, the desired buffer or | ||
| 74 | stream type. This is the same as &v4l2-requestbuffers; | ||
| 75 | <structfield>type</structfield>.</para> | ||
| 76 | |||
| 77 | <para>Note applications can be preempted for unknown periods right | ||
| 78 | before or after the <constant>VIDIOC_STREAMON</constant> or | ||
| 79 | <constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of | ||
| 80 | starting or stopping "now". Buffer timestamps can be used to | ||
| 81 | synchronize with other events.</para> | ||
| 82 | </refsect1> | ||
| 83 | |||
| 84 | <refsect1> | ||
| 85 | &return-value; | ||
| 86 | |||
| 87 | <variablelist> | ||
| 88 | <varlistentry> | ||
| 89 | <term><errorcode>EINVAL</errorcode></term> | ||
| 90 | <listitem> | ||
| 91 | <para>Streaming I/O is not supported, the buffer | ||
| 92 | <structfield>type</structfield> is not supported, or no buffers have | ||
| 93 | been allocated (memory mapping) or enqueued (output) yet.</para> | ||
| 94 | </listitem> | ||
| 95 | </varlistentry> | ||
| 96 | </variablelist> | ||
| 97 | </refsect1> | ||
| 98 | </refentry> | ||
| 99 | |||
| 100 | <!-- | ||
| 101 | Local Variables: | ||
| 102 | mode: sgml | ||
| 103 | sgml-parent-document: "v4l2.sgml" | ||
| 104 | indent-tabs-mode: nil | ||
| 105 | End: | ||
| 106 | --> | ||
diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt index 6650af432523..e83f2ea76415 100644 --- a/Documentation/PCI/pci-error-recovery.txt +++ b/Documentation/PCI/pci-error-recovery.txt | |||
| @@ -4,15 +4,17 @@ | |||
| 4 | February 2, 2006 | 4 | February 2, 2006 |
| 5 | 5 | ||
| 6 | Current document maintainer: | 6 | Current document maintainer: |
| 7 | Linas Vepstas <linas@austin.ibm.com> | 7 | Linas Vepstas <linasvepstas@gmail.com> |
| 8 | updated by Richard Lary <rlary@us.ibm.com> | ||
| 9 | and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009 | ||
| 8 | 10 | ||
| 9 | 11 | ||
| 10 | Many PCI bus controllers are able to detect a variety of hardware | 12 | Many PCI bus controllers are able to detect a variety of hardware |
| 11 | PCI errors on the bus, such as parity errors on the data and address | 13 | PCI errors on the bus, such as parity errors on the data and address |
| 12 | busses, as well as SERR and PERR errors. Some of the more advanced | 14 | busses, as well as SERR and PERR errors. Some of the more advanced |
| 13 | chipsets are able to deal with these errors; these include PCI-E chipsets, | 15 | chipsets are able to deal with these errors; these include PCI-E chipsets, |
| 14 | and the PCI-host bridges found on IBM Power4 and Power5-based pSeries | 16 | and the PCI-host bridges found on IBM Power4, Power5 and Power6-based |
| 15 | boxes. A typical action taken is to disconnect the affected device, | 17 | pSeries boxes. A typical action taken is to disconnect the affected device, |
| 16 | halting all I/O to it. The goal of a disconnection is to avoid system | 18 | halting all I/O to it. The goal of a disconnection is to avoid system |
| 17 | corruption; for example, to halt system memory corruption due to DMA's | 19 | corruption; for example, to halt system memory corruption due to DMA's |
| 18 | to "wild" addresses. Typically, a reconnection mechanism is also | 20 | to "wild" addresses. Typically, a reconnection mechanism is also |
| @@ -37,10 +39,11 @@ is forced by the need to handle multi-function devices, that is, | |||
| 37 | devices that have multiple device drivers associated with them. | 39 | devices that have multiple device drivers associated with them. |
| 38 | In the first stage, each driver is allowed to indicate what type | 40 | In the first stage, each driver is allowed to indicate what type |
| 39 | of reset it desires, the choices being a simple re-enabling of I/O | 41 | of reset it desires, the choices being a simple re-enabling of I/O |
| 40 | or requesting a hard reset (a full electrical #RST of the PCI card). | 42 | or requesting a slot reset. |
| 41 | If any driver requests a full reset, that is what will be done. | ||
| 42 | 43 | ||
| 43 | After a full reset and/or a re-enabling of I/O, all drivers are | 44 | If any driver requests a slot reset, that is what will be done. |
| 45 | |||
| 46 | After a reset and/or a re-enabling of I/O, all drivers are | ||
| 44 | again notified, so that they may then perform any device setup/config | 47 | again notified, so that they may then perform any device setup/config |
| 45 | that may be required. After these have all completed, a final | 48 | that may be required. After these have all completed, a final |
| 46 | "resume normal operations" event is sent out. | 49 | "resume normal operations" event is sent out. |
| @@ -101,7 +104,7 @@ if it implements any, it must implement error_detected(). If a callback | |||
| 101 | is not implemented, the corresponding feature is considered unsupported. | 104 | is not implemented, the corresponding feature is considered unsupported. |
| 102 | For example, if mmio_enabled() and resume() aren't there, then it | 105 | For example, if mmio_enabled() and resume() aren't there, then it |
| 103 | is assumed that the driver is not doing any direct recovery and requires | 106 | is assumed that the driver is not doing any direct recovery and requires |
| 104 | a reset. If link_reset() is not implemented, the card is assumed as | 107 | a slot reset. If link_reset() is not implemented, the card is assumed to |
| 105 | not care about link resets. Typically a driver will want to know about | 108 | not care about link resets. Typically a driver will want to know about |
| 106 | a slot_reset(). | 109 | a slot_reset(). |
| 107 | 110 | ||
| @@ -111,7 +114,7 @@ sequence described below. | |||
| 111 | 114 | ||
| 112 | STEP 0: Error Event | 115 | STEP 0: Error Event |
| 113 | ------------------- | 116 | ------------------- |
| 114 | PCI bus error is detect by the PCI hardware. On powerpc, the slot | 117 | A PCI bus error is detected by the PCI hardware. On powerpc, the slot |
| 115 | is isolated, in that all I/O is blocked: all reads return 0xffffffff, | 118 | is isolated, in that all I/O is blocked: all reads return 0xffffffff, |
| 116 | all writes are ignored. | 119 | all writes are ignored. |
| 117 | 120 | ||
| @@ -139,7 +142,7 @@ The driver must return one of the following result codes: | |||
| 139 | a chance to extract some diagnostic information (see | 142 | a chance to extract some diagnostic information (see |
| 140 | mmio_enable, below). | 143 | mmio_enable, below). |
| 141 | - PCI_ERS_RESULT_NEED_RESET: | 144 | - PCI_ERS_RESULT_NEED_RESET: |
| 142 | Driver returns this if it can't recover without a hard | 145 | Driver returns this if it can't recover without a |
| 143 | slot reset. | 146 | slot reset. |
| 144 | - PCI_ERS_RESULT_DISCONNECT: | 147 | - PCI_ERS_RESULT_DISCONNECT: |
| 145 | Driver returns this if it doesn't want to recover at all. | 148 | Driver returns this if it doesn't want to recover at all. |
| @@ -169,11 +172,11 @@ is STEP 6 (Permanent Failure). | |||
| 169 | 172 | ||
| 170 | >>> The current powerpc implementation doesn't much care if the device | 173 | >>> The current powerpc implementation doesn't much care if the device |
| 171 | >>> attempts I/O at this point, or not. I/O's will fail, returning | 174 | >>> attempts I/O at this point, or not. I/O's will fail, returning |
| 172 | >>> a value of 0xff on read, and writes will be dropped. If the device | 175 | >>> a value of 0xff on read, and writes will be dropped. If more than |
| 173 | >>> driver attempts more than 10K I/O's to a frozen adapter, it will | 176 | >>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH |
| 174 | >>> assume that the device driver has gone into an infinite loop, and | 177 | >>> assumes that the device driver has gone into an infinite loop |
| 175 | >>> it will panic the kernel. There doesn't seem to be any other | 178 | >>> and prints an error to syslog. A reboot is then required to |
| 176 | >>> way of stopping a device driver that insists on spinning on I/O. | 179 | >>> get the device working again. |
| 177 | 180 | ||
| 178 | STEP 2: MMIO Enabled | 181 | STEP 2: MMIO Enabled |
| 179 | ------------------- | 182 | ------------------- |
| @@ -182,15 +185,14 @@ DMA), and then calls the mmio_enabled() callback on all affected | |||
| 182 | device drivers. | 185 | device drivers. |
| 183 | 186 | ||
| 184 | This is the "early recovery" call. IOs are allowed again, but DMA is | 187 | This is the "early recovery" call. IOs are allowed again, but DMA is |
| 185 | not (hrm... to be discussed, I prefer not), with some restrictions. This | 188 | not, with some restrictions. This is NOT a callback for the driver to |
| 186 | is NOT a callback for the driver to start operations again, only to | 189 | start operations again, only to peek/poke at the device, extract diagnostic |
| 187 | peek/poke at the device, extract diagnostic information, if any, and | 190 | information, if any, and eventually do things like trigger a device local |
| 188 | eventually do things like trigger a device local reset or some such, | 191 | reset or some such, but not restart operations. This callback is made if |
| 189 | but not restart operations. This is callback is made if all drivers on | 192 | all drivers on a segment agree that they can try to recover and if no automatic |
| 190 | a segment agree that they can try to recover and if no automatic link reset | 193 | link reset was performed by the HW. If the platform can't just re-enable IOs |
| 191 | was performed by the HW. If the platform can't just re-enable IOs without | 194 | without a slot reset or a link reset, it will not call this callback, and |
| 192 | a slot reset or a link reset, it wont call this callback, and instead | 195 | instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) |
| 193 | will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) | ||
| 194 | 196 | ||
| 195 | >>> The following is proposed; no platform implements this yet: | 197 | >>> The following is proposed; no platform implements this yet: |
| 196 | >>> Proposal: All I/O's should be done _synchronously_ from within | 198 | >>> Proposal: All I/O's should be done _synchronously_ from within |
| @@ -228,9 +230,6 @@ proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). | |||
| 228 | If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform | 230 | If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform |
| 229 | proceeds to STEP 4 (Slot Reset) | 231 | proceeds to STEP 4 (Slot Reset) |
| 230 | 232 | ||
| 231 | >>> The current powerpc implementation does not implement this callback. | ||
| 232 | |||
| 233 | |||
| 234 | STEP 3: Link Reset | 233 | STEP 3: Link Reset |
| 235 | ------------------ | 234 | ------------------ |
| 236 | The platform resets the link, and then calls the link_reset() callback | 235 | The platform resets the link, and then calls the link_reset() callback |
| @@ -253,16 +252,33 @@ The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5 | |||
| 253 | 252 | ||
| 254 | >>> The current powerpc implementation does not implement this callback. | 253 | >>> The current powerpc implementation does not implement this callback. |
| 255 | 254 | ||
| 256 | |||
| 257 | STEP 4: Slot Reset | 255 | STEP 4: Slot Reset |
| 258 | ------------------ | 256 | ------------------ |
| 259 | The platform performs a soft or hard reset of the device, and then | ||
| 260 | calls the slot_reset() callback. | ||
| 261 | 257 | ||
| 262 | A soft reset consists of asserting the adapter #RST line and then | 258 | In response to a return value of PCI_ERS_RESULT_NEED_RESET, the |
| 259 | the platform will peform a slot reset on the requesting PCI device(s). | ||
| 260 | The actual steps taken by a platform to perform a slot reset | ||
| 261 | will be platform-dependent. Upon completion of slot reset, the | ||
| 262 | platform will call the device slot_reset() callback. | ||
| 263 | |||
| 264 | Powerpc platforms implement two levels of slot reset: | ||
| 265 | soft reset(default) and fundamental(optional) reset. | ||
| 266 | |||
| 267 | Powerpc soft reset consists of asserting the adapter #RST line and then | ||
| 263 | restoring the PCI BAR's and PCI configuration header to a state | 268 | restoring the PCI BAR's and PCI configuration header to a state |
| 264 | that is equivalent to what it would be after a fresh system | 269 | that is equivalent to what it would be after a fresh system |
| 265 | power-on followed by power-on BIOS/system firmware initialization. | 270 | power-on followed by power-on BIOS/system firmware initialization. |
| 271 | Soft reset is also known as hot-reset. | ||
| 272 | |||
| 273 | Powerpc fundamental reset is supported by PCI Express cards only | ||
| 274 | and results in device's state machines, hardware logic, port states and | ||
| 275 | configuration registers to initialize to their default conditions. | ||
| 276 | |||
| 277 | For most PCI devices, a soft reset will be sufficient for recovery. | ||
| 278 | Optional fundamental reset is provided to support a limited number | ||
| 279 | of PCI Express PCI devices for which a soft reset is not sufficient | ||
| 280 | for recovery. | ||
| 281 | |||
| 266 | If the platform supports PCI hotplug, then the reset might be | 282 | If the platform supports PCI hotplug, then the reset might be |
| 267 | performed by toggling the slot electrical power off/on. | 283 | performed by toggling the slot electrical power off/on. |
| 268 | 284 | ||
| @@ -274,10 +290,12 @@ may result in hung devices, kernel panics, or silent data corruption. | |||
| 274 | 290 | ||
| 275 | This call gives drivers the chance to re-initialize the hardware | 291 | This call gives drivers the chance to re-initialize the hardware |
| 276 | (re-download firmware, etc.). At this point, the driver may assume | 292 | (re-download firmware, etc.). At this point, the driver may assume |
| 277 | that he card is in a fresh state and is fully functional. In | 293 | that the card is in a fresh state and is fully functional. The slot |
| 278 | particular, interrupt generation should work normally. | 294 | is unfrozen and the driver has full access to PCI config space, |
| 295 | memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X) | ||
| 296 | will also be available. | ||
| 279 | 297 | ||
| 280 | Drivers should not yet restart normal I/O processing operations | 298 | Drivers should not restart normal I/O processing operations |
| 281 | at this point. If all device drivers report success on this | 299 | at this point. If all device drivers report success on this |
| 282 | callback, the platform will call resume() to complete the sequence, | 300 | callback, the platform will call resume() to complete the sequence, |
| 283 | and let the driver restart normal I/O processing. | 301 | and let the driver restart normal I/O processing. |
| @@ -302,11 +320,21 @@ driver performs device init only from PCI function 0: | |||
| 302 | - PCI_ERS_RESULT_DISCONNECT | 320 | - PCI_ERS_RESULT_DISCONNECT |
| 303 | Same as above. | 321 | Same as above. |
| 304 | 322 | ||
| 323 | Drivers for PCI Express cards that require a fundamental reset must | ||
| 324 | set the needs_freset bit in the pci_dev structure in their probe function. | ||
| 325 | For example, the QLogic qla2xxx driver sets the needs_freset bit for certain | ||
| 326 | PCI card types: | ||
| 327 | |||
| 328 | + /* Set EEH reset type to fundamental if required by hba */ | ||
| 329 | + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) | ||
| 330 | + pdev->needs_freset = 1; | ||
| 331 | + | ||
| 332 | |||
| 305 | Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent | 333 | Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent |
| 306 | Failure). | 334 | Failure). |
| 307 | 335 | ||
| 308 | >>> The current powerpc implementation does not currently try a | 336 | >>> The current powerpc implementation does not try a power-cycle |
| 309 | >>> power-cycle reset if the driver returned PCI_ERS_RESULT_DISCONNECT. | 337 | >>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT. |
| 310 | >>> However, it probably should. | 338 | >>> However, it probably should. |
| 311 | 339 | ||
| 312 | 340 | ||
| @@ -348,7 +376,7 @@ software errors. | |||
| 348 | 376 | ||
| 349 | Conclusion; General Remarks | 377 | Conclusion; General Remarks |
| 350 | --------------------------- | 378 | --------------------------- |
| 351 | The way those callbacks are called is platform policy. A platform with | 379 | The way the callbacks are called is platform policy. A platform with |
| 352 | no slot reset capability may want to just "ignore" drivers that can't | 380 | no slot reset capability may want to just "ignore" drivers that can't |
| 353 | recover (disconnect them) and try to let other cards on the same segment | 381 | recover (disconnect them) and try to let other cards on the same segment |
| 354 | recover. Keep in mind that in most real life cases, though, there will | 382 | recover. Keep in mind that in most real life cases, though, there will |
| @@ -361,8 +389,8 @@ That is, the recovery API only requires that: | |||
| 361 | 389 | ||
| 362 | - There is no guarantee that interrupt delivery can proceed from any | 390 | - There is no guarantee that interrupt delivery can proceed from any |
| 363 | device on the segment starting from the error detection and until the | 391 | device on the segment starting from the error detection and until the |
| 364 | resume callback is sent, at which point interrupts are expected to be | 392 | slot_reset callback is called, at which point interrupts are expected |
| 365 | fully operational. | 393 | to be fully operational. |
| 366 | 394 | ||
| 367 | - There is no guarantee that interrupt delivery is stopped, that is, | 395 | - There is no guarantee that interrupt delivery is stopped, that is, |
| 368 | a driver that gets an interrupt after detecting an error, or that detects | 396 | a driver that gets an interrupt after detecting an error, or that detects |
| @@ -381,16 +409,23 @@ anyway :) | |||
| 381 | >>> Implementation details for the powerpc platform are discussed in | 409 | >>> Implementation details for the powerpc platform are discussed in |
| 382 | >>> the file Documentation/powerpc/eeh-pci-error-recovery.txt | 410 | >>> the file Documentation/powerpc/eeh-pci-error-recovery.txt |
| 383 | 411 | ||
| 384 | >>> As of this writing, there are six device drivers with patches | 412 | >>> As of this writing, there is a growing list of device drivers with |
| 385 | >>> implementing error recovery. Not all of these patches are in | 413 | >>> patches implementing error recovery. Not all of these patches are in |
| 386 | >>> mainline yet. These may be used as "examples": | 414 | >>> mainline yet. These may be used as "examples": |
| 387 | >>> | 415 | >>> |
| 388 | >>> drivers/scsi/ipr.c | 416 | >>> drivers/scsi/ipr |
| 389 | >>> drivers/scsi/sym53cxx_2 | 417 | >>> drivers/scsi/sym53c8xx_2 |
| 418 | >>> drivers/scsi/qla2xxx | ||
| 419 | >>> drivers/scsi/lpfc | ||
| 420 | >>> drivers/next/bnx2.c | ||
| 390 | >>> drivers/next/e100.c | 421 | >>> drivers/next/e100.c |
| 391 | >>> drivers/net/e1000 | 422 | >>> drivers/net/e1000 |
| 423 | >>> drivers/net/e1000e | ||
| 392 | >>> drivers/net/ixgb | 424 | >>> drivers/net/ixgb |
| 425 | >>> drivers/net/ixgbe | ||
| 426 | >>> drivers/net/cxgb3 | ||
| 393 | >>> drivers/net/s2io.c | 427 | >>> drivers/net/s2io.c |
| 428 | >>> drivers/net/qlge | ||
| 394 | 429 | ||
| 395 | The End | 430 | The End |
| 396 | ------- | 431 | ------- |
diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 9f711d2df91b..d2b85237c76e 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt | |||
| @@ -743,3 +743,80 @@ Revised: | |||
| 743 | RCU, realtime RCU, sleepable RCU, performance. | 743 | RCU, realtime RCU, sleepable RCU, performance. |
| 744 | " | 744 | " |
| 745 | } | 745 | } |
| 746 | |||
| 747 | @article{PaulEMcKenney2008RCUOSR | ||
| 748 | ,author="Paul E. McKenney and Jonathan Walpole" | ||
| 749 | ,title="Introducing technology into the {Linux} kernel: a case study" | ||
| 750 | ,Year="2008" | ||
| 751 | ,journal="SIGOPS Oper. Syst. Rev." | ||
| 752 | ,volume="42" | ||
| 753 | ,number="5" | ||
| 754 | ,pages="4--17" | ||
| 755 | ,issn="0163-5980" | ||
| 756 | ,doi={http://doi.acm.org/10.1145/1400097.1400099} | ||
| 757 | ,publisher="ACM" | ||
| 758 | ,address="New York, NY, USA" | ||
| 759 | ,annotation={ | ||
| 760 | Linux changed RCU to a far greater degree than RCU has changed Linux. | ||
| 761 | } | ||
| 762 | } | ||
| 763 | |||
| 764 | @unpublished{PaulEMcKenney2008HierarchicalRCU | ||
| 765 | ,Author="Paul E. McKenney" | ||
| 766 | ,Title="Hierarchical {RCU}" | ||
| 767 | ,month="November" | ||
| 768 | ,day="3" | ||
| 769 | ,year="2008" | ||
| 770 | ,note="Available: | ||
| 771 | \url{http://lwn.net/Articles/305782/} | ||
| 772 | [Viewed November 6, 2008]" | ||
| 773 | ,annotation=" | ||
| 774 | RCU with combining-tree-based grace-period detection, | ||
| 775 | permitting it to handle thousands of CPUs. | ||
| 776 | " | ||
| 777 | } | ||
| 778 | |||
| 779 | @conference{PaulEMcKenney2009MaliciousURCU | ||
| 780 | ,Author="Paul E. McKenney" | ||
| 781 | ,Title="Using a Malicious User-Level {RCU} to Torture {RCU}-Based Algorithms" | ||
| 782 | ,Booktitle="linux.conf.au 2009" | ||
| 783 | ,month="January" | ||
| 784 | ,year="2009" | ||
| 785 | ,address="Hobart, Australia" | ||
| 786 | ,note="Available: | ||
| 787 | \url{http://www.rdrop.com/users/paulmck/RCU/urcutorture.2009.01.22a.pdf} | ||
| 788 | [Viewed February 2, 2009]" | ||
| 789 | ,annotation=" | ||
| 790 | Realtime RCU and torture-testing RCU uses. | ||
| 791 | " | ||
| 792 | } | ||
| 793 | |||
| 794 | @unpublished{MathieuDesnoyers2009URCU | ||
| 795 | ,Author="Mathieu Desnoyers" | ||
| 796 | ,Title="[{RFC} git tree] Userspace {RCU} (urcu) for {Linux}" | ||
| 797 | ,month="February" | ||
| 798 | ,day="5" | ||
| 799 | ,year="2009" | ||
| 800 | ,note="Available: | ||
| 801 | \url{http://lkml.org/lkml/2009/2/5/572} | ||
| 802 | \url{git://lttng.org/userspace-rcu.git} | ||
| 803 | [Viewed February 20, 2009]" | ||
| 804 | ,annotation=" | ||
| 805 | Mathieu Desnoyers's user-space RCU implementation. | ||
| 806 | git://lttng.org/userspace-rcu.git | ||
| 807 | " | ||
| 808 | } | ||
| 809 | |||
| 810 | @unpublished{PaulEMcKenney2009BloatWatchRCU | ||
| 811 | ,Author="Paul E. McKenney" | ||
| 812 | ,Title="{RCU}: The {Bloatwatch} Edition" | ||
| 813 | ,month="March" | ||
| 814 | ,day="17" | ||
| 815 | ,year="2009" | ||
| 816 | ,note="Available: | ||
| 817 | \url{http://lwn.net/Articles/323929/} | ||
| 818 | [Viewed March 20, 2009]" | ||
| 819 | ,annotation=" | ||
| 820 | Uniprocessor assumptions allow simplified RCU implementation. | ||
| 821 | " | ||
| 822 | } | ||
diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt index aab4a9ec3931..90ec5341ee98 100644 --- a/Documentation/RCU/UP.txt +++ b/Documentation/RCU/UP.txt | |||
| @@ -2,14 +2,13 @@ RCU on Uniprocessor Systems | |||
| 2 | 2 | ||
| 3 | 3 | ||
| 4 | A common misconception is that, on UP systems, the call_rcu() primitive | 4 | A common misconception is that, on UP systems, the call_rcu() primitive |
| 5 | may immediately invoke its function, and that the synchronize_rcu() | 5 | may immediately invoke its function. The basis of this misconception |
| 6 | primitive may return immediately. The basis of this misconception | ||
| 7 | is that since there is only one CPU, it should not be necessary to | 6 | is that since there is only one CPU, it should not be necessary to |
| 8 | wait for anything else to get done, since there are no other CPUs for | 7 | wait for anything else to get done, since there are no other CPUs for |
| 9 | anything else to be happening on. Although this approach will -sort- -of- | 8 | anything else to be happening on. Although this approach will -sort- -of- |
| 10 | work a surprising amount of the time, it is a very bad idea in general. | 9 | work a surprising amount of the time, it is a very bad idea in general. |
| 11 | This document presents three examples that demonstrate exactly how bad an | 10 | This document presents three examples that demonstrate exactly how bad |
| 12 | idea this is. | 11 | an idea this is. |
| 13 | 12 | ||
| 14 | 13 | ||
| 15 | Example 1: softirq Suicide | 14 | Example 1: softirq Suicide |
| @@ -82,11 +81,18 @@ Quick Quiz #2: What locking restriction must RCU callbacks respect? | |||
| 82 | 81 | ||
| 83 | Summary | 82 | Summary |
| 84 | 83 | ||
| 85 | Permitting call_rcu() to immediately invoke its arguments or permitting | 84 | Permitting call_rcu() to immediately invoke its arguments breaks RCU, |
| 86 | synchronize_rcu() to immediately return breaks RCU, even on a UP system. | 85 | even on a UP system. So do not do it! Even on a UP system, the RCU |
| 87 | So do not do it! Even on a UP system, the RCU infrastructure -must- | 86 | infrastructure -must- respect grace periods, and -must- invoke callbacks |
| 88 | respect grace periods, and -must- invoke callbacks from a known environment | 87 | from a known environment in which no locks are held. |
| 89 | in which no locks are held. | 88 | |
| 89 | It -is- safe for synchronize_sched() and synchronize_rcu_bh() to return | ||
| 90 | immediately on an UP system. It is also safe for synchronize_rcu() | ||
| 91 | to return immediately on UP systems, except when running preemptable | ||
| 92 | RCU. | ||
| 93 | |||
| 94 | Quick Quiz #3: Why can't synchronize_rcu() return immediately on | ||
| 95 | UP systems running preemptable RCU? | ||
| 90 | 96 | ||
| 91 | 97 | ||
| 92 | Answer to Quick Quiz #1: | 98 | Answer to Quick Quiz #1: |
| @@ -117,3 +123,13 @@ Answer to Quick Quiz #2: | |||
| 117 | callbacks acquire locks directly. However, a great many RCU | 123 | callbacks acquire locks directly. However, a great many RCU |
| 118 | callbacks do acquire locks -indirectly-, for example, via | 124 | callbacks do acquire locks -indirectly-, for example, via |
| 119 | the kfree() primitive. | 125 | the kfree() primitive. |
| 126 | |||
| 127 | Answer to Quick Quiz #3: | ||
| 128 | Why can't synchronize_rcu() return immediately on UP systems | ||
| 129 | running preemptable RCU? | ||
| 130 | |||
| 131 | Because some other task might have been preempted in the middle | ||
| 132 | of an RCU read-side critical section. If synchronize_rcu() | ||
| 133 | simply immediately returned, it would prematurely signal the | ||
| 134 | end of the grace period, which would come as a nasty shock to | ||
| 135 | that other thread when it started running again. | ||
diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index accfe2f5247d..51525a30e8b4 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.txt | |||
| @@ -11,7 +11,10 @@ over a rather long period of time, but improvements are always welcome! | |||
| 11 | structure is updated more than about 10% of the time, then | 11 | structure is updated more than about 10% of the time, then |
| 12 | you should strongly consider some other approach, unless | 12 | you should strongly consider some other approach, unless |
| 13 | detailed performance measurements show that RCU is nonetheless | 13 | detailed performance measurements show that RCU is nonetheless |
| 14 | the right tool for the job. | 14 | the right tool for the job. Yes, you might think of RCU |
| 15 | as simply cutting overhead off of the readers and imposing it | ||
| 16 | on the writers. That is exactly why normal uses of RCU will | ||
| 17 | do much more reading than updating. | ||
| 15 | 18 | ||
| 16 | Another exception is where performance is not an issue, and RCU | 19 | Another exception is where performance is not an issue, and RCU |
| 17 | provides a simpler implementation. An example of this situation | 20 | provides a simpler implementation. An example of this situation |
| @@ -240,10 +243,11 @@ over a rather long period of time, but improvements are always welcome! | |||
| 240 | instead need to use synchronize_irq() or synchronize_sched(). | 243 | instead need to use synchronize_irq() or synchronize_sched(). |
| 241 | 244 | ||
| 242 | 12. Any lock acquired by an RCU callback must be acquired elsewhere | 245 | 12. Any lock acquired by an RCU callback must be acquired elsewhere |
| 243 | with irq disabled, e.g., via spin_lock_irqsave(). Failing to | 246 | with softirq disabled, e.g., via spin_lock_irqsave(), |
| 244 | disable irq on a given acquisition of that lock will result in | 247 | spin_lock_bh(), etc. Failing to disable irq on a given |
| 245 | deadlock as soon as the RCU callback happens to interrupt that | 248 | acquisition of that lock will result in deadlock as soon as the |
| 246 | acquisition's critical section. | 249 | RCU callback happens to interrupt that acquisition's critical |
| 250 | section. | ||
| 247 | 251 | ||
| 248 | 13. RCU callbacks can be and are executed in parallel. In many cases, | 252 | 13. RCU callbacks can be and are executed in parallel. In many cases, |
| 249 | the callback code simply wrappers around kfree(), so that this | 253 | the callback code simply wrappers around kfree(), so that this |
| @@ -310,3 +314,9 @@ over a rather long period of time, but improvements are always welcome! | |||
| 310 | Because these primitives only wait for pre-existing readers, | 314 | Because these primitives only wait for pre-existing readers, |
| 311 | it is the caller's responsibility to guarantee safety to | 315 | it is the caller's responsibility to guarantee safety to |
| 312 | any subsequent readers. | 316 | any subsequent readers. |
| 317 | |||
| 318 | 16. The various RCU read-side primitives do -not- contain memory | ||
| 319 | barriers. The CPU (and in some cases, the compiler) is free | ||
| 320 | to reorder code into and out of RCU read-side critical sections. | ||
| 321 | It is the responsibility of the RCU update-side primitives to | ||
| 322 | deal with this. | ||
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt index 7aa2002ade77..2a23523ce471 100644 --- a/Documentation/RCU/rcu.txt +++ b/Documentation/RCU/rcu.txt | |||
| @@ -36,7 +36,7 @@ o How can the updater tell when a grace period has completed | |||
| 36 | executed in user mode, or executed in the idle loop, we can | 36 | executed in user mode, or executed in the idle loop, we can |
| 37 | safely free up that item. | 37 | safely free up that item. |
| 38 | 38 | ||
| 39 | Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the | 39 | Preemptible variants of RCU (CONFIG_TREE_PREEMPT_RCU) get the |
| 40 | same effect, but require that the readers manipulate CPU-local | 40 | same effect, but require that the readers manipulate CPU-local |
| 41 | counters. These counters allow limited types of blocking | 41 | counters. These counters allow limited types of blocking |
| 42 | within RCU read-side critical sections. SRCU also uses | 42 | within RCU read-side critical sections. SRCU also uses |
| @@ -79,10 +79,10 @@ o I hear that RCU is patented? What is with that? | |||
| 79 | o I hear that RCU needs work in order to support realtime kernels? | 79 | o I hear that RCU needs work in order to support realtime kernels? |
| 80 | 80 | ||
| 81 | This work is largely completed. Realtime-friendly RCU can be | 81 | This work is largely completed. Realtime-friendly RCU can be |
| 82 | enabled via the CONFIG_PREEMPT_RCU kernel configuration parameter. | 82 | enabled via the CONFIG_TREE_PREEMPT_RCU kernel configuration |
| 83 | However, work is in progress for enabling priority boosting of | 83 | parameter. However, work is in progress for enabling priority |
| 84 | preempted RCU read-side critical sections. This is needed if you | 84 | boosting of preempted RCU read-side critical sections. This is |
| 85 | have CPU-bound realtime threads. | 85 | needed if you have CPU-bound realtime threads. |
| 86 | 86 | ||
| 87 | o Where can I find more information on RCU? | 87 | o Where can I find more information on RCU? |
| 88 | 88 | ||
diff --git a/Documentation/RCU/rcubarrier.txt b/Documentation/RCU/rcubarrier.txt index 909602d409bb..e439a0edee22 100644 --- a/Documentation/RCU/rcubarrier.txt +++ b/Documentation/RCU/rcubarrier.txt | |||
| @@ -170,6 +170,13 @@ module invokes call_rcu() from timers, you will need to first cancel all | |||
| 170 | the timers, and only then invoke rcu_barrier() to wait for any remaining | 170 | the timers, and only then invoke rcu_barrier() to wait for any remaining |
| 171 | RCU callbacks to complete. | 171 | RCU callbacks to complete. |
| 172 | 172 | ||
| 173 | Of course, if you module uses call_rcu_bh(), you will need to invoke | ||
| 174 | rcu_barrier_bh() before unloading. Similarly, if your module uses | ||
| 175 | call_rcu_sched(), you will need to invoke rcu_barrier_sched() before | ||
| 176 | unloading. If your module uses call_rcu(), call_rcu_bh(), -and- | ||
| 177 | call_rcu_sched(), then you will need to invoke each of rcu_barrier(), | ||
| 178 | rcu_barrier_bh(), and rcu_barrier_sched(). | ||
| 179 | |||
| 173 | 180 | ||
| 174 | Implementing rcu_barrier() | 181 | Implementing rcu_barrier() |
| 175 | 182 | ||
diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt index 93cb28d05dcd..18f9651ff23d 100644 --- a/Documentation/RCU/rculist_nulls.txt +++ b/Documentation/RCU/rculist_nulls.txt | |||
| @@ -83,11 +83,12 @@ not detect it missed following items in original chain. | |||
| 83 | obj = kmem_cache_alloc(...); | 83 | obj = kmem_cache_alloc(...); |
| 84 | lock_chain(); // typically a spin_lock() | 84 | lock_chain(); // typically a spin_lock() |
| 85 | obj->key = key; | 85 | obj->key = key; |
| 86 | atomic_inc(&obj->refcnt); | ||
| 87 | /* | 86 | /* |
| 88 | * we need to make sure obj->key is updated before obj->next | 87 | * we need to make sure obj->key is updated before obj->next |
| 88 | * or obj->refcnt | ||
| 89 | */ | 89 | */ |
| 90 | smp_wmb(); | 90 | smp_wmb(); |
| 91 | atomic_set(&obj->refcnt, 1); | ||
| 91 | hlist_add_head_rcu(&obj->obj_node, list); | 92 | hlist_add_head_rcu(&obj->obj_node, list); |
| 92 | unlock_chain(); // typically a spin_unlock() | 93 | unlock_chain(); // typically a spin_unlock() |
| 93 | 94 | ||
| @@ -159,6 +160,10 @@ out: | |||
| 159 | obj = kmem_cache_alloc(cachep); | 160 | obj = kmem_cache_alloc(cachep); |
| 160 | lock_chain(); // typically a spin_lock() | 161 | lock_chain(); // typically a spin_lock() |
| 161 | obj->key = key; | 162 | obj->key = key; |
| 163 | /* | ||
| 164 | * changes to obj->key must be visible before refcnt one | ||
| 165 | */ | ||
| 166 | smp_wmb(); | ||
| 162 | atomic_set(&obj->refcnt, 1); | 167 | atomic_set(&obj->refcnt, 1); |
| 163 | /* | 168 | /* |
| 164 | * insert obj in RCU way (readers might be traversing chain) | 169 | * insert obj in RCU way (readers might be traversing chain) |
diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt index a342b6e1cc10..9dba3bb90e60 100644 --- a/Documentation/RCU/torture.txt +++ b/Documentation/RCU/torture.txt | |||
| @@ -76,8 +76,10 @@ torture_type The type of RCU to test: "rcu" for the rcu_read_lock() API, | |||
| 76 | "rcu_sync" for rcu_read_lock() with synchronous reclamation, | 76 | "rcu_sync" for rcu_read_lock() with synchronous reclamation, |
| 77 | "rcu_bh" for the rcu_read_lock_bh() API, "rcu_bh_sync" for | 77 | "rcu_bh" for the rcu_read_lock_bh() API, "rcu_bh_sync" for |
| 78 | rcu_read_lock_bh() with synchronous reclamation, "srcu" for | 78 | rcu_read_lock_bh() with synchronous reclamation, "srcu" for |
| 79 | the "srcu_read_lock()" API, and "sched" for the use of | 79 | the "srcu_read_lock()" API, "sched" for the use of |
| 80 | preempt_disable() together with synchronize_sched(). | 80 | preempt_disable() together with synchronize_sched(), |
| 81 | and "sched_expedited" for the use of preempt_disable() | ||
| 82 | with synchronize_sched_expedited(). | ||
| 81 | 83 | ||
| 82 | verbose Enable debug printk()s. Default is disabled. | 84 | verbose Enable debug printk()s. Default is disabled. |
| 83 | 85 | ||
| @@ -162,6 +164,23 @@ of the "old" and "current" counters for the corresponding CPU. The | |||
| 162 | "idx" value maps the "old" and "current" values to the underlying array, | 164 | "idx" value maps the "old" and "current" values to the underlying array, |
| 163 | and is useful for debugging. | 165 | and is useful for debugging. |
| 164 | 166 | ||
| 167 | Similarly, sched_expedited RCU provides the following: | ||
| 168 | |||
| 169 | sched_expedited-torture: rtc: d0000000016c1880 ver: 1090796 tfle: 0 rta: 1090796 rtaf: 0 rtf: 1090787 rtmbe: 0 nt: 27713319 | ||
| 170 | sched_expedited-torture: Reader Pipe: 12660320201 95875 0 0 0 0 0 0 0 0 0 | ||
| 171 | sched_expedited-torture: Reader Batch: 12660424885 0 0 0 0 0 0 0 0 0 0 | ||
| 172 | sched_expedited-torture: Free-Block Circulation: 1090795 1090795 1090794 1090793 1090792 1090791 1090790 1090789 1090788 1090787 0 | ||
| 173 | state: -1 / 0:0 3:0 4:0 | ||
| 174 | |||
| 175 | As before, the first four lines are similar to those for RCU. | ||
| 176 | The last line shows the task-migration state. The first number is | ||
| 177 | -1 if synchronize_sched_expedited() is idle, -2 if in the process of | ||
| 178 | posting wakeups to the migration kthreads, and N when waiting on CPU N. | ||
| 179 | Each of the colon-separated fields following the "/" is a CPU:state pair. | ||
| 180 | Valid states are "0" for idle, "1" for waiting for quiescent state, | ||
| 181 | "2" for passed through quiescent state, and "3" when a race with a | ||
| 182 | CPU-hotplug event forces use of the synchronize_sched() primitive. | ||
| 183 | |||
| 165 | 184 | ||
| 166 | USAGE | 185 | USAGE |
| 167 | 186 | ||
diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt index 02cced183b2d..187bbf10c923 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt | |||
| @@ -191,8 +191,7 @@ rcu/rcuhier (which displays the struct rcu_node hierarchy). | |||
| 191 | 191 | ||
| 192 | The output of "cat rcu/rcudata" looks as follows: | 192 | The output of "cat rcu/rcudata" looks as follows: |
| 193 | 193 | ||
| 194 | rcu: | 194 | rcu_sched: |
| 195 | rcu: | ||
| 196 | 0 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=10951/1 dn=0 df=1101 of=0 ri=36 ql=0 b=10 | 195 | 0 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=10951/1 dn=0 df=1101 of=0 ri=36 ql=0 b=10 |
| 197 | 1 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=16117/1 dn=0 df=1015 of=0 ri=0 ql=0 b=10 | 196 | 1 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=16117/1 dn=0 df=1015 of=0 ri=0 ql=0 b=10 |
| 198 | 2 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1445/1 dn=0 df=1839 of=0 ri=0 ql=0 b=10 | 197 | 2 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1445/1 dn=0 df=1839 of=0 ri=0 ql=0 b=10 |
| @@ -306,7 +305,7 @@ comma-separated-variable spreadsheet format. | |||
| 306 | 305 | ||
| 307 | The output of "cat rcu/rcugp" looks as follows: | 306 | The output of "cat rcu/rcugp" looks as follows: |
| 308 | 307 | ||
| 309 | rcu: completed=33062 gpnum=33063 | 308 | rcu_sched: completed=33062 gpnum=33063 |
| 310 | rcu_bh: completed=464 gpnum=464 | 309 | rcu_bh: completed=464 gpnum=464 |
| 311 | 310 | ||
| 312 | Again, this output is for both "rcu" and "rcu_bh". The fields are | 311 | Again, this output is for both "rcu" and "rcu_bh". The fields are |
| @@ -413,7 +412,7 @@ o Each element of the form "1/1 0:127 ^0" represents one struct | |||
| 413 | 412 | ||
| 414 | The output of "cat rcu/rcu_pending" looks as follows: | 413 | The output of "cat rcu/rcu_pending" looks as follows: |
| 415 | 414 | ||
| 416 | rcu: | 415 | rcu_sched: |
| 417 | 0 np=255892 qsp=53936 cbr=0 cng=14417 gpc=10033 gps=24320 nf=6445 nn=146741 | 416 | 0 np=255892 qsp=53936 cbr=0 cng=14417 gpc=10033 gps=24320 nf=6445 nn=146741 |
| 418 | 1 np=261224 qsp=54638 cbr=0 cng=25723 gpc=16310 gps=2849 nf=5912 nn=155792 | 417 | 1 np=261224 qsp=54638 cbr=0 cng=25723 gpc=16310 gps=2849 nf=5912 nn=155792 |
| 419 | 2 np=237496 qsp=49664 cbr=0 cng=2762 gpc=45478 gps=1762 nf=1201 nn=136629 | 418 | 2 np=237496 qsp=49664 cbr=0 cng=2762 gpc=45478 gps=1762 nf=1201 nn=136629 |
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index 96170824a717..e41a7fecf0d3 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt | |||
| @@ -136,10 +136,10 @@ rcu_read_lock() | |||
| 136 | Used by a reader to inform the reclaimer that the reader is | 136 | Used by a reader to inform the reclaimer that the reader is |
| 137 | entering an RCU read-side critical section. It is illegal | 137 | entering an RCU read-side critical section. It is illegal |
| 138 | to block while in an RCU read-side critical section, though | 138 | to block while in an RCU read-side critical section, though |
| 139 | kernels built with CONFIG_PREEMPT_RCU can preempt RCU read-side | 139 | kernels built with CONFIG_TREE_PREEMPT_RCU can preempt RCU |
| 140 | critical sections. Any RCU-protected data structure accessed | 140 | read-side critical sections. Any RCU-protected data structure |
| 141 | during an RCU read-side critical section is guaranteed to remain | 141 | accessed during an RCU read-side critical section is guaranteed to |
| 142 | unreclaimed for the full duration of that critical section. | 142 | remain unreclaimed for the full duration of that critical section. |
| 143 | Reference counts may be used in conjunction with RCU to maintain | 143 | Reference counts may be used in conjunction with RCU to maintain |
| 144 | longer-term references to data structures. | 144 | longer-term references to data structures. |
| 145 | 145 | ||
| @@ -785,6 +785,7 @@ RCU pointer/list traversal: | |||
| 785 | rcu_dereference | 785 | rcu_dereference |
| 786 | list_for_each_entry_rcu | 786 | list_for_each_entry_rcu |
| 787 | hlist_for_each_entry_rcu | 787 | hlist_for_each_entry_rcu |
| 788 | hlist_nulls_for_each_entry_rcu | ||
| 788 | 789 | ||
| 789 | list_for_each_continue_rcu (to be deprecated in favor of new | 790 | list_for_each_continue_rcu (to be deprecated in favor of new |
| 790 | list_for_each_entry_continue_rcu) | 791 | list_for_each_entry_continue_rcu) |
| @@ -807,19 +808,23 @@ RCU: Critical sections Grace period Barrier | |||
| 807 | 808 | ||
| 808 | rcu_read_lock synchronize_net rcu_barrier | 809 | rcu_read_lock synchronize_net rcu_barrier |
| 809 | rcu_read_unlock synchronize_rcu | 810 | rcu_read_unlock synchronize_rcu |
| 811 | synchronize_rcu_expedited | ||
| 810 | call_rcu | 812 | call_rcu |
| 811 | 813 | ||
| 812 | 814 | ||
| 813 | bh: Critical sections Grace period Barrier | 815 | bh: Critical sections Grace period Barrier |
| 814 | 816 | ||
| 815 | rcu_read_lock_bh call_rcu_bh rcu_barrier_bh | 817 | rcu_read_lock_bh call_rcu_bh rcu_barrier_bh |
| 816 | rcu_read_unlock_bh | 818 | rcu_read_unlock_bh synchronize_rcu_bh |
| 819 | synchronize_rcu_bh_expedited | ||
| 817 | 820 | ||
| 818 | 821 | ||
| 819 | sched: Critical sections Grace period Barrier | 822 | sched: Critical sections Grace period Barrier |
| 820 | 823 | ||
| 821 | [preempt_disable] synchronize_sched rcu_barrier_sched | 824 | rcu_read_lock_sched synchronize_sched rcu_barrier_sched |
| 822 | [and friends] call_rcu_sched | 825 | rcu_read_unlock_sched call_rcu_sched |
| 826 | [preempt_disable] synchronize_sched_expedited | ||
| 827 | [and friends] | ||
| 823 | 828 | ||
| 824 | 829 | ||
| 825 | SRCU: Critical sections Grace period Barrier | 830 | SRCU: Critical sections Grace period Barrier |
| @@ -827,6 +832,9 @@ SRCU: Critical sections Grace period Barrier | |||
| 827 | srcu_read_lock synchronize_srcu N/A | 832 | srcu_read_lock synchronize_srcu N/A |
| 828 | srcu_read_unlock | 833 | srcu_read_unlock |
| 829 | 834 | ||
| 835 | SRCU: Initialization/cleanup | ||
| 836 | init_srcu_struct | ||
| 837 | cleanup_srcu_struct | ||
| 830 | 838 | ||
| 831 | See the comment headers in the source code (or the docbook generated | 839 | See the comment headers in the source code (or the docbook generated |
| 832 | from them) for more information. | 840 | from them) for more information. |
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5c555a8b39e5..b7f9d3b4bbf6 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches | |||
| @@ -183,7 +183,7 @@ the MAN-PAGES maintainer (as listed in the MAINTAINERS file) | |||
| 183 | a man-pages patch, or at least a notification of the change, | 183 | a man-pages patch, or at least a notification of the change, |
| 184 | so that some information makes its way into the manual pages. | 184 | so that some information makes its way into the manual pages. |
| 185 | 185 | ||
| 186 | Even if the maintainer did not respond in step #4, make sure to ALWAYS | 186 | Even if the maintainer did not respond in step #5, make sure to ALWAYS |
| 187 | copy the maintainer when you change their code. | 187 | copy the maintainer when you change their code. |
| 188 | 188 | ||
| 189 | For small patches you may want to CC the Trivial Patch Monkey | 189 | For small patches you may want to CC the Trivial Patch Monkey |
diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/OMAP/omap_pm new file mode 100644 index 000000000000..5389440aade3 --- /dev/null +++ b/Documentation/arm/OMAP/omap_pm | |||
| @@ -0,0 +1,129 @@ | |||
| 1 | |||
| 2 | The OMAP PM interface | ||
| 3 | ===================== | ||
| 4 | |||
| 5 | This document describes the temporary OMAP PM interface. Driver | ||
| 6 | authors use these functions to communicate minimum latency or | ||
| 7 | throughput constraints to the kernel power management code. | ||
| 8 | Over time, the intention is to merge features from the OMAP PM | ||
| 9 | interface into the Linux PM QoS code. | ||
| 10 | |||
| 11 | Drivers need to express PM parameters which: | ||
| 12 | |||
| 13 | - support the range of power management parameters present in the TI SRF; | ||
| 14 | |||
| 15 | - separate the drivers from the underlying PM parameter | ||
| 16 | implementation, whether it is the TI SRF or Linux PM QoS or Linux | ||
| 17 | latency framework or something else; | ||
| 18 | |||
| 19 | - specify PM parameters in terms of fundamental units, such as | ||
| 20 | latency and throughput, rather than units which are specific to OMAP | ||
| 21 | or to particular OMAP variants; | ||
| 22 | |||
| 23 | - allow drivers which are shared with other architectures (e.g., | ||
| 24 | DaVinci) to add these constraints in a way which won't affect non-OMAP | ||
| 25 | systems, | ||
| 26 | |||
| 27 | - can be implemented immediately with minimal disruption of other | ||
| 28 | architectures. | ||
| 29 | |||
| 30 | |||
| 31 | This document proposes the OMAP PM interface, including the following | ||
| 32 | five power management functions for driver code: | ||
| 33 | |||
| 34 | 1. Set the maximum MPU wakeup latency: | ||
| 35 | (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t) | ||
| 36 | |||
| 37 | 2. Set the maximum device wakeup latency: | ||
| 38 | (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) | ||
| 39 | |||
| 40 | 3. Set the maximum system DMA transfer start latency (CORE pwrdm): | ||
| 41 | (*pdata->set_max_sdma_lat)(struct device *dev, long t) | ||
| 42 | |||
| 43 | 4. Set the minimum bus throughput needed by a device: | ||
| 44 | (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r) | ||
| 45 | |||
| 46 | 5. Return the number of times the device has lost context | ||
| 47 | (*pdata->get_dev_context_loss_count)(struct device *dev) | ||
| 48 | |||
| 49 | |||
| 50 | Further documentation for all OMAP PM interface functions can be | ||
| 51 | found in arch/arm/plat-omap/include/mach/omap-pm.h. | ||
| 52 | |||
| 53 | |||
| 54 | The OMAP PM layer is intended to be temporary | ||
| 55 | --------------------------------------------- | ||
| 56 | |||
| 57 | The intention is that eventually the Linux PM QoS layer should support | ||
| 58 | the range of power management features present in OMAP3. As this | ||
| 59 | happens, existing drivers using the OMAP PM interface can be modified | ||
| 60 | to use the Linux PM QoS code; and the OMAP PM interface can disappear. | ||
| 61 | |||
| 62 | |||
| 63 | Driver usage of the OMAP PM functions | ||
| 64 | ------------------------------------- | ||
| 65 | |||
| 66 | As the 'pdata' in the above examples indicates, these functions are | ||
| 67 | exposed to drivers through function pointers in driver .platform_data | ||
| 68 | structures. The function pointers are initialized by the board-*.c | ||
| 69 | files to point to the corresponding OMAP PM functions: | ||
| 70 | .set_max_dev_wakeup_lat will point to | ||
| 71 | omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do | ||
| 72 | not support these functions should leave these function pointers set | ||
| 73 | to NULL. Drivers should use the following idiom: | ||
| 74 | |||
| 75 | if (pdata->set_max_dev_wakeup_lat) | ||
| 76 | (*pdata->set_max_dev_wakeup_lat)(dev, t); | ||
| 77 | |||
| 78 | The most common usage of these functions will probably be to specify | ||
| 79 | the maximum time from when an interrupt occurs, to when the device | ||
| 80 | becomes accessible. To accomplish this, driver writers should use the | ||
| 81 | set_max_mpu_wakeup_lat() function to to constrain the MPU wakeup | ||
| 82 | latency, and the set_max_dev_wakeup_lat() function to constrain the | ||
| 83 | device wakeup latency (from clk_enable() to accessibility). For | ||
| 84 | example, | ||
| 85 | |||
| 86 | /* Limit MPU wakeup latency */ | ||
| 87 | if (pdata->set_max_mpu_wakeup_lat) | ||
| 88 | (*pdata->set_max_mpu_wakeup_lat)(dev, tc); | ||
| 89 | |||
| 90 | /* Limit device powerdomain wakeup latency */ | ||
| 91 | if (pdata->set_max_dev_wakeup_lat) | ||
| 92 | (*pdata->set_max_dev_wakeup_lat)(dev, td); | ||
| 93 | |||
| 94 | /* total wakeup latency in this example: (tc + td) */ | ||
| 95 | |||
| 96 | The PM parameters can be overwritten by calling the function again | ||
| 97 | with the new value. The settings can be removed by calling the | ||
| 98 | function with a t argument of -1 (except in the case of | ||
| 99 | set_max_bus_tput(), which should be called with an r argument of 0). | ||
| 100 | |||
| 101 | The fifth function above, omap_pm_get_dev_context_loss_count(), | ||
| 102 | is intended as an optimization to allow drivers to determine whether the | ||
| 103 | device has lost its internal context. If context has been lost, the | ||
| 104 | driver must restore its internal context before proceeding. | ||
| 105 | |||
| 106 | |||
| 107 | Other specialized interface functions | ||
| 108 | ------------------------------------- | ||
| 109 | |||
| 110 | The five functions listed above are intended to be usable by any | ||
| 111 | device driver. DSPBridge and CPUFreq have a few special requirements. | ||
| 112 | DSPBridge expresses target DSP performance levels in terms of OPP IDs. | ||
| 113 | CPUFreq expresses target MPU performance levels in terms of MPU | ||
| 114 | frequency. The OMAP PM interface contains functions for these | ||
| 115 | specialized cases to convert that input information (OPPs/MPU | ||
| 116 | frequency) into the form that the underlying power management | ||
| 117 | implementation needs: | ||
| 118 | |||
| 119 | 6. (*pdata->dsp_get_opp_table)(void) | ||
| 120 | |||
| 121 | 7. (*pdata->dsp_set_min_opp)(u8 opp_id) | ||
| 122 | |||
| 123 | 8. (*pdata->dsp_get_opp)(void) | ||
| 124 | |||
| 125 | 9. (*pdata->cpu_get_freq_table)(void) | ||
| 126 | |||
| 127 | 10. (*pdata->cpu_set_freq)(unsigned long f) | ||
| 128 | |||
| 129 | 11. (*pdata->cpu_get_freq)(void) | ||
diff --git a/Documentation/arm/SA1100/ADSBitsy b/Documentation/arm/SA1100/ADSBitsy index ab47c3833908..7197a9e958ee 100644 --- a/Documentation/arm/SA1100/ADSBitsy +++ b/Documentation/arm/SA1100/ADSBitsy | |||
| @@ -40,4 +40,4 @@ Notes: | |||
| 40 | mode, the timing is off so the image is corrupted. This will be | 40 | mode, the timing is off so the image is corrupted. This will be |
| 41 | fixed soon. | 41 | fixed soon. |
| 42 | 42 | ||
| 43 | Any contribution can be sent to nico@cam.org and will be greatly welcome! | 43 | Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! |
diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/SA1100/Assabet index 78bc1c1b04e5..91f7ce7ba426 100644 --- a/Documentation/arm/SA1100/Assabet +++ b/Documentation/arm/SA1100/Assabet | |||
| @@ -240,7 +240,7 @@ Then, rebooting the Assabet is just a matter of waiting for the login prompt. | |||
| 240 | 240 | ||
| 241 | 241 | ||
| 242 | Nicolas Pitre | 242 | Nicolas Pitre |
| 243 | nico@cam.org | 243 | nico@fluxnic.net |
| 244 | June 12, 2001 | 244 | June 12, 2001 |
| 245 | 245 | ||
| 246 | 246 | ||
diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/SA1100/Brutus index 2254c8f0b326..b1cfd405dccc 100644 --- a/Documentation/arm/SA1100/Brutus +++ b/Documentation/arm/SA1100/Brutus | |||
| @@ -60,7 +60,7 @@ little modifications. | |||
| 60 | 60 | ||
| 61 | Any contribution is welcome. | 61 | Any contribution is welcome. |
| 62 | 62 | ||
| 63 | Please send patches to nico@cam.org | 63 | Please send patches to nico@fluxnic.net |
| 64 | 64 | ||
| 65 | Have Fun ! | 65 | Have Fun ! |
| 66 | 66 | ||
diff --git a/Documentation/arm/SA1100/GraphicsClient b/Documentation/arm/SA1100/GraphicsClient index 8fa7e8027ff1..6c9c4f5a36e1 100644 --- a/Documentation/arm/SA1100/GraphicsClient +++ b/Documentation/arm/SA1100/GraphicsClient | |||
| @@ -4,7 +4,7 @@ For more details, contact Applied Data Systems or see | |||
| 4 | http://www.applieddata.net/products.html | 4 | http://www.applieddata.net/products.html |
| 5 | 5 | ||
| 6 | The original Linux support for this product has been provided by | 6 | The original Linux support for this product has been provided by |
| 7 | Nicolas Pitre <nico@cam.org>. Continued development work by | 7 | Nicolas Pitre <nico@fluxnic.net>. Continued development work by |
| 8 | Woojung Huh <whuh@applieddata.net> | 8 | Woojung Huh <whuh@applieddata.net> |
| 9 | 9 | ||
| 10 | It's currently possible to mount a root filesystem via NFS providing a | 10 | It's currently possible to mount a root filesystem via NFS providing a |
| @@ -94,5 +94,5 @@ Notes: | |||
| 94 | mode, the timing is off so the image is corrupted. This will be | 94 | mode, the timing is off so the image is corrupted. This will be |
| 95 | fixed soon. | 95 | fixed soon. |
| 96 | 96 | ||
| 97 | Any contribution can be sent to nico@cam.org and will be greatly welcome! | 97 | Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! |
| 98 | 98 | ||
diff --git a/Documentation/arm/SA1100/GraphicsMaster b/Documentation/arm/SA1100/GraphicsMaster index dd28745ac521..ee7c6595f23f 100644 --- a/Documentation/arm/SA1100/GraphicsMaster +++ b/Documentation/arm/SA1100/GraphicsMaster | |||
| @@ -4,7 +4,7 @@ For more details, contact Applied Data Systems or see | |||
| 4 | http://www.applieddata.net/products.html | 4 | http://www.applieddata.net/products.html |
| 5 | 5 | ||
| 6 | The original Linux support for this product has been provided by | 6 | The original Linux support for this product has been provided by |
| 7 | Nicolas Pitre <nico@cam.org>. Continued development work by | 7 | Nicolas Pitre <nico@fluxnic.net>. Continued development work by |
| 8 | Woojung Huh <whuh@applieddata.net> | 8 | Woojung Huh <whuh@applieddata.net> |
| 9 | 9 | ||
| 10 | Use 'make graphicsmaster_config' before any 'make config'. | 10 | Use 'make graphicsmaster_config' before any 'make config'. |
| @@ -50,4 +50,4 @@ Notes: | |||
| 50 | mode, the timing is off so the image is corrupted. This will be | 50 | mode, the timing is off so the image is corrupted. This will be |
| 51 | fixed soon. | 51 | fixed soon. |
| 52 | 52 | ||
| 53 | Any contribution can be sent to nico@cam.org and will be greatly welcome! | 53 | Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! |
diff --git a/Documentation/arm/SA1100/Victor b/Documentation/arm/SA1100/Victor index 01e81fc49461..f938a29fdc20 100644 --- a/Documentation/arm/SA1100/Victor +++ b/Documentation/arm/SA1100/Victor | |||
| @@ -9,7 +9,7 @@ Of course Victor is using Linux as its main operating system. | |||
| 9 | The Victor implementation for Linux is maintained by Nicolas Pitre: | 9 | The Victor implementation for Linux is maintained by Nicolas Pitre: |
| 10 | 10 | ||
| 11 | nico@visuaide.com | 11 | nico@visuaide.com |
| 12 | nico@cam.org | 12 | nico@fluxnic.net |
| 13 | 13 | ||
| 14 | For any comments, please feel free to contact me through the above | 14 | For any comments, please feel free to contact me through the above |
| 15 | addresses. | 15 | addresses. |
diff --git a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt b/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt new file mode 100644 index 000000000000..76b3a11e90be --- /dev/null +++ b/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | S3C24XX CPUfreq support | ||
| 2 | ======================= | ||
| 3 | |||
| 4 | Introduction | ||
| 5 | ------------ | ||
| 6 | |||
| 7 | The S3C24XX series support a number of power saving systems, such as | ||
| 8 | the ability to change the core, memory and peripheral operating | ||
| 9 | frequencies. The core control is exported via the CPUFreq driver | ||
| 10 | which has a number of different manual or automatic controls over the | ||
| 11 | rate the core is running at. | ||
| 12 | |||
| 13 | There are two forms of the driver depending on the specific CPU and | ||
| 14 | how the clocks are arranged. The first implementation used as single | ||
| 15 | PLL to feed the ARM, memory and peripherals via a series of dividers | ||
| 16 | and muxes and this is the implementation that is documented here. A | ||
| 17 | newer version where there is a seperate PLL and clock divider for the | ||
| 18 | ARM core is available as a seperate driver. | ||
| 19 | |||
| 20 | |||
| 21 | Layout | ||
| 22 | ------ | ||
| 23 | |||
| 24 | The code core manages the CPU specific drivers, any data that they | ||
| 25 | need to register and the interface to the generic drivers/cpufreq | ||
| 26 | system. Each CPU registers a driver to control the PLL, clock dividers | ||
| 27 | and anything else associated with it. Any board that wants to use this | ||
| 28 | framework needs to supply at least basic details of what is required. | ||
| 29 | |||
| 30 | The core registers with drivers/cpufreq at init time if all the data | ||
| 31 | necessary has been supplied. | ||
| 32 | |||
| 33 | |||
| 34 | CPU support | ||
| 35 | ----------- | ||
| 36 | |||
| 37 | The support for each CPU depends on the facilities provided by the | ||
| 38 | SoC and the driver as each device has different PLL and clock chains | ||
| 39 | associated with it. | ||
| 40 | |||
| 41 | |||
| 42 | Slow Mode | ||
| 43 | --------- | ||
| 44 | |||
| 45 | The SLOW mode where the PLL is turned off altogether and the | ||
| 46 | system is fed by the external crystal input is currently not | ||
| 47 | supported. | ||
| 48 | |||
| 49 | |||
| 50 | sysfs | ||
| 51 | ----- | ||
| 52 | |||
| 53 | The core code exports extra information via sysfs in the directory | ||
| 54 | devices/system/cpu/cpu0/arch-freq. | ||
| 55 | |||
| 56 | |||
| 57 | Board Support | ||
| 58 | ------------- | ||
| 59 | |||
| 60 | Each board that wants to use the cpufreq code must register some basic | ||
| 61 | information with the core driver to provide information about what the | ||
| 62 | board requires and any restrictions being placed on it. | ||
| 63 | |||
| 64 | The board needs to supply information about whether it needs the IO bank | ||
| 65 | timings changing, any maximum frequency limits and information about the | ||
| 66 | SDRAM refresh rate. | ||
| 67 | |||
| 68 | |||
| 69 | |||
| 70 | |||
| 71 | Document Author | ||
| 72 | --------------- | ||
| 73 | |||
| 74 | Ben Dooks, Copyright 2009 Simtec Electronics | ||
| 75 | Licensed under GPLv2 | ||
diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index 43cb1004d35f..9d58c7c5eddd 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt | |||
| @@ -21,6 +21,8 @@ ffff8000 ffffffff copy_user_page / clear_user_page use. | |||
| 21 | For SA11xx and Xscale, this is used to | 21 | For SA11xx and Xscale, this is used to |
| 22 | setup a minicache mapping. | 22 | setup a minicache mapping. |
| 23 | 23 | ||
| 24 | ffff4000 ffffffff cache aliasing on ARMv6 and later CPUs. | ||
| 25 | |||
| 24 | ffff1000 ffff7fff Reserved. | 26 | ffff1000 ffff7fff Reserved. |
| 25 | Platforms must not use this address range. | 27 | Platforms must not use this address range. |
| 26 | 28 | ||
diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.txt index e8ca040ba2cf..2d735b0ae383 100644 --- a/Documentation/block/data-integrity.txt +++ b/Documentation/block/data-integrity.txt | |||
| @@ -50,7 +50,7 @@ encouraged them to allow separation of the data and integrity metadata | |||
| 50 | scatter-gather lists. | 50 | scatter-gather lists. |
| 51 | 51 | ||
| 52 | The controller will interleave the buffers on write and split them on | 52 | The controller will interleave the buffers on write and split them on |
| 53 | read. This means that the Linux can DMA the data buffers to and from | 53 | read. This means that Linux can DMA the data buffers to and from |
| 54 | host memory without changes to the page cache. | 54 | host memory without changes to the page cache. |
| 55 | 55 | ||
| 56 | Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs | 56 | Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs |
| @@ -66,7 +66,7 @@ software RAID5). | |||
| 66 | 66 | ||
| 67 | The IP checksum is weaker than the CRC in terms of detecting bit | 67 | The IP checksum is weaker than the CRC in terms of detecting bit |
| 68 | errors. However, the strength is really in the separation of the data | 68 | errors. However, the strength is really in the separation of the data |
| 69 | buffers and the integrity metadata. These two distinct buffers much | 69 | buffers and the integrity metadata. These two distinct buffers must |
| 70 | match up for an I/O to complete. | 70 | match up for an I/O to complete. |
| 71 | 71 | ||
| 72 | The separation of the data and integrity metadata buffers as well as | 72 | The separation of the data and integrity metadata buffers as well as |
diff --git a/Documentation/btmrvl.txt b/Documentation/btmrvl.txt new file mode 100644 index 000000000000..34916a46c099 --- /dev/null +++ b/Documentation/btmrvl.txt | |||
| @@ -0,0 +1,119 @@ | |||
| 1 | ======================================================================= | ||
| 2 | README for btmrvl driver | ||
| 3 | ======================================================================= | ||
| 4 | |||
| 5 | |||
| 6 | All commands are used via debugfs interface. | ||
| 7 | |||
| 8 | ===================== | ||
| 9 | Set/get driver configurations: | ||
| 10 | |||
| 11 | Path: /debug/btmrvl/config/ | ||
| 12 | |||
| 13 | gpiogap=[n] | ||
| 14 | hscfgcmd | ||
| 15 | These commands are used to configure the host sleep parameters. | ||
| 16 | bit 8:0 -- Gap | ||
| 17 | bit 16:8 -- GPIO | ||
| 18 | |||
| 19 | where GPIO is the pin number of GPIO used to wake up the host. | ||
| 20 | It could be any valid GPIO pin# (e.g. 0-7) or 0xff (SDIO interface | ||
| 21 | wakeup will be used instead). | ||
| 22 | |||
| 23 | where Gap is the gap in milli seconds between wakeup signal and | ||
| 24 | wakeup event, or 0xff for special host sleep setting. | ||
| 25 | |||
| 26 | Usage: | ||
| 27 | # Use SDIO interface to wake up the host and set GAP to 0x80: | ||
| 28 | echo 0xff80 > /debug/btmrvl/config/gpiogap | ||
| 29 | echo 1 > /debug/btmrvl/config/hscfgcmd | ||
| 30 | |||
| 31 | # Use GPIO pin #3 to wake up the host and set GAP to 0xff: | ||
| 32 | echo 0x03ff > /debug/btmrvl/config/gpiogap | ||
| 33 | echo 1 > /debug/btmrvl/config/hscfgcmd | ||
| 34 | |||
| 35 | psmode=[n] | ||
| 36 | pscmd | ||
| 37 | These commands are used to enable/disable auto sleep mode | ||
| 38 | |||
| 39 | where the option is: | ||
| 40 | 1 -- Enable auto sleep mode | ||
| 41 | 0 -- Disable auto sleep mode | ||
| 42 | |||
| 43 | Usage: | ||
| 44 | # Enable auto sleep mode | ||
| 45 | echo 1 > /debug/btmrvl/config/psmode | ||
| 46 | echo 1 > /debug/btmrvl/config/pscmd | ||
| 47 | |||
| 48 | # Disable auto sleep mode | ||
| 49 | echo 0 > /debug/btmrvl/config/psmode | ||
| 50 | echo 1 > /debug/btmrvl/config/pscmd | ||
| 51 | |||
| 52 | |||
| 53 | hsmode=[n] | ||
| 54 | hscmd | ||
| 55 | These commands are used to enable host sleep or wake up firmware | ||
| 56 | |||
| 57 | where the option is: | ||
| 58 | 1 -- Enable host sleep | ||
| 59 | 0 -- Wake up firmware | ||
| 60 | |||
| 61 | Usage: | ||
| 62 | # Enable host sleep | ||
| 63 | echo 1 > /debug/btmrvl/config/hsmode | ||
| 64 | echo 1 > /debug/btmrvl/config/hscmd | ||
| 65 | |||
| 66 | # Wake up firmware | ||
| 67 | echo 0 > /debug/btmrvl/config/hsmode | ||
| 68 | echo 1 > /debug/btmrvl/config/hscmd | ||
| 69 | |||
| 70 | |||
| 71 | ====================== | ||
| 72 | Get driver status: | ||
| 73 | |||
| 74 | Path: /debug/btmrvl/status/ | ||
| 75 | |||
| 76 | Usage: | ||
| 77 | cat /debug/btmrvl/status/<args> | ||
| 78 | |||
| 79 | where the args are: | ||
| 80 | |||
| 81 | curpsmode | ||
| 82 | This command displays current auto sleep status. | ||
| 83 | |||
| 84 | psstate | ||
| 85 | This command display the power save state. | ||
| 86 | |||
| 87 | hsstate | ||
| 88 | This command display the host sleep state. | ||
| 89 | |||
| 90 | txdnldrdy | ||
| 91 | This command displays the value of Tx download ready flag. | ||
| 92 | |||
| 93 | |||
| 94 | ===================== | ||
| 95 | |||
| 96 | Use hcitool to issue raw hci command, refer to hcitool manual | ||
| 97 | |||
| 98 | Usage: Hcitool cmd <ogf> <ocf> [Parameters] | ||
| 99 | |||
| 100 | Interface Control Command | ||
| 101 | hcitool cmd 0x3f 0x5b 0xf5 0x01 0x00 --Enable All interface | ||
| 102 | hcitool cmd 0x3f 0x5b 0xf5 0x01 0x01 --Enable Wlan interface | ||
| 103 | hcitool cmd 0x3f 0x5b 0xf5 0x01 0x02 --Enable BT interface | ||
| 104 | hcitool cmd 0x3f 0x5b 0xf5 0x00 0x00 --Disable All interface | ||
| 105 | hcitool cmd 0x3f 0x5b 0xf5 0x00 0x01 --Disable Wlan interface | ||
| 106 | hcitool cmd 0x3f 0x5b 0xf5 0x00 0x02 --Disable BT interface | ||
| 107 | |||
| 108 | ======================================================================= | ||
| 109 | |||
| 110 | |||
| 111 | SD8688 firmware: | ||
| 112 | |||
| 113 | /lib/firmware/sd8688_helper.bin | ||
| 114 | /lib/firmware/sd8688.bin | ||
| 115 | |||
| 116 | |||
| 117 | The images can be downloaded from: | ||
| 118 | |||
| 119 | git.infradead.org/users/dwmw2/linux-firmware.git/libertas/ | ||
diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index f9ca389dddf4..1d7e9784439a 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt | |||
| @@ -777,6 +777,18 @@ in cpuset directories: | |||
| 777 | # /bin/echo 1-4 > cpus -> set cpus list to cpus 1,2,3,4 | 777 | # /bin/echo 1-4 > cpus -> set cpus list to cpus 1,2,3,4 |
| 778 | # /bin/echo 1,2,3,4 > cpus -> set cpus list to cpus 1,2,3,4 | 778 | # /bin/echo 1,2,3,4 > cpus -> set cpus list to cpus 1,2,3,4 |
| 779 | 779 | ||
| 780 | To add a CPU to a cpuset, write the new list of CPUs including the | ||
| 781 | CPU to be added. To add 6 to the above cpuset: | ||
| 782 | |||
| 783 | # /bin/echo 1-4,6 > cpus -> set cpus list to cpus 1,2,3,4,6 | ||
| 784 | |||
| 785 | Similarly to remove a CPU from a cpuset, write the new list of CPUs | ||
| 786 | without the CPU to be removed. | ||
| 787 | |||
| 788 | To remove all the CPUs: | ||
| 789 | |||
| 790 | # /bin/echo "" > cpus -> clear cpus list | ||
| 791 | |||
| 780 | 2.3 Setting flags | 792 | 2.3 Setting flags |
| 781 | ----------------- | 793 | ----------------- |
| 782 | 794 | ||
diff --git a/Documentation/connector/Makefile b/Documentation/connector/Makefile index 8df1a7285a06..d98e4df98e24 100644 --- a/Documentation/connector/Makefile +++ b/Documentation/connector/Makefile | |||
| @@ -9,3 +9,8 @@ hostprogs-y := ucon | |||
| 9 | always := $(hostprogs-y) | 9 | always := $(hostprogs-y) |
| 10 | 10 | ||
| 11 | HOSTCFLAGS_ucon.o += -I$(objtree)/usr/include | 11 | HOSTCFLAGS_ucon.o += -I$(objtree)/usr/include |
| 12 | |||
| 13 | all: modules | ||
| 14 | |||
| 15 | modules clean: | ||
| 16 | $(MAKE) -C ../.. SUBDIRS=$(PWD) $@ | ||
diff --git a/Documentation/connector/cn_test.c b/Documentation/connector/cn_test.c index f688eba87704..1711adc33373 100644 --- a/Documentation/connector/cn_test.c +++ b/Documentation/connector/cn_test.c | |||
| @@ -1,7 +1,7 @@ | |||
| 1 | /* | 1 | /* |
| 2 | * cn_test.c | 2 | * cn_test.c |
| 3 | * | 3 | * |
| 4 | * 2004-2005 Copyright (c) Evgeniy Polyakov <johnpol@2ka.mipt.ru> | 4 | * 2004+ Copyright (c) Evgeniy Polyakov <zbr@ioremap.net> |
| 5 | * All rights reserved. | 5 | * All rights reserved. |
| 6 | * | 6 | * |
| 7 | * This program is free software; you can redistribute it and/or modify | 7 | * This program is free software; you can redistribute it and/or modify |
| @@ -19,6 +19,8 @@ | |||
| 19 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | 19 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 20 | */ | 20 | */ |
| 21 | 21 | ||
| 22 | #define pr_fmt(fmt) "cn_test: " fmt | ||
| 23 | |||
| 22 | #include <linux/kernel.h> | 24 | #include <linux/kernel.h> |
| 23 | #include <linux/module.h> | 25 | #include <linux/module.h> |
| 24 | #include <linux/moduleparam.h> | 26 | #include <linux/moduleparam.h> |
| @@ -27,18 +29,17 @@ | |||
| 27 | 29 | ||
| 28 | #include <linux/connector.h> | 30 | #include <linux/connector.h> |
| 29 | 31 | ||
| 30 | static struct cb_id cn_test_id = { 0x123, 0x456 }; | 32 | static struct cb_id cn_test_id = { CN_NETLINK_USERS + 3, 0x456 }; |
| 31 | static char cn_test_name[] = "cn_test"; | 33 | static char cn_test_name[] = "cn_test"; |
| 32 | static struct sock *nls; | 34 | static struct sock *nls; |
| 33 | static struct timer_list cn_test_timer; | 35 | static struct timer_list cn_test_timer; |
| 34 | 36 | ||
| 35 | void cn_test_callback(void *data) | 37 | static void cn_test_callback(struct cn_msg *msg) |
| 36 | { | 38 | { |
| 37 | struct cn_msg *msg = (struct cn_msg *)data; | 39 | pr_info("%s: %lu: idx=%x, val=%x, seq=%u, ack=%u, len=%d: %s.\n", |
| 38 | 40 | __func__, jiffies, msg->id.idx, msg->id.val, | |
| 39 | printk("%s: %lu: idx=%x, val=%x, seq=%u, ack=%u, len=%d: %s.\n", | 41 | msg->seq, msg->ack, msg->len, |
| 40 | __func__, jiffies, msg->id.idx, msg->id.val, | 42 | msg->len ? (char *)msg->data : ""); |
| 41 | msg->seq, msg->ack, msg->len, (char *)msg->data); | ||
| 42 | } | 43 | } |
| 43 | 44 | ||
| 44 | /* | 45 | /* |
| @@ -63,9 +64,7 @@ static int cn_test_want_notify(void) | |||
| 63 | 64 | ||
| 64 | skb = alloc_skb(size, GFP_ATOMIC); | 65 | skb = alloc_skb(size, GFP_ATOMIC); |
| 65 | if (!skb) { | 66 | if (!skb) { |
| 66 | printk(KERN_ERR "Failed to allocate new skb with size=%u.\n", | 67 | pr_err("failed to allocate new skb with size=%u\n", size); |
| 67 | size); | ||
| 68 | |||
| 69 | return -ENOMEM; | 68 | return -ENOMEM; |
| 70 | } | 69 | } |
| 71 | 70 | ||
| @@ -114,12 +113,12 @@ static int cn_test_want_notify(void) | |||
| 114 | //netlink_broadcast(nls, skb, 0, ctl->group, GFP_ATOMIC); | 113 | //netlink_broadcast(nls, skb, 0, ctl->group, GFP_ATOMIC); |
| 115 | netlink_unicast(nls, skb, 0, 0); | 114 | netlink_unicast(nls, skb, 0, 0); |
| 116 | 115 | ||
| 117 | printk(KERN_INFO "Request was sent. Group=0x%x.\n", ctl->group); | 116 | pr_info("request was sent: group=0x%x\n", ctl->group); |
| 118 | 117 | ||
| 119 | return 0; | 118 | return 0; |
| 120 | 119 | ||
| 121 | nlmsg_failure: | 120 | nlmsg_failure: |
| 122 | printk(KERN_ERR "Failed to send %u.%u\n", msg->seq, msg->ack); | 121 | pr_err("failed to send %u.%u\n", msg->seq, msg->ack); |
| 123 | kfree_skb(skb); | 122 | kfree_skb(skb); |
| 124 | return -EINVAL; | 123 | return -EINVAL; |
| 125 | } | 124 | } |
| @@ -131,6 +130,8 @@ static void cn_test_timer_func(unsigned long __data) | |||
| 131 | struct cn_msg *m; | 130 | struct cn_msg *m; |
| 132 | char data[32]; | 131 | char data[32]; |
| 133 | 132 | ||
| 133 | pr_debug("%s: timer fired with data %lu\n", __func__, __data); | ||
| 134 | |||
| 134 | m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); | 135 | m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); |
| 135 | if (m) { | 136 | if (m) { |
| 136 | 137 | ||
| @@ -150,7 +151,7 @@ static void cn_test_timer_func(unsigned long __data) | |||
| 150 | 151 | ||
| 151 | cn_test_timer_counter++; | 152 | cn_test_timer_counter++; |
| 152 | 153 | ||
| 153 | mod_timer(&cn_test_timer, jiffies + HZ); | 154 | mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); |
| 154 | } | 155 | } |
| 155 | 156 | ||
| 156 | static int cn_test_init(void) | 157 | static int cn_test_init(void) |
| @@ -168,8 +169,10 @@ static int cn_test_init(void) | |||
| 168 | } | 169 | } |
| 169 | 170 | ||
| 170 | setup_timer(&cn_test_timer, cn_test_timer_func, 0); | 171 | setup_timer(&cn_test_timer, cn_test_timer_func, 0); |
| 171 | cn_test_timer.expires = jiffies + HZ; | 172 | mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000)); |
| 172 | add_timer(&cn_test_timer); | 173 | |
| 174 | pr_info("initialized with id={%u.%u}\n", | ||
| 175 | cn_test_id.idx, cn_test_id.val); | ||
| 173 | 176 | ||
| 174 | return 0; | 177 | return 0; |
| 175 | 178 | ||
| @@ -194,5 +197,5 @@ module_init(cn_test_init); | |||
| 194 | module_exit(cn_test_fini); | 197 | module_exit(cn_test_fini); |
| 195 | 198 | ||
| 196 | MODULE_LICENSE("GPL"); | 199 | MODULE_LICENSE("GPL"); |
| 197 | MODULE_AUTHOR("Evgeniy Polyakov <johnpol@2ka.mipt.ru>"); | 200 | MODULE_AUTHOR("Evgeniy Polyakov <zbr@ioremap.net>"); |
| 198 | MODULE_DESCRIPTION("Connector's test module"); | 201 | MODULE_DESCRIPTION("Connector's test module"); |
diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt index ad6e0ba7b38c..81e6bf6ead57 100644 --- a/Documentation/connector/connector.txt +++ b/Documentation/connector/connector.txt | |||
| @@ -5,10 +5,10 @@ Kernel Connector. | |||
| 5 | Kernel connector - new netlink based userspace <-> kernel space easy | 5 | Kernel connector - new netlink based userspace <-> kernel space easy |
| 6 | to use communication module. | 6 | to use communication module. |
| 7 | 7 | ||
| 8 | Connector driver adds possibility to connect various agents using | 8 | The Connector driver makes it easy to connect various agents using a |
| 9 | netlink based network. One must register callback and | 9 | netlink based network. One must register a callback and an identifier. |
| 10 | identifier. When driver receives special netlink message with | 10 | When the driver receives a special netlink message with the appropriate |
| 11 | appropriate identifier, appropriate callback will be called. | 11 | identifier, the appropriate callback will be called. |
| 12 | 12 | ||
| 13 | From the userspace point of view it's quite straightforward: | 13 | From the userspace point of view it's quite straightforward: |
| 14 | 14 | ||
| @@ -17,10 +17,10 @@ From the userspace point of view it's quite straightforward: | |||
| 17 | send(); | 17 | send(); |
| 18 | recv(); | 18 | recv(); |
| 19 | 19 | ||
| 20 | But if kernelspace want to use full power of such connections, driver | 20 | But if kernelspace wants to use the full power of such connections, the |
| 21 | writer must create special sockets, must know about struct sk_buff | 21 | driver writer must create special sockets, must know about struct sk_buff |
| 22 | handling... Connector allows any kernelspace agents to use netlink | 22 | handling, etc... The Connector driver allows any kernelspace agents to use |
| 23 | based networking for inter-process communication in a significantly | 23 | netlink based networking for inter-process communication in a significantly |
| 24 | easier way: | 24 | easier way: |
| 25 | 25 | ||
| 26 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); | 26 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); |
| @@ -32,15 +32,15 @@ struct cb_id | |||
| 32 | __u32 val; | 32 | __u32 val; |
| 33 | }; | 33 | }; |
| 34 | 34 | ||
| 35 | idx and val are unique identifiers which must be registered in | 35 | idx and val are unique identifiers which must be registered in the |
| 36 | connector.h for in-kernel usage. void (*callback) (void *) - is a | 36 | connector.h header for in-kernel usage. void (*callback) (void *) is a |
| 37 | callback function which will be called when message with above idx.val | 37 | callback function which will be called when a message with above idx.val |
| 38 | will be received by connector core. Argument for that function must | 38 | is received by the connector core. The argument for that function must |
| 39 | be dereferenced to struct cn_msg *. | 39 | be dereferenced to struct cn_msg *. |
| 40 | 40 | ||
| 41 | struct cn_msg | 41 | struct cn_msg |
| 42 | { | 42 | { |
| 43 | struct cb_id id; | 43 | struct cb_id id; |
| 44 | 44 | ||
| 45 | __u32 seq; | 45 | __u32 seq; |
| 46 | __u32 ack; | 46 | __u32 ack; |
| @@ -55,92 +55,95 @@ Connector interfaces. | |||
| 55 | 55 | ||
| 56 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); | 56 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); |
| 57 | 57 | ||
| 58 | Registers new callback with connector core. | 58 | Registers new callback with connector core. |
| 59 | 59 | ||
| 60 | struct cb_id *id - unique connector's user identifier. | 60 | struct cb_id *id - unique connector's user identifier. |
| 61 | It must be registered in connector.h for legal in-kernel users. | 61 | It must be registered in connector.h for legal in-kernel users. |
| 62 | char *name - connector's callback symbolic name. | 62 | char *name - connector's callback symbolic name. |
| 63 | void (*callback) (void *) - connector's callback. | 63 | void (*callback) (void *) - connector's callback. |
| 64 | Argument must be dereferenced to struct cn_msg *. | 64 | Argument must be dereferenced to struct cn_msg *. |
| 65 | 65 | ||
| 66 | |||
| 66 | void cn_del_callback(struct cb_id *id); | 67 | void cn_del_callback(struct cb_id *id); |
| 67 | 68 | ||
| 68 | Unregisters new callback with connector core. | 69 | Unregisters new callback with connector core. |
| 70 | |||
| 71 | struct cb_id *id - unique connector's user identifier. | ||
| 69 | 72 | ||
| 70 | struct cb_id *id - unique connector's user identifier. | ||
| 71 | 73 | ||
| 72 | int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); | 74 | int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); |
| 73 | 75 | ||
| 74 | Sends message to the specified groups. It can be safely called from | 76 | Sends message to the specified groups. It can be safely called from |
| 75 | softirq context, but may silently fail under strong memory pressure. | 77 | softirq context, but may silently fail under strong memory pressure. |
| 76 | If there are no listeners for given group -ESRCH can be returned. | 78 | If there are no listeners for given group -ESRCH can be returned. |
| 77 | 79 | ||
| 78 | struct cn_msg * - message header(with attached data). | 80 | struct cn_msg * - message header(with attached data). |
| 79 | u32 __group - destination group. | 81 | u32 __group - destination group. |
| 80 | If __group is zero, then appropriate group will | 82 | If __group is zero, then appropriate group will |
| 81 | be searched through all registered connector users, | 83 | be searched through all registered connector users, |
| 82 | and message will be delivered to the group which was | 84 | and message will be delivered to the group which was |
| 83 | created for user with the same ID as in msg. | 85 | created for user with the same ID as in msg. |
| 84 | If __group is not zero, then message will be delivered | 86 | If __group is not zero, then message will be delivered |
| 85 | to the specified group. | 87 | to the specified group. |
| 86 | int gfp_mask - GFP mask. | 88 | int gfp_mask - GFP mask. |
| 87 | 89 | ||
| 88 | Note: When registering new callback user, connector core assigns | 90 | Note: When registering new callback user, connector core assigns |
| 89 | netlink group to the user which is equal to it's id.idx. | 91 | netlink group to the user which is equal to it's id.idx. |
| 90 | 92 | ||
| 91 | /*****************************************/ | 93 | /*****************************************/ |
| 92 | Protocol description. | 94 | Protocol description. |
| 93 | /*****************************************/ | 95 | /*****************************************/ |
| 94 | 96 | ||
| 95 | Current offers transport layer with fixed header. Recommended | 97 | The current framework offers a transport layer with fixed headers. The |
| 96 | protocol which uses such header is following: | 98 | recommended protocol which uses such a header is as following: |
| 97 | 99 | ||
| 98 | msg->seq and msg->ack are used to determine message genealogy. When | 100 | msg->seq and msg->ack are used to determine message genealogy. When |
| 99 | someone sends message it puts there locally unique sequence and random | 101 | someone sends a message, they use a locally unique sequence and random |
| 100 | acknowledge numbers. Sequence number may be copied into | 102 | acknowledge number. The sequence number may be copied into |
| 101 | nlmsghdr->nlmsg_seq too. | 103 | nlmsghdr->nlmsg_seq too. |
| 102 | 104 | ||
| 103 | Sequence number is incremented with each message to be sent. | 105 | The sequence number is incremented with each message sent. |
| 104 | 106 | ||
| 105 | If we expect reply to our message, then sequence number in received | 107 | If you expect a reply to the message, then the sequence number in the |
| 106 | message MUST be the same as in original message, and acknowledge | 108 | received message MUST be the same as in the original message, and the |
| 107 | number MUST be the same + 1. | 109 | acknowledge number MUST be the same + 1. |
| 108 | 110 | ||
| 109 | If we receive message and it's sequence number is not equal to one we | 111 | If we receive a message and its sequence number is not equal to one we |
| 110 | are expecting, then it is new message. If we receive message and it's | 112 | are expecting, then it is a new message. If we receive a message and |
| 111 | sequence number is the same as one we are expecting, but it's | 113 | its sequence number is the same as one we are expecting, but its |
| 112 | acknowledge is not equal acknowledge number in original message + 1, | 114 | acknowledge is not equal to the acknowledge number in the original |
| 113 | then it is new message. | 115 | message + 1, then it is a new message. |
| 114 | 116 | ||
| 115 | Obviously, protocol header contains above id. | 117 | Obviously, the protocol header contains the above id. |
| 116 | 118 | ||
| 117 | connector allows event notification in the following form: kernel | 119 | The connector allows event notification in the following form: kernel |
| 118 | driver or userspace process can ask connector to notify it when | 120 | driver or userspace process can ask connector to notify it when |
| 119 | selected id's will be turned on or off(registered or unregistered it's | 121 | selected ids will be turned on or off (registered or unregistered its |
| 120 | callback). It is done by sending special command to connector | 122 | callback). It is done by sending a special command to the connector |
| 121 | driver(it also registers itself with id={-1, -1}). | 123 | driver (it also registers itself with id={-1, -1}). |
| 122 | 124 | ||
| 123 | As example of usage Documentation/connector now contains cn_test.c - | 125 | As example of this usage can be found in the cn_test.c module which |
| 124 | testing module which uses connector to request notification and to | 126 | uses the connector to request notification and to send messages. |
| 125 | send messages. | ||
| 126 | 127 | ||
| 127 | /*****************************************/ | 128 | /*****************************************/ |
| 128 | Reliability. | 129 | Reliability. |
| 129 | /*****************************************/ | 130 | /*****************************************/ |
| 130 | 131 | ||
| 131 | Netlink itself is not reliable protocol, that means that messages can | 132 | Netlink itself is not a reliable protocol. That means that messages can |
| 132 | be lost due to memory pressure or process' receiving queue overflowed, | 133 | be lost due to memory pressure or process' receiving queue overflowed, |
| 133 | so caller is warned must be prepared. That is why struct cn_msg [main | 134 | so caller is warned that it must be prepared. That is why the struct |
| 134 | connector's message header] contains u32 seq and u32 ack fields. | 135 | cn_msg [main connector's message header] contains u32 seq and u32 ack |
| 136 | fields. | ||
| 135 | 137 | ||
| 136 | /*****************************************/ | 138 | /*****************************************/ |
| 137 | Userspace usage. | 139 | Userspace usage. |
| 138 | /*****************************************/ | 140 | /*****************************************/ |
| 141 | |||
| 139 | 2.6.14 has a new netlink socket implementation, which by default does not | 142 | 2.6.14 has a new netlink socket implementation, which by default does not |
| 140 | allow to send data to netlink groups other than 1. | 143 | allow people to send data to netlink groups other than 1. |
| 141 | So, if to use netlink socket (for example using connector) | 144 | So, if you wish to use a netlink socket (for example using connector) |
| 142 | with different group number userspace application must subscribe to | 145 | with a different group number, the userspace application must subscribe to |
| 143 | that group. It can be achieved by following pseudocode: | 146 | that group first. It can be achieved by the following pseudocode: |
| 144 | 147 | ||
| 145 | s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); | 148 | s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); |
| 146 | 149 | ||
| @@ -160,8 +163,8 @@ if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { | |||
| 160 | } | 163 | } |
| 161 | 164 | ||
| 162 | Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket | 165 | Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket |
| 163 | option. To drop multicast subscription one should call above socket option | 166 | option. To drop a multicast subscription, one should call the above socket |
| 164 | with NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. | 167 | option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. |
| 165 | 168 | ||
| 166 | 2.6.14 netlink code only allows to select a group which is less or equal to | 169 | 2.6.14 netlink code only allows to select a group which is less or equal to |
| 167 | the maximum group number, which is used at netlink_kernel_create() time. | 170 | the maximum group number, which is used at netlink_kernel_create() time. |
diff --git a/Documentation/connector/ucon.c b/Documentation/connector/ucon.c index d738cde2a8d5..4848db8c71ff 100644 --- a/Documentation/connector/ucon.c +++ b/Documentation/connector/ucon.c | |||
| @@ -1,7 +1,7 @@ | |||
| 1 | /* | 1 | /* |
| 2 | * ucon.c | 2 | * ucon.c |
| 3 | * | 3 | * |
| 4 | * Copyright (c) 2004+ Evgeniy Polyakov <johnpol@2ka.mipt.ru> | 4 | * Copyright (c) 2004+ Evgeniy Polyakov <zbr@ioremap.net> |
| 5 | * | 5 | * |
| 6 | * | 6 | * |
| 7 | * This program is free software; you can redistribute it and/or modify | 7 | * This program is free software; you can redistribute it and/or modify |
| @@ -30,18 +30,24 @@ | |||
| 30 | 30 | ||
| 31 | #include <arpa/inet.h> | 31 | #include <arpa/inet.h> |
| 32 | 32 | ||
| 33 | #include <stdbool.h> | ||
| 33 | #include <stdio.h> | 34 | #include <stdio.h> |
| 34 | #include <stdlib.h> | 35 | #include <stdlib.h> |
| 35 | #include <unistd.h> | 36 | #include <unistd.h> |
| 36 | #include <string.h> | 37 | #include <string.h> |
| 37 | #include <errno.h> | 38 | #include <errno.h> |
| 38 | #include <time.h> | 39 | #include <time.h> |
| 40 | #include <getopt.h> | ||
| 39 | 41 | ||
| 40 | #include <linux/connector.h> | 42 | #include <linux/connector.h> |
| 41 | 43 | ||
| 42 | #define DEBUG | 44 | #define DEBUG |
| 43 | #define NETLINK_CONNECTOR 11 | 45 | #define NETLINK_CONNECTOR 11 |
| 44 | 46 | ||
| 47 | /* Hopefully your userspace connector.h matches this kernel */ | ||
| 48 | #define CN_TEST_IDX CN_NETLINK_USERS + 3 | ||
| 49 | #define CN_TEST_VAL 0x456 | ||
| 50 | |||
| 45 | #ifdef DEBUG | 51 | #ifdef DEBUG |
| 46 | #define ulog(f, a...) fprintf(stdout, f, ##a) | 52 | #define ulog(f, a...) fprintf(stdout, f, ##a) |
| 47 | #else | 53 | #else |
| @@ -83,6 +89,25 @@ static int netlink_send(int s, struct cn_msg *msg) | |||
| 83 | return err; | 89 | return err; |
| 84 | } | 90 | } |
| 85 | 91 | ||
| 92 | static void usage(void) | ||
| 93 | { | ||
| 94 | printf( | ||
| 95 | "Usage: ucon [options] [output file]\n" | ||
| 96 | "\n" | ||
| 97 | "\t-h\tthis help screen\n" | ||
| 98 | "\t-s\tsend buffers to the test module\n" | ||
| 99 | "\n" | ||
| 100 | "The default behavior of ucon is to subscribe to the test module\n" | ||
| 101 | "and wait for state messages. Any ones received are dumped to the\n" | ||
| 102 | "specified output file (or stdout). The test module is assumed to\n" | ||
| 103 | "have an id of {%u.%u}\n" | ||
| 104 | "\n" | ||
| 105 | "If you get no output, then verify the cn_test module id matches\n" | ||
| 106 | "the expected id above.\n" | ||
| 107 | , CN_TEST_IDX, CN_TEST_VAL | ||
| 108 | ); | ||
| 109 | } | ||
| 110 | |||
| 86 | int main(int argc, char *argv[]) | 111 | int main(int argc, char *argv[]) |
| 87 | { | 112 | { |
| 88 | int s; | 113 | int s; |
| @@ -94,17 +119,34 @@ int main(int argc, char *argv[]) | |||
| 94 | FILE *out; | 119 | FILE *out; |
| 95 | time_t tm; | 120 | time_t tm; |
| 96 | struct pollfd pfd; | 121 | struct pollfd pfd; |
| 122 | bool send_msgs = false; | ||
| 97 | 123 | ||
| 98 | if (argc < 2) | 124 | while ((s = getopt(argc, argv, "hs")) != -1) { |
| 99 | out = stdout; | 125 | switch (s) { |
| 100 | else { | 126 | case 's': |
| 101 | out = fopen(argv[1], "a+"); | 127 | send_msgs = true; |
| 128 | break; | ||
| 129 | |||
| 130 | case 'h': | ||
| 131 | usage(); | ||
| 132 | return 0; | ||
| 133 | |||
| 134 | default: | ||
| 135 | /* getopt() outputs an error for us */ | ||
| 136 | usage(); | ||
| 137 | return 1; | ||
| 138 | } | ||
| 139 | } | ||
| 140 | |||
| 141 | if (argc != optind) { | ||
| 142 | out = fopen(argv[optind], "a+"); | ||
| 102 | if (!out) { | 143 | if (!out) { |
| 103 | ulog("Unable to open %s for writing: %s\n", | 144 | ulog("Unable to open %s for writing: %s\n", |
| 104 | argv[1], strerror(errno)); | 145 | argv[1], strerror(errno)); |
| 105 | out = stdout; | 146 | out = stdout; |
| 106 | } | 147 | } |
| 107 | } | 148 | } else |
| 149 | out = stdout; | ||
| 108 | 150 | ||
| 109 | memset(buf, 0, sizeof(buf)); | 151 | memset(buf, 0, sizeof(buf)); |
| 110 | 152 | ||
| @@ -115,9 +157,11 @@ int main(int argc, char *argv[]) | |||
| 115 | } | 157 | } |
| 116 | 158 | ||
| 117 | l_local.nl_family = AF_NETLINK; | 159 | l_local.nl_family = AF_NETLINK; |
| 118 | l_local.nl_groups = 0x123; /* bitmask of requested groups */ | 160 | l_local.nl_groups = -1; /* bitmask of requested groups */ |
| 119 | l_local.nl_pid = 0; | 161 | l_local.nl_pid = 0; |
| 120 | 162 | ||
| 163 | ulog("subscribing to %u.%u\n", CN_TEST_IDX, CN_TEST_VAL); | ||
| 164 | |||
| 121 | if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { | 165 | if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { |
| 122 | perror("bind"); | 166 | perror("bind"); |
| 123 | close(s); | 167 | close(s); |
| @@ -130,15 +174,15 @@ int main(int argc, char *argv[]) | |||
| 130 | setsockopt(s, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, &on, sizeof(on)); | 174 | setsockopt(s, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, &on, sizeof(on)); |
| 131 | } | 175 | } |
| 132 | #endif | 176 | #endif |
| 133 | if (0) { | 177 | if (send_msgs) { |
| 134 | int i, j; | 178 | int i, j; |
| 135 | 179 | ||
| 136 | memset(buf, 0, sizeof(buf)); | 180 | memset(buf, 0, sizeof(buf)); |
| 137 | 181 | ||
| 138 | data = (struct cn_msg *)buf; | 182 | data = (struct cn_msg *)buf; |
| 139 | 183 | ||
| 140 | data->id.idx = 0x123; | 184 | data->id.idx = CN_TEST_IDX; |
| 141 | data->id.val = 0x456; | 185 | data->id.val = CN_TEST_VAL; |
| 142 | data->seq = seq++; | 186 | data->seq = seq++; |
| 143 | data->ack = 0; | 187 | data->ack = 0; |
| 144 | data->len = 0; | 188 | data->len = 0; |
diff --git a/Documentation/cpu-freq/user-guide.txt b/Documentation/cpu-freq/user-guide.txt index 5d5f5fadd1c2..2a5b850847c0 100644 --- a/Documentation/cpu-freq/user-guide.txt +++ b/Documentation/cpu-freq/user-guide.txt | |||
| @@ -176,7 +176,9 @@ scaling_governor, and by "echoing" the name of another | |||
| 176 | work on some specific architectures or | 176 | work on some specific architectures or |
| 177 | processors. | 177 | processors. |
| 178 | 178 | ||
| 179 | cpuinfo_cur_freq : Current speed of the CPU, in KHz. | 179 | cpuinfo_cur_freq : Current frequency of the CPU as obtained from |
| 180 | the hardware, in KHz. This is the frequency | ||
| 181 | the CPU actually runs at. | ||
| 180 | 182 | ||
| 181 | scaling_available_frequencies : List of available frequencies, in KHz. | 183 | scaling_available_frequencies : List of available frequencies, in KHz. |
| 182 | 184 | ||
| @@ -196,7 +198,10 @@ related_cpus : List of CPUs that need some sort of frequency | |||
| 196 | 198 | ||
| 197 | scaling_driver : Hardware driver for cpufreq. | 199 | scaling_driver : Hardware driver for cpufreq. |
| 198 | 200 | ||
| 199 | scaling_cur_freq : Current frequency of the CPU, in KHz. | 201 | scaling_cur_freq : Current frequency of the CPU as determined by |
| 202 | the governor and cpufreq core, in KHz. This is | ||
| 203 | the frequency the kernel thinks the CPU runs | ||
| 204 | at. | ||
| 200 | 205 | ||
| 201 | If you have selected the "userspace" governor which allows you to | 206 | If you have selected the "userspace" governor which allows you to |
| 202 | set the CPU operating frequency to a specific value, you can read out | 207 | set the CPU operating frequency to a specific value, you can read out |
diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 88519daab6e9..e1efc400bed6 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff | |||
| @@ -152,7 +152,6 @@ piggy.gz | |||
| 152 | piggyback | 152 | piggyback |
| 153 | pnmtologo | 153 | pnmtologo |
| 154 | ppc_defs.h* | 154 | ppc_defs.h* |
| 155 | promcon_tbl.c | ||
| 156 | pss_boot.h | 155 | pss_boot.h |
| 157 | qconf | 156 | qconf |
| 158 | raid6altivec*.c | 157 | raid6altivec*.c |
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.txt index 82132169d47a..60120fb3b961 100644 --- a/Documentation/driver-model/driver.txt +++ b/Documentation/driver-model/driver.txt | |||
| @@ -207,8 +207,8 @@ Attributes | |||
| 207 | ~~~~~~~~~~ | 207 | ~~~~~~~~~~ |
| 208 | struct driver_attribute { | 208 | struct driver_attribute { |
| 209 | struct attribute attr; | 209 | struct attribute attr; |
| 210 | ssize_t (*show)(struct device_driver *, char * buf, size_t count, loff_t off); | 210 | ssize_t (*show)(struct device_driver *driver, char *buf); |
| 211 | ssize_t (*store)(struct device_driver *, const char * buf, size_t count, loff_t off); | 211 | ssize_t (*store)(struct device_driver *, const char * buf, size_t count); |
| 212 | }; | 212 | }; |
| 213 | 213 | ||
| 214 | Device drivers can export attributes via their sysfs directories. | 214 | Device drivers can export attributes via their sysfs directories. |
diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index a52adfc9a57f..14b7b5a3bcb9 100644 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware | |||
| @@ -25,7 +25,8 @@ use IO::Handle; | |||
| 25 | "tda10046lifeview", "av7110", "dec2000t", "dec2540t", | 25 | "tda10046lifeview", "av7110", "dec2000t", "dec2540t", |
| 26 | "dec3000s", "vp7041", "dibusb", "nxt2002", "nxt2004", | 26 | "dec3000s", "vp7041", "dibusb", "nxt2002", "nxt2004", |
| 27 | "or51211", "or51132_qam", "or51132_vsb", "bluebird", | 27 | "or51211", "or51132_qam", "or51132_vsb", "bluebird", |
| 28 | "opera1", "cx231xx", "cx18", "cx23885", "pvrusb2" ); | 28 | "opera1", "cx231xx", "cx18", "cx23885", "pvrusb2", "mpc718", |
| 29 | "af9015"); | ||
| 29 | 30 | ||
| 30 | # Check args | 31 | # Check args |
| 31 | syntax() if (scalar(@ARGV) != 1); | 32 | syntax() if (scalar(@ARGV) != 1); |
| @@ -381,6 +382,57 @@ sub cx18 { | |||
| 381 | $allfiles; | 382 | $allfiles; |
| 382 | } | 383 | } |
| 383 | 384 | ||
| 385 | sub mpc718 { | ||
| 386 | my $archive = 'Yuan MPC718 TV Tuner Card 2.13.10.1016.zip'; | ||
| 387 | my $url = "ftp://ftp.work.acer-euro.com/desktop/aspire_idea510/vista/Drivers/$archive"; | ||
| 388 | my $fwfile = "dvb-cx18-mpc718-mt352.fw"; | ||
| 389 | my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); | ||
| 390 | |||
| 391 | checkstandard(); | ||
| 392 | wgetfile($archive, $url); | ||
| 393 | unzip($archive, $tmpdir); | ||
| 394 | |||
| 395 | my $sourcefile = "$tmpdir/Yuan MPC718 TV Tuner Card 2.13.10.1016/mpc718_32bit/yuanrap.sys"; | ||
| 396 | my $found = 0; | ||
| 397 | |||
| 398 | open IN, '<', $sourcefile or die "Couldn't open $sourcefile to extract $fwfile data\n"; | ||
| 399 | binmode IN; | ||
| 400 | open OUT, '>', $fwfile; | ||
| 401 | binmode OUT; | ||
| 402 | { | ||
| 403 | # Block scope because we change the line terminator variable $/ | ||
| 404 | my $prevlen = 0; | ||
| 405 | my $currlen; | ||
| 406 | |||
| 407 | # Buried in the data segment are 3 runs of almost identical | ||
| 408 | # register-value pairs that end in 0x5d 0x01 which is a "TUNER GO" | ||
| 409 | # command for the MT352. | ||
| 410 | # Pull out the middle run (because it's easy) of register-value | ||
| 411 | # pairs to make the "firmware" file. | ||
| 412 | |||
| 413 | local $/ = "\x5d\x01"; # MT352 "TUNER GO" | ||
| 414 | |||
| 415 | while (<IN>) { | ||
| 416 | $currlen = length($_); | ||
| 417 | if ($prevlen == $currlen && $currlen <= 64) { | ||
| 418 | chop; chop; # Get rid of "TUNER GO" | ||
| 419 | s/^\0\0//; # get rid of leading 00 00 if it's there | ||
| 420 | printf OUT "$_"; | ||
| 421 | $found = 1; | ||
| 422 | last; | ||
| 423 | } | ||
| 424 | $prevlen = $currlen; | ||
| 425 | } | ||
| 426 | } | ||
| 427 | close OUT; | ||
| 428 | close IN; | ||
| 429 | if (!$found) { | ||
| 430 | unlink $fwfile; | ||
| 431 | die "Couldn't find valid register-value sequence in $sourcefile for $fwfile\n"; | ||
| 432 | } | ||
| 433 | $fwfile; | ||
| 434 | } | ||
| 435 | |||
| 384 | sub cx23885 { | 436 | sub cx23885 { |
| 385 | my $url = "http://linuxtv.org/downloads/firmware/"; | 437 | my $url = "http://linuxtv.org/downloads/firmware/"; |
| 386 | 438 | ||
| @@ -463,6 +515,40 @@ sub bluebird { | |||
| 463 | $outfile; | 515 | $outfile; |
| 464 | } | 516 | } |
| 465 | 517 | ||
| 518 | sub af9015 { | ||
| 519 | my $sourcefile = "download.ashx?file=57"; | ||
| 520 | my $url = "http://www.ite.com.tw/EN/Services/$sourcefile"; | ||
| 521 | my $hash = "ff5b096ed47c080870eacdab2de33ad6"; | ||
| 522 | my $outfile = "dvb-usb-af9015.fw"; | ||
| 523 | my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); | ||
| 524 | my $fwoffset = 0x22708; | ||
| 525 | my $fwlength = 18225; | ||
| 526 | my ($chunklength, $buf, $rcount); | ||
| 527 | |||
| 528 | checkstandard(); | ||
| 529 | |||
| 530 | wgetfile($sourcefile, $url); | ||
| 531 | unzip($sourcefile, $tmpdir); | ||
| 532 | verify("$tmpdir/Driver/Files/AF15BDA.sys", $hash); | ||
| 533 | |||
| 534 | open INFILE, '<', "$tmpdir/Driver/Files/AF15BDA.sys"; | ||
| 535 | open OUTFILE, '>', $outfile; | ||
| 536 | |||
| 537 | sysseek(INFILE, $fwoffset, SEEK_SET); | ||
| 538 | while($fwlength > 0) { | ||
| 539 | $chunklength = 55; | ||
| 540 | $chunklength = $fwlength if ($chunklength > $fwlength); | ||
| 541 | $rcount = sysread(INFILE, $buf, $chunklength); | ||
| 542 | die "Ran out of data\n" if ($rcount != $chunklength); | ||
| 543 | syswrite(OUTFILE, $buf); | ||
| 544 | sysread(INFILE, $buf, 8); | ||
| 545 | $fwlength -= $rcount + 8; | ||
| 546 | } | ||
| 547 | |||
| 548 | close OUTFILE; | ||
| 549 | close INFILE; | ||
| 550 | } | ||
| 551 | |||
| 466 | # --------------------------------------------------------------- | 552 | # --------------------------------------------------------------- |
| 467 | # Utilities | 553 | # Utilities |
| 468 | 554 | ||
diff --git a/Documentation/dvb/technisat.txt b/Documentation/dvb/technisat.txt index 3f435ffb289c..f0cc4f2d8365 100644 --- a/Documentation/dvb/technisat.txt +++ b/Documentation/dvb/technisat.txt | |||
| @@ -4,9 +4,12 @@ How to set up the Technisat/B2C2 Flexcop devices | |||
| 4 | 1) Find out what device you have | 4 | 1) Find out what device you have |
| 5 | ================================ | 5 | ================================ |
| 6 | 6 | ||
| 7 | Important Notice: The driver does NOT support Technisat USB 2 devices! | ||
| 8 | |||
| 7 | First start your linux box with a shipped kernel: | 9 | First start your linux box with a shipped kernel: |
| 8 | lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: | 10 | lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: |
| 9 | 02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / Technisat SkyStar2 DVB card (rev 02) | 11 | 02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / |
| 12 | Technisat SkyStar2 DVB card (rev 02) | ||
| 10 | 13 | ||
| 11 | dmesg | grep frontend may show you for example: | 14 | dmesg | grep frontend may show you for example: |
| 12 | DVB: registering frontend 0 (Conexant CX24123/CX24109)... | 15 | DVB: registering frontend 0 (Conexant CX24123/CX24109)... |
| @@ -14,62 +17,62 @@ DVB: registering frontend 0 (Conexant CX24123/CX24109)... | |||
| 14 | 2) Kernel compilation: | 17 | 2) Kernel compilation: |
| 15 | ====================== | 18 | ====================== |
| 16 | 19 | ||
| 17 | If the Technisat is the only TV device in your box get rid of unnecessary modules and check this one: | 20 | If the Flexcop / Technisat is the only DVB / TV / Radio device in your box |
| 18 | "Multimedia devices" => "Customise analog and hybrid tuner modules to build" | 21 | get rid of unnecessary modules and check this one: |
| 19 | In this directory uncheck every driver which is activated there (except "Simple tuner support" for case 9 only). | 22 | "Multimedia support" => "Customise analog and hybrid tuner modules to build" |
| 23 | In this directory uncheck every driver which is activated there | ||
| 24 | (except "Simple tuner support" for ATSC 3rd generation only -> see case 9 please). | ||
| 20 | 25 | ||
| 21 | Then please activate: | 26 | Then please activate: |
| 22 | 2a) Main module part: | 27 | 2a) Main module part: |
| 28 | "Multimedia support" => "DVB/ATSC adapters" | ||
| 29 | => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" | ||
| 23 | 30 | ||
| 24 | a.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" | 31 | a.) => "Technisat/B2C2 Air/Sky/Cable2PC PCI" (PCI card) or |
| 25 | b.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC PCI" in case of a PCI card | 32 | b.) => "Technisat/B2C2 Air/Sky/Cable2PC USB" (USB 1.1 adapter) |
| 26 | OR | 33 | and for troubleshooting purposes: |
| 27 | c.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC USB" in case of an USB 1.1 adapter | 34 | c.) => "Enable debug for the B2C2 FlexCop drivers" |
| 28 | d.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Enable debug for the B2C2 FlexCop drivers" | ||
| 29 | Notice: d.) is helpful for troubleshooting | ||
| 30 | 35 | ||
| 31 | 2b) Frontend module part: | 36 | 2b) Frontend / Tuner / Demodulator module part: |
| 37 | "Multimedia support" => "DVB/ATSC adapters" | ||
| 38 | => "Customise the frontend modules to build" "Customise DVB frontends" => | ||
| 32 | 39 | ||
| 33 | 1.) SkyStar DVB-S Revision 2.3: | 40 | 1.) SkyStar DVB-S Revision 2.3: |
| 34 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 41 | a.) => "Zarlink VP310/MT312/ZL10313 based" |
| 35 | b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink VP310/MT312/ZL10313 based" | 42 | b.) => "Generic I2C PLL based tuners" |
| 36 | 43 | ||
| 37 | 2.) SkyStar DVB-S Revision 2.6: | 44 | 2.) SkyStar DVB-S Revision 2.6: |
| 38 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 45 | a.) => "ST STV0299 based" |
| 39 | b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0299 based" | 46 | b.) => "Generic I2C PLL based tuners" |
| 40 | 47 | ||
| 41 | 3.) SkyStar DVB-S Revision 2.7: | 48 | 3.) SkyStar DVB-S Revision 2.7: |
| 42 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 49 | a.) => "Samsung S5H1420 based" |
| 43 | b.)"Multimedia devices" => "Customise DVB frontends" => "Samsung S5H1420 based" | 50 | b.) => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" |
| 44 | c.)"Multimedia devices" => "Customise DVB frontends" => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" | 51 | c.) => "ISL6421 SEC controller" |
| 45 | d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" | ||
| 46 | 52 | ||
| 47 | 4.) SkyStar DVB-S Revision 2.8: | 53 | 4.) SkyStar DVB-S Revision 2.8: |
| 48 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 54 | a.) => "Conexant CX24123 based" |
| 49 | b.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" | 55 | b.) => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" |
| 50 | c.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24123 based" | 56 | c.) => "ISL6421 SEC controller" |
| 51 | d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" | ||
| 52 | 57 | ||
| 53 | 5.) AirStar DVB-T card: | 58 | 5.) AirStar DVB-T card: |
| 54 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 59 | a.) => "Zarlink MT352 based" |
| 55 | b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink MT352 based" | 60 | b.) => "Generic I2C PLL based tuners" |
| 56 | 61 | ||
| 57 | 6.) CableStar DVB-C card: | 62 | 6.) CableStar DVB-C card: |
| 58 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 63 | a.) => "ST STV0297 based" |
| 59 | b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0297 based" | 64 | b.) => "Generic I2C PLL based tuners" |
| 60 | 65 | ||
| 61 | 7.) AirStar ATSC card 1st generation: | 66 | 7.) AirStar ATSC card 1st generation: |
| 62 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 67 | a.) => "Broadcom BCM3510" |
| 63 | b.)"Multimedia devices" => "Customise DVB frontends" => "Broadcom BCM3510" | ||
| 64 | 68 | ||
| 65 | 8.) AirStar ATSC card 2nd generation: | 69 | 8.) AirStar ATSC card 2nd generation: |
| 66 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 70 | a.) => "NxtWave Communications NXT2002/NXT2004 based" |
| 67 | b.)"Multimedia devices" => "Customise DVB frontends" => "NxtWave Communications NXT2002/NXT2004 based" | 71 | b.) => "Generic I2C PLL based tuners" |
| 68 | c.)"Multimedia devices" => "Customise DVB frontends" => "Generic I2C PLL based tuners" | ||
| 69 | 72 | ||
| 70 | 9.) AirStar ATSC card 3rd generation: | 73 | 9.) AirStar ATSC card 3rd generation: |
| 71 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 74 | a.) => "LG Electronics LGDT3302/LGDT3303 based" |
| 72 | b.)"Multimedia devices" => "Customise DVB frontends" => "LG Electronics LGDT3302/LGDT3303 based" | 75 | b.) "Multimedia support" => "Customise analog and hybrid tuner modules to build" |
| 73 | c.)"Multimedia devices" => "Customise analog and hybrid tuner modules to build" => "Simple tuner support" | 76 | => "Simple tuner support" |
| 74 | 77 | ||
| 75 | Author: Uwe Bugla <uwe.bugla@gmx.de> February 2009 | 78 | Author: Uwe Bugla <uwe.bugla@gmx.de> August 2009 |
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index f8cd450be9aa..fa75220f8d34 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt | |||
| @@ -6,6 +6,35 @@ be removed from this file. | |||
| 6 | 6 | ||
| 7 | --------------------------- | 7 | --------------------------- |
| 8 | 8 | ||
| 9 | What: PRISM54 | ||
| 10 | When: 2.6.34 | ||
| 11 | |||
| 12 | Why: prism54 FullMAC PCI / Cardbus devices used to be supported only by the | ||
| 13 | prism54 wireless driver. After Intersil stopped selling these | ||
| 14 | devices in preference for the newer more flexible SoftMAC devices | ||
| 15 | a SoftMAC device driver was required and prism54 did not support | ||
| 16 | them. The p54pci driver now exists and has been present in the kernel for | ||
| 17 | a while. This driver supports both SoftMAC devices and FullMAC devices. | ||
| 18 | The main difference between these devices was the amount of memory which | ||
| 19 | could be used for the firmware. The SoftMAC devices support a smaller | ||
| 20 | amount of memory. Because of this the SoftMAC firmware fits into FullMAC | ||
| 21 | devices's memory. p54pci supports not only PCI / Cardbus but also USB | ||
| 22 | and SPI. Since p54pci supports all devices prism54 supports | ||
| 23 | you will have a conflict. I'm not quite sure how distributions are | ||
| 24 | handling this conflict right now. prism54 was kept around due to | ||
| 25 | claims users may experience issues when using the SoftMAC driver. | ||
| 26 | Time has passed users have not reported issues. If you use prism54 | ||
| 27 | and for whatever reason you cannot use p54pci please let us know! | ||
| 28 | E-mail us at: linux-wireless@vger.kernel.org | ||
| 29 | |||
| 30 | For more information see the p54 wiki page: | ||
| 31 | |||
| 32 | http://wireless.kernel.org/en/users/Drivers/p54 | ||
| 33 | |||
| 34 | Who: Luis R. Rodriguez <lrodriguez@atheros.com> | ||
| 35 | |||
| 36 | --------------------------- | ||
| 37 | |||
| 9 | What: IRQF_SAMPLE_RANDOM | 38 | What: IRQF_SAMPLE_RANDOM |
| 10 | Check: IRQF_SAMPLE_RANDOM | 39 | Check: IRQF_SAMPLE_RANDOM |
| 11 | When: July 2009 | 40 | When: July 2009 |
| @@ -206,24 +235,6 @@ Who: Len Brown <len.brown@intel.com> | |||
| 206 | 235 | ||
| 207 | --------------------------- | 236 | --------------------------- |
| 208 | 237 | ||
| 209 | What: libata spindown skipping and warning | ||
| 210 | When: Dec 2008 | ||
| 211 | Why: Some halt(8) implementations synchronize caches for and spin | ||
| 212 | down libata disks because libata didn't use to spin down disk on | ||
| 213 | system halt (only synchronized caches). | ||
| 214 | Spin down on system halt is now implemented. sysfs node | ||
| 215 | /sys/class/scsi_disk/h:c:i:l/manage_start_stop is present if | ||
| 216 | spin down support is available. | ||
| 217 | Because issuing spin down command to an already spun down disk | ||
| 218 | makes some disks spin up just to spin down again, libata tracks | ||
| 219 | device spindown status to skip the extra spindown command and | ||
| 220 | warn about it. | ||
| 221 | This is to give userspace tools the time to get updated and will | ||
| 222 | be removed after userspace is reasonably updated. | ||
| 223 | Who: Tejun Heo <htejun@gmail.com> | ||
| 224 | |||
| 225 | --------------------------- | ||
| 226 | |||
| 227 | What: i386/x86_64 bzImage symlinks | 238 | What: i386/x86_64 bzImage symlinks |
| 228 | When: April 2010 | 239 | When: April 2010 |
| 229 | 240 | ||
| @@ -235,31 +246,6 @@ Who: Thomas Gleixner <tglx@linutronix.de> | |||
| 235 | --------------------------- | 246 | --------------------------- |
| 236 | 247 | ||
| 237 | What (Why): | 248 | What (Why): |
| 238 | - include/linux/netfilter_ipv4/ipt_TOS.h ipt_tos.h header files | ||
| 239 | (superseded by xt_TOS/xt_tos target & match) | ||
| 240 | |||
| 241 | - "forwarding" header files like ipt_mac.h in | ||
| 242 | include/linux/netfilter_ipv4/ and include/linux/netfilter_ipv6/ | ||
| 243 | |||
| 244 | - xt_CONNMARK match revision 0 | ||
| 245 | (superseded by xt_CONNMARK match revision 1) | ||
| 246 | |||
| 247 | - xt_MARK target revisions 0 and 1 | ||
| 248 | (superseded by xt_MARK match revision 2) | ||
| 249 | |||
| 250 | - xt_connmark match revision 0 | ||
| 251 | (superseded by xt_connmark match revision 1) | ||
| 252 | |||
| 253 | - xt_conntrack match revision 0 | ||
| 254 | (superseded by xt_conntrack match revision 1) | ||
| 255 | |||
| 256 | - xt_iprange match revision 0, | ||
| 257 | include/linux/netfilter_ipv4/ipt_iprange.h | ||
| 258 | (superseded by xt_iprange match revision 1) | ||
| 259 | |||
| 260 | - xt_mark match revision 0 | ||
| 261 | (superseded by xt_mark match revision 1) | ||
| 262 | |||
| 263 | - xt_recent: the old ipt_recent proc dir | 249 | - xt_recent: the old ipt_recent proc dir |
| 264 | (superseded by /proc/net/xt_recent) | 250 | (superseded by /proc/net/xt_recent) |
| 265 | 251 | ||
| @@ -394,15 +380,6 @@ Who: Thomas Gleixner <tglx@linutronix.de> | |||
| 394 | 380 | ||
| 395 | ----------------------------- | 381 | ----------------------------- |
| 396 | 382 | ||
| 397 | What: obsolete generic irq defines and typedefs | ||
| 398 | When: 2.6.30 | ||
| 399 | Why: The defines and typedefs (hw_interrupt_type, no_irq_type, irq_desc_t) | ||
| 400 | have been kept around for migration reasons. After more than two years | ||
| 401 | it's time to remove them finally | ||
| 402 | Who: Thomas Gleixner <tglx@linutronix.de> | ||
| 403 | |||
| 404 | --------------------------- | ||
| 405 | |||
| 406 | What: fakephp and associated sysfs files in /sys/bus/pci/slots/ | 383 | What: fakephp and associated sysfs files in /sys/bus/pci/slots/ |
| 407 | When: 2011 | 384 | When: 2011 |
| 408 | Why: In 2.6.27, the semantics of /sys/bus/pci/slots was redefined to | 385 | Why: In 2.6.27, the semantics of /sys/bus/pci/slots was redefined to |
| @@ -451,10 +428,34 @@ Who: Johannes Berg <johannes@sipsolutions.net> | |||
| 451 | 428 | ||
| 452 | ---------------------------- | 429 | ---------------------------- |
| 453 | 430 | ||
| 454 | What: CONFIG_X86_OLD_MCE | 431 | What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be |
| 455 | When: 2.6.32 | 432 | exported interface anymore. |
| 456 | Why: Remove the old legacy 32bit machine check code. This has been | 433 | When: 2.6.33 |
| 457 | superseded by the newer machine check code from the 64bit port, | 434 | Why: cpu_policy_rwsem has a new cleaner definition making it local to |
| 458 | but the old version has been kept around for easier testing. Note this | 435 | cpufreq core and contained inside cpufreq.c. Other dependent |
| 459 | doesn't impact the old P5 and WinChip machine check handlers. | 436 | drivers should not use it in order to safely avoid lockdep issues. |
| 460 | Who: Andi Kleen <andi@firstfloor.org> | 437 | Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> |
| 438 | |||
| 439 | ---------------------------- | ||
| 440 | |||
| 441 | What: sound-slot/service-* module aliases and related clutters in | ||
| 442 | sound/sound_core.c | ||
| 443 | When: August 2010 | ||
| 444 | Why: OSS sound_core grabs all legacy minors (0-255) of SOUND_MAJOR | ||
| 445 | (14) and requests modules using custom sound-slot/service-* | ||
| 446 | module aliases. The only benefit of doing this is allowing | ||
| 447 | use of custom module aliases which might as well be considered | ||
| 448 | a bug at this point. This preemptive claiming prevents | ||
| 449 | alternative OSS implementations. | ||
| 450 | |||
| 451 | Till the feature is removed, the kernel will be requesting | ||
| 452 | both sound-slot/service-* and the standard char-major-* module | ||
| 453 | aliases and allow turning off the pre-claiming selectively via | ||
| 454 | CONFIG_SOUND_OSS_CORE_PRECLAIM and soundcore.preclaim_oss | ||
| 455 | kernel parameter. | ||
| 456 | |||
| 457 | After the transition phase is complete, both the custom module | ||
| 458 | aliases and switches to disable it will go away. This removal | ||
| 459 | will also allow making ALSA OSS emulation independent of | ||
| 460 | sound_core. The dependency will be broken then too. | ||
| 461 | Who: Tejun Heo <tj@kernel.org> | ||
diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt index bf8080640eba..6208f55c44c3 100644 --- a/Documentation/filesystems/9p.txt +++ b/Documentation/filesystems/9p.txt | |||
| @@ -123,6 +123,9 @@ available from the same CVS repository. | |||
| 123 | There are user and developer mailing lists available through the v9fs project | 123 | There are user and developer mailing lists available through the v9fs project |
| 124 | on sourceforge (http://sourceforge.net/projects/v9fs). | 124 | on sourceforge (http://sourceforge.net/projects/v9fs). |
| 125 | 125 | ||
| 126 | A stand-alone version of the module (which should build for any 2.6 kernel) | ||
| 127 | is available via (http://github.com/ericvh/9p-sac/tree/master) | ||
| 128 | |||
| 126 | News and other information is maintained on SWiK (http://swik.net/v9fs). | 129 | News and other information is maintained on SWiK (http://swik.net/v9fs). |
| 127 | 130 | ||
| 128 | Bug reports may be issued through the kernel.org bugzilla | 131 | Bug reports may be issued through the kernel.org bugzilla |
diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index 12ad6c7f4e50..ffef91c4e0d6 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt | |||
| @@ -23,15 +23,13 @@ it does support include: | |||
| 23 | 23 | ||
| 24 | (*) Security (currently only AFS kaserver and KerberosIV tickets). | 24 | (*) Security (currently only AFS kaserver and KerberosIV tickets). |
| 25 | 25 | ||
| 26 | (*) File reading. | 26 | (*) File reading and writing. |
| 27 | 27 | ||
| 28 | (*) Automounting. | 28 | (*) Automounting. |
| 29 | 29 | ||
| 30 | It does not yet support the following AFS features: | 30 | (*) Local caching (via fscache). |
| 31 | |||
| 32 | (*) Write support. | ||
| 33 | 31 | ||
| 34 | (*) Local caching. | 32 | It does not yet support the following AFS features: |
| 35 | 33 | ||
| 36 | (*) pioctl() system call. | 34 | (*) pioctl() system call. |
| 37 | 35 | ||
| @@ -56,7 +54,7 @@ They permit the debugging messages to be turned on dynamically by manipulating | |||
| 56 | the masks in the following files: | 54 | the masks in the following files: |
| 57 | 55 | ||
| 58 | /sys/module/af_rxrpc/parameters/debug | 56 | /sys/module/af_rxrpc/parameters/debug |
| 59 | /sys/module/afs/parameters/debug | 57 | /sys/module/kafs/parameters/debug |
| 60 | 58 | ||
| 61 | 59 | ||
| 62 | ===== | 60 | ===== |
| @@ -66,9 +64,9 @@ USAGE | |||
| 66 | When inserting the driver modules the root cell must be specified along with a | 64 | When inserting the driver modules the root cell must be specified along with a |
| 67 | list of volume location server IP addresses: | 65 | list of volume location server IP addresses: |
| 68 | 66 | ||
| 69 | insmod af_rxrpc.o | 67 | modprobe af_rxrpc |
| 70 | insmod rxkad.o | 68 | modprobe rxkad |
| 71 | insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 | 69 | modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 |
| 72 | 70 | ||
| 73 | The first module is the AF_RXRPC network protocol driver. This provides the | 71 | The first module is the AF_RXRPC network protocol driver. This provides the |
| 74 | RxRPC remote operation protocol and may also be accessed from userspace. See: | 72 | RxRPC remote operation protocol and may also be accessed from userspace. See: |
| @@ -81,7 +79,7 @@ is the actual filesystem driver for the AFS filesystem. | |||
| 81 | Once the module has been loaded, more modules can be added by the following | 79 | Once the module has been loaded, more modules can be added by the following |
| 82 | procedure: | 80 | procedure: |
| 83 | 81 | ||
| 84 | echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells | 82 | echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells |
| 85 | 83 | ||
| 86 | Where the parameters to the "add" command are the name of a cell and a list of | 84 | Where the parameters to the "add" command are the name of a cell and a list of |
| 87 | volume location servers within that cell, with the latter separated by colons. | 85 | volume location servers within that cell, with the latter separated by colons. |
| @@ -101,7 +99,7 @@ The name of the volume can be suffixes with ".backup" or ".readonly" to | |||
| 101 | specify connection to only volumes of those types. | 99 | specify connection to only volumes of those types. |
| 102 | 100 | ||
| 103 | The name of the cell is optional, and if not given during a mount, then the | 101 | The name of the cell is optional, and if not given during a mount, then the |
| 104 | named volume will be looked up in the cell specified during insmod. | 102 | named volume will be looked up in the cell specified during modprobe. |
| 105 | 103 | ||
| 106 | Additional cells can be added through /proc (see later section). | 104 | Additional cells can be added through /proc (see later section). |
| 107 | 105 | ||
| @@ -163,14 +161,14 @@ THE CELL DATABASE | |||
| 163 | 161 | ||
| 164 | The filesystem maintains an internal database of all the cells it knows and the | 162 | The filesystem maintains an internal database of all the cells it knows and the |
| 165 | IP addresses of the volume location servers for those cells. The cell to which | 163 | IP addresses of the volume location servers for those cells. The cell to which |
| 166 | the system belongs is added to the database when insmod is performed by the | 164 | the system belongs is added to the database when modprobe is performed by the |
| 167 | "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on | 165 | "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on |
| 168 | the kernel command line. | 166 | the kernel command line. |
| 169 | 167 | ||
| 170 | Further cells can be added by commands similar to the following: | 168 | Further cells can be added by commands similar to the following: |
| 171 | 169 | ||
| 172 | echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells | 170 | echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells |
| 173 | echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells | 171 | echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells |
| 174 | 172 | ||
| 175 | No other cell database operations are available at this time. | 173 | No other cell database operations are available at this time. |
| 176 | 174 | ||
| @@ -233,7 +231,7 @@ insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91 | |||
| 233 | mount -t afs \%root.afs. /afs | 231 | mount -t afs \%root.afs. /afs |
| 234 | mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ | 232 | mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ |
| 235 | 233 | ||
| 236 | echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells | 234 | echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells |
| 237 | mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ | 235 | mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ |
| 238 | mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive | 236 | mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive |
| 239 | mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib | 237 | mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib |
diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 7be02ac5fa36..18b5ec8cea45 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt | |||
| @@ -134,15 +134,9 @@ ro Mount filesystem read only. Note that ext4 will | |||
| 134 | mount options "ro,noload" can be used to prevent | 134 | mount options "ro,noload" can be used to prevent |
| 135 | writes to the filesystem. | 135 | writes to the filesystem. |
| 136 | 136 | ||
| 137 | journal_checksum Enable checksumming of the journal transactions. | ||
| 138 | This will allow the recovery code in e2fsck and the | ||
| 139 | kernel to detect corruption in the kernel. It is a | ||
| 140 | compatible change and will be ignored by older kernels. | ||
| 141 | |||
| 142 | journal_async_commit Commit block can be written to disk without waiting | 137 | journal_async_commit Commit block can be written to disk without waiting |
| 143 | for descriptor blocks. If enabled older kernels cannot | 138 | for descriptor blocks. If enabled older kernels cannot |
| 144 | mount the device. This will enable 'journal_checksum' | 139 | mount the device. |
| 145 | internally. | ||
| 146 | 140 | ||
| 147 | journal=update Update the ext4 file system's journal to the current | 141 | journal=update Update the ext4 file system's journal to the current |
| 148 | format. | 142 | format. |
| @@ -263,10 +257,18 @@ resuid=n The user ID which may use the reserved blocks. | |||
| 263 | 257 | ||
| 264 | sb=n Use alternate superblock at this location. | 258 | sb=n Use alternate superblock at this location. |
| 265 | 259 | ||
| 266 | quota | 260 | quota These options are ignored by the filesystem. They |
| 267 | noquota | 261 | noquota are used only by quota tools to recognize volumes |
| 268 | grpquota | 262 | grpquota where quota should be turned on. See documentation |
| 269 | usrquota | 263 | usrquota in the quota-tools package for more details |
| 264 | (http://sourceforge.net/projects/linuxquota). | ||
| 265 | |||
| 266 | jqfmt=<quota type> These options tell filesystem details about quota | ||
| 267 | usrjquota=<file> so that quota information can be properly updated | ||
| 268 | grpjquota=<file> during journal replay. They replace the above | ||
| 269 | quota options. See documentation in the quota-tools | ||
| 270 | package for more details | ||
| 271 | (http://sourceforge.net/projects/linuxquota). | ||
| 270 | 272 | ||
| 271 | bh (*) ext4 associates buffer heads to data pages to | 273 | bh (*) ext4 associates buffer heads to data pages to |
| 272 | nobh (a) cache disk block mapping information | 274 | nobh (a) cache disk block mapping information |
diff --git a/Documentation/filesystems/gfs2-uevents.txt b/Documentation/filesystems/gfs2-uevents.txt new file mode 100644 index 000000000000..fd966dc9979a --- /dev/null +++ b/Documentation/filesystems/gfs2-uevents.txt | |||
| @@ -0,0 +1,100 @@ | |||
| 1 | uevents and GFS2 | ||
| 2 | ================== | ||
| 3 | |||
| 4 | During the lifetime of a GFS2 mount, a number of uevents are generated. | ||
| 5 | This document explains what the events are and what they are used | ||
| 6 | for (by gfs_controld in gfs2-utils). | ||
| 7 | |||
| 8 | A list of GFS2 uevents | ||
| 9 | ----------------------- | ||
| 10 | |||
| 11 | 1. ADD | ||
| 12 | |||
| 13 | The ADD event occurs at mount time. It will always be the first | ||
| 14 | uevent generated by the newly created filesystem. If the mount | ||
| 15 | is successful, an ONLINE uevent will follow. If it is not successful | ||
| 16 | then a REMOVE uevent will follow. | ||
| 17 | |||
| 18 | The ADD uevent has two environment variables: SPECTATOR=[0|1] | ||
| 19 | and RDONLY=[0|1] that specify the spectator status (a read-only mount | ||
| 20 | with no journal assigned), and read-only (with journal assigned) status | ||
| 21 | of the filesystem respectively. | ||
| 22 | |||
| 23 | 2. ONLINE | ||
| 24 | |||
| 25 | The ONLINE uevent is generated after a successful mount or remount. It | ||
| 26 | has the same environment variables as the ADD uevent. The ONLINE | ||
| 27 | uevent, along with the two environment variables for spectator and | ||
| 28 | RDONLY are a relatively recent addition (2.6.32-rc+) and will not | ||
| 29 | be generated by older kernels. | ||
| 30 | |||
| 31 | 3. CHANGE | ||
| 32 | |||
| 33 | The CHANGE uevent is used in two places. One is when reporting the | ||
| 34 | successful mount of the filesystem by the first node (FIRSTMOUNT=Done). | ||
| 35 | This is used as a signal by gfs_controld that it is then ok for other | ||
| 36 | nodes in the cluster to mount the filesystem. | ||
| 37 | |||
| 38 | The other CHANGE uevent is used to inform of the completion | ||
| 39 | of journal recovery for one of the filesystems journals. It has | ||
| 40 | two environment variables, JID= which specifies the journal id which | ||
| 41 | has just been recovered, and RECOVERY=[Done|Failed] to indicate the | ||
| 42 | success (or otherwise) of the operation. These uevents are generated | ||
| 43 | for every journal recovered, whether it is during the initial mount | ||
| 44 | process or as the result of gfs_controld requesting a specific journal | ||
| 45 | recovery via the /sys/fs/gfs2/<fsname>/lock_module/recovery file. | ||
| 46 | |||
| 47 | Because the CHANGE uevent was used (in early versions of gfs_controld) | ||
| 48 | without checking the environment variables to discover the state, we | ||
| 49 | cannot add any more functions to it without running the risk of | ||
| 50 | someone using an older version of the user tools and breaking their | ||
| 51 | cluster. For this reason the ONLINE uevent was used when adding a new | ||
| 52 | uevent for a successful mount or remount. | ||
| 53 | |||
| 54 | 4. OFFLINE | ||
| 55 | |||
| 56 | The OFFLINE uevent is only generated due to filesystem errors and is used | ||
| 57 | as part of the "withdraw" mechanism. Currently this doesn't give any | ||
| 58 | information about what the error is, which is something that needs to | ||
| 59 | be fixed. | ||
| 60 | |||
| 61 | 5. REMOVE | ||
| 62 | |||
| 63 | The REMOVE uevent is generated at the end of an unsuccessful mount | ||
| 64 | or at the end of a umount of the filesystem. All REMOVE uevents will | ||
| 65 | have been preceeded by at least an ADD uevent for the same fileystem, | ||
| 66 | and unlike the other uevents is generated automatically by the kernel's | ||
| 67 | kobject subsystem. | ||
| 68 | |||
| 69 | |||
| 70 | Information common to all GFS2 uevents (uevent environment variables) | ||
| 71 | ---------------------------------------------------------------------- | ||
| 72 | |||
| 73 | 1. LOCKTABLE= | ||
| 74 | |||
| 75 | The LOCKTABLE is a string, as supplied on the mount command | ||
| 76 | line (locktable=) or via fstab. It is used as a filesystem label | ||
| 77 | as well as providing the information for a lock_dlm mount to be | ||
| 78 | able to join the cluster. | ||
| 79 | |||
| 80 | 2. LOCKPROTO= | ||
| 81 | |||
| 82 | The LOCKPROTO is a string, and its value depends on what is set | ||
| 83 | on the mount command line, or via fstab. It will be either | ||
| 84 | lock_nolock or lock_dlm. In the future other lock managers | ||
| 85 | may be supported. | ||
| 86 | |||
| 87 | 3. JOURNALID= | ||
| 88 | |||
| 89 | If a journal is in use by the filesystem (journals are not | ||
| 90 | assigned for spectator mounts) then this will give the | ||
| 91 | numeric journal id in all GFS2 uevents. | ||
| 92 | |||
| 93 | 4. UUID= | ||
| 94 | |||
| 95 | With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID | ||
| 96 | into the filesystem superblock. If it exists, this will | ||
| 97 | be included in every uevent relating to the filesystem. | ||
| 98 | |||
| 99 | |||
| 100 | |||
diff --git a/Documentation/filesystems/nfs.txt b/Documentation/filesystems/nfs.txt new file mode 100644 index 000000000000..f50f26ce6cd0 --- /dev/null +++ b/Documentation/filesystems/nfs.txt | |||
| @@ -0,0 +1,98 @@ | |||
| 1 | |||
| 2 | The NFS client | ||
| 3 | ============== | ||
| 4 | |||
| 5 | The NFS version 2 protocol was first documented in RFC1094 (March 1989). | ||
| 6 | Since then two more major releases of NFS have been published, with NFSv3 | ||
| 7 | being documented in RFC1813 (June 1995), and NFSv4 in RFC3530 (April | ||
| 8 | 2003). | ||
| 9 | |||
| 10 | The Linux NFS client currently supports all the above published versions, | ||
| 11 | and work is in progress on adding support for minor version 1 of the NFSv4 | ||
| 12 | protocol. | ||
| 13 | |||
| 14 | The purpose of this document is to provide information on some of the | ||
| 15 | upcall interfaces that are used in order to provide the NFS client with | ||
| 16 | some of the information that it requires in order to fully comply with | ||
| 17 | the NFS spec. | ||
| 18 | |||
| 19 | The DNS resolver | ||
| 20 | ================ | ||
| 21 | |||
| 22 | NFSv4 allows for one server to refer the NFS client to data that has been | ||
| 23 | migrated onto another server by means of the special "fs_locations" | ||
| 24 | attribute. See | ||
| 25 | http://tools.ietf.org/html/rfc3530#section-6 | ||
| 26 | and | ||
| 27 | http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 | ||
| 28 | |||
| 29 | The fs_locations information can take the form of either an ip address and | ||
| 30 | a path, or a DNS hostname and a path. The latter requires the NFS client to | ||
| 31 | do a DNS lookup in order to mount the new volume, and hence the need for an | ||
| 32 | upcall to allow userland to provide this service. | ||
| 33 | |||
| 34 | Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual | ||
| 35 | /var/lib/nfs/rpc_pipefs, the upcall consists of the following steps: | ||
| 36 | |||
| 37 | (1) The process checks the dns_resolve cache to see if it contains a | ||
| 38 | valid entry. If so, it returns that entry and exits. | ||
| 39 | |||
| 40 | (2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent' | ||
| 41 | (may be changed using the 'nfs.cache_getent' kernel boot parameter) | ||
| 42 | is run, with two arguments: | ||
| 43 | - the cache name, "dns_resolve" | ||
| 44 | - the hostname to resolve | ||
| 45 | |||
| 46 | (3) After looking up the corresponding ip address, the helper script | ||
| 47 | writes the result into the rpc_pipefs pseudo-file | ||
| 48 | '/var/lib/nfs/rpc_pipefs/cache/dns_resolve/channel' | ||
| 49 | in the following (text) format: | ||
| 50 | |||
| 51 | "<ip address> <hostname> <ttl>\n" | ||
| 52 | |||
| 53 | Where <ip address> is in the usual IPv4 (123.456.78.90) or IPv6 | ||
| 54 | (ffee:ddcc:bbaa:9988:7766:5544:3322:1100, ffee::1100, ...) format. | ||
| 55 | <hostname> is identical to the second argument of the helper | ||
| 56 | script, and <ttl> is the 'time to live' of this cache entry (in | ||
| 57 | units of seconds). | ||
| 58 | |||
| 59 | Note: If <ip address> is invalid, say the string "0", then a negative | ||
| 60 | entry is created, which will cause the kernel to treat the hostname | ||
| 61 | as having no valid DNS translation. | ||
| 62 | |||
| 63 | |||
| 64 | |||
| 65 | |||
| 66 | A basic sample /sbin/nfs_cache_getent | ||
| 67 | ===================================== | ||
| 68 | |||
| 69 | #!/bin/bash | ||
| 70 | # | ||
| 71 | ttl=600 | ||
| 72 | # | ||
| 73 | cut=/usr/bin/cut | ||
| 74 | getent=/usr/bin/getent | ||
| 75 | rpc_pipefs=/var/lib/nfs/rpc_pipefs | ||
| 76 | # | ||
| 77 | die() | ||
| 78 | { | ||
| 79 | echo "Usage: $0 cache_name entry_name" | ||
| 80 | exit 1 | ||
| 81 | } | ||
| 82 | |||
| 83 | [ $# -lt 2 ] && die | ||
| 84 | cachename="$1" | ||
| 85 | cache_path=${rpc_pipefs}/cache/${cachename}/channel | ||
| 86 | |||
| 87 | case "${cachename}" in | ||
| 88 | dns_resolve) | ||
| 89 | name="$2" | ||
| 90 | result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )" | ||
| 91 | [ -z "${result}" ] && result="0" | ||
| 92 | ;; | ||
| 93 | *) | ||
| 94 | die | ||
| 95 | ;; | ||
| 96 | esac | ||
| 97 | echo "${result} ${name} ${ttl}" >${cache_path} | ||
| 98 | |||
diff --git a/Documentation/filesystems/nfs41-server.txt b/Documentation/filesystems/nfs41-server.txt index 05d81cbcb2e1..5920fe26e6ff 100644 --- a/Documentation/filesystems/nfs41-server.txt +++ b/Documentation/filesystems/nfs41-server.txt | |||
| @@ -11,6 +11,11 @@ the /proc/fs/nfsd/versions control file. Note that to write this | |||
| 11 | control file, the nfsd service must be taken down. Use your user-mode | 11 | control file, the nfsd service must be taken down. Use your user-mode |
| 12 | nfs-utils to set this up; see rpc.nfsd(8) | 12 | nfs-utils to set this up; see rpc.nfsd(8) |
| 13 | 13 | ||
| 14 | (Warning: older servers will interpret "+4.1" and "-4.1" as "+4" and | ||
| 15 | "-4", respectively. Therefore, code meant to work on both new and old | ||
| 16 | kernels must turn 4.1 on or off *before* turning support for version 4 | ||
| 17 | on or off; rpc.nfsd does this correctly.) | ||
| 18 | |||
| 14 | The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based | 19 | The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based |
| 15 | on the latest NFSv4.1 Internet Draft: | 20 | on the latest NFSv4.1 Internet Draft: |
| 16 | http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29 | 21 | http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29 |
| @@ -25,6 +30,49 @@ are still under development out of tree. | |||
| 25 | See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design | 30 | See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design |
| 26 | for more information. | 31 | for more information. |
| 27 | 32 | ||
| 33 | The current implementation is intended for developers only: while it | ||
| 34 | does support ordinary file operations on clients we have tested against | ||
| 35 | (including the linux client), it is incomplete in ways which may limit | ||
| 36 | features unexpectedly, cause known bugs in rare cases, or cause | ||
| 37 | interoperability problems with future clients. Known issues: | ||
| 38 | |||
| 39 | - gss support is questionable: currently mounts with kerberos | ||
| 40 | from a linux client are possible, but we aren't really | ||
| 41 | conformant with the spec (for example, we don't use kerberos | ||
| 42 | on the backchannel correctly). | ||
| 43 | - no trunking support: no clients currently take advantage of | ||
| 44 | trunking, but this is a mandatory failure, and its use is | ||
| 45 | recommended to clients in a number of places. (E.g. to ensure | ||
| 46 | timely renewal in case an existing connection's retry timeouts | ||
| 47 | have gotten too long; see section 8.3 of the draft.) | ||
| 48 | Therefore, lack of this feature may cause future clients to | ||
| 49 | fail. | ||
| 50 | - Incomplete backchannel support: incomplete backchannel gss | ||
| 51 | support and no support for BACKCHANNEL_CTL mean that | ||
| 52 | callbacks (hence delegations and layouts) may not be | ||
| 53 | available and clients confused by the incomplete | ||
| 54 | implementation may fail. | ||
| 55 | - Server reboot recovery is unsupported; if the server reboots, | ||
| 56 | clients may fail. | ||
| 57 | - We do not support SSV, which provides security for shared | ||
| 58 | client-server state (thus preventing unauthorized tampering | ||
| 59 | with locks and opens, for example). It is mandatory for | ||
| 60 | servers to support this, though no clients use it yet. | ||
| 61 | - Mandatory operations which we do not support, such as | ||
| 62 | DESTROY_CLIENTID, FREE_STATEID, SECINFO_NO_NAME, and | ||
| 63 | TEST_STATEID, are not currently used by clients, but will be | ||
| 64 | (and the spec recommends their uses in common cases), and | ||
| 65 | clients should not be expected to know how to recover from the | ||
| 66 | case where they are not supported. This will eventually cause | ||
| 67 | interoperability failures. | ||
| 68 | |||
| 69 | In addition, some limitations are inherited from the current NFSv4 | ||
| 70 | implementation: | ||
| 71 | |||
| 72 | - Incomplete delegation enforcement: if a file is renamed or | ||
| 73 | unlinked, a client holding a delegation may continue to | ||
| 74 | indefinitely allow opens of the file under the old name. | ||
| 75 | |||
| 28 | The table below, taken from the NFSv4.1 document, lists | 76 | The table below, taken from the NFSv4.1 document, lists |
| 29 | the operations that are mandatory to implement (REQ), optional | 77 | the operations that are mandatory to implement (REQ), optional |
| 30 | (OPT), and NFSv4.0 operations that are required not to implement (MNI) | 78 | (OPT), and NFSv4.0 operations that are required not to implement (MNI) |
| @@ -142,6 +190,12 @@ NS*| CB_WANTS_CANCELLED | OPT | FDELG, | Section 20.10 | | |||
| 142 | 190 | ||
| 143 | Implementation notes: | 191 | Implementation notes: |
| 144 | 192 | ||
| 193 | DELEGPURGE: | ||
| 194 | * mandatory only for servers that support CLAIM_DELEGATE_PREV and/or | ||
| 195 | CLAIM_DELEG_PREV_FH (which allows clients to keep delegations that | ||
| 196 | persist across client reboots). Thus we need not implement this for | ||
| 197 | now. | ||
| 198 | |||
| 145 | EXCHANGE_ID: | 199 | EXCHANGE_ID: |
| 146 | * only SP4_NONE state protection supported | 200 | * only SP4_NONE state protection supported |
| 147 | * implementation ids are ignored | 201 | * implementation ids are ignored |
diff --git a/Documentation/filesystems/nfsroot.txt b/Documentation/filesystems/nfsroot.txt index 68baddf3c3e0..3ba0b945aaf8 100644 --- a/Documentation/filesystems/nfsroot.txt +++ b/Documentation/filesystems/nfsroot.txt | |||
| @@ -105,7 +105,7 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> | |||
| 105 | the client address and this parameter is NOT empty only | 105 | the client address and this parameter is NOT empty only |
| 106 | replies from the specified server are accepted. | 106 | replies from the specified server are accepted. |
| 107 | 107 | ||
| 108 | Only required for for NFS root. That is autoconfiguration | 108 | Only required for NFS root. That is autoconfiguration |
| 109 | will not be triggered if it is missing and NFS root is not | 109 | will not be triggered if it is missing and NFS root is not |
| 110 | in operation. | 110 | in operation. |
| 111 | 111 | ||
diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index fad18f9456e4..75988ba26a51 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt | |||
| @@ -375,6 +375,19 @@ of memory currently marked as referenced or accessed. | |||
| 375 | This file is only present if the CONFIG_MMU kernel configuration option is | 375 | This file is only present if the CONFIG_MMU kernel configuration option is |
| 376 | enabled. | 376 | enabled. |
| 377 | 377 | ||
| 378 | The /proc/PID/clear_refs is used to reset the PG_Referenced and ACCESSED/YOUNG | ||
| 379 | bits on both physical and virtual pages associated with a process. | ||
| 380 | To clear the bits for all the pages associated with the process | ||
| 381 | > echo 1 > /proc/PID/clear_refs | ||
| 382 | |||
| 383 | To clear the bits for the anonymous pages associated with the process | ||
| 384 | > echo 2 > /proc/PID/clear_refs | ||
| 385 | |||
| 386 | To clear the bits for the file mapped pages associated with the process | ||
| 387 | > echo 3 > /proc/PID/clear_refs | ||
| 388 | Any other value written to /proc/PID/clear_refs will have no effect. | ||
| 389 | |||
| 390 | |||
| 378 | 1.2 Kernel data | 391 | 1.2 Kernel data |
| 379 | --------------- | 392 | --------------- |
| 380 | 393 | ||
| @@ -1032,9 +1045,9 @@ Various pieces of information about kernel activity are available in the | |||
| 1032 | since the system first booted. For a quick look, simply cat the file: | 1045 | since the system first booted. For a quick look, simply cat the file: |
| 1033 | 1046 | ||
| 1034 | > cat /proc/stat | 1047 | > cat /proc/stat |
| 1035 | cpu 2255 34 2290 22625563 6290 127 456 0 | 1048 | cpu 2255 34 2290 22625563 6290 127 456 0 0 |
| 1036 | cpu0 1132 34 1441 11311718 3675 127 438 0 | 1049 | cpu0 1132 34 1441 11311718 3675 127 438 0 0 |
| 1037 | cpu1 1123 0 849 11313845 2614 0 18 0 | 1050 | cpu1 1123 0 849 11313845 2614 0 18 0 0 |
| 1038 | intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...] | 1051 | intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...] |
| 1039 | ctxt 1990473 | 1052 | ctxt 1990473 |
| 1040 | btime 1062191376 | 1053 | btime 1062191376 |
| @@ -1056,6 +1069,7 @@ second). The meanings of the columns are as follows, from left to right: | |||
| 1056 | - irq: servicing interrupts | 1069 | - irq: servicing interrupts |
| 1057 | - softirq: servicing softirqs | 1070 | - softirq: servicing softirqs |
| 1058 | - steal: involuntary wait | 1071 | - steal: involuntary wait |
| 1072 | - guest: running a guest | ||
| 1059 | 1073 | ||
| 1060 | The "intr" line gives counts of interrupts serviced since boot time, for each | 1074 | The "intr" line gives counts of interrupts serviced since boot time, for each |
| 1061 | of the possible system interrupts. The first column is the total of all | 1075 | of the possible system interrupts. The first column is the total of all |
| @@ -1167,13 +1181,11 @@ CHAPTER 3: PER-PROCESS PARAMETERS | |||
| 1167 | 3.1 /proc/<pid>/oom_adj - Adjust the oom-killer score | 1181 | 3.1 /proc/<pid>/oom_adj - Adjust the oom-killer score |
| 1168 | ------------------------------------------------------ | 1182 | ------------------------------------------------------ |
| 1169 | 1183 | ||
| 1170 | This file can be used to adjust the score used to select which processes should | 1184 | This file can be used to adjust the score used to select which processes |
| 1171 | be killed in an out-of-memory situation. The oom_adj value is a characteristic | 1185 | should be killed in an out-of-memory situation. Giving it a high score will |
| 1172 | of the task's mm, so all threads that share an mm with pid will have the same | 1186 | increase the likelihood of this process being killed by the oom-killer. Valid |
| 1173 | oom_adj value. A high value will increase the likelihood of this process being | 1187 | values are in the range -16 to +15, plus the special value -17, which disables |
| 1174 | killed by the oom-killer. Valid values are in the range -16 to +15 as | 1188 | oom-killing altogether for this process. |
| 1175 | explained below and a special value of -17, which disables oom-killing | ||
| 1176 | altogether for threads sharing pid's mm. | ||
| 1177 | 1189 | ||
| 1178 | The process to be killed in an out-of-memory situation is selected among all others | 1190 | The process to be killed in an out-of-memory situation is selected among all others |
| 1179 | based on its badness score. This value equals the original memory size of the process | 1191 | based on its badness score. This value equals the original memory size of the process |
| @@ -1187,16 +1199,13 @@ the parent's score if they do not share the same memory. Thus forking servers | |||
| 1187 | are the prime candidates to be killed. Having only one 'hungry' child will make | 1199 | are the prime candidates to be killed. Having only one 'hungry' child will make |
| 1188 | parent less preferable than the child. | 1200 | parent less preferable than the child. |
| 1189 | 1201 | ||
| 1190 | /proc/<pid>/oom_adj cannot be changed for kthreads since they are immune from | ||
| 1191 | oom-killing already. | ||
| 1192 | |||
| 1193 | /proc/<pid>/oom_score shows process' current badness score. | 1202 | /proc/<pid>/oom_score shows process' current badness score. |
| 1194 | 1203 | ||
| 1195 | The following heuristics are then applied: | 1204 | The following heuristics are then applied: |
| 1196 | * if the task was reniced, its score doubles | 1205 | * if the task was reniced, its score doubles |
| 1197 | * superuser or direct hardware access tasks (CAP_SYS_ADMIN, CAP_SYS_RESOURCE | 1206 | * superuser or direct hardware access tasks (CAP_SYS_ADMIN, CAP_SYS_RESOURCE |
| 1198 | or CAP_SYS_RAWIO) have their score divided by 4 | 1207 | or CAP_SYS_RAWIO) have their score divided by 4 |
| 1199 | * if oom condition happened in one cpuset and checked task does not belong | 1208 | * if oom condition happened in one cpuset and checked process does not belong |
| 1200 | to it, its score is divided by 8 | 1209 | to it, its score is divided by 8 |
| 1201 | * the resulting score is multiplied by two to the power of oom_adj, i.e. | 1210 | * the resulting score is multiplied by two to the power of oom_adj, i.e. |
| 1202 | points <<= oom_adj when it is positive and | 1211 | points <<= oom_adj when it is positive and |
diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt index b843743aa0b5..0d15ebccf5b0 100644 --- a/Documentation/filesystems/seq_file.txt +++ b/Documentation/filesystems/seq_file.txt | |||
| @@ -46,7 +46,7 @@ better to do. The file is seekable, in that one can do something like the | |||
| 46 | following: | 46 | following: |
| 47 | 47 | ||
| 48 | dd if=/proc/sequence of=out1 count=1 | 48 | dd if=/proc/sequence of=out1 count=1 |
| 49 | dd if=/proc/sequence skip=1 out=out2 count=1 | 49 | dd if=/proc/sequence skip=1 of=out2 count=1 |
| 50 | 50 | ||
| 51 | Then concatenate the output files out1 and out2 and get the right | 51 | Then concatenate the output files out1 and out2 and get the right |
| 52 | result. Yes, it is a thoroughly useless module, but the point is to show | 52 | result. Yes, it is a thoroughly useless module, but the point is to show |
diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 7e81e37c0b1e..b245d524d568 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt | |||
| @@ -23,7 +23,8 @@ interface. | |||
| 23 | Using sysfs | 23 | Using sysfs |
| 24 | ~~~~~~~~~~~ | 24 | ~~~~~~~~~~~ |
| 25 | 25 | ||
| 26 | sysfs is always compiled in. You can access it by doing: | 26 | sysfs is always compiled in if CONFIG_SYSFS is defined. You can access |
| 27 | it by doing: | ||
| 27 | 28 | ||
| 28 | mount -t sysfs sysfs /sys | 29 | mount -t sysfs sysfs /sys |
| 29 | 30 | ||
diff --git a/Documentation/flexible-arrays.txt b/Documentation/flexible-arrays.txt new file mode 100644 index 000000000000..84eb26808dee --- /dev/null +++ b/Documentation/flexible-arrays.txt | |||
| @@ -0,0 +1,99 @@ | |||
| 1 | Using flexible arrays in the kernel | ||
| 2 | Last updated for 2.6.31 | ||
| 3 | Jonathan Corbet <corbet@lwn.net> | ||
| 4 | |||
| 5 | Large contiguous memory allocations can be unreliable in the Linux kernel. | ||
| 6 | Kernel programmers will sometimes respond to this problem by allocating | ||
| 7 | pages with vmalloc(). This solution not ideal, though. On 32-bit systems, | ||
| 8 | memory from vmalloc() must be mapped into a relatively small address space; | ||
| 9 | it's easy to run out. On SMP systems, the page table changes required by | ||
| 10 | vmalloc() allocations can require expensive cross-processor interrupts on | ||
| 11 | all CPUs. And, on all systems, use of space in the vmalloc() range | ||
| 12 | increases pressure on the translation lookaside buffer (TLB), reducing the | ||
| 13 | performance of the system. | ||
| 14 | |||
| 15 | In many cases, the need for memory from vmalloc() can be eliminated by | ||
| 16 | piecing together an array from smaller parts; the flexible array library | ||
| 17 | exists to make this task easier. | ||
| 18 | |||
| 19 | A flexible array holds an arbitrary (within limits) number of fixed-sized | ||
| 20 | objects, accessed via an integer index. Sparse arrays are handled | ||
| 21 | reasonably well. Only single-page allocations are made, so memory | ||
| 22 | allocation failures should be relatively rare. The down sides are that the | ||
| 23 | arrays cannot be indexed directly, individual object size cannot exceed the | ||
| 24 | system page size, and putting data into a flexible array requires a copy | ||
| 25 | operation. It's also worth noting that flexible arrays do no internal | ||
| 26 | locking at all; if concurrent access to an array is possible, then the | ||
| 27 | caller must arrange for appropriate mutual exclusion. | ||
| 28 | |||
| 29 | The creation of a flexible array is done with: | ||
| 30 | |||
| 31 | #include <linux/flex_array.h> | ||
| 32 | |||
| 33 | struct flex_array *flex_array_alloc(int element_size, | ||
| 34 | unsigned int total, | ||
| 35 | gfp_t flags); | ||
| 36 | |||
| 37 | The individual object size is provided by element_size, while total is the | ||
| 38 | maximum number of objects which can be stored in the array. The flags | ||
| 39 | argument is passed directly to the internal memory allocation calls. With | ||
| 40 | the current code, using flags to ask for high memory is likely to lead to | ||
| 41 | notably unpleasant side effects. | ||
| 42 | |||
| 43 | Storing data into a flexible array is accomplished with a call to: | ||
| 44 | |||
| 45 | int flex_array_put(struct flex_array *array, unsigned int element_nr, | ||
| 46 | void *src, gfp_t flags); | ||
| 47 | |||
| 48 | This call will copy the data from src into the array, in the position | ||
| 49 | indicated by element_nr (which must be less than the maximum specified when | ||
| 50 | the array was created). If any memory allocations must be performed, flags | ||
| 51 | will be used. The return value is zero on success, a negative error code | ||
| 52 | otherwise. | ||
| 53 | |||
| 54 | There might possibly be a need to store data into a flexible array while | ||
| 55 | running in some sort of atomic context; in this situation, sleeping in the | ||
| 56 | memory allocator would be a bad thing. That can be avoided by using | ||
| 57 | GFP_ATOMIC for the flags value, but, often, there is a better way. The | ||
| 58 | trick is to ensure that any needed memory allocations are done before | ||
| 59 | entering atomic context, using: | ||
| 60 | |||
| 61 | int flex_array_prealloc(struct flex_array *array, unsigned int start, | ||
| 62 | unsigned int end, gfp_t flags); | ||
| 63 | |||
| 64 | This function will ensure that memory for the elements indexed in the range | ||
| 65 | defined by start and end has been allocated. Thereafter, a | ||
| 66 | flex_array_put() call on an element in that range is guaranteed not to | ||
| 67 | block. | ||
| 68 | |||
| 69 | Getting data back out of the array is done with: | ||
| 70 | |||
| 71 | void *flex_array_get(struct flex_array *fa, unsigned int element_nr); | ||
| 72 | |||
| 73 | The return value is a pointer to the data element, or NULL if that | ||
| 74 | particular element has never been allocated. | ||
| 75 | |||
| 76 | Note that it is possible to get back a valid pointer for an element which | ||
| 77 | has never been stored in the array. Memory for array elements is allocated | ||
| 78 | one page at a time; a single allocation could provide memory for several | ||
| 79 | adjacent elements. The flexible array code does not know if a specific | ||
| 80 | element has been written; it only knows if the associated memory is | ||
| 81 | present. So a flex_array_get() call on an element which was never stored | ||
| 82 | in the array has the potential to return a pointer to random data. If the | ||
| 83 | caller does not have a separate way to know which elements were actually | ||
| 84 | stored, it might be wise, at least, to add GFP_ZERO to the flags argument | ||
| 85 | to ensure that all elements are zeroed. | ||
| 86 | |||
| 87 | There is no way to remove a single element from the array. It is possible, | ||
| 88 | though, to remove all elements with a call to: | ||
| 89 | |||
| 90 | void flex_array_free_parts(struct flex_array *array); | ||
| 91 | |||
| 92 | This call frees all elements, but leaves the array itself in place. | ||
| 93 | Freeing the entire array is done with: | ||
| 94 | |||
| 95 | void flex_array_free(struct flex_array *array); | ||
| 96 | |||
| 97 | As of this writing, there are no users of flexible arrays in the mainline | ||
| 98 | kernel. The functions described here are also not exported to modules; | ||
| 99 | that will probably be fixed when somebody comes up with a need for it. | ||
diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt index e716aadb3a33..e7ca6478cd93 100644 --- a/Documentation/gcov.txt +++ b/Documentation/gcov.txt | |||
| @@ -47,7 +47,7 @@ Possible uses: | |||
| 47 | 47 | ||
| 48 | Configure the kernel with: | 48 | Configure the kernel with: |
| 49 | 49 | ||
| 50 | CONFIG_DEBUGFS=y | 50 | CONFIG_DEBUG_FS=y |
| 51 | CONFIG_GCOV_KERNEL=y | 51 | CONFIG_GCOV_KERNEL=y |
| 52 | 52 | ||
| 53 | and to get coverage data for the entire kernel: | 53 | and to get coverage data for the entire kernel: |
| @@ -188,13 +188,18 @@ Solution: Exclude affected source files from profiling by specifying | |||
| 188 | GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the | 188 | GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the |
| 189 | corresponding Makefile. | 189 | corresponding Makefile. |
| 190 | 190 | ||
| 191 | Problem: Files copied from sysfs appear empty or incomplete. | ||
| 192 | Cause: Due to the way seq_file works, some tools such as cp or tar | ||
| 193 | may not correctly copy files from sysfs. | ||
| 194 | Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links. | ||
| 195 | Alternatively use the mechanism shown in Appendix B. | ||
| 196 | |||
| 191 | 197 | ||
| 192 | Appendix A: gather_on_build.sh | 198 | Appendix A: gather_on_build.sh |
| 193 | ============================== | 199 | ============================== |
| 194 | 200 | ||
| 195 | Sample script to gather coverage meta files on the build machine | 201 | Sample script to gather coverage meta files on the build machine |
| 196 | (see 6a): | 202 | (see 6a): |
| 197 | |||
| 198 | #!/bin/bash | 203 | #!/bin/bash |
| 199 | 204 | ||
| 200 | KSRC=$1 | 205 | KSRC=$1 |
| @@ -226,7 +231,7 @@ Appendix B: gather_on_test.sh | |||
| 226 | Sample script to gather coverage data files on the test machine | 231 | Sample script to gather coverage data files on the test machine |
| 227 | (see 6b): | 232 | (see 6b): |
| 228 | 233 | ||
| 229 | #!/bin/bash | 234 | #!/bin/bash -e |
| 230 | 235 | ||
| 231 | DEST=$1 | 236 | DEST=$1 |
| 232 | GCDA=/sys/kernel/debug/gcov | 237 | GCDA=/sys/kernel/debug/gcov |
| @@ -236,11 +241,13 @@ if [ -z "$DEST" ] ; then | |||
| 236 | exit 1 | 241 | exit 1 |
| 237 | fi | 242 | fi |
| 238 | 243 | ||
| 239 | find $GCDA -name '*.gcno' -o -name '*.gcda' | tar cfz $DEST -T - | 244 | TEMPDIR=$(mktemp -d) |
| 245 | echo Collecting data.. | ||
| 246 | find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; | ||
| 247 | find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; | ||
| 248 | find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; | ||
| 249 | tar czf $DEST -C $TEMPDIR sys | ||
| 250 | rm -rf $TEMPDIR | ||
| 240 | 251 | ||
| 241 | if [ $? -eq 0 ] ; then | 252 | echo "$DEST successfully created, copy to build system and unpack with:" |
| 242 | echo "$DEST successfully created, copy to build system and unpack with:" | 253 | echo " tar xfz $DEST" |
| 243 | echo " tar xfz $DEST" | ||
| 244 | else | ||
| 245 | echo "Could not create file $DEST" | ||
| 246 | fi | ||
diff --git a/Documentation/hwmon/hpfall.c b/Documentation/hwmon/hpfall.c index bbea1ccfd46a..681ec22b9d0e 100644 --- a/Documentation/hwmon/hpfall.c +++ b/Documentation/hwmon/hpfall.c | |||
| @@ -16,6 +16,34 @@ | |||
| 16 | #include <stdint.h> | 16 | #include <stdint.h> |
| 17 | #include <errno.h> | 17 | #include <errno.h> |
| 18 | #include <signal.h> | 18 | #include <signal.h> |
| 19 | #include <sys/mman.h> | ||
| 20 | #include <sched.h> | ||
| 21 | |||
| 22 | char unload_heads_path[64]; | ||
| 23 | |||
| 24 | int set_unload_heads_path(char *device) | ||
| 25 | { | ||
| 26 | char devname[64]; | ||
| 27 | |||
| 28 | if (strlen(device) <= 5 || strncmp(device, "/dev/", 5) != 0) | ||
| 29 | return -EINVAL; | ||
| 30 | strncpy(devname, device + 5, sizeof(devname)); | ||
| 31 | |||
| 32 | snprintf(unload_heads_path, sizeof(unload_heads_path), | ||
| 33 | "/sys/block/%s/device/unload_heads", devname); | ||
| 34 | return 0; | ||
| 35 | } | ||
| 36 | int valid_disk(void) | ||
| 37 | { | ||
| 38 | int fd = open(unload_heads_path, O_RDONLY); | ||
| 39 | if (fd < 0) { | ||
| 40 | perror(unload_heads_path); | ||
| 41 | return 0; | ||
| 42 | } | ||
| 43 | |||
| 44 | close(fd); | ||
| 45 | return 1; | ||
| 46 | } | ||
| 19 | 47 | ||
| 20 | void write_int(char *path, int i) | 48 | void write_int(char *path, int i) |
| 21 | { | 49 | { |
| @@ -40,7 +68,7 @@ void set_led(int on) | |||
| 40 | 68 | ||
| 41 | void protect(int seconds) | 69 | void protect(int seconds) |
| 42 | { | 70 | { |
| 43 | write_int("/sys/block/sda/device/unload_heads", seconds*1000); | 71 | write_int(unload_heads_path, seconds*1000); |
| 44 | } | 72 | } |
| 45 | 73 | ||
| 46 | int on_ac(void) | 74 | int on_ac(void) |
| @@ -57,45 +85,62 @@ void ignore_me(void) | |||
| 57 | { | 85 | { |
| 58 | protect(0); | 86 | protect(0); |
| 59 | set_led(0); | 87 | set_led(0); |
| 60 | |||
| 61 | } | 88 | } |
| 62 | 89 | ||
| 63 | int main(int argc, char* argv[]) | 90 | int main(int argc, char **argv) |
| 64 | { | 91 | { |
| 65 | int fd, ret; | 92 | int fd, ret; |
| 93 | struct sched_param param; | ||
| 94 | |||
| 95 | if (argc == 1) | ||
| 96 | ret = set_unload_heads_path("/dev/sda"); | ||
| 97 | else if (argc == 2) | ||
| 98 | ret = set_unload_heads_path(argv[1]); | ||
| 99 | else | ||
| 100 | ret = -EINVAL; | ||
| 101 | |||
| 102 | if (ret || !valid_disk()) { | ||
| 103 | fprintf(stderr, "usage: %s <device> (default: /dev/sda)\n", | ||
| 104 | argv[0]); | ||
| 105 | exit(1); | ||
| 106 | } | ||
| 107 | |||
| 108 | fd = open("/dev/freefall", O_RDONLY); | ||
| 109 | if (fd < 0) { | ||
| 110 | perror("/dev/freefall"); | ||
| 111 | return EXIT_FAILURE; | ||
| 112 | } | ||
| 66 | 113 | ||
| 67 | fd = open("/dev/freefall", O_RDONLY); | 114 | daemon(0, 0); |
| 68 | if (fd < 0) { | 115 | param.sched_priority = sched_get_priority_max(SCHED_FIFO); |
| 69 | perror("open"); | 116 | sched_setscheduler(0, SCHED_FIFO, ¶m); |
| 70 | return EXIT_FAILURE; | 117 | mlockall(MCL_CURRENT|MCL_FUTURE); |
| 71 | } | ||
| 72 | 118 | ||
| 73 | signal(SIGALRM, ignore_me); | 119 | signal(SIGALRM, ignore_me); |
| 74 | 120 | ||
| 75 | for (;;) { | 121 | for (;;) { |
| 76 | unsigned char count; | 122 | unsigned char count; |
| 77 | 123 | ||
| 78 | ret = read(fd, &count, sizeof(count)); | 124 | ret = read(fd, &count, sizeof(count)); |
| 79 | alarm(0); | 125 | alarm(0); |
| 80 | if ((ret == -1) && (errno == EINTR)) { | 126 | if ((ret == -1) && (errno == EINTR)) { |
| 81 | /* Alarm expired, time to unpark the heads */ | 127 | /* Alarm expired, time to unpark the heads */ |
| 82 | continue; | 128 | continue; |
| 83 | } | 129 | } |
| 84 | 130 | ||
| 85 | if (ret != sizeof(count)) { | 131 | if (ret != sizeof(count)) { |
| 86 | perror("read"); | 132 | perror("read"); |
| 87 | break; | 133 | break; |
| 88 | } | 134 | } |
| 89 | 135 | ||
| 90 | protect(21); | 136 | protect(21); |
| 91 | set_led(1); | 137 | set_led(1); |
| 92 | if (1 || on_ac() || lid_open()) { | 138 | if (1 || on_ac() || lid_open()) |
| 93 | alarm(2); | 139 | alarm(2); |
| 94 | } else { | 140 | else |
| 95 | alarm(20); | 141 | alarm(20); |
| 96 | } | 142 | } |
| 97 | } | 143 | |
| 98 | 144 | close(fd); | |
| 99 | close(fd); | 145 | return EXIT_SUCCESS; |
| 100 | return EXIT_SUCCESS; | ||
| 101 | } | 146 | } |
diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427 index d1ebbe510f35..db5cc1227a83 100644 --- a/Documentation/hwmon/pc87427 +++ b/Documentation/hwmon/pc87427 | |||
| @@ -34,5 +34,5 @@ Fan rotation speeds are reported as 14-bit values from a gated clock | |||
| 34 | signal. Speeds down to 83 RPM can be measured. | 34 | signal. Speeds down to 83 RPM can be measured. |
| 35 | 35 | ||
| 36 | An alarm is triggered if the rotation speed drops below a programmable | 36 | An alarm is triggered if the rotation speed drops below a programmable |
| 37 | limit. Another alarm is triggered if the speed is too low to to be measured | 37 | limit. Another alarm is triggered if the speed is too low to be measured |
| 38 | (including stalled or missing fan). | 38 | (including stalled or missing fan). |
diff --git a/Documentation/hwmon/pcf8591 b/Documentation/hwmon/pcf8591 index 5628fcf4207f..e76a7892f68e 100644 --- a/Documentation/hwmon/pcf8591 +++ b/Documentation/hwmon/pcf8591 | |||
| @@ -2,11 +2,11 @@ Kernel driver pcf8591 | |||
| 2 | ===================== | 2 | ===================== |
| 3 | 3 | ||
| 4 | Supported chips: | 4 | Supported chips: |
| 5 | * Philips PCF8591 | 5 | * Philips/NXP PCF8591 |
| 6 | Prefix: 'pcf8591' | 6 | Prefix: 'pcf8591' |
| 7 | Addresses scanned: I2C 0x48 - 0x4f | 7 | Addresses scanned: I2C 0x48 - 0x4f |
| 8 | Datasheet: Publicly available at the Philips Semiconductor website | 8 | Datasheet: Publicly available at the NXP website |
| 9 | http://www.semiconductors.philips.com/pip/PCF8591P.html | 9 | http://www.nxp.com/pip/PCF8591_6.html |
| 10 | 10 | ||
| 11 | Authors: | 11 | Authors: |
| 12 | Aurelien Jarno <aurelien@aurel32.net> | 12 | Aurelien Jarno <aurelien@aurel32.net> |
| @@ -16,9 +16,10 @@ Authors: | |||
| 16 | 16 | ||
| 17 | Description | 17 | Description |
| 18 | ----------- | 18 | ----------- |
| 19 | |||
| 19 | The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one | 20 | The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one |
| 20 | analog output) for the I2C bus produced by Philips Semiconductors. It | 21 | analog output) for the I2C bus produced by Philips Semiconductors (now NXP). |
| 21 | is designed to provide a byte I2C interface to up to 4 separate devices. | 22 | It is designed to provide a byte I2C interface to up to 4 separate devices. |
| 22 | 23 | ||
| 23 | The PCF8591 has 4 analog inputs programmable as single-ended or | 24 | The PCF8591 has 4 analog inputs programmable as single-ended or |
| 24 | differential inputs : | 25 | differential inputs : |
| @@ -58,8 +59,8 @@ Accessing PCF8591 via /sys interface | |||
| 58 | ------------------------------------- | 59 | ------------------------------------- |
| 59 | 60 | ||
| 60 | ! Be careful ! | 61 | ! Be careful ! |
| 61 | The PCF8591 is plainly impossible to detect ! Stupid chip. | 62 | The PCF8591 is plainly impossible to detect! Stupid chip. |
| 62 | So every chip with address in the interval [48..4f] is | 63 | So every chip with address in the interval [0x48..0x4f] is |
| 63 | detected as PCF8591. If you have other chips in this address | 64 | detected as PCF8591. If you have other chips in this address |
| 64 | range, the workaround is to load this module after the one | 65 | range, the workaround is to load this module after the one |
| 65 | for your others chips. | 66 | for your others chips. |
| @@ -67,19 +68,20 @@ for your others chips. | |||
| 67 | On detection (i.e. insmod, modprobe et al.), directories are being | 68 | On detection (i.e. insmod, modprobe et al.), directories are being |
| 68 | created for each detected PCF8591: | 69 | created for each detected PCF8591: |
| 69 | 70 | ||
| 70 | /sys/bus/devices/<0>-<1>/ | 71 | /sys/bus/i2c/devices/<0>-<1>/ |
| 71 | where <0> is the bus the chip was detected on (e. g. i2c-0) | 72 | where <0> is the bus the chip was detected on (e. g. i2c-0) |
| 72 | and <1> the chip address ([48..4f]) | 73 | and <1> the chip address ([48..4f]) |
| 73 | 74 | ||
| 74 | Inside these directories, there are such files: | 75 | Inside these directories, there are such files: |
| 75 | in0, in1, in2, in3, out0_enable, out0_output, name | 76 | in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name |
| 76 | 77 | ||
| 77 | Name contains chip name. | 78 | Name contains chip name. |
| 78 | 79 | ||
| 79 | The in0, in1, in2 and in3 files are RO. Reading gives the value of the | 80 | The in0_input, in1_input, in2_input and in3_input files are RO. Reading gives |
| 80 | corresponding channel. Depending on the current analog inputs configuration, | 81 | the value of the corresponding channel. Depending on the current analog inputs |
| 81 | files in2 and/or in3 do not exist. Values range are from 0 to 255 for single | 82 | configuration, files in2_input and in3_input may not exist. Values range |
| 82 | ended inputs and -128 to +127 for differential inputs (8-bit ADC). | 83 | from 0 to 255 for single ended inputs and -128 to +127 for differential inputs |
| 84 | (8-bit ADC). | ||
| 83 | 85 | ||
| 84 | The out0_enable file is RW. Reading gives "1" for analog output enabled and | 86 | The out0_enable file is RW. Reading gives "1" for analog output enabled and |
| 85 | "0" for analog output disabled. Writing accepts "0" and "1" accordingly. | 87 | "0" for analog output disabled. Writing accepts "0" and "1" accordingly. |
diff --git a/Documentation/hwmon/tmp421 b/Documentation/hwmon/tmp421 new file mode 100644 index 000000000000..0cf07f824741 --- /dev/null +++ b/Documentation/hwmon/tmp421 | |||
| @@ -0,0 +1,36 @@ | |||
| 1 | Kernel driver tmp421 | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Texas Instruments TMP421 | ||
| 6 | Prefix: 'tmp421' | ||
| 7 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 8 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 9 | * Texas Instruments TMP422 | ||
| 10 | Prefix: 'tmp422' | ||
| 11 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 12 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 13 | * Texas Instruments TMP423 | ||
| 14 | Prefix: 'tmp423' | ||
| 15 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 16 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 17 | |||
| 18 | Authors: | ||
| 19 | Andre Prendel <andre.prendel@gmx.de> | ||
| 20 | |||
| 21 | Description | ||
| 22 | ----------- | ||
| 23 | |||
| 24 | This driver implements support for Texas Instruments TMP421, TMP422 | ||
| 25 | and TMP423 temperature sensor chips. These chips implement one local | ||
| 26 | and up to one (TMP421), up to two (TMP422) or up to three (TMP423) | ||
| 27 | remote sensors. Temperature is measured in degrees Celsius. The chips | ||
| 28 | are wired over I2C/SMBus and specified over a temperature range of -40 | ||
| 29 | to +125 degrees Celsius. Resolution for both the local and remote | ||
| 30 | channels is 0.0625 degree C. | ||
| 31 | |||
| 32 | The chips support only temperature measurement. The driver exports | ||
| 33 | the temperature values via the following sysfs files: | ||
| 34 | |||
| 35 | temp[1-4]_input | ||
| 36 | temp[2-4]_fault | ||
diff --git a/Documentation/hwmon/wm831x b/Documentation/hwmon/wm831x new file mode 100644 index 000000000000..24f47d8f6a42 --- /dev/null +++ b/Documentation/hwmon/wm831x | |||
| @@ -0,0 +1,37 @@ | |||
| 1 | Kernel driver wm831x-hwmon | ||
| 2 | ========================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Wolfson Microelectronics WM831x PMICs | ||
| 6 | Prefix: 'wm831x' | ||
| 7 | Datasheet: | ||
| 8 | http://www.wolfsonmicro.com/products/WM8310 | ||
| 9 | http://www.wolfsonmicro.com/products/WM8311 | ||
| 10 | http://www.wolfsonmicro.com/products/WM8312 | ||
| 11 | |||
| 12 | Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> | ||
| 13 | |||
| 14 | Description | ||
| 15 | ----------- | ||
| 16 | |||
| 17 | The WM831x series of PMICs include an AUXADC which can be used to | ||
| 18 | monitor a range of system operating parameters, including the voltages | ||
| 19 | of the major supplies within the system. Currently the driver provides | ||
| 20 | reporting of all the input values but does not provide any alarms. | ||
| 21 | |||
| 22 | Voltage Monitoring | ||
| 23 | ------------------ | ||
| 24 | |||
| 25 | Voltages are sampled by a 12 bit ADC. Voltages in milivolts are 1.465 | ||
| 26 | times the ADC value. | ||
| 27 | |||
| 28 | Temperature Monitoring | ||
| 29 | ---------------------- | ||
| 30 | |||
| 31 | Temperatures are sampled by a 12 bit ADC. Chip and battery temperatures | ||
| 32 | are available. The chip temperature is calculated as: | ||
| 33 | |||
| 34 | Degrees celsius = (512.18 - data) / 1.0983 | ||
| 35 | |||
| 36 | while the battery temperature calculation will depend on the NTC | ||
| 37 | thermistor component. | ||
diff --git a/Documentation/hwmon/wm8350 b/Documentation/hwmon/wm8350 new file mode 100644 index 000000000000..98f923bd2e92 --- /dev/null +++ b/Documentation/hwmon/wm8350 | |||
| @@ -0,0 +1,26 @@ | |||
| 1 | Kernel driver wm8350-hwmon | ||
| 2 | ========================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Wolfson Microelectronics WM835x PMICs | ||
| 6 | Prefix: 'wm8350' | ||
| 7 | Datasheet: | ||
| 8 | http://www.wolfsonmicro.com/products/WM8350 | ||
| 9 | http://www.wolfsonmicro.com/products/WM8351 | ||
| 10 | http://www.wolfsonmicro.com/products/WM8352 | ||
| 11 | |||
| 12 | Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> | ||
| 13 | |||
| 14 | Description | ||
| 15 | ----------- | ||
| 16 | |||
| 17 | The WM835x series of PMICs include an AUXADC which can be used to | ||
| 18 | monitor a range of system operating parameters, including the voltages | ||
| 19 | of the major supplies within the system. Currently the driver provides | ||
| 20 | simple access to these major supplies. | ||
| 21 | |||
| 22 | Voltage Monitoring | ||
| 23 | ------------------ | ||
| 24 | |||
| 25 | Voltages are sampled by a 12 bit ADC. For the internal supplies the ADC | ||
| 26 | is referenced to the system VRTC. | ||
diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt new file mode 100644 index 000000000000..f7160a2fb6a2 --- /dev/null +++ b/Documentation/input/sentelic.txt | |||
| @@ -0,0 +1,475 @@ | |||
| 1 | Copyright (C) 2002-2008 Sentelic Corporation. | ||
| 2 | Last update: Oct-31-2008 | ||
| 3 | |||
| 4 | ============================================================================== | ||
| 5 | * Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons) | ||
| 6 | ============================================================================== | ||
| 7 | A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward | ||
| 8 | page (5th button) | ||
| 9 | @1. Set sample rate to 200; | ||
| 10 | @2. Set sample rate to 200; | ||
| 11 | @3. Set sample rate to 80; | ||
| 12 | @4. Issuing the "Get device ID" command (0xF2) and waits for the response; | ||
| 13 | @5. FSP will respond 0x04. | ||
| 14 | |||
| 15 | Packet 1 | ||
| 16 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 17 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 18 | 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|W|W|W|W| | ||
| 19 | |---------------| |---------------| |---------------| |---------------| | ||
| 20 | |||
| 21 | Byte 1: Bit7 => Y overflow | ||
| 22 | Bit6 => X overflow | ||
| 23 | Bit5 => Y sign bit | ||
| 24 | Bit4 => X sign bit | ||
| 25 | Bit3 => 1 | ||
| 26 | Bit2 => Middle Button, 1 is pressed, 0 is not pressed. | ||
| 27 | Bit1 => Right Button, 1 is pressed, 0 is not pressed. | ||
| 28 | Bit0 => Left Button, 1 is pressed, 0 is not pressed. | ||
| 29 | Byte 2: X Movement(9-bit 2's complement integers) | ||
| 30 | Byte 3: Y Movement(9-bit 2's complement integers) | ||
| 31 | Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report. | ||
| 32 | valid values, -8 ~ +7 | ||
| 33 | Bit4 => 1 = 4th mouse button is pressed, Forward one page. | ||
| 34 | 0 = 4th mouse button is not pressed. | ||
| 35 | Bit5 => 1 = 5th mouse button is pressed, Backward one page. | ||
| 36 | 0 = 5th mouse button is not pressed. | ||
| 37 | |||
| 38 | B) MSID 6: Horizontal and Vertical scrolling. | ||
| 39 | @ Set bit 1 in register 0x40 to 1 | ||
| 40 | |||
| 41 | # FSP replaces scrolling wheel's movement as 4 bits to show horizontal and | ||
| 42 | vertical scrolling. | ||
| 43 | |||
| 44 | Packet 1 | ||
| 45 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 46 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 47 | 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|l|r|u|d| | ||
| 48 | |---------------| |---------------| |---------------| |---------------| | ||
| 49 | |||
| 50 | Byte 1: Bit7 => Y overflow | ||
| 51 | Bit6 => X overflow | ||
| 52 | Bit5 => Y sign bit | ||
| 53 | Bit4 => X sign bit | ||
| 54 | Bit3 => 1 | ||
| 55 | Bit2 => Middle Button, 1 is pressed, 0 is not pressed. | ||
| 56 | Bit1 => Right Button, 1 is pressed, 0 is not pressed. | ||
| 57 | Bit0 => Left Button, 1 is pressed, 0 is not pressed. | ||
| 58 | Byte 2: X Movement(9-bit 2's complement integers) | ||
| 59 | Byte 3: Y Movement(9-bit 2's complement integers) | ||
| 60 | Byte 4: Bit0 => the Vertical scrolling movement downward. | ||
| 61 | Bit1 => the Vertical scrolling movement upward. | ||
| 62 | Bit2 => the Vertical scrolling movement rightward. | ||
| 63 | Bit3 => the Vertical scrolling movement leftward. | ||
| 64 | Bit4 => 1 = 4th mouse button is pressed, Forward one page. | ||
| 65 | 0 = 4th mouse button is not pressed. | ||
| 66 | Bit5 => 1 = 5th mouse button is pressed, Backward one page. | ||
| 67 | 0 = 5th mouse button is not pressed. | ||
| 68 | |||
| 69 | C) MSID 7: | ||
| 70 | # FSP uses 2 packets(8 Bytes) data to represent Absolute Position | ||
| 71 | so we have PACKET NUMBER to identify packets. | ||
| 72 | If PACKET NUMBER is 0, the packet is Packet 1. | ||
| 73 | If PACKET NUMBER is 1, the packet is Packet 2. | ||
| 74 | Please count this number in program. | ||
| 75 | |||
| 76 | # MSID6 special packet will be enable at the same time when enable MSID 7. | ||
| 77 | |||
| 78 | ============================================================================== | ||
| 79 | * Absolute position for STL3886-G0. | ||
| 80 | ============================================================================== | ||
| 81 | @ Set bit 2 or 3 in register 0x40 to 1 | ||
| 82 | @ Set bit 6 in register 0x40 to 1 | ||
| 83 | |||
| 84 | Packet 1 (ABSOLUTE POSITION) | ||
| 85 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 86 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 87 | 1 |0|1|V|1|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|d|u|X|X|Y|Y| | ||
| 88 | |---------------| |---------------| |---------------| |---------------| | ||
| 89 | |||
| 90 | Byte 1: Bit7~Bit6 => 00, Normal data packet | ||
| 91 | => 01, Absolute coordination packet | ||
| 92 | => 10, Notify packet | ||
| 93 | Bit5 => valid bit | ||
| 94 | Bit4 => 1 | ||
| 95 | Bit3 => 1 | ||
| 96 | Bit2 => Middle Button, 1 is pressed, 0 is not pressed. | ||
| 97 | Bit1 => Right Button, 1 is pressed, 0 is not pressed. | ||
| 98 | Bit0 => Left Button, 1 is pressed, 0 is not pressed. | ||
| 99 | Byte 2: X coordinate (xpos[9:2]) | ||
| 100 | Byte 3: Y coordinate (ypos[9:2]) | ||
| 101 | Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) | ||
| 102 | Bit3~Bit2 => X coordinate (ypos[1:0]) | ||
| 103 | Bit4 => scroll up | ||
| 104 | Bit5 => scroll down | ||
| 105 | Bit6 => scroll left | ||
| 106 | Bit7 => scroll right | ||
| 107 | |||
| 108 | Notify Packet for G0 | ||
| 109 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 110 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 111 | 1 |1|0|0|1|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |M|M|M|M|M|M|M|M| 4 |0|0|0|0|0|0|0|0| | ||
| 112 | |---------------| |---------------| |---------------| |---------------| | ||
| 113 | |||
| 114 | Byte 1: Bit7~Bit6 => 00, Normal data packet | ||
| 115 | => 01, Absolute coordination packet | ||
| 116 | => 10, Notify packet | ||
| 117 | Bit5 => 0 | ||
| 118 | Bit4 => 1 | ||
| 119 | Bit3 => 1 | ||
| 120 | Bit2 => Middle Button, 1 is pressed, 0 is not pressed. | ||
| 121 | Bit1 => Right Button, 1 is pressed, 0 is not pressed. | ||
| 122 | Bit0 => Left Button, 1 is pressed, 0 is not pressed. | ||
| 123 | Byte 2: Message Type => 0x5A (Enable/Disable status packet) | ||
| 124 | Mode Type => 0xA5 (Normal/Icon mode status) | ||
| 125 | Byte 3: Message Type => 0x00 (Disabled) | ||
| 126 | => 0x01 (Enabled) | ||
| 127 | Mode Type => 0x00 (Normal) | ||
| 128 | => 0x01 (Icon) | ||
| 129 | Byte 4: Bit7~Bit0 => Don't Care | ||
| 130 | |||
| 131 | ============================================================================== | ||
| 132 | * Absolute position for STL3888-A0. | ||
| 133 | ============================================================================== | ||
| 134 | Packet 1 (ABSOLUTE POSITION) | ||
| 135 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 136 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 137 | 1 |0|1|V|A|1|L|0|1| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| | ||
| 138 | |---------------| |---------------| |---------------| |---------------| | ||
| 139 | |||
| 140 | Byte 1: Bit7~Bit6 => 00, Normal data packet | ||
| 141 | => 01, Absolute coordination packet | ||
| 142 | => 10, Notify packet | ||
| 143 | Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. | ||
| 144 | When both fingers are up, the last two reports have zero valid | ||
| 145 | bit. | ||
| 146 | Bit4 => arc | ||
| 147 | Bit3 => 1 | ||
| 148 | Bit2 => Left Button, 1 is pressed, 0 is released. | ||
| 149 | Bit1 => 0 | ||
| 150 | Bit0 => 1 | ||
| 151 | Byte 2: X coordinate (xpos[9:2]) | ||
| 152 | Byte 3: Y coordinate (ypos[9:2]) | ||
| 153 | Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) | ||
| 154 | Bit3~Bit2 => X coordinate (ypos[1:0]) | ||
| 155 | Bit5~Bit4 => y1_g | ||
| 156 | Bit7~Bit6 => x1_g | ||
| 157 | |||
| 158 | Packet 2 (ABSOLUTE POSITION) | ||
| 159 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 160 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 161 | 1 |0|1|V|A|1|R|1|0| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| | ||
| 162 | |---------------| |---------------| |---------------| |---------------| | ||
| 163 | |||
| 164 | Byte 1: Bit7~Bit6 => 00, Normal data packet | ||
| 165 | => 01, Absolute coordinates packet | ||
| 166 | => 10, Notify packet | ||
| 167 | Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. | ||
| 168 | When both fingers are up, the last two reports have zero valid | ||
| 169 | bit. | ||
| 170 | Bit4 => arc | ||
| 171 | Bit3 => 1 | ||
| 172 | Bit2 => Right Button, 1 is pressed, 0 is released. | ||
| 173 | Bit1 => 1 | ||
| 174 | Bit0 => 0 | ||
| 175 | Byte 2: X coordinate (xpos[9:2]) | ||
| 176 | Byte 3: Y coordinate (ypos[9:2]) | ||
| 177 | Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) | ||
| 178 | Bit3~Bit2 => X coordinate (ypos[1:0]) | ||
| 179 | Bit5~Bit4 => y2_g | ||
| 180 | Bit7~Bit6 => x2_g | ||
| 181 | |||
| 182 | Notify Packet for STL3888-A0 | ||
| 183 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 184 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 185 | 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|d|u|0|0|0|0| | ||
| 186 | |---------------| |---------------| |---------------| |---------------| | ||
| 187 | |||
| 188 | Byte 1: Bit7~Bit6 => 00, Normal data packet | ||
| 189 | => 01, Absolute coordination packet | ||
| 190 | => 10, Notify packet | ||
| 191 | Bit5 => 1 | ||
| 192 | Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): | ||
| 193 | 0: left button is generated by the on-pad command | ||
| 194 | 1: left button is generated by the external button | ||
| 195 | Bit3 => 1 | ||
| 196 | Bit2 => Middle Button, 1 is pressed, 0 is not pressed. | ||
| 197 | Bit1 => Right Button, 1 is pressed, 0 is not pressed. | ||
| 198 | Bit0 => Left Button, 1 is pressed, 0 is not pressed. | ||
| 199 | Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) | ||
| 200 | Byte 3: Bit7~Bit6 => Don't care | ||
| 201 | Bit5~Bit4 => Number of fingers | ||
| 202 | Bit3~Bit1 => Reserved | ||
| 203 | Bit0 => 1: enter gesture mode; 0: leaving gesture mode | ||
| 204 | Byte 4: Bit7 => scroll right button | ||
| 205 | Bit6 => scroll left button | ||
| 206 | Bit5 => scroll down button | ||
| 207 | Bit4 => scroll up button | ||
| 208 | * Note that if gesture and additional button (Bit4~Bit7) | ||
| 209 | happen at the same time, the button information will not | ||
| 210 | be sent. | ||
| 211 | Bit3~Bit0 => Reserved | ||
| 212 | |||
| 213 | Sample sequence of Multi-finger, Multi-coordinate mode: | ||
| 214 | |||
| 215 | notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, | ||
| 216 | abs pkt 2, ..., notify packet(valid bit == 0) | ||
| 217 | |||
| 218 | ============================================================================== | ||
| 219 | * FSP Enable/Disable packet | ||
| 220 | ============================================================================== | ||
| 221 | Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 | ||
| 222 | BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| | ||
| 223 | 1 |Y|X|0|0|1|M|R|L| 2 |0|1|0|1|1|0|1|E| 3 | | | | | | | | | 4 | | | | | | | | | | ||
| 224 | |---------------| |---------------| |---------------| |---------------| | ||
| 225 | |||
| 226 | FSP will send out enable/disable packet when FSP receive PS/2 enable/disable | ||
| 227 | command. Host will receive the packet which Middle, Right, Left button will | ||
| 228 | be set. The packet only use byte 0 and byte 1 as a pattern of original packet. | ||
| 229 | Ignore the other bytes of the packet. | ||
| 230 | |||
| 231 | Byte 1: Bit7 => 0, Y overflow | ||
| 232 | Bit6 => 0, X overflow | ||
| 233 | Bit5 => 0, Y sign bit | ||
| 234 | Bit4 => 0, X sign bit | ||
| 235 | Bit3 => 1 | ||
| 236 | Bit2 => 1, Middle Button | ||
| 237 | Bit1 => 1, Right Button | ||
| 238 | Bit0 => 1, Left Button | ||
| 239 | Byte 2: Bit7~1 => (0101101b) | ||
| 240 | Bit0 => 1 = Enable | ||
| 241 | 0 = Disable | ||
| 242 | Byte 3: Don't care | ||
| 243 | Byte 4: Don't care (MOUSE ID 3, 4) | ||
| 244 | Byte 5~8: Don't care (Absolute packet) | ||
| 245 | |||
| 246 | ============================================================================== | ||
| 247 | * PS/2 Command Set | ||
| 248 | ============================================================================== | ||
| 249 | |||
| 250 | FSP supports basic PS/2 commanding set and modes, refer to following URL for | ||
| 251 | details about PS/2 commands: | ||
| 252 | |||
| 253 | http://www.computer-engineering.org/index.php?title=PS/2_Mouse_Interface | ||
| 254 | |||
| 255 | ============================================================================== | ||
| 256 | * Programming Sequence for Determining Packet Parsing Flow | ||
| 257 | ============================================================================== | ||
| 258 | 1. Identify FSP by reading device ID(0x00) and version(0x01) register | ||
| 259 | |||
| 260 | 2. Determine number of buttons by reading status2 (0x0b) register | ||
| 261 | |||
| 262 | buttons = reg[0x0b] & 0x30 | ||
| 263 | |||
| 264 | if buttons == 0x30 or buttons == 0x20: | ||
| 265 | # two/four buttons | ||
| 266 | Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' | ||
| 267 | section A for packet parsing detail(ignore byte 4, bit ~ 7) | ||
| 268 | elif buttons == 0x10: | ||
| 269 | # 6 buttons | ||
| 270 | Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' | ||
| 271 | section B for packet parsing detail | ||
| 272 | elif buttons == 0x00: | ||
| 273 | # 6 buttons | ||
| 274 | Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' | ||
| 275 | section A for packet parsing detail | ||
| 276 | |||
| 277 | ============================================================================== | ||
| 278 | * Programming Sequence for Register Reading/Writing | ||
| 279 | ============================================================================== | ||
| 280 | |||
| 281 | Register inversion requirement: | ||
| 282 | |||
| 283 | Following values needed to be inverted(the '~' operator in C) before being | ||
| 284 | sent to FSP: | ||
| 285 | |||
| 286 | 0xe9, 0xee, 0xf2 and 0xff. | ||
| 287 | |||
| 288 | Register swapping requirement: | ||
| 289 | |||
| 290 | Following values needed to have their higher 4 bits and lower 4 bits being | ||
| 291 | swapped before being sent to FSP: | ||
| 292 | |||
| 293 | 10, 20, 40, 60, 80, 100 and 200. | ||
| 294 | |||
| 295 | Register reading sequence: | ||
| 296 | |||
| 297 | 1. send 0xf3 PS/2 command to FSP; | ||
| 298 | |||
| 299 | 2. send 0x66 PS/2 command to FSP; | ||
| 300 | |||
| 301 | 3. send 0x88 PS/2 command to FSP; | ||
| 302 | |||
| 303 | 4. send 0xf3 PS/2 command to FSP; | ||
| 304 | |||
| 305 | 5. if the register address being to read is not required to be | ||
| 306 | inverted(refer to the 'Register inversion requirement' section), | ||
| 307 | goto step 6 | ||
| 308 | |||
| 309 | 5a. send 0x68 PS/2 command to FSP; | ||
| 310 | |||
| 311 | 5b. send the inverted register address to FSP and goto step 8; | ||
| 312 | |||
| 313 | 6. if the register address being to read is not required to be | ||
| 314 | swapped(refer to the 'Register swapping requirement' section), | ||
| 315 | goto step 7 | ||
| 316 | |||
| 317 | 6a. send 0xcc PS/2 command to FSP; | ||
| 318 | |||
| 319 | 6b. send the swapped register address to FSP and goto step 8; | ||
| 320 | |||
| 321 | 7. send 0x66 PS/2 command to FSP; | ||
| 322 | |||
| 323 | 7a. send the original register address to FSP and goto step 8; | ||
| 324 | |||
| 325 | 8. send 0xe9(status request) PS/2 command to FSP; | ||
| 326 | |||
| 327 | 9. the response read from FSP should be the requested register value. | ||
| 328 | |||
| 329 | Register writing sequence: | ||
| 330 | |||
| 331 | 1. send 0xf3 PS/2 command to FSP; | ||
| 332 | |||
| 333 | 2. if the register address being to write is not required to be | ||
| 334 | inverted(refer to the 'Register inversion requirement' section), | ||
| 335 | goto step 3 | ||
| 336 | |||
| 337 | 2a. send 0x74 PS/2 command to FSP; | ||
| 338 | |||
| 339 | 2b. send the inverted register address to FSP and goto step 5; | ||
| 340 | |||
| 341 | 3. if the register address being to write is not required to be | ||
| 342 | swapped(refer to the 'Register swapping requirement' section), | ||
| 343 | goto step 4 | ||
| 344 | |||
| 345 | 3a. send 0x77 PS/2 command to FSP; | ||
| 346 | |||
| 347 | 3b. send the swapped register address to FSP and goto step 5; | ||
| 348 | |||
| 349 | 4. send 0x55 PS/2 command to FSP; | ||
| 350 | |||
| 351 | 4a. send the register address to FSP and goto step 5; | ||
| 352 | |||
| 353 | 5. send 0xf3 PS/2 command to FSP; | ||
| 354 | |||
| 355 | 6. if the register value being to write is not required to be | ||
| 356 | inverted(refer to the 'Register inversion requirement' section), | ||
| 357 | goto step 7 | ||
| 358 | |||
| 359 | 6a. send 0x47 PS/2 command to FSP; | ||
| 360 | |||
| 361 | 6b. send the inverted register value to FSP and goto step 9; | ||
| 362 | |||
| 363 | 7. if the register value being to write is not required to be | ||
| 364 | swapped(refer to the 'Register swapping requirement' section), | ||
| 365 | goto step 8 | ||
| 366 | |||
| 367 | 7a. send 0x44 PS/2 command to FSP; | ||
| 368 | |||
| 369 | 7b. send the swapped register value to FSP and goto step 9; | ||
| 370 | |||
| 371 | 8. send 0x33 PS/2 command to FSP; | ||
| 372 | |||
| 373 | 8a. send the register value to FSP; | ||
| 374 | |||
| 375 | 9. the register writing sequence is completed. | ||
| 376 | |||
| 377 | ============================================================================== | ||
| 378 | * Register Listing | ||
| 379 | ============================================================================== | ||
| 380 | |||
| 381 | offset width default r/w name | ||
| 382 | 0x00 bit7~bit0 0x01 RO device ID | ||
| 383 | |||
| 384 | 0x01 bit7~bit0 0xc0 RW version ID | ||
| 385 | |||
| 386 | 0x02 bit7~bit0 0x01 RO vendor ID | ||
| 387 | |||
| 388 | 0x03 bit7~bit0 0x01 RO product ID | ||
| 389 | |||
| 390 | 0x04 bit3~bit0 0x01 RW revision ID | ||
| 391 | |||
| 392 | 0x0b RO test mode status 1 | ||
| 393 | bit3 1 RO 0: rotate 180 degree, 1: no rotation | ||
| 394 | |||
| 395 | bit5~bit4 RO number of buttons | ||
| 396 | 11 => 2, lbtn/rbtn | ||
| 397 | 10 => 4, lbtn/rbtn/scru/scrd | ||
| 398 | 01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr | ||
| 399 | 00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn | ||
| 400 | |||
| 401 | 0x0f RW register file page control | ||
| 402 | bit0 0 RW 1 to enable page 1 register files | ||
| 403 | |||
| 404 | 0x10 RW system control 1 | ||
| 405 | bit0 1 RW Reserved, must be 1 | ||
| 406 | bit1 0 RW Reserved, must be 0 | ||
| 407 | bit4 1 RW Reserved, must be 0 | ||
| 408 | bit5 0 RW register clock gating enable | ||
| 409 | 0: read only, 1: read/write enable | ||
| 410 | (Note that following registers does not require clock gating being | ||
| 411 | enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e | ||
| 412 | 40 41 42 43.) | ||
| 413 | |||
| 414 | 0x31 RW on-pad command detection | ||
| 415 | bit7 0 RW on-pad command left button down tag | ||
| 416 | enable | ||
| 417 | 0: disable, 1: enable | ||
| 418 | |||
| 419 | 0x34 RW on-pad command control 5 | ||
| 420 | bit4~bit0 0x05 RW XLO in 0s/4/1, so 03h = 0010.1b = 2.5 | ||
| 421 | (Note that position unit is in 0.5 scanline) | ||
| 422 | |||
| 423 | bit7 0 RW on-pad tap zone enable | ||
| 424 | 0: disable, 1: enable | ||
| 425 | |||
| 426 | 0x35 RW on-pad command control 6 | ||
| 427 | bit4~bit0 0x1d RW XHI in 0s/4/1, so 19h = 1100.1b = 12.5 | ||
| 428 | (Note that position unit is in 0.5 scanline) | ||
| 429 | |||
| 430 | 0x36 RW on-pad command control 7 | ||
| 431 | bit4~bit0 0x04 RW YLO in 0s/4/1, so 03h = 0010.1b = 2.5 | ||
| 432 | (Note that position unit is in 0.5 scanline) | ||
| 433 | |||
| 434 | 0x37 RW on-pad command control 8 | ||
| 435 | bit4~bit0 0x13 RW YHI in 0s/4/1, so 11h = 1000.1b = 8.5 | ||
| 436 | (Note that position unit is in 0.5 scanline) | ||
| 437 | |||
| 438 | 0x40 RW system control 5 | ||
| 439 | bit1 0 RW FSP Intellimouse mode enable | ||
| 440 | 0: disable, 1: enable | ||
| 441 | |||
| 442 | bit2 0 RW movement + abs. coordinate mode enable | ||
| 443 | 0: disable, 1: enable | ||
| 444 | (Note that this function has the functionality of bit 1 even when | ||
| 445 | bit 1 is not set. However, the format is different from that of bit 1. | ||
| 446 | In addition, when bit 1 and bit 2 are set at the same time, bit 2 will | ||
| 447 | override bit 1.) | ||
| 448 | |||
| 449 | bit3 0 RW abs. coordinate only mode enable | ||
| 450 | 0: disable, 1: enable | ||
| 451 | (Note that this function has the functionality of bit 1 even when | ||
| 452 | bit 1 is not set. However, the format is different from that of bit 1. | ||
| 453 | In addition, when bit 1, bit 2 and bit 3 are set at the same time, | ||
| 454 | bit 3 will override bit 1 and 2.) | ||
| 455 | |||
| 456 | bit5 0 RW auto switch enable | ||
| 457 | 0: disable, 1: enable | ||
| 458 | |||
| 459 | bit6 0 RW G0 abs. + notify packet format enable | ||
| 460 | 0: disable, 1: enable | ||
| 461 | (Note that the absolute/relative coordinate output still depends on | ||
| 462 | bit 2 and 3. That is, if any of those bit is 1, host will receive | ||
| 463 | absolute coordinates; otherwise, host only receives packets with | ||
| 464 | relative coordinate.) | ||
| 465 | |||
| 466 | 0x43 RW on-pad control | ||
| 467 | bit0 0 RW on-pad control enable | ||
| 468 | 0: disable, 1: enable | ||
| 469 | (Note that if this bit is cleared, bit 3/5 will be ineffective) | ||
| 470 | |||
| 471 | bit3 0 RW on-pad fix vertical scrolling enable | ||
| 472 | 0: disable, 1: enable | ||
| 473 | |||
| 474 | bit5 0 RW on-pad fix horizontal scrolling enable | ||
| 475 | 0: disable, 1: enable | ||
diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.txt new file mode 100644 index 000000000000..f40a1f030019 --- /dev/null +++ b/Documentation/intel_txt.txt | |||
| @@ -0,0 +1,210 @@ | |||
| 1 | Intel(R) TXT Overview: | ||
| 2 | ===================== | ||
| 3 | |||
| 4 | Intel's technology for safer computing, Intel(R) Trusted Execution | ||
| 5 | Technology (Intel(R) TXT), defines platform-level enhancements that | ||
| 6 | provide the building blocks for creating trusted platforms. | ||
| 7 | |||
| 8 | Intel TXT was formerly known by the code name LaGrande Technology (LT). | ||
| 9 | |||
| 10 | Intel TXT in Brief: | ||
| 11 | o Provides dynamic root of trust for measurement (DRTM) | ||
| 12 | o Data protection in case of improper shutdown | ||
| 13 | o Measurement and verification of launched environment | ||
| 14 | |||
| 15 | Intel TXT is part of the vPro(TM) brand and is also available some | ||
| 16 | non-vPro systems. It is currently available on desktop systems | ||
| 17 | based on the Q35, X38, Q45, and Q43 Express chipsets (e.g. Dell | ||
| 18 | Optiplex 755, HP dc7800, etc.) and mobile systems based on the GM45, | ||
| 19 | PM45, and GS45 Express chipsets. | ||
| 20 | |||
| 21 | For more information, see http://www.intel.com/technology/security/. | ||
| 22 | This site also has a link to the Intel TXT MLE Developers Manual, | ||
| 23 | which has been updated for the new released platforms. | ||
| 24 | |||
| 25 | Intel TXT has been presented at various events over the past few | ||
| 26 | years, some of which are: | ||
| 27 | LinuxTAG 2008: | ||
| 28 | http://www.linuxtag.org/2008/en/conf/events/vp-donnerstag/ | ||
| 29 | details.html?talkid=110 | ||
| 30 | TRUST2008: | ||
| 31 | http://www.trust2008.eu/downloads/Keynote-Speakers/ | ||
| 32 | 3_David-Grawrock_The-Front-Door-of-Trusted-Computing.pdf | ||
| 33 | IDF 2008, Shanghai: | ||
| 34 | http://inteldeveloperforum.com.edgesuite.net/shanghai_2008/ | ||
| 35 | aep/PROS003/index.html | ||
| 36 | IDFs 2006, 2007 (I'm not sure if/where they are online) | ||
| 37 | |||
| 38 | Trusted Boot Project Overview: | ||
| 39 | ============================= | ||
| 40 | |||
| 41 | Trusted Boot (tboot) is an open source, pre- kernel/VMM module that | ||
| 42 | uses Intel TXT to perform a measured and verified launch of an OS | ||
| 43 | kernel/VMM. | ||
| 44 | |||
| 45 | It is hosted on SourceForge at http://sourceforge.net/projects/tboot. | ||
| 46 | The mercurial source repo is available at http://www.bughost.org/ | ||
| 47 | repos.hg/tboot.hg. | ||
| 48 | |||
| 49 | Tboot currently supports launching Xen (open source VMM/hypervisor | ||
| 50 | w/ TXT support since v3.2), and now Linux kernels. | ||
| 51 | |||
| 52 | |||
| 53 | Value Proposition for Linux or "Why should you care?" | ||
| 54 | ===================================================== | ||
| 55 | |||
| 56 | While there are many products and technologies that attempt to | ||
| 57 | measure or protect the integrity of a running kernel, they all | ||
| 58 | assume the kernel is "good" to begin with. The Integrity | ||
| 59 | Measurement Architecture (IMA) and Linux Integrity Module interface | ||
| 60 | are examples of such solutions. | ||
| 61 | |||
| 62 | To get trust in the initial kernel without using Intel TXT, a | ||
| 63 | static root of trust must be used. This bases trust in BIOS | ||
| 64 | starting at system reset and requires measurement of all code | ||
| 65 | executed between system reset through the completion of the kernel | ||
| 66 | boot as well as data objects used by that code. In the case of a | ||
| 67 | Linux kernel, this means all of BIOS, any option ROMs, the | ||
| 68 | bootloader and the boot config. In practice, this is a lot of | ||
| 69 | code/data, much of which is subject to change from boot to boot | ||
| 70 | (e.g. changing NICs may change option ROMs). Without reference | ||
| 71 | hashes, these measurement changes are difficult to assess or | ||
| 72 | confirm as benign. This process also does not provide DMA | ||
| 73 | protection, memory configuration/alias checks and locks, crash | ||
| 74 | protection, or policy support. | ||
| 75 | |||
| 76 | By using the hardware-based root of trust that Intel TXT provides, | ||
| 77 | many of these issues can be mitigated. Specifically: many | ||
| 78 | pre-launch components can be removed from the trust chain, DMA | ||
| 79 | protection is provided to all launched components, a large number | ||
| 80 | of platform configuration checks are performed and values locked, | ||
| 81 | protection is provided for any data in the event of an improper | ||
| 82 | shutdown, and there is support for policy-based execution/verification. | ||
| 83 | This provides a more stable measurement and a higher assurance of | ||
| 84 | system configuration and initial state than would be otherwise | ||
| 85 | possible. Since the tboot project is open source, source code for | ||
| 86 | almost all parts of the trust chain is available (excepting SMM and | ||
| 87 | Intel-provided firmware). | ||
| 88 | |||
| 89 | How Does it Work? | ||
| 90 | ================= | ||
| 91 | |||
| 92 | o Tboot is an executable that is launched by the bootloader as | ||
| 93 | the "kernel" (the binary the bootloader executes). | ||
| 94 | o It performs all of the work necessary to determine if the | ||
| 95 | platform supports Intel TXT and, if so, executes the GETSEC[SENTER] | ||
| 96 | processor instruction that initiates the dynamic root of trust. | ||
| 97 | - If tboot determines that the system does not support Intel TXT | ||
| 98 | or is not configured correctly (e.g. the SINIT AC Module was | ||
| 99 | incorrect), it will directly launch the kernel with no changes | ||
| 100 | to any state. | ||
| 101 | - Tboot will output various information about its progress to the | ||
| 102 | terminal, serial port, and/or an in-memory log; the output | ||
| 103 | locations can be configured with a command line switch. | ||
| 104 | o The GETSEC[SENTER] instruction will return control to tboot and | ||
| 105 | tboot then verifies certain aspects of the environment (e.g. TPM NV | ||
| 106 | lock, e820 table does not have invalid entries, etc.). | ||
| 107 | o It will wake the APs from the special sleep state the GETSEC[SENTER] | ||
| 108 | instruction had put them in and place them into a wait-for-SIPI | ||
| 109 | state. | ||
| 110 | - Because the processors will not respond to an INIT or SIPI when | ||
| 111 | in the TXT environment, it is necessary to create a small VT-x | ||
| 112 | guest for the APs. When they run in this guest, they will | ||
| 113 | simply wait for the INIT-SIPI-SIPI sequence, which will cause | ||
| 114 | VMEXITs, and then disable VT and jump to the SIPI vector. This | ||
| 115 | approach seemed like a better choice than having to insert | ||
| 116 | special code into the kernel's MP wakeup sequence. | ||
| 117 | o Tboot then applies an (optional) user-defined launch policy to | ||
| 118 | verify the kernel and initrd. | ||
| 119 | - This policy is rooted in TPM NV and is described in the tboot | ||
| 120 | project. The tboot project also contains code for tools to | ||
| 121 | create and provision the policy. | ||
| 122 | - Policies are completely under user control and if not present | ||
| 123 | then any kernel will be launched. | ||
| 124 | - Policy action is flexible and can include halting on failures | ||
| 125 | or simply logging them and continuing. | ||
| 126 | o Tboot adjusts the e820 table provided by the bootloader to reserve | ||
| 127 | its own location in memory as well as to reserve certain other | ||
| 128 | TXT-related regions. | ||
| 129 | o As part of it's launch, tboot DMA protects all of RAM (using the | ||
| 130 | VT-d PMRs). Thus, the kernel must be booted with 'intel_iommu=on' | ||
| 131 | in order to remove this blanket protection and use VT-d's | ||
| 132 | page-level protection. | ||
| 133 | o Tboot will populate a shared page with some data about itself and | ||
| 134 | pass this to the Linux kernel as it transfers control. | ||
| 135 | - The location of the shared page is passed via the boot_params | ||
| 136 | struct as a physical address. | ||
| 137 | o The kernel will look for the tboot shared page address and, if it | ||
| 138 | exists, map it. | ||
| 139 | o As one of the checks/protections provided by TXT, it makes a copy | ||
| 140 | of the VT-d DMARs in a DMA-protected region of memory and verifies | ||
| 141 | them for correctness. The VT-d code will detect if the kernel was | ||
| 142 | launched with tboot and use this copy instead of the one in the | ||
| 143 | ACPI table. | ||
| 144 | o At this point, tboot and TXT are out of the picture until a | ||
| 145 | shutdown (S<n>) | ||
| 146 | o In order to put a system into any of the sleep states after a TXT | ||
| 147 | launch, TXT must first be exited. This is to prevent attacks that | ||
| 148 | attempt to crash the system to gain control on reboot and steal | ||
| 149 | data left in memory. | ||
| 150 | - The kernel will perform all of its sleep preparation and | ||
| 151 | populate the shared page with the ACPI data needed to put the | ||
| 152 | platform in the desired sleep state. | ||
| 153 | - Then the kernel jumps into tboot via the vector specified in the | ||
| 154 | shared page. | ||
| 155 | - Tboot will clean up the environment and disable TXT, then use the | ||
| 156 | kernel-provided ACPI information to actually place the platform | ||
| 157 | into the desired sleep state. | ||
| 158 | - In the case of S3, tboot will also register itself as the resume | ||
| 159 | vector. This is necessary because it must re-establish the | ||
| 160 | measured environment upon resume. Once the TXT environment | ||
| 161 | has been restored, it will restore the TPM PCRs and then | ||
| 162 | transfer control back to the kernel's S3 resume vector. | ||
| 163 | In order to preserve system integrity across S3, the kernel | ||
| 164 | provides tboot with a set of memory ranges (kernel | ||
| 165 | code/data/bss, S3 resume code, and AP trampoline) that tboot | ||
| 166 | will calculate a MAC (message authentication code) over and then | ||
| 167 | seal with the TPM. On resume and once the measured environment | ||
| 168 | has been re-established, tboot will re-calculate the MAC and | ||
| 169 | verify it against the sealed value. Tboot's policy determines | ||
| 170 | what happens if the verification fails. | ||
| 171 | |||
| 172 | That's pretty much it for TXT support. | ||
| 173 | |||
| 174 | |||
| 175 | Configuring the System: | ||
| 176 | ====================== | ||
| 177 | |||
| 178 | This code works with 32bit, 32bit PAE, and 64bit (x86_64) kernels. | ||
| 179 | |||
| 180 | In BIOS, the user must enable: TPM, TXT, VT-x, VT-d. Not all BIOSes | ||
| 181 | allow these to be individually enabled/disabled and the screens in | ||
| 182 | which to find them are BIOS-specific. | ||
| 183 | |||
| 184 | grub.conf needs to be modified as follows: | ||
| 185 | title Linux 2.6.29-tip w/ tboot | ||
| 186 | root (hd0,0) | ||
| 187 | kernel /tboot.gz logging=serial,vga,memory | ||
| 188 | module /vmlinuz-2.6.29-tip intel_iommu=on ro | ||
| 189 | root=LABEL=/ rhgb console=ttyS0,115200 3 | ||
| 190 | module /initrd-2.6.29-tip.img | ||
| 191 | module /Q35_SINIT_17.BIN | ||
| 192 | |||
| 193 | The kernel option for enabling Intel TXT support is found under the | ||
| 194 | Security top-level menu and is called "Enable Intel(R) Trusted | ||
| 195 | Execution Technology (TXT)". It is marked as EXPERIMENTAL and | ||
| 196 | depends on the generic x86 support (to allow maximum flexibility in | ||
| 197 | kernel build options), since the tboot code will detect whether the | ||
| 198 | platform actually supports Intel TXT and thus whether any of the | ||
| 199 | kernel code is executed. | ||
| 200 | |||
| 201 | The Q35_SINIT_17.BIN file is what Intel TXT refers to as an | ||
| 202 | Authenticated Code Module. It is specific to the chipset in the | ||
| 203 | system and can also be found on the Trusted Boot site. It is an | ||
| 204 | (unencrypted) module signed by Intel that is used as part of the | ||
| 205 | DRTM process to verify and configure the system. It is signed | ||
| 206 | because it operates at a higher privilege level in the system than | ||
| 207 | any other macrocode and its correct operation is critical to the | ||
| 208 | establishment of the DRTM. The process for determining the correct | ||
| 209 | SINIT ACM for a system is documented in the SINIT-guide.txt file | ||
| 210 | that is on the tboot SourceForge site under the SINIT ACM downloads. | ||
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 7bb0d934b6d8..aafca0a8f66a 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt | |||
| @@ -121,6 +121,7 @@ Code Seq# Include File Comments | |||
| 121 | 'c' 00-7F linux/comstats.h conflict! | 121 | 'c' 00-7F linux/comstats.h conflict! |
| 122 | 'c' 00-7F linux/coda.h conflict! | 122 | 'c' 00-7F linux/coda.h conflict! |
| 123 | 'c' 80-9F arch/s390/include/asm/chsc.h | 123 | 'c' 80-9F arch/s390/include/asm/chsc.h |
| 124 | 'c' A0-AF arch/x86/include/asm/msr.h | ||
| 124 | 'd' 00-FF linux/char/drm/drm/h conflict! | 125 | 'd' 00-FF linux/char/drm/drm/h conflict! |
| 125 | 'd' F0-FF linux/digi1.h | 126 | 'd' F0-FF linux/digi1.h |
| 126 | 'e' all linux/digi1.h conflict! | 127 | 'e' all linux/digi1.h conflict! |
| @@ -139,6 +140,7 @@ Code Seq# Include File Comments | |||
| 139 | 'm' all linux/synclink.h conflict! | 140 | 'm' all linux/synclink.h conflict! |
| 140 | 'm' 00-1F net/irda/irmod.h conflict! | 141 | 'm' 00-1F net/irda/irmod.h conflict! |
| 141 | 'n' 00-7F linux/ncp_fs.h | 142 | 'n' 00-7F linux/ncp_fs.h |
| 143 | 'n' 80-8F linux/nilfs2_fs.h NILFS2 | ||
| 142 | 'n' E0-FF video/matrox.h matroxfb | 144 | 'n' E0-FF video/matrox.h matroxfb |
| 143 | 'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 | 145 | 'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 |
| 144 | 'o' 00-03 include/mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) | 146 | 'o' 00-03 include/mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) |
| @@ -191,7 +193,7 @@ Code Seq# Include File Comments | |||
| 191 | 0xAD 00 Netfilter device in development: | 193 | 0xAD 00 Netfilter device in development: |
| 192 | <mailto:rusty@rustcorp.com.au> | 194 | <mailto:rusty@rustcorp.com.au> |
| 193 | 0xAE all linux/kvm.h Kernel-based Virtual Machine | 195 | 0xAE all linux/kvm.h Kernel-based Virtual Machine |
| 194 | <mailto:kvm-devel@lists.sourceforge.net> | 196 | <mailto:kvm@vger.kernel.org> |
| 195 | 0xB0 all RATIO devices in development: | 197 | 0xB0 all RATIO devices in development: |
| 196 | <mailto:vgo@ratio.de> | 198 | <mailto:vgo@ratio.de> |
| 197 | 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> | 199 | 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> |
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 4d04572b6549..348b9e5e28fc 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt | |||
| @@ -66,7 +66,9 @@ Example kernel-doc function comment: | |||
| 66 | * The longer description can have multiple paragraphs. | 66 | * The longer description can have multiple paragraphs. |
| 67 | */ | 67 | */ |
| 68 | 68 | ||
| 69 | The first line, with the short description, must be on a single line. | 69 | The short description following the subject can span multiple lines |
| 70 | and ends with an @argument description, an empty line or the end of | ||
| 71 | the comment block. | ||
| 70 | 72 | ||
| 71 | The @argument descriptions must begin on the very next line following | 73 | The @argument descriptions must begin on the very next line following |
| 72 | this opening short function description line, with no intervening | 74 | this opening short function description line, with no intervening |
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index d77fbd8b79ac..c363840cdcea 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt | |||
| @@ -57,6 +57,7 @@ parameter is applicable: | |||
| 57 | ISAPNP ISA PnP code is enabled. | 57 | ISAPNP ISA PnP code is enabled. |
| 58 | ISDN Appropriate ISDN support is enabled. | 58 | ISDN Appropriate ISDN support is enabled. |
| 59 | JOY Appropriate joystick support is enabled. | 59 | JOY Appropriate joystick support is enabled. |
| 60 | KVM Kernel Virtual Machine support is enabled. | ||
| 60 | LIBATA Libata driver is enabled | 61 | LIBATA Libata driver is enabled |
| 61 | LP Printer support is enabled. | 62 | LP Printer support is enabled. |
| 62 | LOOP Loopback device support is enabled. | 63 | LOOP Loopback device support is enabled. |
| @@ -932,7 +933,7 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 932 | 1 -- enable informational integrity auditing messages. | 933 | 1 -- enable informational integrity auditing messages. |
| 933 | 934 | ||
| 934 | ima_hash= [IMA] | 935 | ima_hash= [IMA] |
| 935 | Formt: { "sha1" | "md5" } | 936 | Format: { "sha1" | "md5" } |
| 936 | default: "sha1" | 937 | default: "sha1" |
| 937 | 938 | ||
| 938 | ima_tcb [IMA] | 939 | ima_tcb [IMA] |
| @@ -1098,6 +1099,44 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1098 | kstack=N [X86] Print N words from the kernel stack | 1099 | kstack=N [X86] Print N words from the kernel stack |
| 1099 | in oops dumps. | 1100 | in oops dumps. |
| 1100 | 1101 | ||
| 1102 | kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. | ||
| 1103 | Default is 0 (don't ignore, but inject #GP) | ||
| 1104 | |||
| 1105 | kvm.oos_shadow= [KVM] Disable out-of-sync shadow paging. | ||
| 1106 | Default is 1 (enabled) | ||
| 1107 | |||
| 1108 | kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. | ||
| 1109 | Default is 0 (off) | ||
| 1110 | |||
| 1111 | kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) | ||
| 1112 | for all guests. | ||
| 1113 | Default is 1 (enabled) if in 64bit or 32bit-PAE mode | ||
| 1114 | |||
| 1115 | kvm-intel.bypass_guest_pf= | ||
| 1116 | [KVM,Intel] Disables bypassing of guest page faults | ||
| 1117 | on Intel chips. Default is 1 (enabled) | ||
| 1118 | |||
| 1119 | kvm-intel.ept= [KVM,Intel] Disable extended page tables | ||
| 1120 | (virtualized MMU) support on capable Intel chips. | ||
| 1121 | Default is 1 (enabled) | ||
| 1122 | |||
| 1123 | kvm-intel.emulate_invalid_guest_state= | ||
| 1124 | [KVM,Intel] Enable emulation of invalid guest states | ||
| 1125 | Default is 0 (disabled) | ||
| 1126 | |||
| 1127 | kvm-intel.flexpriority= | ||
| 1128 | [KVM,Intel] Disable FlexPriority feature (TPR shadow). | ||
| 1129 | Default is 1 (enabled) | ||
| 1130 | |||
| 1131 | kvm-intel.unrestricted_guest= | ||
| 1132 | [KVM,Intel] Disable unrestricted guest feature | ||
| 1133 | (virtualized real and unpaged mode) on capable | ||
| 1134 | Intel chips. Default is 1 (enabled) | ||
| 1135 | |||
| 1136 | kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification | ||
| 1137 | feature (tagged TLBs) on capable Intel chips. | ||
| 1138 | Default is 1 (enabled) | ||
| 1139 | |||
| 1101 | l2cr= [PPC] | 1140 | l2cr= [PPC] |
| 1102 | 1141 | ||
| 1103 | l3cr= [PPC] | 1142 | l3cr= [PPC] |
| @@ -1115,6 +1154,10 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1115 | libata.dma=4 Compact Flash DMA only | 1154 | libata.dma=4 Compact Flash DMA only |
| 1116 | Combinations also work, so libata.dma=3 enables DMA | 1155 | Combinations also work, so libata.dma=3 enables DMA |
| 1117 | for disks and CDROMs, but not CFs. | 1156 | for disks and CDROMs, but not CFs. |
| 1157 | |||
| 1158 | libata.ignore_hpa= [LIBATA] Ignore HPA limit | ||
| 1159 | libata.ignore_hpa=0 keep BIOS limits (default) | ||
| 1160 | libata.ignore_hpa=1 ignore limits, using full disk | ||
| 1118 | 1161 | ||
| 1119 | libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume | 1162 | libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume |
| 1120 | when set. | 1163 | when set. |
| @@ -1243,6 +1286,10 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1243 | (machvec) in a generic kernel. | 1286 | (machvec) in a generic kernel. |
| 1244 | Example: machvec=hpzx1_swiotlb | 1287 | Example: machvec=hpzx1_swiotlb |
| 1245 | 1288 | ||
| 1289 | machtype= [Loongson] Share the same kernel image file between different | ||
| 1290 | yeeloong laptop. | ||
| 1291 | Example: machtype=lemote-yeeloong-2f-7inch | ||
| 1292 | |||
| 1246 | max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater | 1293 | max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater |
| 1247 | than or equal to this physical address is ignored. | 1294 | than or equal to this physical address is ignored. |
| 1248 | 1295 | ||
| @@ -1499,6 +1546,14 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1499 | [NFS] set the TCP port on which the NFSv4 callback | 1546 | [NFS] set the TCP port on which the NFSv4 callback |
| 1500 | channel should listen. | 1547 | channel should listen. |
| 1501 | 1548 | ||
| 1549 | nfs.cache_getent= | ||
| 1550 | [NFS] sets the pathname to the program which is used | ||
| 1551 | to update the NFS client cache entries. | ||
| 1552 | |||
| 1553 | nfs.cache_getent_timeout= | ||
| 1554 | [NFS] sets the timeout after which an attempt to | ||
| 1555 | update a cache entry is deemed to have failed. | ||
| 1556 | |||
| 1502 | nfs.idmap_cache_timeout= | 1557 | nfs.idmap_cache_timeout= |
| 1503 | [NFS] set the maximum lifetime for idmapper cache | 1558 | [NFS] set the maximum lifetime for idmapper cache |
| 1504 | entries. | 1559 | entries. |
| @@ -1510,7 +1565,7 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1510 | of returning the full 64-bit number. | 1565 | of returning the full 64-bit number. |
| 1511 | The default is to return 64-bit inode numbers. | 1566 | The default is to return 64-bit inode numbers. |
| 1512 | 1567 | ||
| 1513 | nmi_debug= [KNL,AVR32] Specify one or more actions to take | 1568 | nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take |
| 1514 | when a NMI is triggered. | 1569 | when a NMI is triggered. |
| 1515 | Format: [state][,regs][,debounce][,die] | 1570 | Format: [state][,regs][,debounce][,die] |
| 1516 | 1571 | ||
| @@ -1531,6 +1586,11 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1531 | symbolic names: lapic and ioapic | 1586 | symbolic names: lapic and ioapic |
| 1532 | Example: nmi_watchdog=2 or nmi_watchdog=panic,lapic | 1587 | Example: nmi_watchdog=2 or nmi_watchdog=panic,lapic |
| 1533 | 1588 | ||
| 1589 | netpoll.carrier_timeout= | ||
| 1590 | [NET] Specifies amount of time (in seconds) that | ||
| 1591 | netpoll should wait for a carrier. By default netpoll | ||
| 1592 | waits 4 seconds. | ||
| 1593 | |||
| 1534 | no387 [BUGS=X86-32] Tells the kernel to use the 387 maths | 1594 | no387 [BUGS=X86-32] Tells the kernel to use the 387 maths |
| 1535 | emulation library even if a 387 maths coprocessor | 1595 | emulation library even if a 387 maths coprocessor |
| 1536 | is present. | 1596 | is present. |
| @@ -1720,8 +1780,8 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1720 | oprofile.cpu_type= Force an oprofile cpu type | 1780 | oprofile.cpu_type= Force an oprofile cpu type |
| 1721 | This might be useful if you have an older oprofile | 1781 | This might be useful if you have an older oprofile |
| 1722 | userland or if you want common events. | 1782 | userland or if you want common events. |
| 1723 | Format: { archperfmon } | 1783 | Format: { arch_perfmon } |
| 1724 | archperfmon: [X86] Force use of architectural | 1784 | arch_perfmon: [X86] Force use of architectural |
| 1725 | perfmon on Intel CPUs instead of the | 1785 | perfmon on Intel CPUs instead of the |
| 1726 | CPU specific event set. | 1786 | CPU specific event set. |
| 1727 | 1787 | ||
| @@ -1915,11 +1975,12 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 1915 | Format: { 0 | 1 } | 1975 | Format: { 0 | 1 } |
| 1916 | See arch/parisc/kernel/pdc_chassis.c | 1976 | See arch/parisc/kernel/pdc_chassis.c |
| 1917 | 1977 | ||
| 1918 | percpu_alloc= [X86] Select which percpu first chunk allocator to use. | 1978 | percpu_alloc= Select which percpu first chunk allocator to use. |
| 1919 | Allowed values are one of "lpage", "embed" and "4k". | 1979 | Currently supported values are "embed" and "page". |
| 1920 | See comments in arch/x86/kernel/setup_percpu.c for | 1980 | Archs may support subset or none of the selections. |
| 1921 | details on each allocator. This parameter is primarily | 1981 | See comments in mm/percpu.c for details on each |
| 1922 | for debugging and performance comparison. | 1982 | allocator. This parameter is primarily for debugging |
| 1983 | and performance comparison. | ||
| 1923 | 1984 | ||
| 1924 | pf. [PARIDE] | 1985 | pf. [PARIDE] |
| 1925 | See Documentation/blockdev/paride.txt. | 1986 | See Documentation/blockdev/paride.txt. |
| @@ -2391,6 +2452,18 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 2391 | stifb= [HW] | 2452 | stifb= [HW] |
| 2392 | Format: bpp:<bpp1>[:<bpp2>[:<bpp3>...]] | 2453 | Format: bpp:<bpp1>[:<bpp2>[:<bpp3>...]] |
| 2393 | 2454 | ||
| 2455 | sunrpc.min_resvport= | ||
| 2456 | sunrpc.max_resvport= | ||
| 2457 | [NFS,SUNRPC] | ||
| 2458 | SunRPC servers often require that client requests | ||
| 2459 | originate from a privileged port (i.e. a port in the | ||
| 2460 | range 0 < portnr < 1024). | ||
| 2461 | An administrator who wishes to reserve some of these | ||
| 2462 | ports for other uses may adjust the range that the | ||
| 2463 | kernel's sunrpc client considers to be privileged | ||
| 2464 | using these two parameters to set the minimum and | ||
| 2465 | maximum port values. | ||
| 2466 | |||
| 2394 | sunrpc.pool_mode= | 2467 | sunrpc.pool_mode= |
| 2395 | [NFS] | 2468 | [NFS] |
| 2396 | Control how the NFS server code allocates CPUs to | 2469 | Control how the NFS server code allocates CPUs to |
| @@ -2407,6 +2480,15 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 2407 | pernode one pool for each NUMA node (equivalent | 2480 | pernode one pool for each NUMA node (equivalent |
| 2408 | to global on non-NUMA machines) | 2481 | to global on non-NUMA machines) |
| 2409 | 2482 | ||
| 2483 | sunrpc.tcp_slot_table_entries= | ||
| 2484 | sunrpc.udp_slot_table_entries= | ||
| 2485 | [NFS,SUNRPC] | ||
| 2486 | Sets the upper limit on the number of simultaneous | ||
| 2487 | RPC calls that can be sent from the client to a | ||
| 2488 | server. Increasing these values may allow you to | ||
| 2489 | improve throughput, but will also increase the | ||
| 2490 | amount of memory reserved for use by the client. | ||
| 2491 | |||
| 2410 | swiotlb= [IA-64] Number of I/O TLB slabs | 2492 | swiotlb= [IA-64] Number of I/O TLB slabs |
| 2411 | 2493 | ||
| 2412 | switches= [HW,M68k] | 2494 | switches= [HW,M68k] |
| @@ -2476,6 +2558,11 @@ and is between 256 and 4096 characters. It is defined in the file | |||
| 2476 | trace_buf_size=nn[KMG] | 2558 | trace_buf_size=nn[KMG] |
| 2477 | [FTRACE] will set tracing buffer size. | 2559 | [FTRACE] will set tracing buffer size. |
| 2478 | 2560 | ||
| 2561 | trace_event=[event-list] | ||
| 2562 | [FTRACE] Set and start specified trace events in order | ||
| 2563 | to facilitate early boot debugging. | ||
| 2564 | See also Documentation/trace/events.txt | ||
| 2565 | |||
| 2479 | trix= [HW,OSS] MediaTrix AudioTrix Pro | 2566 | trix= [HW,OSS] MediaTrix AudioTrix Pro |
| 2480 | Format: | 2567 | Format: |
| 2481 | <io>,<irq>,<dma>,<dma2>,<sb_io>,<sb_irq>,<sb_dma>,<mpu_io>,<mpu_irq> | 2568 | <io>,<irq>,<dma>,<dma2>,<sb_io>,<sb_irq>,<sb_dma>,<mpu_io>,<mpu_irq> |
diff --git a/Documentation/keys.txt b/Documentation/keys.txt index b56aacc1fff8..e4dbbdb1bd96 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt | |||
| @@ -26,7 +26,7 @@ This document has the following sections: | |||
| 26 | - Notes on accessing payload contents | 26 | - Notes on accessing payload contents |
| 27 | - Defining a key type | 27 | - Defining a key type |
| 28 | - Request-key callback service | 28 | - Request-key callback service |
| 29 | - Key access filesystem | 29 | - Garbage collection |
| 30 | 30 | ||
| 31 | 31 | ||
| 32 | ============ | 32 | ============ |
| @@ -113,6 +113,9 @@ Each key has a number of attributes: | |||
| 113 | 113 | ||
| 114 | (*) Dead. The key's type was unregistered, and so the key is now useless. | 114 | (*) Dead. The key's type was unregistered, and so the key is now useless. |
| 115 | 115 | ||
| 116 | Keys in the last three states are subject to garbage collection. See the | ||
| 117 | section on "Garbage collection". | ||
| 118 | |||
| 116 | 119 | ||
| 117 | ==================== | 120 | ==================== |
| 118 | KEY SERVICE OVERVIEW | 121 | KEY SERVICE OVERVIEW |
| @@ -754,6 +757,26 @@ The keyctl syscall functions are: | |||
| 754 | successful. | 757 | successful. |
| 755 | 758 | ||
| 756 | 759 | ||
| 760 | (*) Install the calling process's session keyring on its parent. | ||
| 761 | |||
| 762 | long keyctl(KEYCTL_SESSION_TO_PARENT); | ||
| 763 | |||
| 764 | This functions attempts to install the calling process's session keyring | ||
| 765 | on to the calling process's parent, replacing the parent's current session | ||
| 766 | keyring. | ||
| 767 | |||
| 768 | The calling process must have the same ownership as its parent, the | ||
| 769 | keyring must have the same ownership as the calling process, the calling | ||
| 770 | process must have LINK permission on the keyring and the active LSM module | ||
| 771 | mustn't deny permission, otherwise error EPERM will be returned. | ||
| 772 | |||
| 773 | Error ENOMEM will be returned if there was insufficient memory to complete | ||
| 774 | the operation, otherwise 0 will be returned to indicate success. | ||
| 775 | |||
| 776 | The keyring will be replaced next time the parent process leaves the | ||
| 777 | kernel and resumes executing userspace. | ||
| 778 | |||
| 779 | |||
| 757 | =============== | 780 | =============== |
| 758 | KERNEL SERVICES | 781 | KERNEL SERVICES |
| 759 | =============== | 782 | =============== |
| @@ -1231,3 +1254,17 @@ by executing: | |||
| 1231 | 1254 | ||
| 1232 | In this case, the program isn't required to actually attach the key to a ring; | 1255 | In this case, the program isn't required to actually attach the key to a ring; |
| 1233 | the rings are provided for reference. | 1256 | the rings are provided for reference. |
| 1257 | |||
| 1258 | |||
| 1259 | ================== | ||
| 1260 | GARBAGE COLLECTION | ||
| 1261 | ================== | ||
| 1262 | |||
| 1263 | Dead keys (for which the type has been removed) will be automatically unlinked | ||
| 1264 | from those keyrings that point to them and deleted as soon as possible by a | ||
| 1265 | background garbage collector. | ||
| 1266 | |||
| 1267 | Similarly, revoked and expired keys will be garbage collected, but only after a | ||
| 1268 | certain amount of time has passed. This time is set as a number of seconds in: | ||
| 1269 | |||
| 1270 | /proc/sys/kernel/keys/gc_delay | ||
diff --git a/Documentation/kmemcheck.txt b/Documentation/kmemcheck.txt index 363044609dad..c28f82895d6b 100644 --- a/Documentation/kmemcheck.txt +++ b/Documentation/kmemcheck.txt | |||
| @@ -43,26 +43,7 @@ feature. | |||
| 43 | 1. Downloading | 43 | 1. Downloading |
| 44 | ============== | 44 | ============== |
| 45 | 45 | ||
| 46 | kmemcheck can only be downloaded using git. If you want to write patches | 46 | As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. |
| 47 | against the current code, you should use the kmemcheck development branch of | ||
| 48 | the tip tree. It is also possible to use the linux-next tree, which also | ||
| 49 | includes the latest version of kmemcheck. | ||
| 50 | |||
| 51 | Assuming that you've already cloned the linux-2.6.git repository, all you | ||
| 52 | have to do is add the -tip tree as a remote, like this: | ||
| 53 | |||
| 54 | $ git remote add tip git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip.git | ||
| 55 | |||
| 56 | To actually download the tree, fetch the remote: | ||
| 57 | |||
| 58 | $ git fetch tip | ||
| 59 | |||
| 60 | And to check out a new local branch with the kmemcheck code: | ||
| 61 | |||
| 62 | $ git checkout -b kmemcheck tip/kmemcheck | ||
| 63 | |||
| 64 | General instructions for the -tip tree can be found here: | ||
| 65 | http://people.redhat.com/mingo/tip.git/readme.txt | ||
| 66 | 47 | ||
| 67 | 48 | ||
| 68 | 2. Configuring and compiling | 49 | 2. Configuring and compiling |
diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt index 0112da3b9ab8..34f6638aa5ac 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/kmemleak.txt | |||
| @@ -16,13 +16,24 @@ Usage | |||
| 16 | ----- | 16 | ----- |
| 17 | 17 | ||
| 18 | CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel | 18 | CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel |
| 19 | thread scans the memory every 10 minutes (by default) and prints any new | 19 | thread scans the memory every 10 minutes (by default) and prints the |
| 20 | unreferenced objects found. To trigger an intermediate scan and display | 20 | number of new unreferenced objects found. To display the details of all |
| 21 | all the possible memory leaks: | 21 | the possible memory leaks: |
| 22 | 22 | ||
| 23 | # mount -t debugfs nodev /sys/kernel/debug/ | 23 | # mount -t debugfs nodev /sys/kernel/debug/ |
| 24 | # cat /sys/kernel/debug/kmemleak | 24 | # cat /sys/kernel/debug/kmemleak |
| 25 | 25 | ||
| 26 | To trigger an intermediate memory scan: | ||
| 27 | |||
| 28 | # echo scan > /sys/kernel/debug/kmemleak | ||
| 29 | |||
| 30 | To clear the list of all current possible memory leaks: | ||
| 31 | |||
| 32 | # echo clear > /sys/kernel/debug/kmemleak | ||
| 33 | |||
| 34 | New leaks will then come up upon reading /sys/kernel/debug/kmemleak | ||
| 35 | again. | ||
| 36 | |||
| 26 | Note that the orphan objects are listed in the order they were allocated | 37 | Note that the orphan objects are listed in the order they were allocated |
| 27 | and one object at the beginning of the list may cause other subsequent | 38 | and one object at the beginning of the list may cause other subsequent |
| 28 | objects to be reported as orphan. | 39 | objects to be reported as orphan. |
| @@ -31,16 +42,24 @@ Memory scanning parameters can be modified at run-time by writing to the | |||
| 31 | /sys/kernel/debug/kmemleak file. The following parameters are supported: | 42 | /sys/kernel/debug/kmemleak file. The following parameters are supported: |
| 32 | 43 | ||
| 33 | off - disable kmemleak (irreversible) | 44 | off - disable kmemleak (irreversible) |
| 34 | stack=on - enable the task stacks scanning | 45 | stack=on - enable the task stacks scanning (default) |
| 35 | stack=off - disable the tasks stacks scanning | 46 | stack=off - disable the tasks stacks scanning |
| 36 | scan=on - start the automatic memory scanning thread | 47 | scan=on - start the automatic memory scanning thread (default) |
| 37 | scan=off - stop the automatic memory scanning thread | 48 | scan=off - stop the automatic memory scanning thread |
| 38 | scan=<secs> - set the automatic memory scanning period in seconds (0 | 49 | scan=<secs> - set the automatic memory scanning period in seconds |
| 39 | to disable it) | 50 | (default 600, 0 to stop the automatic scanning) |
| 51 | scan - trigger a memory scan | ||
| 52 | clear - clear list of current memory leak suspects, done by | ||
| 53 | marking all current reported unreferenced objects grey | ||
| 54 | dump=<addr> - dump information about the object found at <addr> | ||
| 40 | 55 | ||
| 41 | Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on | 56 | Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on |
| 42 | the kernel command line. | 57 | the kernel command line. |
| 43 | 58 | ||
| 59 | Memory may be allocated or freed before kmemleak is initialised and | ||
| 60 | these actions are stored in an early log buffer. The size of this buffer | ||
| 61 | is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. | ||
| 62 | |||
| 44 | Basic Algorithm | 63 | Basic Algorithm |
| 45 | --------------- | 64 | --------------- |
| 46 | 65 | ||
| @@ -77,6 +96,27 @@ avoid this, kmemleak can also store the number of values pointing to an | |||
| 77 | address inside the block address range that need to be found so that the | 96 | address inside the block address range that need to be found so that the |
| 78 | block is not considered a leak. One example is __vmalloc(). | 97 | block is not considered a leak. One example is __vmalloc(). |
| 79 | 98 | ||
| 99 | Testing specific sections with kmemleak | ||
| 100 | --------------------------------------- | ||
| 101 | |||
| 102 | Upon initial bootup your /sys/kernel/debug/kmemleak output page may be | ||
| 103 | quite extensive. This can also be the case if you have very buggy code | ||
| 104 | when doing development. To work around these situations you can use the | ||
| 105 | 'clear' command to clear all reported unreferenced objects from the | ||
| 106 | /sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' | ||
| 107 | you can find new unreferenced objects; this should help with testing | ||
| 108 | specific sections of code. | ||
| 109 | |||
| 110 | To test a critical section on demand with a clean kmemleak do: | ||
| 111 | |||
| 112 | # echo clear > /sys/kernel/debug/kmemleak | ||
| 113 | ... test your kernel or modules ... | ||
| 114 | # echo scan > /sys/kernel/debug/kmemleak | ||
| 115 | |||
| 116 | Then as usual to get your report with: | ||
| 117 | |||
| 118 | # cat /sys/kernel/debug/kmemleak | ||
| 119 | |||
| 80 | Kmemleak API | 120 | Kmemleak API |
| 81 | ------------ | 121 | ------------ |
| 82 | 122 | ||
diff --git a/Documentation/kref.txt b/Documentation/kref.txt index 130b6e87aa7e..ae203f91ee9b 100644 --- a/Documentation/kref.txt +++ b/Documentation/kref.txt | |||
| @@ -84,7 +84,6 @@ int my_data_handler(void) | |||
| 84 | task = kthread_run(more_data_handling, data, "more_data_handling"); | 84 | task = kthread_run(more_data_handling, data, "more_data_handling"); |
| 85 | if (task == ERR_PTR(-ENOMEM)) { | 85 | if (task == ERR_PTR(-ENOMEM)) { |
| 86 | rv = -ENOMEM; | 86 | rv = -ENOMEM; |
| 87 | kref_put(&data->refcount, data_release); | ||
| 88 | goto out; | 87 | goto out; |
| 89 | } | 88 | } |
| 90 | 89 | ||
diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt new file mode 100644 index 000000000000..5a4bc8cf6d04 --- /dev/null +++ b/Documentation/kvm/api.txt | |||
| @@ -0,0 +1,759 @@ | |||
| 1 | The Definitive KVM (Kernel-based Virtual Machine) API Documentation | ||
| 2 | =================================================================== | ||
| 3 | |||
| 4 | 1. General description | ||
| 5 | |||
| 6 | The kvm API is a set of ioctls that are issued to control various aspects | ||
| 7 | of a virtual machine. The ioctls belong to three classes | ||
| 8 | |||
| 9 | - System ioctls: These query and set global attributes which affect the | ||
| 10 | whole kvm subsystem. In addition a system ioctl is used to create | ||
| 11 | virtual machines | ||
| 12 | |||
| 13 | - VM ioctls: These query and set attributes that affect an entire virtual | ||
| 14 | machine, for example memory layout. In addition a VM ioctl is used to | ||
| 15 | create virtual cpus (vcpus). | ||
| 16 | |||
| 17 | Only run VM ioctls from the same process (address space) that was used | ||
| 18 | to create the VM. | ||
| 19 | |||
| 20 | - vcpu ioctls: These query and set attributes that control the operation | ||
| 21 | of a single virtual cpu. | ||
| 22 | |||
| 23 | Only run vcpu ioctls from the same thread that was used to create the | ||
| 24 | vcpu. | ||
| 25 | |||
| 26 | 2. File descritpors | ||
| 27 | |||
| 28 | The kvm API is centered around file descriptors. An initial | ||
| 29 | open("/dev/kvm") obtains a handle to the kvm subsystem; this handle | ||
| 30 | can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this | ||
| 31 | handle will create a VM file descripror which can be used to issue VM | ||
| 32 | ioctls. A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu | ||
| 33 | and return a file descriptor pointing to it. Finally, ioctls on a vcpu | ||
| 34 | fd can be used to control the vcpu, including the important task of | ||
| 35 | actually running guest code. | ||
| 36 | |||
| 37 | In general file descriptors can be migrated among processes by means | ||
| 38 | of fork() and the SCM_RIGHTS facility of unix domain socket. These | ||
| 39 | kinds of tricks are explicitly not supported by kvm. While they will | ||
| 40 | not cause harm to the host, their actual behavior is not guaranteed by | ||
| 41 | the API. The only supported use is one virtual machine per process, | ||
| 42 | and one vcpu per thread. | ||
| 43 | |||
| 44 | 3. Extensions | ||
| 45 | |||
| 46 | As of Linux 2.6.22, the KVM ABI has been stabilized: no backward | ||
| 47 | incompatible change are allowed. However, there is an extension | ||
| 48 | facility that allows backward-compatible extensions to the API to be | ||
| 49 | queried and used. | ||
| 50 | |||
| 51 | The extension mechanism is not based on on the Linux version number. | ||
| 52 | Instead, kvm defines extension identifiers and a facility to query | ||
| 53 | whether a particular extension identifier is available. If it is, a | ||
| 54 | set of ioctls is available for application use. | ||
| 55 | |||
| 56 | 4. API description | ||
| 57 | |||
| 58 | This section describes ioctls that can be used to control kvm guests. | ||
| 59 | For each ioctl, the following information is provided along with a | ||
| 60 | description: | ||
| 61 | |||
| 62 | Capability: which KVM extension provides this ioctl. Can be 'basic', | ||
| 63 | which means that is will be provided by any kernel that supports | ||
| 64 | API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which | ||
| 65 | means availability needs to be checked with KVM_CHECK_EXTENSION | ||
| 66 | (see section 4.4). | ||
| 67 | |||
| 68 | Architectures: which instruction set architectures provide this ioctl. | ||
| 69 | x86 includes both i386 and x86_64. | ||
| 70 | |||
| 71 | Type: system, vm, or vcpu. | ||
| 72 | |||
| 73 | Parameters: what parameters are accepted by the ioctl. | ||
| 74 | |||
| 75 | Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) | ||
| 76 | are not detailed, but errors with specific meanings are. | ||
| 77 | |||
| 78 | 4.1 KVM_GET_API_VERSION | ||
| 79 | |||
| 80 | Capability: basic | ||
| 81 | Architectures: all | ||
| 82 | Type: system ioctl | ||
| 83 | Parameters: none | ||
| 84 | Returns: the constant KVM_API_VERSION (=12) | ||
| 85 | |||
| 86 | This identifies the API version as the stable kvm API. It is not | ||
| 87 | expected that this number will change. However, Linux 2.6.20 and | ||
| 88 | 2.6.21 report earlier versions; these are not documented and not | ||
| 89 | supported. Applications should refuse to run if KVM_GET_API_VERSION | ||
| 90 | returns a value other than 12. If this check passes, all ioctls | ||
| 91 | described as 'basic' will be available. | ||
| 92 | |||
| 93 | 4.2 KVM_CREATE_VM | ||
| 94 | |||
| 95 | Capability: basic | ||
| 96 | Architectures: all | ||
| 97 | Type: system ioctl | ||
| 98 | Parameters: none | ||
| 99 | Returns: a VM fd that can be used to control the new virtual machine. | ||
| 100 | |||
| 101 | The new VM has no virtual cpus and no memory. An mmap() of a VM fd | ||
| 102 | will access the virtual machine's physical address space; offset zero | ||
| 103 | corresponds to guest physical address zero. Use of mmap() on a VM fd | ||
| 104 | is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is | ||
| 105 | available. | ||
| 106 | |||
| 107 | 4.3 KVM_GET_MSR_INDEX_LIST | ||
| 108 | |||
| 109 | Capability: basic | ||
| 110 | Architectures: x86 | ||
| 111 | Type: system | ||
| 112 | Parameters: struct kvm_msr_list (in/out) | ||
| 113 | Returns: 0 on success; -1 on error | ||
| 114 | Errors: | ||
| 115 | E2BIG: the msr index list is to be to fit in the array specified by | ||
| 116 | the user. | ||
| 117 | |||
| 118 | struct kvm_msr_list { | ||
| 119 | __u32 nmsrs; /* number of msrs in entries */ | ||
| 120 | __u32 indices[0]; | ||
| 121 | }; | ||
| 122 | |||
| 123 | This ioctl returns the guest msrs that are supported. The list varies | ||
| 124 | by kvm version and host processor, but does not change otherwise. The | ||
| 125 | user fills in the size of the indices array in nmsrs, and in return | ||
| 126 | kvm adjusts nmsrs to reflect the actual number of msrs and fills in | ||
| 127 | the indices array with their numbers. | ||
| 128 | |||
| 129 | 4.4 KVM_CHECK_EXTENSION | ||
| 130 | |||
| 131 | Capability: basic | ||
| 132 | Architectures: all | ||
| 133 | Type: system ioctl | ||
| 134 | Parameters: extension identifier (KVM_CAP_*) | ||
| 135 | Returns: 0 if unsupported; 1 (or some other positive integer) if supported | ||
| 136 | |||
| 137 | The API allows the application to query about extensions to the core | ||
| 138 | kvm API. Userspace passes an extension identifier (an integer) and | ||
| 139 | receives an integer that describes the extension availability. | ||
| 140 | Generally 0 means no and 1 means yes, but some extensions may report | ||
| 141 | additional information in the integer return value. | ||
| 142 | |||
| 143 | 4.5 KVM_GET_VCPU_MMAP_SIZE | ||
| 144 | |||
| 145 | Capability: basic | ||
| 146 | Architectures: all | ||
| 147 | Type: system ioctl | ||
| 148 | Parameters: none | ||
| 149 | Returns: size of vcpu mmap area, in bytes | ||
| 150 | |||
| 151 | The KVM_RUN ioctl (cf.) communicates with userspace via a shared | ||
| 152 | memory region. This ioctl returns the size of that region. See the | ||
| 153 | KVM_RUN documentation for details. | ||
| 154 | |||
| 155 | 4.6 KVM_SET_MEMORY_REGION | ||
| 156 | |||
| 157 | Capability: basic | ||
| 158 | Architectures: all | ||
| 159 | Type: vm ioctl | ||
| 160 | Parameters: struct kvm_memory_region (in) | ||
| 161 | Returns: 0 on success, -1 on error | ||
| 162 | |||
| 163 | struct kvm_memory_region { | ||
| 164 | __u32 slot; | ||
| 165 | __u32 flags; | ||
| 166 | __u64 guest_phys_addr; | ||
| 167 | __u64 memory_size; /* bytes */ | ||
| 168 | }; | ||
| 169 | |||
| 170 | /* for kvm_memory_region::flags */ | ||
| 171 | #define KVM_MEM_LOG_DIRTY_PAGES 1UL | ||
| 172 | |||
| 173 | This ioctl allows the user to create or modify a guest physical memory | ||
| 174 | slot. When changing an existing slot, it may be moved in the guest | ||
| 175 | physical memory space, or its flags may be modified. It may not be | ||
| 176 | resized. Slots may not overlap. | ||
| 177 | |||
| 178 | The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which | ||
| 179 | instructs kvm to keep track of writes to memory within the slot. See | ||
| 180 | the KVM_GET_DIRTY_LOG ioctl. | ||
| 181 | |||
| 182 | It is recommended to use the KVM_SET_USER_MEMORY_REGION ioctl instead | ||
| 183 | of this API, if available. This newer API allows placing guest memory | ||
| 184 | at specified locations in the host address space, yielding better | ||
| 185 | control and easy access. | ||
| 186 | |||
| 187 | 4.6 KVM_CREATE_VCPU | ||
| 188 | |||
| 189 | Capability: basic | ||
| 190 | Architectures: all | ||
| 191 | Type: vm ioctl | ||
| 192 | Parameters: vcpu id (apic id on x86) | ||
| 193 | Returns: vcpu fd on success, -1 on error | ||
| 194 | |||
| 195 | This API adds a vcpu to a virtual machine. The vcpu id is a small integer | ||
| 196 | in the range [0, max_vcpus). | ||
| 197 | |||
| 198 | 4.7 KVM_GET_DIRTY_LOG (vm ioctl) | ||
| 199 | |||
| 200 | Capability: basic | ||
| 201 | Architectures: x86 | ||
| 202 | Type: vm ioctl | ||
| 203 | Parameters: struct kvm_dirty_log (in/out) | ||
| 204 | Returns: 0 on success, -1 on error | ||
| 205 | |||
| 206 | /* for KVM_GET_DIRTY_LOG */ | ||
| 207 | struct kvm_dirty_log { | ||
| 208 | __u32 slot; | ||
| 209 | __u32 padding; | ||
| 210 | union { | ||
| 211 | void __user *dirty_bitmap; /* one bit per page */ | ||
| 212 | __u64 padding; | ||
| 213 | }; | ||
| 214 | }; | ||
| 215 | |||
| 216 | Given a memory slot, return a bitmap containing any pages dirtied | ||
| 217 | since the last call to this ioctl. Bit 0 is the first page in the | ||
| 218 | memory slot. Ensure the entire structure is cleared to avoid padding | ||
| 219 | issues. | ||
| 220 | |||
| 221 | 4.8 KVM_SET_MEMORY_ALIAS | ||
| 222 | |||
| 223 | Capability: basic | ||
| 224 | Architectures: x86 | ||
| 225 | Type: vm ioctl | ||
| 226 | Parameters: struct kvm_memory_alias (in) | ||
| 227 | Returns: 0 (success), -1 (error) | ||
| 228 | |||
| 229 | struct kvm_memory_alias { | ||
| 230 | __u32 slot; /* this has a different namespace than memory slots */ | ||
| 231 | __u32 flags; | ||
| 232 | __u64 guest_phys_addr; | ||
| 233 | __u64 memory_size; | ||
| 234 | __u64 target_phys_addr; | ||
| 235 | }; | ||
| 236 | |||
| 237 | Defines a guest physical address space region as an alias to another | ||
| 238 | region. Useful for aliased address, for example the VGA low memory | ||
| 239 | window. Should not be used with userspace memory. | ||
| 240 | |||
| 241 | 4.9 KVM_RUN | ||
| 242 | |||
| 243 | Capability: basic | ||
| 244 | Architectures: all | ||
| 245 | Type: vcpu ioctl | ||
| 246 | Parameters: none | ||
| 247 | Returns: 0 on success, -1 on error | ||
| 248 | Errors: | ||
| 249 | EINTR: an unmasked signal is pending | ||
| 250 | |||
| 251 | This ioctl is used to run a guest virtual cpu. While there are no | ||
| 252 | explicit parameters, there is an implicit parameter block that can be | ||
| 253 | obtained by mmap()ing the vcpu fd at offset 0, with the size given by | ||
| 254 | KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct | ||
| 255 | kvm_run' (see below). | ||
| 256 | |||
| 257 | 4.10 KVM_GET_REGS | ||
| 258 | |||
| 259 | Capability: basic | ||
| 260 | Architectures: all | ||
| 261 | Type: vcpu ioctl | ||
| 262 | Parameters: struct kvm_regs (out) | ||
| 263 | Returns: 0 on success, -1 on error | ||
| 264 | |||
| 265 | Reads the general purpose registers from the vcpu. | ||
| 266 | |||
| 267 | /* x86 */ | ||
| 268 | struct kvm_regs { | ||
| 269 | /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ | ||
| 270 | __u64 rax, rbx, rcx, rdx; | ||
| 271 | __u64 rsi, rdi, rsp, rbp; | ||
| 272 | __u64 r8, r9, r10, r11; | ||
| 273 | __u64 r12, r13, r14, r15; | ||
| 274 | __u64 rip, rflags; | ||
| 275 | }; | ||
| 276 | |||
| 277 | 4.11 KVM_SET_REGS | ||
| 278 | |||
| 279 | Capability: basic | ||
| 280 | Architectures: all | ||
| 281 | Type: vcpu ioctl | ||
| 282 | Parameters: struct kvm_regs (in) | ||
| 283 | Returns: 0 on success, -1 on error | ||
| 284 | |||
| 285 | Writes the general purpose registers into the vcpu. | ||
| 286 | |||
| 287 | See KVM_GET_REGS for the data structure. | ||
| 288 | |||
| 289 | 4.12 KVM_GET_SREGS | ||
| 290 | |||
| 291 | Capability: basic | ||
| 292 | Architectures: x86 | ||
| 293 | Type: vcpu ioctl | ||
| 294 | Parameters: struct kvm_sregs (out) | ||
| 295 | Returns: 0 on success, -1 on error | ||
| 296 | |||
| 297 | Reads special registers from the vcpu. | ||
| 298 | |||
| 299 | /* x86 */ | ||
| 300 | struct kvm_sregs { | ||
| 301 | struct kvm_segment cs, ds, es, fs, gs, ss; | ||
| 302 | struct kvm_segment tr, ldt; | ||
| 303 | struct kvm_dtable gdt, idt; | ||
| 304 | __u64 cr0, cr2, cr3, cr4, cr8; | ||
| 305 | __u64 efer; | ||
| 306 | __u64 apic_base; | ||
| 307 | __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64]; | ||
| 308 | }; | ||
| 309 | |||
| 310 | interrupt_bitmap is a bitmap of pending external interrupts. At most | ||
| 311 | one bit may be set. This interrupt has been acknowledged by the APIC | ||
| 312 | but not yet injected into the cpu core. | ||
| 313 | |||
| 314 | 4.13 KVM_SET_SREGS | ||
| 315 | |||
| 316 | Capability: basic | ||
| 317 | Architectures: x86 | ||
| 318 | Type: vcpu ioctl | ||
| 319 | Parameters: struct kvm_sregs (in) | ||
| 320 | Returns: 0 on success, -1 on error | ||
| 321 | |||
| 322 | Writes special registers into the vcpu. See KVM_GET_SREGS for the | ||
| 323 | data structures. | ||
| 324 | |||
| 325 | 4.14 KVM_TRANSLATE | ||
| 326 | |||
| 327 | Capability: basic | ||
| 328 | Architectures: x86 | ||
| 329 | Type: vcpu ioctl | ||
| 330 | Parameters: struct kvm_translation (in/out) | ||
| 331 | Returns: 0 on success, -1 on error | ||
| 332 | |||
| 333 | Translates a virtual address according to the vcpu's current address | ||
| 334 | translation mode. | ||
| 335 | |||
| 336 | struct kvm_translation { | ||
| 337 | /* in */ | ||
| 338 | __u64 linear_address; | ||
| 339 | |||
| 340 | /* out */ | ||
| 341 | __u64 physical_address; | ||
| 342 | __u8 valid; | ||
| 343 | __u8 writeable; | ||
| 344 | __u8 usermode; | ||
| 345 | __u8 pad[5]; | ||
| 346 | }; | ||
| 347 | |||
| 348 | 4.15 KVM_INTERRUPT | ||
| 349 | |||
| 350 | Capability: basic | ||
| 351 | Architectures: x86 | ||
| 352 | Type: vcpu ioctl | ||
| 353 | Parameters: struct kvm_interrupt (in) | ||
| 354 | Returns: 0 on success, -1 on error | ||
| 355 | |||
| 356 | Queues a hardware interrupt vector to be injected. This is only | ||
| 357 | useful if in-kernel local APIC is not used. | ||
| 358 | |||
| 359 | /* for KVM_INTERRUPT */ | ||
| 360 | struct kvm_interrupt { | ||
| 361 | /* in */ | ||
| 362 | __u32 irq; | ||
| 363 | }; | ||
| 364 | |||
| 365 | Note 'irq' is an interrupt vector, not an interrupt pin or line. | ||
| 366 | |||
| 367 | 4.16 KVM_DEBUG_GUEST | ||
| 368 | |||
| 369 | Capability: basic | ||
| 370 | Architectures: none | ||
| 371 | Type: vcpu ioctl | ||
| 372 | Parameters: none) | ||
| 373 | Returns: -1 on error | ||
| 374 | |||
| 375 | Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. | ||
| 376 | |||
| 377 | 4.17 KVM_GET_MSRS | ||
| 378 | |||
| 379 | Capability: basic | ||
| 380 | Architectures: x86 | ||
| 381 | Type: vcpu ioctl | ||
| 382 | Parameters: struct kvm_msrs (in/out) | ||
| 383 | Returns: 0 on success, -1 on error | ||
| 384 | |||
| 385 | Reads model-specific registers from the vcpu. Supported msr indices can | ||
| 386 | be obtained using KVM_GET_MSR_INDEX_LIST. | ||
| 387 | |||
| 388 | struct kvm_msrs { | ||
| 389 | __u32 nmsrs; /* number of msrs in entries */ | ||
| 390 | __u32 pad; | ||
| 391 | |||
| 392 | struct kvm_msr_entry entries[0]; | ||
| 393 | }; | ||
| 394 | |||
| 395 | struct kvm_msr_entry { | ||
| 396 | __u32 index; | ||
| 397 | __u32 reserved; | ||
| 398 | __u64 data; | ||
| 399 | }; | ||
| 400 | |||
| 401 | Application code should set the 'nmsrs' member (which indicates the | ||
| 402 | size of the entries array) and the 'index' member of each array entry. | ||
| 403 | kvm will fill in the 'data' member. | ||
| 404 | |||
| 405 | 4.18 KVM_SET_MSRS | ||
| 406 | |||
| 407 | Capability: basic | ||
| 408 | Architectures: x86 | ||
| 409 | Type: vcpu ioctl | ||
| 410 | Parameters: struct kvm_msrs (in) | ||
| 411 | Returns: 0 on success, -1 on error | ||
| 412 | |||
| 413 | Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the | ||
| 414 | data structures. | ||
| 415 | |||
| 416 | Application code should set the 'nmsrs' member (which indicates the | ||
| 417 | size of the entries array), and the 'index' and 'data' members of each | ||
| 418 | array entry. | ||
| 419 | |||
| 420 | 4.19 KVM_SET_CPUID | ||
| 421 | |||
| 422 | Capability: basic | ||
| 423 | Architectures: x86 | ||
| 424 | Type: vcpu ioctl | ||
| 425 | Parameters: struct kvm_cpuid (in) | ||
| 426 | Returns: 0 on success, -1 on error | ||
| 427 | |||
| 428 | Defines the vcpu responses to the cpuid instruction. Applications | ||
| 429 | should use the KVM_SET_CPUID2 ioctl if available. | ||
| 430 | |||
| 431 | |||
| 432 | struct kvm_cpuid_entry { | ||
| 433 | __u32 function; | ||
| 434 | __u32 eax; | ||
| 435 | __u32 ebx; | ||
| 436 | __u32 ecx; | ||
| 437 | __u32 edx; | ||
| 438 | __u32 padding; | ||
| 439 | }; | ||
| 440 | |||
| 441 | /* for KVM_SET_CPUID */ | ||
| 442 | struct kvm_cpuid { | ||
| 443 | __u32 nent; | ||
| 444 | __u32 padding; | ||
| 445 | struct kvm_cpuid_entry entries[0]; | ||
| 446 | }; | ||
| 447 | |||
| 448 | 4.20 KVM_SET_SIGNAL_MASK | ||
| 449 | |||
| 450 | Capability: basic | ||
| 451 | Architectures: x86 | ||
| 452 | Type: vcpu ioctl | ||
| 453 | Parameters: struct kvm_signal_mask (in) | ||
| 454 | Returns: 0 on success, -1 on error | ||
| 455 | |||
| 456 | Defines which signals are blocked during execution of KVM_RUN. This | ||
| 457 | signal mask temporarily overrides the threads signal mask. Any | ||
| 458 | unblocked signal received (except SIGKILL and SIGSTOP, which retain | ||
| 459 | their traditional behaviour) will cause KVM_RUN to return with -EINTR. | ||
| 460 | |||
| 461 | Note the signal will only be delivered if not blocked by the original | ||
| 462 | signal mask. | ||
| 463 | |||
| 464 | /* for KVM_SET_SIGNAL_MASK */ | ||
| 465 | struct kvm_signal_mask { | ||
| 466 | __u32 len; | ||
| 467 | __u8 sigset[0]; | ||
| 468 | }; | ||
| 469 | |||
| 470 | 4.21 KVM_GET_FPU | ||
| 471 | |||
| 472 | Capability: basic | ||
| 473 | Architectures: x86 | ||
| 474 | Type: vcpu ioctl | ||
| 475 | Parameters: struct kvm_fpu (out) | ||
| 476 | Returns: 0 on success, -1 on error | ||
| 477 | |||
| 478 | Reads the floating point state from the vcpu. | ||
| 479 | |||
| 480 | /* for KVM_GET_FPU and KVM_SET_FPU */ | ||
| 481 | struct kvm_fpu { | ||
| 482 | __u8 fpr[8][16]; | ||
| 483 | __u16 fcw; | ||
| 484 | __u16 fsw; | ||
| 485 | __u8 ftwx; /* in fxsave format */ | ||
| 486 | __u8 pad1; | ||
| 487 | __u16 last_opcode; | ||
| 488 | __u64 last_ip; | ||
| 489 | __u64 last_dp; | ||
| 490 | __u8 xmm[16][16]; | ||
| 491 | __u32 mxcsr; | ||
| 492 | __u32 pad2; | ||
| 493 | }; | ||
| 494 | |||
| 495 | 4.22 KVM_SET_FPU | ||
| 496 | |||
| 497 | Capability: basic | ||
| 498 | Architectures: x86 | ||
| 499 | Type: vcpu ioctl | ||
| 500 | Parameters: struct kvm_fpu (in) | ||
| 501 | Returns: 0 on success, -1 on error | ||
| 502 | |||
| 503 | Writes the floating point state to the vcpu. | ||
| 504 | |||
| 505 | /* for KVM_GET_FPU and KVM_SET_FPU */ | ||
| 506 | struct kvm_fpu { | ||
| 507 | __u8 fpr[8][16]; | ||
| 508 | __u16 fcw; | ||
| 509 | __u16 fsw; | ||
| 510 | __u8 ftwx; /* in fxsave format */ | ||
| 511 | __u8 pad1; | ||
| 512 | __u16 last_opcode; | ||
| 513 | __u64 last_ip; | ||
| 514 | __u64 last_dp; | ||
| 515 | __u8 xmm[16][16]; | ||
| 516 | __u32 mxcsr; | ||
| 517 | __u32 pad2; | ||
| 518 | }; | ||
| 519 | |||
| 520 | 4.23 KVM_CREATE_IRQCHIP | ||
| 521 | |||
| 522 | Capability: KVM_CAP_IRQCHIP | ||
| 523 | Architectures: x86, ia64 | ||
| 524 | Type: vm ioctl | ||
| 525 | Parameters: none | ||
| 526 | Returns: 0 on success, -1 on error | ||
| 527 | |||
| 528 | Creates an interrupt controller model in the kernel. On x86, creates a virtual | ||
| 529 | ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a | ||
| 530 | local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 | ||
| 531 | only go to the IOAPIC. On ia64, a IOSAPIC is created. | ||
| 532 | |||
| 533 | 4.24 KVM_IRQ_LINE | ||
| 534 | |||
| 535 | Capability: KVM_CAP_IRQCHIP | ||
| 536 | Architectures: x86, ia64 | ||
| 537 | Type: vm ioctl | ||
| 538 | Parameters: struct kvm_irq_level | ||
| 539 | Returns: 0 on success, -1 on error | ||
| 540 | |||
| 541 | Sets the level of a GSI input to the interrupt controller model in the kernel. | ||
| 542 | Requires that an interrupt controller model has been previously created with | ||
| 543 | KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level | ||
| 544 | to be set to 1 and then back to 0. | ||
| 545 | |||
| 546 | struct kvm_irq_level { | ||
| 547 | union { | ||
| 548 | __u32 irq; /* GSI */ | ||
| 549 | __s32 status; /* not used for KVM_IRQ_LEVEL */ | ||
| 550 | }; | ||
| 551 | __u32 level; /* 0 or 1 */ | ||
| 552 | }; | ||
| 553 | |||
| 554 | 4.25 KVM_GET_IRQCHIP | ||
| 555 | |||
| 556 | Capability: KVM_CAP_IRQCHIP | ||
| 557 | Architectures: x86, ia64 | ||
| 558 | Type: vm ioctl | ||
| 559 | Parameters: struct kvm_irqchip (in/out) | ||
| 560 | Returns: 0 on success, -1 on error | ||
| 561 | |||
| 562 | Reads the state of a kernel interrupt controller created with | ||
| 563 | KVM_CREATE_IRQCHIP into a buffer provided by the caller. | ||
| 564 | |||
| 565 | struct kvm_irqchip { | ||
| 566 | __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ | ||
| 567 | __u32 pad; | ||
| 568 | union { | ||
| 569 | char dummy[512]; /* reserving space */ | ||
| 570 | struct kvm_pic_state pic; | ||
| 571 | struct kvm_ioapic_state ioapic; | ||
| 572 | } chip; | ||
| 573 | }; | ||
| 574 | |||
| 575 | 4.26 KVM_SET_IRQCHIP | ||
| 576 | |||
| 577 | Capability: KVM_CAP_IRQCHIP | ||
| 578 | Architectures: x86, ia64 | ||
| 579 | Type: vm ioctl | ||
| 580 | Parameters: struct kvm_irqchip (in) | ||
| 581 | Returns: 0 on success, -1 on error | ||
| 582 | |||
| 583 | Sets the state of a kernel interrupt controller created with | ||
| 584 | KVM_CREATE_IRQCHIP from a buffer provided by the caller. | ||
| 585 | |||
| 586 | struct kvm_irqchip { | ||
| 587 | __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ | ||
| 588 | __u32 pad; | ||
| 589 | union { | ||
| 590 | char dummy[512]; /* reserving space */ | ||
| 591 | struct kvm_pic_state pic; | ||
| 592 | struct kvm_ioapic_state ioapic; | ||
| 593 | } chip; | ||
| 594 | }; | ||
| 595 | |||
| 596 | 5. The kvm_run structure | ||
| 597 | |||
| 598 | Application code obtains a pointer to the kvm_run structure by | ||
| 599 | mmap()ing a vcpu fd. From that point, application code can control | ||
| 600 | execution by changing fields in kvm_run prior to calling the KVM_RUN | ||
| 601 | ioctl, and obtain information about the reason KVM_RUN returned by | ||
| 602 | looking up structure members. | ||
| 603 | |||
| 604 | struct kvm_run { | ||
| 605 | /* in */ | ||
| 606 | __u8 request_interrupt_window; | ||
| 607 | |||
| 608 | Request that KVM_RUN return when it becomes possible to inject external | ||
| 609 | interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. | ||
| 610 | |||
| 611 | __u8 padding1[7]; | ||
| 612 | |||
| 613 | /* out */ | ||
| 614 | __u32 exit_reason; | ||
| 615 | |||
| 616 | When KVM_RUN has returned successfully (return value 0), this informs | ||
| 617 | application code why KVM_RUN has returned. Allowable values for this | ||
| 618 | field are detailed below. | ||
| 619 | |||
| 620 | __u8 ready_for_interrupt_injection; | ||
| 621 | |||
| 622 | If request_interrupt_window has been specified, this field indicates | ||
| 623 | an interrupt can be injected now with KVM_INTERRUPT. | ||
| 624 | |||
| 625 | __u8 if_flag; | ||
| 626 | |||
| 627 | The value of the current interrupt flag. Only valid if in-kernel | ||
| 628 | local APIC is not used. | ||
| 629 | |||
| 630 | __u8 padding2[2]; | ||
| 631 | |||
| 632 | /* in (pre_kvm_run), out (post_kvm_run) */ | ||
| 633 | __u64 cr8; | ||
| 634 | |||
| 635 | The value of the cr8 register. Only valid if in-kernel local APIC is | ||
| 636 | not used. Both input and output. | ||
| 637 | |||
| 638 | __u64 apic_base; | ||
| 639 | |||
| 640 | The value of the APIC BASE msr. Only valid if in-kernel local | ||
| 641 | APIC is not used. Both input and output. | ||
| 642 | |||
| 643 | union { | ||
| 644 | /* KVM_EXIT_UNKNOWN */ | ||
| 645 | struct { | ||
| 646 | __u64 hardware_exit_reason; | ||
| 647 | } hw; | ||
| 648 | |||
| 649 | If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown | ||
| 650 | reasons. Further architecture-specific information is available in | ||
| 651 | hardware_exit_reason. | ||
| 652 | |||
| 653 | /* KVM_EXIT_FAIL_ENTRY */ | ||
| 654 | struct { | ||
| 655 | __u64 hardware_entry_failure_reason; | ||
| 656 | } fail_entry; | ||
| 657 | |||
| 658 | If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due | ||
| 659 | to unknown reasons. Further architecture-specific information is | ||
| 660 | available in hardware_entry_failure_reason. | ||
| 661 | |||
| 662 | /* KVM_EXIT_EXCEPTION */ | ||
| 663 | struct { | ||
| 664 | __u32 exception; | ||
| 665 | __u32 error_code; | ||
| 666 | } ex; | ||
| 667 | |||
| 668 | Unused. | ||
| 669 | |||
| 670 | /* KVM_EXIT_IO */ | ||
| 671 | struct { | ||
| 672 | #define KVM_EXIT_IO_IN 0 | ||
| 673 | #define KVM_EXIT_IO_OUT 1 | ||
| 674 | __u8 direction; | ||
| 675 | __u8 size; /* bytes */ | ||
| 676 | __u16 port; | ||
| 677 | __u32 count; | ||
| 678 | __u64 data_offset; /* relative to kvm_run start */ | ||
| 679 | } io; | ||
| 680 | |||
| 681 | If exit_reason is KVM_EXIT_IO_IN or KVM_EXIT_IO_OUT, then the vcpu has | ||
| 682 | executed a port I/O instruction which could not be satisfied by kvm. | ||
| 683 | data_offset describes where the data is located (KVM_EXIT_IO_OUT) or | ||
| 684 | where kvm expects application code to place the data for the next | ||
| 685 | KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a patcked array. | ||
| 686 | |||
| 687 | struct { | ||
| 688 | struct kvm_debug_exit_arch arch; | ||
| 689 | } debug; | ||
| 690 | |||
| 691 | Unused. | ||
| 692 | |||
| 693 | /* KVM_EXIT_MMIO */ | ||
| 694 | struct { | ||
| 695 | __u64 phys_addr; | ||
| 696 | __u8 data[8]; | ||
| 697 | __u32 len; | ||
| 698 | __u8 is_write; | ||
| 699 | } mmio; | ||
| 700 | |||
| 701 | If exit_reason is KVM_EXIT_MMIO or KVM_EXIT_IO_OUT, then the vcpu has | ||
| 702 | executed a memory-mapped I/O instruction which could not be satisfied | ||
| 703 | by kvm. The 'data' member contains the written data if 'is_write' is | ||
| 704 | true, and should be filled by application code otherwise. | ||
| 705 | |||
| 706 | /* KVM_EXIT_HYPERCALL */ | ||
| 707 | struct { | ||
| 708 | __u64 nr; | ||
| 709 | __u64 args[6]; | ||
| 710 | __u64 ret; | ||
| 711 | __u32 longmode; | ||
| 712 | __u32 pad; | ||
| 713 | } hypercall; | ||
| 714 | |||
| 715 | Unused. | ||
| 716 | |||
| 717 | /* KVM_EXIT_TPR_ACCESS */ | ||
| 718 | struct { | ||
| 719 | __u64 rip; | ||
| 720 | __u32 is_write; | ||
| 721 | __u32 pad; | ||
| 722 | } tpr_access; | ||
| 723 | |||
| 724 | To be documented (KVM_TPR_ACCESS_REPORTING). | ||
| 725 | |||
| 726 | /* KVM_EXIT_S390_SIEIC */ | ||
| 727 | struct { | ||
| 728 | __u8 icptcode; | ||
| 729 | __u64 mask; /* psw upper half */ | ||
| 730 | __u64 addr; /* psw lower half */ | ||
| 731 | __u16 ipa; | ||
| 732 | __u32 ipb; | ||
| 733 | } s390_sieic; | ||
| 734 | |||
| 735 | s390 specific. | ||
| 736 | |||
| 737 | /* KVM_EXIT_S390_RESET */ | ||
| 738 | #define KVM_S390_RESET_POR 1 | ||
| 739 | #define KVM_S390_RESET_CLEAR 2 | ||
| 740 | #define KVM_S390_RESET_SUBSYSTEM 4 | ||
| 741 | #define KVM_S390_RESET_CPU_INIT 8 | ||
| 742 | #define KVM_S390_RESET_IPL 16 | ||
| 743 | __u64 s390_reset_flags; | ||
| 744 | |||
| 745 | s390 specific. | ||
| 746 | |||
| 747 | /* KVM_EXIT_DCR */ | ||
| 748 | struct { | ||
| 749 | __u32 dcrn; | ||
| 750 | __u32 data; | ||
| 751 | __u8 is_write; | ||
| 752 | } dcr; | ||
| 753 | |||
| 754 | powerpc specific. | ||
| 755 | |||
| 756 | /* Fix the size of the union. */ | ||
| 757 | char padding[256]; | ||
| 758 | }; | ||
| 759 | }; | ||
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt index f2296ecedb89..e2ddcdeb61b6 100644 --- a/Documentation/laptops/thinkpad-acpi.txt +++ b/Documentation/laptops/thinkpad-acpi.txt | |||
| @@ -36,8 +36,6 @@ detailed description): | |||
| 36 | - Bluetooth enable and disable | 36 | - Bluetooth enable and disable |
| 37 | - video output switching, expansion control | 37 | - video output switching, expansion control |
| 38 | - ThinkLight on and off | 38 | - ThinkLight on and off |
| 39 | - limited docking and undocking | ||
| 40 | - UltraBay eject | ||
| 41 | - CMOS/UCMS control | 39 | - CMOS/UCMS control |
| 42 | - LED control | 40 | - LED control |
| 43 | - ACPI sounds | 41 | - ACPI sounds |
| @@ -729,131 +727,6 @@ cannot be read or if it is unknown, thinkpad-acpi will report it as "off". | |||
| 729 | It is impossible to know if the status returned through sysfs is valid. | 727 | It is impossible to know if the status returned through sysfs is valid. |
| 730 | 728 | ||
| 731 | 729 | ||
| 732 | Docking / undocking -- /proc/acpi/ibm/dock | ||
| 733 | ------------------------------------------ | ||
| 734 | |||
| 735 | Docking and undocking (e.g. with the X4 UltraBase) requires some | ||
| 736 | actions to be taken by the operating system to safely make or break | ||
| 737 | the electrical connections with the dock. | ||
| 738 | |||
| 739 | The docking feature of this driver generates the following ACPI events: | ||
| 740 | |||
| 741 | ibm/dock GDCK 00000003 00000001 -- eject request | ||
| 742 | ibm/dock GDCK 00000003 00000002 -- undocked | ||
| 743 | ibm/dock GDCK 00000000 00000003 -- docked | ||
| 744 | |||
| 745 | NOTE: These events will only be generated if the laptop was docked | ||
| 746 | when originally booted. This is due to the current lack of support for | ||
| 747 | hot plugging of devices in the Linux ACPI framework. If the laptop was | ||
| 748 | booted while not in the dock, the following message is shown in the | ||
| 749 | logs: | ||
| 750 | |||
| 751 | Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present | ||
| 752 | |||
| 753 | In this case, no dock-related events are generated but the dock and | ||
| 754 | undock commands described below still work. They can be executed | ||
| 755 | manually or triggered by Fn key combinations (see the example acpid | ||
| 756 | configuration files included in the driver tarball package available | ||
| 757 | on the web site). | ||
| 758 | |||
| 759 | When the eject request button on the dock is pressed, the first event | ||
| 760 | above is generated. The handler for this event should issue the | ||
| 761 | following command: | ||
| 762 | |||
| 763 | echo undock > /proc/acpi/ibm/dock | ||
| 764 | |||
| 765 | After the LED on the dock goes off, it is safe to eject the laptop. | ||
| 766 | Note: if you pressed this key by mistake, go ahead and eject the | ||
| 767 | laptop, then dock it back in. Otherwise, the dock may not function as | ||
| 768 | expected. | ||
| 769 | |||
| 770 | When the laptop is docked, the third event above is generated. The | ||
| 771 | handler for this event should issue the following command to fully | ||
| 772 | enable the dock: | ||
| 773 | |||
| 774 | echo dock > /proc/acpi/ibm/dock | ||
| 775 | |||
| 776 | The contents of the /proc/acpi/ibm/dock file shows the current status | ||
| 777 | of the dock, as provided by the ACPI framework. | ||
| 778 | |||
| 779 | The docking support in this driver does not take care of enabling or | ||
| 780 | disabling any other devices you may have attached to the dock. For | ||
| 781 | example, a CD drive plugged into the UltraBase needs to be disabled or | ||
| 782 | enabled separately. See the provided example acpid configuration files | ||
| 783 | for how this can be accomplished. | ||
| 784 | |||
| 785 | There is no support yet for PCI devices that may be attached to a | ||
| 786 | docking station, e.g. in the ThinkPad Dock II. The driver currently | ||
| 787 | does not recognize, enable or disable such devices. This means that | ||
| 788 | the only docking stations currently supported are the X-series | ||
| 789 | UltraBase docks and "dumb" port replicators like the Mini Dock (the | ||
| 790 | latter don't need any ACPI support, actually). | ||
| 791 | |||
| 792 | |||
| 793 | UltraBay eject -- /proc/acpi/ibm/bay | ||
| 794 | ------------------------------------ | ||
| 795 | |||
| 796 | Inserting or ejecting an UltraBay device requires some actions to be | ||
| 797 | taken by the operating system to safely make or break the electrical | ||
| 798 | connections with the device. | ||
| 799 | |||
| 800 | This feature generates the following ACPI events: | ||
| 801 | |||
| 802 | ibm/bay MSTR 00000003 00000000 -- eject request | ||
| 803 | ibm/bay MSTR 00000001 00000000 -- eject lever inserted | ||
| 804 | |||
| 805 | NOTE: These events will only be generated if the UltraBay was present | ||
| 806 | when the laptop was originally booted (on the X series, the UltraBay | ||
| 807 | is in the dock, so it may not be present if the laptop was undocked). | ||
| 808 | This is due to the current lack of support for hot plugging of devices | ||
| 809 | in the Linux ACPI framework. If the laptop was booted without the | ||
| 810 | UltraBay, the following message is shown in the logs: | ||
| 811 | |||
| 812 | Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present | ||
| 813 | |||
| 814 | In this case, no bay-related events are generated but the eject | ||
| 815 | command described below still works. It can be executed manually or | ||
| 816 | triggered by a hot key combination. | ||
| 817 | |||
| 818 | Sliding the eject lever generates the first event shown above. The | ||
| 819 | handler for this event should take whatever actions are necessary to | ||
| 820 | shut down the device in the UltraBay (e.g. call idectl), then issue | ||
| 821 | the following command: | ||
| 822 | |||
| 823 | echo eject > /proc/acpi/ibm/bay | ||
| 824 | |||
| 825 | After the LED on the UltraBay goes off, it is safe to pull out the | ||
| 826 | device. | ||
| 827 | |||
| 828 | When the eject lever is inserted, the second event above is | ||
| 829 | generated. The handler for this event should take whatever actions are | ||
| 830 | necessary to enable the UltraBay device (e.g. call idectl). | ||
| 831 | |||
| 832 | The contents of the /proc/acpi/ibm/bay file shows the current status | ||
| 833 | of the UltraBay, as provided by the ACPI framework. | ||
| 834 | |||
| 835 | EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use | ||
| 836 | this feature, you need to supply the experimental=1 parameter when | ||
| 837 | loading the module): | ||
| 838 | |||
| 839 | These models do not have a button near the UltraBay device to request | ||
| 840 | a hot eject but rather require the laptop to be put to sleep | ||
| 841 | (suspend-to-ram) before the bay device is ejected or inserted). | ||
| 842 | The sequence of steps to eject the device is as follows: | ||
| 843 | |||
| 844 | echo eject > /proc/acpi/ibm/bay | ||
| 845 | put the ThinkPad to sleep | ||
| 846 | remove the drive | ||
| 847 | resume from sleep | ||
| 848 | cat /proc/acpi/ibm/bay should show that the drive was removed | ||
| 849 | |||
| 850 | On the A3x, both the UltraBay 2000 and UltraBay Plus devices are | ||
| 851 | supported. Use "eject2" instead of "eject" for the second bay. | ||
| 852 | |||
| 853 | Note: the UltraBay eject support on the 600e/x, A22p and A3x is | ||
| 854 | EXPERIMENTAL and may not work as expected. USE WITH CAUTION! | ||
| 855 | |||
| 856 | |||
| 857 | CMOS/UCMS control | 730 | CMOS/UCMS control |
| 858 | ----------------- | 731 | ----------------- |
| 859 | 732 | ||
diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index 9ebcd6ef361b..950cde6d6e58 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c | |||
| @@ -1,7 +1,9 @@ | |||
| 1 | /*P:100 This is the Launcher code, a simple program which lays out the | 1 | /*P:100 |
| 2 | * "physical" memory for the new Guest by mapping the kernel image and | 2 | * This is the Launcher code, a simple program which lays out the "physical" |
| 3 | * the virtual devices, then opens /dev/lguest to tell the kernel | 3 | * memory for the new Guest by mapping the kernel image and the virtual |
| 4 | * about the Guest and control it. :*/ | 4 | * devices, then opens /dev/lguest to tell the kernel about the Guest and |
| 5 | * control it. | ||
| 6 | :*/ | ||
| 5 | #define _LARGEFILE64_SOURCE | 7 | #define _LARGEFILE64_SOURCE |
| 6 | #define _GNU_SOURCE | 8 | #define _GNU_SOURCE |
| 7 | #include <stdio.h> | 9 | #include <stdio.h> |
| @@ -46,13 +48,15 @@ | |||
| 46 | #include "linux/virtio_rng.h" | 48 | #include "linux/virtio_rng.h" |
| 47 | #include "linux/virtio_ring.h" | 49 | #include "linux/virtio_ring.h" |
| 48 | #include "asm/bootparam.h" | 50 | #include "asm/bootparam.h" |
| 49 | /*L:110 We can ignore the 39 include files we need for this program, but I do | 51 | /*L:110 |
| 50 | * want to draw attention to the use of kernel-style types. | 52 | * We can ignore the 42 include files we need for this program, but I do want |
| 53 | * to draw attention to the use of kernel-style types. | ||
| 51 | * | 54 | * |
| 52 | * As Linus said, "C is a Spartan language, and so should your naming be." I | 55 | * As Linus said, "C is a Spartan language, and so should your naming be." I |
| 53 | * like these abbreviations, so we define them here. Note that u64 is always | 56 | * like these abbreviations, so we define them here. Note that u64 is always |
| 54 | * unsigned long long, which works on all Linux systems: this means that we can | 57 | * unsigned long long, which works on all Linux systems: this means that we can |
| 55 | * use %llu in printf for any u64. */ | 58 | * use %llu in printf for any u64. |
| 59 | */ | ||
| 56 | typedef unsigned long long u64; | 60 | typedef unsigned long long u64; |
| 57 | typedef uint32_t u32; | 61 | typedef uint32_t u32; |
| 58 | typedef uint16_t u16; | 62 | typedef uint16_t u16; |
| @@ -69,8 +73,10 @@ typedef uint8_t u8; | |||
| 69 | /* This will occupy 3 pages: it must be a power of 2. */ | 73 | /* This will occupy 3 pages: it must be a power of 2. */ |
| 70 | #define VIRTQUEUE_NUM 256 | 74 | #define VIRTQUEUE_NUM 256 |
| 71 | 75 | ||
| 72 | /*L:120 verbose is both a global flag and a macro. The C preprocessor allows | 76 | /*L:120 |
| 73 | * this, and although I wouldn't recommend it, it works quite nicely here. */ | 77 | * verbose is both a global flag and a macro. The C preprocessor allows |
| 78 | * this, and although I wouldn't recommend it, it works quite nicely here. | ||
| 79 | */ | ||
| 74 | static bool verbose; | 80 | static bool verbose; |
| 75 | #define verbose(args...) \ | 81 | #define verbose(args...) \ |
| 76 | do { if (verbose) printf(args); } while(0) | 82 | do { if (verbose) printf(args); } while(0) |
| @@ -87,8 +93,7 @@ static int lguest_fd; | |||
| 87 | static unsigned int __thread cpu_id; | 93 | static unsigned int __thread cpu_id; |
| 88 | 94 | ||
| 89 | /* This is our list of devices. */ | 95 | /* This is our list of devices. */ |
| 90 | struct device_list | 96 | struct device_list { |
| 91 | { | ||
| 92 | /* Counter to assign interrupt numbers. */ | 97 | /* Counter to assign interrupt numbers. */ |
| 93 | unsigned int next_irq; | 98 | unsigned int next_irq; |
| 94 | 99 | ||
| @@ -100,8 +105,7 @@ struct device_list | |||
| 100 | 105 | ||
| 101 | /* A single linked list of devices. */ | 106 | /* A single linked list of devices. */ |
| 102 | struct device *dev; | 107 | struct device *dev; |
| 103 | /* And a pointer to the last device for easy append and also for | 108 | /* And a pointer to the last device for easy append. */ |
| 104 | * configuration appending. */ | ||
| 105 | struct device *lastdev; | 109 | struct device *lastdev; |
| 106 | }; | 110 | }; |
| 107 | 111 | ||
| @@ -109,8 +113,7 @@ struct device_list | |||
| 109 | static struct device_list devices; | 113 | static struct device_list devices; |
| 110 | 114 | ||
| 111 | /* The device structure describes a single device. */ | 115 | /* The device structure describes a single device. */ |
| 112 | struct device | 116 | struct device { |
| 113 | { | ||
| 114 | /* The linked-list pointer. */ | 117 | /* The linked-list pointer. */ |
| 115 | struct device *next; | 118 | struct device *next; |
| 116 | 119 | ||
| @@ -135,8 +138,7 @@ struct device | |||
| 135 | }; | 138 | }; |
| 136 | 139 | ||
| 137 | /* The virtqueue structure describes a queue attached to a device. */ | 140 | /* The virtqueue structure describes a queue attached to a device. */ |
| 138 | struct virtqueue | 141 | struct virtqueue { |
| 139 | { | ||
| 140 | struct virtqueue *next; | 142 | struct virtqueue *next; |
| 141 | 143 | ||
| 142 | /* Which device owns me. */ | 144 | /* Which device owns me. */ |
| @@ -168,20 +170,24 @@ static char **main_args; | |||
| 168 | /* The original tty settings to restore on exit. */ | 170 | /* The original tty settings to restore on exit. */ |
| 169 | static struct termios orig_term; | 171 | static struct termios orig_term; |
| 170 | 172 | ||
| 171 | /* We have to be careful with barriers: our devices are all run in separate | 173 | /* |
| 174 | * We have to be careful with barriers: our devices are all run in separate | ||
| 172 | * threads and so we need to make sure that changes visible to the Guest happen | 175 | * threads and so we need to make sure that changes visible to the Guest happen |
| 173 | * in precise order. */ | 176 | * in precise order. |
| 177 | */ | ||
| 174 | #define wmb() __asm__ __volatile__("" : : : "memory") | 178 | #define wmb() __asm__ __volatile__("" : : : "memory") |
| 175 | #define mb() __asm__ __volatile__("" : : : "memory") | 179 | #define mb() __asm__ __volatile__("" : : : "memory") |
| 176 | 180 | ||
| 177 | /* Convert an iovec element to the given type. | 181 | /* |
| 182 | * Convert an iovec element to the given type. | ||
| 178 | * | 183 | * |
| 179 | * This is a fairly ugly trick: we need to know the size of the type and | 184 | * This is a fairly ugly trick: we need to know the size of the type and |
| 180 | * alignment requirement to check the pointer is kosher. It's also nice to | 185 | * alignment requirement to check the pointer is kosher. It's also nice to |
| 181 | * have the name of the type in case we report failure. | 186 | * have the name of the type in case we report failure. |
| 182 | * | 187 | * |
| 183 | * Typing those three things all the time is cumbersome and error prone, so we | 188 | * Typing those three things all the time is cumbersome and error prone, so we |
| 184 | * have a macro which sets them all up and passes to the real function. */ | 189 | * have a macro which sets them all up and passes to the real function. |
| 190 | */ | ||
| 185 | #define convert(iov, type) \ | 191 | #define convert(iov, type) \ |
| 186 | ((type *)_convert((iov), sizeof(type), __alignof__(type), #type)) | 192 | ((type *)_convert((iov), sizeof(type), __alignof__(type), #type)) |
| 187 | 193 | ||
| @@ -198,8 +204,10 @@ static void *_convert(struct iovec *iov, size_t size, size_t align, | |||
| 198 | /* Wrapper for the last available index. Makes it easier to change. */ | 204 | /* Wrapper for the last available index. Makes it easier to change. */ |
| 199 | #define lg_last_avail(vq) ((vq)->last_avail_idx) | 205 | #define lg_last_avail(vq) ((vq)->last_avail_idx) |
| 200 | 206 | ||
| 201 | /* The virtio configuration space is defined to be little-endian. x86 is | 207 | /* |
| 202 | * little-endian too, but it's nice to be explicit so we have these helpers. */ | 208 | * The virtio configuration space is defined to be little-endian. x86 is |
| 209 | * little-endian too, but it's nice to be explicit so we have these helpers. | ||
| 210 | */ | ||
| 203 | #define cpu_to_le16(v16) (v16) | 211 | #define cpu_to_le16(v16) (v16) |
| 204 | #define cpu_to_le32(v32) (v32) | 212 | #define cpu_to_le32(v32) (v32) |
| 205 | #define cpu_to_le64(v64) (v64) | 213 | #define cpu_to_le64(v64) (v64) |
| @@ -241,11 +249,12 @@ static u8 *get_feature_bits(struct device *dev) | |||
| 241 | + dev->num_vq * sizeof(struct lguest_vqconfig); | 249 | + dev->num_vq * sizeof(struct lguest_vqconfig); |
| 242 | } | 250 | } |
| 243 | 251 | ||
| 244 | /*L:100 The Launcher code itself takes us out into userspace, that scary place | 252 | /*L:100 |
| 245 | * where pointers run wild and free! Unfortunately, like most userspace | 253 | * The Launcher code itself takes us out into userspace, that scary place where |
| 246 | * programs, it's quite boring (which is why everyone likes to hack on the | 254 | * pointers run wild and free! Unfortunately, like most userspace programs, |
| 247 | * kernel!). Perhaps if you make up an Lguest Drinking Game at this point, it | 255 | * it's quite boring (which is why everyone likes to hack on the kernel!). |
| 248 | * will get you through this section. Or, maybe not. | 256 | * Perhaps if you make up an Lguest Drinking Game at this point, it will get |
| 257 | * you through this section. Or, maybe not. | ||
| 249 | * | 258 | * |
| 250 | * The Launcher sets up a big chunk of memory to be the Guest's "physical" | 259 | * The Launcher sets up a big chunk of memory to be the Guest's "physical" |
| 251 | * memory and stores it in "guest_base". In other words, Guest physical == | 260 | * memory and stores it in "guest_base". In other words, Guest physical == |
| @@ -253,7 +262,8 @@ static u8 *get_feature_bits(struct device *dev) | |||
| 253 | * | 262 | * |
| 254 | * This can be tough to get your head around, but usually it just means that we | 263 | * This can be tough to get your head around, but usually it just means that we |
| 255 | * use these trivial conversion functions when the Guest gives us it's | 264 | * use these trivial conversion functions when the Guest gives us it's |
| 256 | * "physical" addresses: */ | 265 | * "physical" addresses: |
| 266 | */ | ||
| 257 | static void *from_guest_phys(unsigned long addr) | 267 | static void *from_guest_phys(unsigned long addr) |
| 258 | { | 268 | { |
| 259 | return guest_base + addr; | 269 | return guest_base + addr; |
| @@ -268,7 +278,8 @@ static unsigned long to_guest_phys(const void *addr) | |||
| 268 | * Loading the Kernel. | 278 | * Loading the Kernel. |
| 269 | * | 279 | * |
| 270 | * We start with couple of simple helper routines. open_or_die() avoids | 280 | * We start with couple of simple helper routines. open_or_die() avoids |
| 271 | * error-checking code cluttering the callers: */ | 281 | * error-checking code cluttering the callers: |
| 282 | */ | ||
| 272 | static int open_or_die(const char *name, int flags) | 283 | static int open_or_die(const char *name, int flags) |
| 273 | { | 284 | { |
| 274 | int fd = open(name, flags); | 285 | int fd = open(name, flags); |
| @@ -283,12 +294,19 @@ static void *map_zeroed_pages(unsigned int num) | |||
| 283 | int fd = open_or_die("/dev/zero", O_RDONLY); | 294 | int fd = open_or_die("/dev/zero", O_RDONLY); |
| 284 | void *addr; | 295 | void *addr; |
| 285 | 296 | ||
| 286 | /* We use a private mapping (ie. if we write to the page, it will be | 297 | /* |
| 287 | * copied). */ | 298 | * We use a private mapping (ie. if we write to the page, it will be |
| 299 | * copied). | ||
| 300 | */ | ||
| 288 | addr = mmap(NULL, getpagesize() * num, | 301 | addr = mmap(NULL, getpagesize() * num, |
| 289 | PROT_READ|PROT_WRITE|PROT_EXEC, MAP_PRIVATE, fd, 0); | 302 | PROT_READ|PROT_WRITE|PROT_EXEC, MAP_PRIVATE, fd, 0); |
| 290 | if (addr == MAP_FAILED) | 303 | if (addr == MAP_FAILED) |
| 291 | err(1, "Mmaping %u pages of /dev/zero", num); | 304 | err(1, "Mmaping %u pages of /dev/zero", num); |
| 305 | |||
| 306 | /* | ||
| 307 | * One neat mmap feature is that you can close the fd, and it | ||
| 308 | * stays mapped. | ||
| 309 | */ | ||
| 292 | close(fd); | 310 | close(fd); |
| 293 | 311 | ||
| 294 | return addr; | 312 | return addr; |
| @@ -305,20 +323,24 @@ static void *get_pages(unsigned int num) | |||
| 305 | return addr; | 323 | return addr; |
| 306 | } | 324 | } |
| 307 | 325 | ||
| 308 | /* This routine is used to load the kernel or initrd. It tries mmap, but if | 326 | /* |
| 327 | * This routine is used to load the kernel or initrd. It tries mmap, but if | ||
| 309 | * that fails (Plan 9's kernel file isn't nicely aligned on page boundaries), | 328 | * that fails (Plan 9's kernel file isn't nicely aligned on page boundaries), |
| 310 | * it falls back to reading the memory in. */ | 329 | * it falls back to reading the memory in. |
| 330 | */ | ||
| 311 | static void map_at(int fd, void *addr, unsigned long offset, unsigned long len) | 331 | static void map_at(int fd, void *addr, unsigned long offset, unsigned long len) |
| 312 | { | 332 | { |
| 313 | ssize_t r; | 333 | ssize_t r; |
| 314 | 334 | ||
| 315 | /* We map writable even though for some segments are marked read-only. | 335 | /* |
| 336 | * We map writable even though for some segments are marked read-only. | ||
| 316 | * The kernel really wants to be writable: it patches its own | 337 | * The kernel really wants to be writable: it patches its own |
| 317 | * instructions. | 338 | * instructions. |
| 318 | * | 339 | * |
| 319 | * MAP_PRIVATE means that the page won't be copied until a write is | 340 | * MAP_PRIVATE means that the page won't be copied until a write is |
| 320 | * done to it. This allows us to share untouched memory between | 341 | * done to it. This allows us to share untouched memory between |
| 321 | * Guests. */ | 342 | * Guests. |
| 343 | */ | ||
| 322 | if (mmap(addr, len, PROT_READ|PROT_WRITE|PROT_EXEC, | 344 | if (mmap(addr, len, PROT_READ|PROT_WRITE|PROT_EXEC, |
| 323 | MAP_FIXED|MAP_PRIVATE, fd, offset) != MAP_FAILED) | 345 | MAP_FIXED|MAP_PRIVATE, fd, offset) != MAP_FAILED) |
| 324 | return; | 346 | return; |
| @@ -329,7 +351,8 @@ static void map_at(int fd, void *addr, unsigned long offset, unsigned long len) | |||
| 329 | err(1, "Reading offset %lu len %lu gave %zi", offset, len, r); | 351 | err(1, "Reading offset %lu len %lu gave %zi", offset, len, r); |
| 330 | } | 352 | } |
| 331 | 353 | ||
| 332 | /* This routine takes an open vmlinux image, which is in ELF, and maps it into | 354 | /* |
| 355 | * This routine takes an open vmlinux image, which is in ELF, and maps it into | ||
| 333 | * the Guest memory. ELF = Embedded Linking Format, which is the format used | 356 | * the Guest memory. ELF = Embedded Linking Format, which is the format used |
| 334 | * by all modern binaries on Linux including the kernel. | 357 | * by all modern binaries on Linux including the kernel. |
| 335 | * | 358 | * |
| @@ -337,23 +360,28 @@ static void map_at(int fd, void *addr, unsigned long offset, unsigned long len) | |||
| 337 | * address. We use the physical address; the Guest will map itself to the | 360 | * address. We use the physical address; the Guest will map itself to the |
| 338 | * virtual address. | 361 | * virtual address. |
| 339 | * | 362 | * |
| 340 | * We return the starting address. */ | 363 | * We return the starting address. |
| 364 | */ | ||
| 341 | static unsigned long map_elf(int elf_fd, const Elf32_Ehdr *ehdr) | 365 | static unsigned long map_elf(int elf_fd, const Elf32_Ehdr *ehdr) |
| 342 | { | 366 | { |
| 343 | Elf32_Phdr phdr[ehdr->e_phnum]; | 367 | Elf32_Phdr phdr[ehdr->e_phnum]; |
| 344 | unsigned int i; | 368 | unsigned int i; |
| 345 | 369 | ||
| 346 | /* Sanity checks on the main ELF header: an x86 executable with a | 370 | /* |
| 347 | * reasonable number of correctly-sized program headers. */ | 371 | * Sanity checks on the main ELF header: an x86 executable with a |
| 372 | * reasonable number of correctly-sized program headers. | ||
| 373 | */ | ||
| 348 | if (ehdr->e_type != ET_EXEC | 374 | if (ehdr->e_type != ET_EXEC |
| 349 | || ehdr->e_machine != EM_386 | 375 | || ehdr->e_machine != EM_386 |
| 350 | || ehdr->e_phentsize != sizeof(Elf32_Phdr) | 376 | || ehdr->e_phentsize != sizeof(Elf32_Phdr) |
| 351 | || ehdr->e_phnum < 1 || ehdr->e_phnum > 65536U/sizeof(Elf32_Phdr)) | 377 | || ehdr->e_phnum < 1 || ehdr->e_phnum > 65536U/sizeof(Elf32_Phdr)) |
| 352 | errx(1, "Malformed elf header"); | 378 | errx(1, "Malformed elf header"); |
| 353 | 379 | ||
| 354 | /* An ELF executable contains an ELF header and a number of "program" | 380 | /* |
| 381 | * An ELF executable contains an ELF header and a number of "program" | ||
| 355 | * headers which indicate which parts ("segments") of the program to | 382 | * headers which indicate which parts ("segments") of the program to |
| 356 | * load where. */ | 383 | * load where. |
| 384 | */ | ||
| 357 | 385 | ||
| 358 | /* We read in all the program headers at once: */ | 386 | /* We read in all the program headers at once: */ |
| 359 | if (lseek(elf_fd, ehdr->e_phoff, SEEK_SET) < 0) | 387 | if (lseek(elf_fd, ehdr->e_phoff, SEEK_SET) < 0) |
| @@ -361,8 +389,10 @@ static unsigned long map_elf(int elf_fd, const Elf32_Ehdr *ehdr) | |||
| 361 | if (read(elf_fd, phdr, sizeof(phdr)) != sizeof(phdr)) | 389 | if (read(elf_fd, phdr, sizeof(phdr)) != sizeof(phdr)) |
| 362 | err(1, "Reading program headers"); | 390 | err(1, "Reading program headers"); |
| 363 | 391 | ||
| 364 | /* Try all the headers: there are usually only three. A read-only one, | 392 | /* |
| 365 | * a read-write one, and a "note" section which we don't load. */ | 393 | * Try all the headers: there are usually only three. A read-only one, |
| 394 | * a read-write one, and a "note" section which we don't load. | ||
| 395 | */ | ||
| 366 | for (i = 0; i < ehdr->e_phnum; i++) { | 396 | for (i = 0; i < ehdr->e_phnum; i++) { |
| 367 | /* If this isn't a loadable segment, we ignore it */ | 397 | /* If this isn't a loadable segment, we ignore it */ |
| 368 | if (phdr[i].p_type != PT_LOAD) | 398 | if (phdr[i].p_type != PT_LOAD) |
| @@ -380,13 +410,15 @@ static unsigned long map_elf(int elf_fd, const Elf32_Ehdr *ehdr) | |||
| 380 | return ehdr->e_entry; | 410 | return ehdr->e_entry; |
| 381 | } | 411 | } |
| 382 | 412 | ||
| 383 | /*L:150 A bzImage, unlike an ELF file, is not meant to be loaded. You're | 413 | /*L:150 |
| 384 | * supposed to jump into it and it will unpack itself. We used to have to | 414 | * A bzImage, unlike an ELF file, is not meant to be loaded. You're supposed |
| 385 | * perform some hairy magic because the unpacking code scared me. | 415 | * to jump into it and it will unpack itself. We used to have to perform some |
| 416 | * hairy magic because the unpacking code scared me. | ||
| 386 | * | 417 | * |
| 387 | * Fortunately, Jeremy Fitzhardinge convinced me it wasn't that hard and wrote | 418 | * Fortunately, Jeremy Fitzhardinge convinced me it wasn't that hard and wrote |
| 388 | * a small patch to jump over the tricky bits in the Guest, so now we just read | 419 | * a small patch to jump over the tricky bits in the Guest, so now we just read |
| 389 | * the funky header so we know where in the file to load, and away we go! */ | 420 | * the funky header so we know where in the file to load, and away we go! |
| 421 | */ | ||
| 390 | static unsigned long load_bzimage(int fd) | 422 | static unsigned long load_bzimage(int fd) |
| 391 | { | 423 | { |
| 392 | struct boot_params boot; | 424 | struct boot_params boot; |
| @@ -394,8 +426,10 @@ static unsigned long load_bzimage(int fd) | |||
| 394 | /* Modern bzImages get loaded at 1M. */ | 426 | /* Modern bzImages get loaded at 1M. */ |
| 395 | void *p = from_guest_phys(0x100000); | 427 | void *p = from_guest_phys(0x100000); |
| 396 | 428 | ||
| 397 | /* Go back to the start of the file and read the header. It should be | 429 | /* |
| 398 | * a Linux boot header (see Documentation/x86/i386/boot.txt) */ | 430 | * Go back to the start of the file and read the header. It should be |
| 431 | * a Linux boot header (see Documentation/x86/i386/boot.txt) | ||
| 432 | */ | ||
| 399 | lseek(fd, 0, SEEK_SET); | 433 | lseek(fd, 0, SEEK_SET); |
| 400 | read(fd, &boot, sizeof(boot)); | 434 | read(fd, &boot, sizeof(boot)); |
| 401 | 435 | ||
| @@ -414,9 +448,11 @@ static unsigned long load_bzimage(int fd) | |||
| 414 | return boot.hdr.code32_start; | 448 | return boot.hdr.code32_start; |
| 415 | } | 449 | } |
| 416 | 450 | ||
| 417 | /*L:140 Loading the kernel is easy when it's a "vmlinux", but most kernels | 451 | /*L:140 |
| 452 | * Loading the kernel is easy when it's a "vmlinux", but most kernels | ||
| 418 | * come wrapped up in the self-decompressing "bzImage" format. With a little | 453 | * come wrapped up in the self-decompressing "bzImage" format. With a little |
| 419 | * work, we can load those, too. */ | 454 | * work, we can load those, too. |
| 455 | */ | ||
| 420 | static unsigned long load_kernel(int fd) | 456 | static unsigned long load_kernel(int fd) |
| 421 | { | 457 | { |
| 422 | Elf32_Ehdr hdr; | 458 | Elf32_Ehdr hdr; |
| @@ -433,24 +469,28 @@ static unsigned long load_kernel(int fd) | |||
| 433 | return load_bzimage(fd); | 469 | return load_bzimage(fd); |
| 434 | } | 470 | } |
| 435 | 471 | ||
| 436 | /* This is a trivial little helper to align pages. Andi Kleen hated it because | 472 | /* |
| 473 | * This is a trivial little helper to align pages. Andi Kleen hated it because | ||
| 437 | * it calls getpagesize() twice: "it's dumb code." | 474 | * it calls getpagesize() twice: "it's dumb code." |
| 438 | * | 475 | * |
| 439 | * Kernel guys get really het up about optimization, even when it's not | 476 | * Kernel guys get really het up about optimization, even when it's not |
| 440 | * necessary. I leave this code as a reaction against that. */ | 477 | * necessary. I leave this code as a reaction against that. |
| 478 | */ | ||
| 441 | static inline unsigned long page_align(unsigned long addr) | 479 | static inline unsigned long page_align(unsigned long addr) |
| 442 | { | 480 | { |
| 443 | /* Add upwards and truncate downwards. */ | 481 | /* Add upwards and truncate downwards. */ |
| 444 | return ((addr + getpagesize()-1) & ~(getpagesize()-1)); | 482 | return ((addr + getpagesize()-1) & ~(getpagesize()-1)); |
| 445 | } | 483 | } |
| 446 | 484 | ||
| 447 | /*L:180 An "initial ram disk" is a disk image loaded into memory along with | 485 | /*L:180 |
| 448 | * the kernel which the kernel can use to boot from without needing any | 486 | * An "initial ram disk" is a disk image loaded into memory along with the |
| 449 | * drivers. Most distributions now use this as standard: the initrd contains | 487 | * kernel which the kernel can use to boot from without needing any drivers. |
| 450 | * the code to load the appropriate driver modules for the current machine. | 488 | * Most distributions now use this as standard: the initrd contains the code to |
| 489 | * load the appropriate driver modules for the current machine. | ||
| 451 | * | 490 | * |
| 452 | * Importantly, James Morris works for RedHat, and Fedora uses initrds for its | 491 | * Importantly, James Morris works for RedHat, and Fedora uses initrds for its |
| 453 | * kernels. He sent me this (and tells me when I break it). */ | 492 | * kernels. He sent me this (and tells me when I break it). |
| 493 | */ | ||
| 454 | static unsigned long load_initrd(const char *name, unsigned long mem) | 494 | static unsigned long load_initrd(const char *name, unsigned long mem) |
| 455 | { | 495 | { |
| 456 | int ifd; | 496 | int ifd; |
| @@ -462,12 +502,16 @@ static unsigned long load_initrd(const char *name, unsigned long mem) | |||
| 462 | if (fstat(ifd, &st) < 0) | 502 | if (fstat(ifd, &st) < 0) |
| 463 | err(1, "fstat() on initrd '%s'", name); | 503 | err(1, "fstat() on initrd '%s'", name); |
| 464 | 504 | ||
| 465 | /* We map the initrd at the top of memory, but mmap wants it to be | 505 | /* |
| 466 | * page-aligned, so we round the size up for that. */ | 506 | * We map the initrd at the top of memory, but mmap wants it to be |
| 507 | * page-aligned, so we round the size up for that. | ||
| 508 | */ | ||
| 467 | len = page_align(st.st_size); | 509 | len = page_align(st.st_size); |
| 468 | map_at(ifd, from_guest_phys(mem - len), 0, st.st_size); | 510 | map_at(ifd, from_guest_phys(mem - len), 0, st.st_size); |
| 469 | /* Once a file is mapped, you can close the file descriptor. It's a | 511 | /* |
| 470 | * little odd, but quite useful. */ | 512 | * Once a file is mapped, you can close the file descriptor. It's a |
| 513 | * little odd, but quite useful. | ||
| 514 | */ | ||
| 471 | close(ifd); | 515 | close(ifd); |
| 472 | verbose("mapped initrd %s size=%lu @ %p\n", name, len, (void*)mem-len); | 516 | verbose("mapped initrd %s size=%lu @ %p\n", name, len, (void*)mem-len); |
| 473 | 517 | ||
| @@ -476,8 +520,10 @@ static unsigned long load_initrd(const char *name, unsigned long mem) | |||
| 476 | } | 520 | } |
| 477 | /*:*/ | 521 | /*:*/ |
| 478 | 522 | ||
| 479 | /* Simple routine to roll all the commandline arguments together with spaces | 523 | /* |
| 480 | * between them. */ | 524 | * Simple routine to roll all the commandline arguments together with spaces |
| 525 | * between them. | ||
| 526 | */ | ||
| 481 | static void concat(char *dst, char *args[]) | 527 | static void concat(char *dst, char *args[]) |
| 482 | { | 528 | { |
| 483 | unsigned int i, len = 0; | 529 | unsigned int i, len = 0; |
| @@ -494,10 +540,12 @@ static void concat(char *dst, char *args[]) | |||
| 494 | dst[len] = '\0'; | 540 | dst[len] = '\0'; |
| 495 | } | 541 | } |
| 496 | 542 | ||
| 497 | /*L:185 This is where we actually tell the kernel to initialize the Guest. We | 543 | /*L:185 |
| 544 | * This is where we actually tell the kernel to initialize the Guest. We | ||
| 498 | * saw the arguments it expects when we looked at initialize() in lguest_user.c: | 545 | * saw the arguments it expects when we looked at initialize() in lguest_user.c: |
| 499 | * the base of Guest "physical" memory, the top physical page to allow and the | 546 | * the base of Guest "physical" memory, the top physical page to allow and the |
| 500 | * entry point for the Guest. */ | 547 | * entry point for the Guest. |
| 548 | */ | ||
| 501 | static void tell_kernel(unsigned long start) | 549 | static void tell_kernel(unsigned long start) |
| 502 | { | 550 | { |
| 503 | unsigned long args[] = { LHREQ_INITIALIZE, | 551 | unsigned long args[] = { LHREQ_INITIALIZE, |
| @@ -511,7 +559,7 @@ static void tell_kernel(unsigned long start) | |||
| 511 | } | 559 | } |
| 512 | /*:*/ | 560 | /*:*/ |
| 513 | 561 | ||
| 514 | /* | 562 | /*L:200 |
| 515 | * Device Handling. | 563 | * Device Handling. |
| 516 | * | 564 | * |
| 517 | * When the Guest gives us a buffer, it sends an array of addresses and sizes. | 565 | * When the Guest gives us a buffer, it sends an array of addresses and sizes. |
| @@ -522,20 +570,26 @@ static void tell_kernel(unsigned long start) | |||
| 522 | static void *_check_pointer(unsigned long addr, unsigned int size, | 570 | static void *_check_pointer(unsigned long addr, unsigned int size, |
| 523 | unsigned int line) | 571 | unsigned int line) |
| 524 | { | 572 | { |
| 525 | /* We have to separately check addr and addr+size, because size could | 573 | /* |
| 526 | * be huge and addr + size might wrap around. */ | 574 | * We have to separately check addr and addr+size, because size could |
| 575 | * be huge and addr + size might wrap around. | ||
| 576 | */ | ||
| 527 | if (addr >= guest_limit || addr + size >= guest_limit) | 577 | if (addr >= guest_limit || addr + size >= guest_limit) |
| 528 | errx(1, "%s:%i: Invalid address %#lx", __FILE__, line, addr); | 578 | errx(1, "%s:%i: Invalid address %#lx", __FILE__, line, addr); |
| 529 | /* We return a pointer for the caller's convenience, now we know it's | 579 | /* |
| 530 | * safe to use. */ | 580 | * We return a pointer for the caller's convenience, now we know it's |
| 581 | * safe to use. | ||
| 582 | */ | ||
| 531 | return from_guest_phys(addr); | 583 | return from_guest_phys(addr); |
| 532 | } | 584 | } |
| 533 | /* A macro which transparently hands the line number to the real function. */ | 585 | /* A macro which transparently hands the line number to the real function. */ |
| 534 | #define check_pointer(addr,size) _check_pointer(addr, size, __LINE__) | 586 | #define check_pointer(addr,size) _check_pointer(addr, size, __LINE__) |
| 535 | 587 | ||
| 536 | /* Each buffer in the virtqueues is actually a chain of descriptors. This | 588 | /* |
| 589 | * Each buffer in the virtqueues is actually a chain of descriptors. This | ||
| 537 | * function returns the next descriptor in the chain, or vq->vring.num if we're | 590 | * function returns the next descriptor in the chain, or vq->vring.num if we're |
| 538 | * at the end. */ | 591 | * at the end. |
| 592 | */ | ||
| 539 | static unsigned next_desc(struct vring_desc *desc, | 593 | static unsigned next_desc(struct vring_desc *desc, |
| 540 | unsigned int i, unsigned int max) | 594 | unsigned int i, unsigned int max) |
| 541 | { | 595 | { |
| @@ -556,7 +610,10 @@ static unsigned next_desc(struct vring_desc *desc, | |||
| 556 | return next; | 610 | return next; |
| 557 | } | 611 | } |
| 558 | 612 | ||
| 559 | /* This actually sends the interrupt for this virtqueue */ | 613 | /* |
| 614 | * This actually sends the interrupt for this virtqueue, if we've used a | ||
| 615 | * buffer. | ||
| 616 | */ | ||
| 560 | static void trigger_irq(struct virtqueue *vq) | 617 | static void trigger_irq(struct virtqueue *vq) |
| 561 | { | 618 | { |
| 562 | unsigned long buf[] = { LHREQ_IRQ, vq->config.irq }; | 619 | unsigned long buf[] = { LHREQ_IRQ, vq->config.irq }; |
| @@ -576,12 +633,14 @@ static void trigger_irq(struct virtqueue *vq) | |||
| 576 | err(1, "Triggering irq %i", vq->config.irq); | 633 | err(1, "Triggering irq %i", vq->config.irq); |
| 577 | } | 634 | } |
| 578 | 635 | ||
| 579 | /* This looks in the virtqueue and for the first available buffer, and converts | 636 | /* |
| 637 | * This looks in the virtqueue for the first available buffer, and converts | ||
| 580 | * it to an iovec for convenient access. Since descriptors consist of some | 638 | * it to an iovec for convenient access. Since descriptors consist of some |
| 581 | * number of output then some number of input descriptors, it's actually two | 639 | * number of output then some number of input descriptors, it's actually two |
| 582 | * iovecs, but we pack them into one and note how many of each there were. | 640 | * iovecs, but we pack them into one and note how many of each there were. |
| 583 | * | 641 | * |
| 584 | * This function returns the descriptor number found. */ | 642 | * This function waits if necessary, and returns the descriptor number found. |
| 643 | */ | ||
| 585 | static unsigned wait_for_vq_desc(struct virtqueue *vq, | 644 | static unsigned wait_for_vq_desc(struct virtqueue *vq, |
| 586 | struct iovec iov[], | 645 | struct iovec iov[], |
| 587 | unsigned int *out_num, unsigned int *in_num) | 646 | unsigned int *out_num, unsigned int *in_num) |
| @@ -590,17 +649,23 @@ static unsigned wait_for_vq_desc(struct virtqueue *vq, | |||
| 590 | struct vring_desc *desc; | 649 | struct vring_desc *desc; |
| 591 | u16 last_avail = lg_last_avail(vq); | 650 | u16 last_avail = lg_last_avail(vq); |
| 592 | 651 | ||
| 652 | /* There's nothing available? */ | ||
| 593 | while (last_avail == vq->vring.avail->idx) { | 653 | while (last_avail == vq->vring.avail->idx) { |
| 594 | u64 event; | 654 | u64 event; |
| 595 | 655 | ||
| 596 | /* OK, tell Guest about progress up to now. */ | 656 | /* |
| 657 | * Since we're about to sleep, now is a good time to tell the | ||
| 658 | * Guest about what we've used up to now. | ||
| 659 | */ | ||
| 597 | trigger_irq(vq); | 660 | trigger_irq(vq); |
| 598 | 661 | ||
| 599 | /* OK, now we need to know about added descriptors. */ | 662 | /* OK, now we need to know about added descriptors. */ |
| 600 | vq->vring.used->flags &= ~VRING_USED_F_NO_NOTIFY; | 663 | vq->vring.used->flags &= ~VRING_USED_F_NO_NOTIFY; |
| 601 | 664 | ||
| 602 | /* They could have slipped one in as we were doing that: make | 665 | /* |
| 603 | * sure it's written, then check again. */ | 666 | * They could have slipped one in as we were doing that: make |
| 667 | * sure it's written, then check again. | ||
| 668 | */ | ||
| 604 | mb(); | 669 | mb(); |
| 605 | if (last_avail != vq->vring.avail->idx) { | 670 | if (last_avail != vq->vring.avail->idx) { |
| 606 | vq->vring.used->flags |= VRING_USED_F_NO_NOTIFY; | 671 | vq->vring.used->flags |= VRING_USED_F_NO_NOTIFY; |
| @@ -620,8 +685,10 @@ static unsigned wait_for_vq_desc(struct virtqueue *vq, | |||
| 620 | errx(1, "Guest moved used index from %u to %u", | 685 | errx(1, "Guest moved used index from %u to %u", |
| 621 | last_avail, vq->vring.avail->idx); | 686 | last_avail, vq->vring.avail->idx); |
| 622 | 687 | ||
| 623 | /* Grab the next descriptor number they're advertising, and increment | 688 | /* |
| 624 | * the index we've seen. */ | 689 | * Grab the next descriptor number they're advertising, and increment |
| 690 | * the index we've seen. | ||
| 691 | */ | ||
| 625 | head = vq->vring.avail->ring[last_avail % vq->vring.num]; | 692 | head = vq->vring.avail->ring[last_avail % vq->vring.num]; |
| 626 | lg_last_avail(vq)++; | 693 | lg_last_avail(vq)++; |
| 627 | 694 | ||
| @@ -636,8 +703,10 @@ static unsigned wait_for_vq_desc(struct virtqueue *vq, | |||
| 636 | desc = vq->vring.desc; | 703 | desc = vq->vring.desc; |
| 637 | i = head; | 704 | i = head; |
| 638 | 705 | ||
| 639 | /* If this is an indirect entry, then this buffer contains a descriptor | 706 | /* |
| 640 | * table which we handle as if it's any normal descriptor chain. */ | 707 | * If this is an indirect entry, then this buffer contains a descriptor |
| 708 | * table which we handle as if it's any normal descriptor chain. | ||
| 709 | */ | ||
| 641 | if (desc[i].flags & VRING_DESC_F_INDIRECT) { | 710 | if (desc[i].flags & VRING_DESC_F_INDIRECT) { |
| 642 | if (desc[i].len % sizeof(struct vring_desc)) | 711 | if (desc[i].len % sizeof(struct vring_desc)) |
| 643 | errx(1, "Invalid size for indirect buffer table"); | 712 | errx(1, "Invalid size for indirect buffer table"); |
| @@ -656,8 +725,10 @@ static unsigned wait_for_vq_desc(struct virtqueue *vq, | |||
| 656 | if (desc[i].flags & VRING_DESC_F_WRITE) | 725 | if (desc[i].flags & VRING_DESC_F_WRITE) |
| 657 | (*in_num)++; | 726 | (*in_num)++; |
| 658 | else { | 727 | else { |
| 659 | /* If it's an output descriptor, they're all supposed | 728 | /* |
| 660 | * to come before any input descriptors. */ | 729 | * If it's an output descriptor, they're all supposed |
| 730 | * to come before any input descriptors. | ||
| 731 | */ | ||
| 661 | if (*in_num) | 732 | if (*in_num) |
| 662 | errx(1, "Descriptor has out after in"); | 733 | errx(1, "Descriptor has out after in"); |
| 663 | (*out_num)++; | 734 | (*out_num)++; |
| @@ -671,14 +742,19 @@ static unsigned wait_for_vq_desc(struct virtqueue *vq, | |||
| 671 | return head; | 742 | return head; |
| 672 | } | 743 | } |
| 673 | 744 | ||
| 674 | /* After we've used one of their buffers, we tell them about it. We'll then | 745 | /* |
| 675 | * want to send them an interrupt, using trigger_irq(). */ | 746 | * After we've used one of their buffers, we tell the Guest about it. Sometime |
| 747 | * later we'll want to send them an interrupt using trigger_irq(); note that | ||
| 748 | * wait_for_vq_desc() does that for us if it has to wait. | ||
| 749 | */ | ||
| 676 | static void add_used(struct virtqueue *vq, unsigned int head, int len) | 750 | static void add_used(struct virtqueue *vq, unsigned int head, int len) |
| 677 | { | 751 | { |
| 678 | struct vring_used_elem *used; | 752 | struct vring_used_elem *used; |
| 679 | 753 | ||
| 680 | /* The virtqueue contains a ring of used buffers. Get a pointer to the | 754 | /* |
| 681 | * next entry in that used ring. */ | 755 | * The virtqueue contains a ring of used buffers. Get a pointer to the |
| 756 | * next entry in that used ring. | ||
| 757 | */ | ||
| 682 | used = &vq->vring.used->ring[vq->vring.used->idx % vq->vring.num]; | 758 | used = &vq->vring.used->ring[vq->vring.used->idx % vq->vring.num]; |
| 683 | used->id = head; | 759 | used->id = head; |
| 684 | used->len = len; | 760 | used->len = len; |
| @@ -698,9 +774,9 @@ static void add_used_and_trigger(struct virtqueue *vq, unsigned head, int len) | |||
| 698 | /* | 774 | /* |
| 699 | * The Console | 775 | * The Console |
| 700 | * | 776 | * |
| 701 | * We associate some data with the console for our exit hack. */ | 777 | * We associate some data with the console for our exit hack. |
| 702 | struct console_abort | 778 | */ |
| 703 | { | 779 | struct console_abort { |
| 704 | /* How many times have they hit ^C? */ | 780 | /* How many times have they hit ^C? */ |
| 705 | int count; | 781 | int count; |
| 706 | /* When did they start? */ | 782 | /* When did they start? */ |
| @@ -715,30 +791,35 @@ static void console_input(struct virtqueue *vq) | |||
| 715 | struct console_abort *abort = vq->dev->priv; | 791 | struct console_abort *abort = vq->dev->priv; |
| 716 | struct iovec iov[vq->vring.num]; | 792 | struct iovec iov[vq->vring.num]; |
| 717 | 793 | ||
| 718 | /* Make sure there's a descriptor waiting. */ | 794 | /* Make sure there's a descriptor available. */ |
| 719 | head = wait_for_vq_desc(vq, iov, &out_num, &in_num); | 795 | head = wait_for_vq_desc(vq, iov, &out_num, &in_num); |
| 720 | if (out_num) | 796 | if (out_num) |
| 721 | errx(1, "Output buffers in console in queue?"); | 797 | errx(1, "Output buffers in console in queue?"); |
| 722 | 798 | ||
| 723 | /* Read it in. */ | 799 | /* Read into it. This is where we usually wait. */ |
| 724 | len = readv(STDIN_FILENO, iov, in_num); | 800 | len = readv(STDIN_FILENO, iov, in_num); |
| 725 | if (len <= 0) { | 801 | if (len <= 0) { |
| 726 | /* Ran out of input? */ | 802 | /* Ran out of input? */ |
| 727 | warnx("Failed to get console input, ignoring console."); | 803 | warnx("Failed to get console input, ignoring console."); |
| 728 | /* For simplicity, dying threads kill the whole Launcher. So | 804 | /* |
| 729 | * just nap here. */ | 805 | * For simplicity, dying threads kill the whole Launcher. So |
| 806 | * just nap here. | ||
| 807 | */ | ||
| 730 | for (;;) | 808 | for (;;) |
| 731 | pause(); | 809 | pause(); |
| 732 | } | 810 | } |
| 733 | 811 | ||
| 812 | /* Tell the Guest we used a buffer. */ | ||
| 734 | add_used_and_trigger(vq, head, len); | 813 | add_used_and_trigger(vq, head, len); |
| 735 | 814 | ||
| 736 | /* Three ^C within one second? Exit. | 815 | /* |
| 816 | * Three ^C within one second? Exit. | ||
| 737 | * | 817 | * |
| 738 | * This is such a hack, but works surprisingly well. Each ^C has to | 818 | * This is such a hack, but works surprisingly well. Each ^C has to |
| 739 | * be in a buffer by itself, so they can't be too fast. But we check | 819 | * be in a buffer by itself, so they can't be too fast. But we check |
| 740 | * that we get three within about a second, so they can't be too | 820 | * that we get three within about a second, so they can't be too |
| 741 | * slow. */ | 821 | * slow. |
| 822 | */ | ||
| 742 | if (len != 1 || ((char *)iov[0].iov_base)[0] != 3) { | 823 | if (len != 1 || ((char *)iov[0].iov_base)[0] != 3) { |
| 743 | abort->count = 0; | 824 | abort->count = 0; |
| 744 | return; | 825 | return; |
| @@ -763,15 +844,23 @@ static void console_output(struct virtqueue *vq) | |||
| 763 | unsigned int head, out, in; | 844 | unsigned int head, out, in; |
| 764 | struct iovec iov[vq->vring.num]; | 845 | struct iovec iov[vq->vring.num]; |
| 765 | 846 | ||
| 847 | /* We usually wait in here, for the Guest to give us something. */ | ||
| 766 | head = wait_for_vq_desc(vq, iov, &out, &in); | 848 | head = wait_for_vq_desc(vq, iov, &out, &in); |
| 767 | if (in) | 849 | if (in) |
| 768 | errx(1, "Input buffers in console output queue?"); | 850 | errx(1, "Input buffers in console output queue?"); |
| 851 | |||
| 852 | /* writev can return a partial write, so we loop here. */ | ||
| 769 | while (!iov_empty(iov, out)) { | 853 | while (!iov_empty(iov, out)) { |
| 770 | int len = writev(STDOUT_FILENO, iov, out); | 854 | int len = writev(STDOUT_FILENO, iov, out); |
| 771 | if (len <= 0) | 855 | if (len <= 0) |
| 772 | err(1, "Write to stdout gave %i", len); | 856 | err(1, "Write to stdout gave %i", len); |
| 773 | iov_consume(iov, out, len); | 857 | iov_consume(iov, out, len); |
| 774 | } | 858 | } |
| 859 | |||
| 860 | /* | ||
| 861 | * We're finished with that buffer: if we're going to sleep, | ||
| 862 | * wait_for_vq_desc() will prod the Guest with an interrupt. | ||
| 863 | */ | ||
| 775 | add_used(vq, head, 0); | 864 | add_used(vq, head, 0); |
| 776 | } | 865 | } |
| 777 | 866 | ||
| @@ -791,15 +880,30 @@ static void net_output(struct virtqueue *vq) | |||
| 791 | unsigned int head, out, in; | 880 | unsigned int head, out, in; |
| 792 | struct iovec iov[vq->vring.num]; | 881 | struct iovec iov[vq->vring.num]; |
| 793 | 882 | ||
| 883 | /* We usually wait in here for the Guest to give us a packet. */ | ||
| 794 | head = wait_for_vq_desc(vq, iov, &out, &in); | 884 | head = wait_for_vq_desc(vq, iov, &out, &in); |
| 795 | if (in) | 885 | if (in) |
| 796 | errx(1, "Input buffers in net output queue?"); | 886 | errx(1, "Input buffers in net output queue?"); |
| 887 | /* | ||
| 888 | * Send the whole thing through to /dev/net/tun. It expects the exact | ||
| 889 | * same format: what a coincidence! | ||
| 890 | */ | ||
| 797 | if (writev(net_info->tunfd, iov, out) < 0) | 891 | if (writev(net_info->tunfd, iov, out) < 0) |
| 798 | errx(1, "Write to tun failed?"); | 892 | errx(1, "Write to tun failed?"); |
| 893 | |||
| 894 | /* | ||
| 895 | * Done with that one; wait_for_vq_desc() will send the interrupt if | ||
| 896 | * all packets are processed. | ||
| 897 | */ | ||
| 799 | add_used(vq, head, 0); | 898 | add_used(vq, head, 0); |
| 800 | } | 899 | } |
| 801 | 900 | ||
| 802 | /* Will reading from this file descriptor block? */ | 901 | /* |
| 902 | * Handling network input is a bit trickier, because I've tried to optimize it. | ||
| 903 | * | ||
| 904 | * First we have a helper routine which tells is if from this file descriptor | ||
| 905 | * (ie. the /dev/net/tun device) will block: | ||
| 906 | */ | ||
| 803 | static bool will_block(int fd) | 907 | static bool will_block(int fd) |
| 804 | { | 908 | { |
| 805 | fd_set fdset; | 909 | fd_set fdset; |
| @@ -809,8 +913,11 @@ static bool will_block(int fd) | |||
| 809 | return select(fd+1, &fdset, NULL, NULL, &zero) != 1; | 913 | return select(fd+1, &fdset, NULL, NULL, &zero) != 1; |
| 810 | } | 914 | } |
| 811 | 915 | ||
| 812 | /* This is where we handle packets coming in from the tun device to our | 916 | /* |
| 813 | * Guest. */ | 917 | * This handles packets coming in from the tun device to our Guest. Like all |
| 918 | * service routines, it gets called again as soon as it returns, so you don't | ||
| 919 | * see a while(1) loop here. | ||
| 920 | */ | ||
| 814 | static void net_input(struct virtqueue *vq) | 921 | static void net_input(struct virtqueue *vq) |
| 815 | { | 922 | { |
| 816 | int len; | 923 | int len; |
| @@ -818,21 +925,38 @@ static void net_input(struct virtqueue *vq) | |||
| 818 | struct iovec iov[vq->vring.num]; | 925 | struct iovec iov[vq->vring.num]; |
| 819 | struct net_info *net_info = vq->dev->priv; | 926 | struct net_info *net_info = vq->dev->priv; |
| 820 | 927 | ||
| 928 | /* | ||
| 929 | * Get a descriptor to write an incoming packet into. This will also | ||
| 930 | * send an interrupt if they're out of descriptors. | ||
| 931 | */ | ||
| 821 | head = wait_for_vq_desc(vq, iov, &out, &in); | 932 | head = wait_for_vq_desc(vq, iov, &out, &in); |
| 822 | if (out) | 933 | if (out) |
| 823 | errx(1, "Output buffers in net input queue?"); | 934 | errx(1, "Output buffers in net input queue?"); |
| 824 | 935 | ||
| 825 | /* Deliver interrupt now, since we're about to sleep. */ | 936 | /* |
| 937 | * If it looks like we'll block reading from the tun device, send them | ||
| 938 | * an interrupt. | ||
| 939 | */ | ||
| 826 | if (vq->pending_used && will_block(net_info->tunfd)) | 940 | if (vq->pending_used && will_block(net_info->tunfd)) |
| 827 | trigger_irq(vq); | 941 | trigger_irq(vq); |
| 828 | 942 | ||
| 943 | /* | ||
| 944 | * Read in the packet. This is where we normally wait (when there's no | ||
| 945 | * incoming network traffic). | ||
| 946 | */ | ||
| 829 | len = readv(net_info->tunfd, iov, in); | 947 | len = readv(net_info->tunfd, iov, in); |
| 830 | if (len <= 0) | 948 | if (len <= 0) |
| 831 | err(1, "Failed to read from tun."); | 949 | err(1, "Failed to read from tun."); |
| 950 | |||
| 951 | /* | ||
| 952 | * Mark that packet buffer as used, but don't interrupt here. We want | ||
| 953 | * to wait until we've done as much work as we can. | ||
| 954 | */ | ||
| 832 | add_used(vq, head, len); | 955 | add_used(vq, head, len); |
| 833 | } | 956 | } |
| 957 | /*:*/ | ||
| 834 | 958 | ||
| 835 | /* This is the helper to create threads. */ | 959 | /* This is the helper to create threads: run the service routine in a loop. */ |
| 836 | static int do_thread(void *_vq) | 960 | static int do_thread(void *_vq) |
| 837 | { | 961 | { |
| 838 | struct virtqueue *vq = _vq; | 962 | struct virtqueue *vq = _vq; |
| @@ -842,8 +966,10 @@ static int do_thread(void *_vq) | |||
| 842 | return 0; | 966 | return 0; |
| 843 | } | 967 | } |
| 844 | 968 | ||
| 845 | /* When a child dies, we kill our entire process group with SIGTERM. This | 969 | /* |
| 846 | * also has the side effect that the shell restores the console for us! */ | 970 | * When a child dies, we kill our entire process group with SIGTERM. This |
| 971 | * also has the side effect that the shell restores the console for us! | ||
| 972 | */ | ||
| 847 | static void kill_launcher(int signal) | 973 | static void kill_launcher(int signal) |
| 848 | { | 974 | { |
| 849 | kill(0, SIGTERM); | 975 | kill(0, SIGTERM); |
| @@ -878,11 +1004,15 @@ static void reset_device(struct device *dev) | |||
| 878 | signal(SIGCHLD, (void *)kill_launcher); | 1004 | signal(SIGCHLD, (void *)kill_launcher); |
| 879 | } | 1005 | } |
| 880 | 1006 | ||
| 1007 | /*L:216 | ||
| 1008 | * This actually creates the thread which services the virtqueue for a device. | ||
| 1009 | */ | ||
| 881 | static void create_thread(struct virtqueue *vq) | 1010 | static void create_thread(struct virtqueue *vq) |
| 882 | { | 1011 | { |
| 883 | /* Create stack for thread and run it. Since stack grows | 1012 | /* |
| 884 | * upwards, we point the stack pointer to the end of this | 1013 | * Create stack for thread. Since the stack grows upwards, we point |
| 885 | * region. */ | 1014 | * the stack pointer to the end of this region. |
| 1015 | */ | ||
| 886 | char *stack = malloc(32768); | 1016 | char *stack = malloc(32768); |
| 887 | unsigned long args[] = { LHREQ_EVENTFD, | 1017 | unsigned long args[] = { LHREQ_EVENTFD, |
| 888 | vq->config.pfn*getpagesize(), 0 }; | 1018 | vq->config.pfn*getpagesize(), 0 }; |
| @@ -893,17 +1023,22 @@ static void create_thread(struct virtqueue *vq) | |||
| 893 | err(1, "Creating eventfd"); | 1023 | err(1, "Creating eventfd"); |
| 894 | args[2] = vq->eventfd; | 1024 | args[2] = vq->eventfd; |
| 895 | 1025 | ||
| 896 | /* Attach an eventfd to this virtqueue: it will go off | 1026 | /* |
| 897 | * when the Guest does an LHCALL_NOTIFY for this vq. */ | 1027 | * Attach an eventfd to this virtqueue: it will go off when the Guest |
| 1028 | * does an LHCALL_NOTIFY for this vq. | ||
| 1029 | */ | ||
| 898 | if (write(lguest_fd, &args, sizeof(args)) != 0) | 1030 | if (write(lguest_fd, &args, sizeof(args)) != 0) |
| 899 | err(1, "Attaching eventfd"); | 1031 | err(1, "Attaching eventfd"); |
| 900 | 1032 | ||
| 901 | /* CLONE_VM: because it has to access the Guest memory, and | 1033 | /* |
| 902 | * SIGCHLD so we get a signal if it dies. */ | 1034 | * CLONE_VM: because it has to access the Guest memory, and SIGCHLD so |
| 1035 | * we get a signal if it dies. | ||
| 1036 | */ | ||
| 903 | vq->thread = clone(do_thread, stack + 32768, CLONE_VM | SIGCHLD, vq); | 1037 | vq->thread = clone(do_thread, stack + 32768, CLONE_VM | SIGCHLD, vq); |
| 904 | if (vq->thread == (pid_t)-1) | 1038 | if (vq->thread == (pid_t)-1) |
| 905 | err(1, "Creating clone"); | 1039 | err(1, "Creating clone"); |
| 906 | /* We close our local copy, now the child has it. */ | 1040 | |
| 1041 | /* We close our local copy now the child has it. */ | ||
| 907 | close(vq->eventfd); | 1042 | close(vq->eventfd); |
| 908 | } | 1043 | } |
| 909 | 1044 | ||
| @@ -955,7 +1090,10 @@ static void update_device_status(struct device *dev) | |||
| 955 | } | 1090 | } |
| 956 | } | 1091 | } |
| 957 | 1092 | ||
| 958 | /* This is the generic routine we call when the Guest uses LHCALL_NOTIFY. */ | 1093 | /*L:215 |
| 1094 | * This is the generic routine we call when the Guest uses LHCALL_NOTIFY. In | ||
| 1095 | * particular, it's used to notify us of device status changes during boot. | ||
| 1096 | */ | ||
| 959 | static void handle_output(unsigned long addr) | 1097 | static void handle_output(unsigned long addr) |
| 960 | { | 1098 | { |
| 961 | struct device *i; | 1099 | struct device *i; |
| @@ -964,25 +1102,42 @@ static void handle_output(unsigned long addr) | |||
| 964 | for (i = devices.dev; i; i = i->next) { | 1102 | for (i = devices.dev; i; i = i->next) { |
| 965 | struct virtqueue *vq; | 1103 | struct virtqueue *vq; |
| 966 | 1104 | ||
| 967 | /* Notifications to device descriptors update device status. */ | 1105 | /* |
| 1106 | * Notifications to device descriptors mean they updated the | ||
| 1107 | * device status. | ||
| 1108 | */ | ||
| 968 | if (from_guest_phys(addr) == i->desc) { | 1109 | if (from_guest_phys(addr) == i->desc) { |
| 969 | update_device_status(i); | 1110 | update_device_status(i); |
| 970 | return; | 1111 | return; |
| 971 | } | 1112 | } |
| 972 | 1113 | ||
| 973 | /* Devices *can* be used before status is set to DRIVER_OK. */ | 1114 | /* |
| 1115 | * Devices *can* be used before status is set to DRIVER_OK. | ||
| 1116 | * The original plan was that they would never do this: they | ||
| 1117 | * would always finish setting up their status bits before | ||
| 1118 | * actually touching the virtqueues. In practice, we allowed | ||
| 1119 | * them to, and they do (eg. the disk probes for partition | ||
| 1120 | * tables as part of initialization). | ||
| 1121 | * | ||
| 1122 | * If we see this, we start the device: once it's running, we | ||
| 1123 | * expect the device to catch all the notifications. | ||
| 1124 | */ | ||
| 974 | for (vq = i->vq; vq; vq = vq->next) { | 1125 | for (vq = i->vq; vq; vq = vq->next) { |
| 975 | if (addr != vq->config.pfn*getpagesize()) | 1126 | if (addr != vq->config.pfn*getpagesize()) |
| 976 | continue; | 1127 | continue; |
| 977 | if (i->running) | 1128 | if (i->running) |
| 978 | errx(1, "Notification on running %s", i->name); | 1129 | errx(1, "Notification on running %s", i->name); |
| 1130 | /* This just calls create_thread() for each virtqueue */ | ||
| 979 | start_device(i); | 1131 | start_device(i); |
| 980 | return; | 1132 | return; |
| 981 | } | 1133 | } |
| 982 | } | 1134 | } |
| 983 | 1135 | ||
| 984 | /* Early console write is done using notify on a nul-terminated string | 1136 | /* |
| 985 | * in Guest memory. */ | 1137 | * Early console write is done using notify on a nul-terminated string |
| 1138 | * in Guest memory. It's also great for hacking debugging messages | ||
| 1139 | * into a Guest. | ||
| 1140 | */ | ||
| 986 | if (addr >= guest_limit) | 1141 | if (addr >= guest_limit) |
| 987 | errx(1, "Bad NOTIFY %#lx", addr); | 1142 | errx(1, "Bad NOTIFY %#lx", addr); |
| 988 | 1143 | ||
| @@ -998,10 +1153,12 @@ static void handle_output(unsigned long addr) | |||
| 998 | * routines to allocate and manage them. | 1153 | * routines to allocate and manage them. |
| 999 | */ | 1154 | */ |
| 1000 | 1155 | ||
| 1001 | /* The layout of the device page is a "struct lguest_device_desc" followed by a | 1156 | /* |
| 1157 | * The layout of the device page is a "struct lguest_device_desc" followed by a | ||
| 1002 | * number of virtqueue descriptors, then two sets of feature bits, then an | 1158 | * number of virtqueue descriptors, then two sets of feature bits, then an |
| 1003 | * array of configuration bytes. This routine returns the configuration | 1159 | * array of configuration bytes. This routine returns the configuration |
| 1004 | * pointer. */ | 1160 | * pointer. |
| 1161 | */ | ||
| 1005 | static u8 *device_config(const struct device *dev) | 1162 | static u8 *device_config(const struct device *dev) |
| 1006 | { | 1163 | { |
| 1007 | return (void *)(dev->desc + 1) | 1164 | return (void *)(dev->desc + 1) |
| @@ -1009,9 +1166,11 @@ static u8 *device_config(const struct device *dev) | |||
| 1009 | + dev->feature_len * 2; | 1166 | + dev->feature_len * 2; |
| 1010 | } | 1167 | } |
| 1011 | 1168 | ||
| 1012 | /* This routine allocates a new "struct lguest_device_desc" from descriptor | 1169 | /* |
| 1170 | * This routine allocates a new "struct lguest_device_desc" from descriptor | ||
| 1013 | * table page just above the Guest's normal memory. It returns a pointer to | 1171 | * table page just above the Guest's normal memory. It returns a pointer to |
| 1014 | * that descriptor. */ | 1172 | * that descriptor. |
| 1173 | */ | ||
| 1015 | static struct lguest_device_desc *new_dev_desc(u16 type) | 1174 | static struct lguest_device_desc *new_dev_desc(u16 type) |
| 1016 | { | 1175 | { |
| 1017 | struct lguest_device_desc d = { .type = type }; | 1176 | struct lguest_device_desc d = { .type = type }; |
| @@ -1032,8 +1191,10 @@ static struct lguest_device_desc *new_dev_desc(u16 type) | |||
| 1032 | return memcpy(p, &d, sizeof(d)); | 1191 | return memcpy(p, &d, sizeof(d)); |
| 1033 | } | 1192 | } |
| 1034 | 1193 | ||
| 1035 | /* Each device descriptor is followed by the description of its virtqueues. We | 1194 | /* |
| 1036 | * specify how many descriptors the virtqueue is to have. */ | 1195 | * Each device descriptor is followed by the description of its virtqueues. We |
| 1196 | * specify how many descriptors the virtqueue is to have. | ||
| 1197 | */ | ||
| 1037 | static void add_virtqueue(struct device *dev, unsigned int num_descs, | 1198 | static void add_virtqueue(struct device *dev, unsigned int num_descs, |
| 1038 | void (*service)(struct virtqueue *)) | 1199 | void (*service)(struct virtqueue *)) |
| 1039 | { | 1200 | { |
| @@ -1050,6 +1211,11 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, | |||
| 1050 | vq->next = NULL; | 1211 | vq->next = NULL; |
| 1051 | vq->last_avail_idx = 0; | 1212 | vq->last_avail_idx = 0; |
| 1052 | vq->dev = dev; | 1213 | vq->dev = dev; |
| 1214 | |||
| 1215 | /* | ||
| 1216 | * This is the routine the service thread will run, and its Process ID | ||
| 1217 | * once it's running. | ||
| 1218 | */ | ||
| 1053 | vq->service = service; | 1219 | vq->service = service; |
| 1054 | vq->thread = (pid_t)-1; | 1220 | vq->thread = (pid_t)-1; |
| 1055 | 1221 | ||
| @@ -1061,10 +1227,12 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, | |||
| 1061 | /* Initialize the vring. */ | 1227 | /* Initialize the vring. */ |
| 1062 | vring_init(&vq->vring, num_descs, p, LGUEST_VRING_ALIGN); | 1228 | vring_init(&vq->vring, num_descs, p, LGUEST_VRING_ALIGN); |
| 1063 | 1229 | ||
| 1064 | /* Append virtqueue to this device's descriptor. We use | 1230 | /* |
| 1231 | * Append virtqueue to this device's descriptor. We use | ||
| 1065 | * device_config() to get the end of the device's current virtqueues; | 1232 | * device_config() to get the end of the device's current virtqueues; |
| 1066 | * we check that we haven't added any config or feature information | 1233 | * we check that we haven't added any config or feature information |
| 1067 | * yet, otherwise we'd be overwriting them. */ | 1234 | * yet, otherwise we'd be overwriting them. |
| 1235 | */ | ||
| 1068 | assert(dev->desc->config_len == 0 && dev->desc->feature_len == 0); | 1236 | assert(dev->desc->config_len == 0 && dev->desc->feature_len == 0); |
| 1069 | memcpy(device_config(dev), &vq->config, sizeof(vq->config)); | 1237 | memcpy(device_config(dev), &vq->config, sizeof(vq->config)); |
| 1070 | dev->num_vq++; | 1238 | dev->num_vq++; |
| @@ -1072,14 +1240,18 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, | |||
| 1072 | 1240 | ||
| 1073 | verbose("Virtqueue page %#lx\n", to_guest_phys(p)); | 1241 | verbose("Virtqueue page %#lx\n", to_guest_phys(p)); |
| 1074 | 1242 | ||
| 1075 | /* Add to tail of list, so dev->vq is first vq, dev->vq->next is | 1243 | /* |
| 1076 | * second. */ | 1244 | * Add to tail of list, so dev->vq is first vq, dev->vq->next is |
| 1245 | * second. | ||
| 1246 | */ | ||
| 1077 | for (i = &dev->vq; *i; i = &(*i)->next); | 1247 | for (i = &dev->vq; *i; i = &(*i)->next); |
| 1078 | *i = vq; | 1248 | *i = vq; |
| 1079 | } | 1249 | } |
| 1080 | 1250 | ||
| 1081 | /* The first half of the feature bitmask is for us to advertise features. The | 1251 | /* |
| 1082 | * second half is for the Guest to accept features. */ | 1252 | * The first half of the feature bitmask is for us to advertise features. The |
| 1253 | * second half is for the Guest to accept features. | ||
| 1254 | */ | ||
| 1083 | static void add_feature(struct device *dev, unsigned bit) | 1255 | static void add_feature(struct device *dev, unsigned bit) |
| 1084 | { | 1256 | { |
| 1085 | u8 *features = get_feature_bits(dev); | 1257 | u8 *features = get_feature_bits(dev); |
| @@ -1093,9 +1265,11 @@ static void add_feature(struct device *dev, unsigned bit) | |||
| 1093 | features[bit / CHAR_BIT] |= (1 << (bit % CHAR_BIT)); | 1265 | features[bit / CHAR_BIT] |= (1 << (bit % CHAR_BIT)); |
| 1094 | } | 1266 | } |
| 1095 | 1267 | ||
| 1096 | /* This routine sets the configuration fields for an existing device's | 1268 | /* |
| 1269 | * This routine sets the configuration fields for an existing device's | ||
| 1097 | * descriptor. It only works for the last device, but that's OK because that's | 1270 | * descriptor. It only works for the last device, but that's OK because that's |
| 1098 | * how we use it. */ | 1271 | * how we use it. |
| 1272 | */ | ||
| 1099 | static void set_config(struct device *dev, unsigned len, const void *conf) | 1273 | static void set_config(struct device *dev, unsigned len, const void *conf) |
| 1100 | { | 1274 | { |
| 1101 | /* Check we haven't overflowed our single page. */ | 1275 | /* Check we haven't overflowed our single page. */ |
| @@ -1105,12 +1279,18 @@ static void set_config(struct device *dev, unsigned len, const void *conf) | |||
| 1105 | /* Copy in the config information, and store the length. */ | 1279 | /* Copy in the config information, and store the length. */ |
| 1106 | memcpy(device_config(dev), conf, len); | 1280 | memcpy(device_config(dev), conf, len); |
| 1107 | dev->desc->config_len = len; | 1281 | dev->desc->config_len = len; |
| 1282 | |||
| 1283 | /* Size must fit in config_len field (8 bits)! */ | ||
| 1284 | assert(dev->desc->config_len == len); | ||
| 1108 | } | 1285 | } |
| 1109 | 1286 | ||
| 1110 | /* This routine does all the creation and setup of a new device, including | 1287 | /* |
| 1111 | * calling new_dev_desc() to allocate the descriptor and device memory. | 1288 | * This routine does all the creation and setup of a new device, including |
| 1289 | * calling new_dev_desc() to allocate the descriptor and device memory. We | ||
| 1290 | * don't actually start the service threads until later. | ||
| 1112 | * | 1291 | * |
| 1113 | * See what I mean about userspace being boring? */ | 1292 | * See what I mean about userspace being boring? |
| 1293 | */ | ||
| 1114 | static struct device *new_device(const char *name, u16 type) | 1294 | static struct device *new_device(const char *name, u16 type) |
| 1115 | { | 1295 | { |
| 1116 | struct device *dev = malloc(sizeof(*dev)); | 1296 | struct device *dev = malloc(sizeof(*dev)); |
| @@ -1123,10 +1303,12 @@ static struct device *new_device(const char *name, u16 type) | |||
| 1123 | dev->num_vq = 0; | 1303 | dev->num_vq = 0; |
| 1124 | dev->running = false; | 1304 | dev->running = false; |
| 1125 | 1305 | ||
| 1126 | /* Append to device list. Prepending to a single-linked list is | 1306 | /* |
| 1307 | * Append to device list. Prepending to a single-linked list is | ||
| 1127 | * easier, but the user expects the devices to be arranged on the bus | 1308 | * easier, but the user expects the devices to be arranged on the bus |
| 1128 | * in command-line order. The first network device on the command line | 1309 | * in command-line order. The first network device on the command line |
| 1129 | * is eth0, the first block device /dev/vda, etc. */ | 1310 | * is eth0, the first block device /dev/vda, etc. |
| 1311 | */ | ||
| 1130 | if (devices.lastdev) | 1312 | if (devices.lastdev) |
| 1131 | devices.lastdev->next = dev; | 1313 | devices.lastdev->next = dev; |
| 1132 | else | 1314 | else |
| @@ -1136,8 +1318,10 @@ static struct device *new_device(const char *name, u16 type) | |||
| 1136 | return dev; | 1318 | return dev; |
| 1137 | } | 1319 | } |
| 1138 | 1320 | ||
| 1139 | /* Our first setup routine is the console. It's a fairly simple device, but | 1321 | /* |
| 1140 | * UNIX tty handling makes it uglier than it could be. */ | 1322 | * Our first setup routine is the console. It's a fairly simple device, but |
| 1323 | * UNIX tty handling makes it uglier than it could be. | ||
| 1324 | */ | ||
| 1141 | static void setup_console(void) | 1325 | static void setup_console(void) |
| 1142 | { | 1326 | { |
| 1143 | struct device *dev; | 1327 | struct device *dev; |
| @@ -1145,8 +1329,10 @@ static void setup_console(void) | |||
| 1145 | /* If we can save the initial standard input settings... */ | 1329 | /* If we can save the initial standard input settings... */ |
| 1146 | if (tcgetattr(STDIN_FILENO, &orig_term) == 0) { | 1330 | if (tcgetattr(STDIN_FILENO, &orig_term) == 0) { |
| 1147 | struct termios term = orig_term; | 1331 | struct termios term = orig_term; |
| 1148 | /* Then we turn off echo, line buffering and ^C etc. We want a | 1332 | /* |
| 1149 | * raw input stream to the Guest. */ | 1333 | * Then we turn off echo, line buffering and ^C etc: We want a |
| 1334 | * raw input stream to the Guest. | ||
| 1335 | */ | ||
| 1150 | term.c_lflag &= ~(ISIG|ICANON|ECHO); | 1336 | term.c_lflag &= ~(ISIG|ICANON|ECHO); |
| 1151 | tcsetattr(STDIN_FILENO, TCSANOW, &term); | 1337 | tcsetattr(STDIN_FILENO, TCSANOW, &term); |
| 1152 | } | 1338 | } |
| @@ -1157,10 +1343,12 @@ static void setup_console(void) | |||
| 1157 | dev->priv = malloc(sizeof(struct console_abort)); | 1343 | dev->priv = malloc(sizeof(struct console_abort)); |
| 1158 | ((struct console_abort *)dev->priv)->count = 0; | 1344 | ((struct console_abort *)dev->priv)->count = 0; |
| 1159 | 1345 | ||
| 1160 | /* The console needs two virtqueues: the input then the output. When | 1346 | /* |
| 1347 | * The console needs two virtqueues: the input then the output. When | ||
| 1161 | * they put something the input queue, we make sure we're listening to | 1348 | * they put something the input queue, we make sure we're listening to |
| 1162 | * stdin. When they put something in the output queue, we write it to | 1349 | * stdin. When they put something in the output queue, we write it to |
| 1163 | * stdout. */ | 1350 | * stdout. |
| 1351 | */ | ||
| 1164 | add_virtqueue(dev, VIRTQUEUE_NUM, console_input); | 1352 | add_virtqueue(dev, VIRTQUEUE_NUM, console_input); |
| 1165 | add_virtqueue(dev, VIRTQUEUE_NUM, console_output); | 1353 | add_virtqueue(dev, VIRTQUEUE_NUM, console_output); |
| 1166 | 1354 | ||
| @@ -1168,7 +1356,8 @@ static void setup_console(void) | |||
| 1168 | } | 1356 | } |
| 1169 | /*:*/ | 1357 | /*:*/ |
| 1170 | 1358 | ||
| 1171 | /*M:010 Inter-guest networking is an interesting area. Simplest is to have a | 1359 | /*M:010 |
| 1360 | * Inter-guest networking is an interesting area. Simplest is to have a | ||
| 1172 | * --sharenet=<name> option which opens or creates a named pipe. This can be | 1361 | * --sharenet=<name> option which opens or creates a named pipe. This can be |
| 1173 | * used to send packets to another guest in a 1:1 manner. | 1362 | * used to send packets to another guest in a 1:1 manner. |
| 1174 | * | 1363 | * |
| @@ -1182,7 +1371,8 @@ static void setup_console(void) | |||
| 1182 | * multiple inter-guest channels behind one interface, although it would | 1371 | * multiple inter-guest channels behind one interface, although it would |
| 1183 | * require some manner of hotplugging new virtio channels. | 1372 | * require some manner of hotplugging new virtio channels. |
| 1184 | * | 1373 | * |
| 1185 | * Finally, we could implement a virtio network switch in the kernel. :*/ | 1374 | * Finally, we could implement a virtio network switch in the kernel. |
| 1375 | :*/ | ||
| 1186 | 1376 | ||
| 1187 | static u32 str2ip(const char *ipaddr) | 1377 | static u32 str2ip(const char *ipaddr) |
| 1188 | { | 1378 | { |
| @@ -1207,11 +1397,13 @@ static void str2mac(const char *macaddr, unsigned char mac[6]) | |||
| 1207 | mac[5] = m[5]; | 1397 | mac[5] = m[5]; |
| 1208 | } | 1398 | } |
| 1209 | 1399 | ||
| 1210 | /* This code is "adapted" from libbridge: it attaches the Host end of the | 1400 | /* |
| 1401 | * This code is "adapted" from libbridge: it attaches the Host end of the | ||
| 1211 | * network device to the bridge device specified by the command line. | 1402 | * network device to the bridge device specified by the command line. |
| 1212 | * | 1403 | * |
| 1213 | * This is yet another James Morris contribution (I'm an IP-level guy, so I | 1404 | * This is yet another James Morris contribution (I'm an IP-level guy, so I |
| 1214 | * dislike bridging), and I just try not to break it. */ | 1405 | * dislike bridging), and I just try not to break it. |
| 1406 | */ | ||
| 1215 | static void add_to_bridge(int fd, const char *if_name, const char *br_name) | 1407 | static void add_to_bridge(int fd, const char *if_name, const char *br_name) |
| 1216 | { | 1408 | { |
| 1217 | int ifidx; | 1409 | int ifidx; |
| @@ -1231,9 +1423,11 @@ static void add_to_bridge(int fd, const char *if_name, const char *br_name) | |||
| 1231 | err(1, "can't add %s to bridge %s", if_name, br_name); | 1423 | err(1, "can't add %s to bridge %s", if_name, br_name); |
| 1232 | } | 1424 | } |
| 1233 | 1425 | ||
| 1234 | /* This sets up the Host end of the network device with an IP address, brings | 1426 | /* |
| 1427 | * This sets up the Host end of the network device with an IP address, brings | ||
| 1235 | * it up so packets will flow, the copies the MAC address into the hwaddr | 1428 | * it up so packets will flow, the copies the MAC address into the hwaddr |
| 1236 | * pointer. */ | 1429 | * pointer. |
| 1430 | */ | ||
| 1237 | static void configure_device(int fd, const char *tapif, u32 ipaddr) | 1431 | static void configure_device(int fd, const char *tapif, u32 ipaddr) |
| 1238 | { | 1432 | { |
| 1239 | struct ifreq ifr; | 1433 | struct ifreq ifr; |
| @@ -1260,10 +1454,12 @@ static int get_tun_device(char tapif[IFNAMSIZ]) | |||
| 1260 | /* Start with this zeroed. Messy but sure. */ | 1454 | /* Start with this zeroed. Messy but sure. */ |
| 1261 | memset(&ifr, 0, sizeof(ifr)); | 1455 | memset(&ifr, 0, sizeof(ifr)); |
| 1262 | 1456 | ||
| 1263 | /* We open the /dev/net/tun device and tell it we want a tap device. A | 1457 | /* |
| 1458 | * We open the /dev/net/tun device and tell it we want a tap device. A | ||
| 1264 | * tap device is like a tun device, only somehow different. To tell | 1459 | * tap device is like a tun device, only somehow different. To tell |
| 1265 | * the truth, I completely blundered my way through this code, but it | 1460 | * the truth, I completely blundered my way through this code, but it |
| 1266 | * works now! */ | 1461 | * works now! |
| 1462 | */ | ||
| 1267 | netfd = open_or_die("/dev/net/tun", O_RDWR); | 1463 | netfd = open_or_die("/dev/net/tun", O_RDWR); |
| 1268 | ifr.ifr_flags = IFF_TAP | IFF_NO_PI | IFF_VNET_HDR; | 1464 | ifr.ifr_flags = IFF_TAP | IFF_NO_PI | IFF_VNET_HDR; |
| 1269 | strcpy(ifr.ifr_name, "tap%d"); | 1465 | strcpy(ifr.ifr_name, "tap%d"); |
| @@ -1274,18 +1470,22 @@ static int get_tun_device(char tapif[IFNAMSIZ]) | |||
| 1274 | TUN_F_CSUM|TUN_F_TSO4|TUN_F_TSO6|TUN_F_TSO_ECN) != 0) | 1470 | TUN_F_CSUM|TUN_F_TSO4|TUN_F_TSO6|TUN_F_TSO_ECN) != 0) |
| 1275 | err(1, "Could not set features for tun device"); | 1471 | err(1, "Could not set features for tun device"); |
| 1276 | 1472 | ||
| 1277 | /* We don't need checksums calculated for packets coming in this | 1473 | /* |
| 1278 | * device: trust us! */ | 1474 | * We don't need checksums calculated for packets coming in this |
| 1475 | * device: trust us! | ||
| 1476 | */ | ||
| 1279 | ioctl(netfd, TUNSETNOCSUM, 1); | 1477 | ioctl(netfd, TUNSETNOCSUM, 1); |
| 1280 | 1478 | ||
| 1281 | memcpy(tapif, ifr.ifr_name, IFNAMSIZ); | 1479 | memcpy(tapif, ifr.ifr_name, IFNAMSIZ); |
| 1282 | return netfd; | 1480 | return netfd; |
| 1283 | } | 1481 | } |
| 1284 | 1482 | ||
| 1285 | /*L:195 Our network is a Host<->Guest network. This can either use bridging or | 1483 | /*L:195 |
| 1484 | * Our network is a Host<->Guest network. This can either use bridging or | ||
| 1286 | * routing, but the principle is the same: it uses the "tun" device to inject | 1485 | * routing, but the principle is the same: it uses the "tun" device to inject |
| 1287 | * packets into the Host as if they came in from a normal network card. We | 1486 | * packets into the Host as if they came in from a normal network card. We |
| 1288 | * just shunt packets between the Guest and the tun device. */ | 1487 | * just shunt packets between the Guest and the tun device. |
| 1488 | */ | ||
| 1289 | static void setup_tun_net(char *arg) | 1489 | static void setup_tun_net(char *arg) |
| 1290 | { | 1490 | { |
| 1291 | struct device *dev; | 1491 | struct device *dev; |
| @@ -1302,13 +1502,14 @@ static void setup_tun_net(char *arg) | |||
| 1302 | dev = new_device("net", VIRTIO_ID_NET); | 1502 | dev = new_device("net", VIRTIO_ID_NET); |
| 1303 | dev->priv = net_info; | 1503 | dev->priv = net_info; |
| 1304 | 1504 | ||
| 1305 | /* Network devices need a receive and a send queue, just like | 1505 | /* Network devices need a recv and a send queue, just like console. */ |
| 1306 | * console. */ | ||
| 1307 | add_virtqueue(dev, VIRTQUEUE_NUM, net_input); | 1506 | add_virtqueue(dev, VIRTQUEUE_NUM, net_input); |
| 1308 | add_virtqueue(dev, VIRTQUEUE_NUM, net_output); | 1507 | add_virtqueue(dev, VIRTQUEUE_NUM, net_output); |
| 1309 | 1508 | ||
| 1310 | /* We need a socket to perform the magic network ioctls to bring up the | 1509 | /* |
| 1311 | * tap interface, connect to the bridge etc. Any socket will do! */ | 1510 | * We need a socket to perform the magic network ioctls to bring up the |
| 1511 | * tap interface, connect to the bridge etc. Any socket will do! | ||
| 1512 | */ | ||
| 1312 | ipfd = socket(PF_INET, SOCK_DGRAM, IPPROTO_IP); | 1513 | ipfd = socket(PF_INET, SOCK_DGRAM, IPPROTO_IP); |
| 1313 | if (ipfd < 0) | 1514 | if (ipfd < 0) |
| 1314 | err(1, "opening IP socket"); | 1515 | err(1, "opening IP socket"); |
| @@ -1362,39 +1563,31 @@ static void setup_tun_net(char *arg) | |||
| 1362 | verbose("device %u: tun %s: %s\n", | 1563 | verbose("device %u: tun %s: %s\n", |
| 1363 | devices.device_num, tapif, arg); | 1564 | devices.device_num, tapif, arg); |
| 1364 | } | 1565 | } |
| 1365 | 1566 | /*:*/ | |
| 1366 | /* Our block (disk) device should be really simple: the Guest asks for a block | ||
| 1367 | * number and we read or write that position in the file. Unfortunately, that | ||
| 1368 | * was amazingly slow: the Guest waits until the read is finished before | ||
| 1369 | * running anything else, even if it could have been doing useful work. | ||
| 1370 | * | ||
| 1371 | * We could use async I/O, except it's reputed to suck so hard that characters | ||
| 1372 | * actually go missing from your code when you try to use it. | ||
| 1373 | * | ||
| 1374 | * So we farm the I/O out to thread, and communicate with it via a pipe. */ | ||
| 1375 | 1567 | ||
| 1376 | /* This hangs off device->priv. */ | 1568 | /* This hangs off device->priv. */ |
| 1377 | struct vblk_info | 1569 | struct vblk_info { |
| 1378 | { | ||
| 1379 | /* The size of the file. */ | 1570 | /* The size of the file. */ |
| 1380 | off64_t len; | 1571 | off64_t len; |
| 1381 | 1572 | ||
| 1382 | /* The file descriptor for the file. */ | 1573 | /* The file descriptor for the file. */ |
| 1383 | int fd; | 1574 | int fd; |
| 1384 | 1575 | ||
| 1385 | /* IO thread listens on this file descriptor [0]. */ | ||
| 1386 | int workpipe[2]; | ||
| 1387 | |||
| 1388 | /* IO thread writes to this file descriptor to mark it done, then | ||
| 1389 | * Launcher triggers interrupt to Guest. */ | ||
| 1390 | int done_fd; | ||
| 1391 | }; | 1576 | }; |
| 1392 | 1577 | ||
| 1393 | /*L:210 | 1578 | /*L:210 |
| 1394 | * The Disk | 1579 | * The Disk |
| 1395 | * | 1580 | * |
| 1396 | * Remember that the block device is handled by a separate I/O thread. We head | 1581 | * The disk only has one virtqueue, so it only has one thread. It is really |
| 1397 | * straight into the core of that thread here: | 1582 | * simple: the Guest asks for a block number and we read or write that position |
| 1583 | * in the file. | ||
| 1584 | * | ||
| 1585 | * Before we serviced each virtqueue in a separate thread, that was unacceptably | ||
| 1586 | * slow: the Guest waits until the read is finished before running anything | ||
| 1587 | * else, even if it could have been doing useful work. | ||
| 1588 | * | ||
| 1589 | * We could have used async I/O, except it's reputed to suck so hard that | ||
| 1590 | * characters actually go missing from your code when you try to use it. | ||
| 1398 | */ | 1591 | */ |
| 1399 | static void blk_request(struct virtqueue *vq) | 1592 | static void blk_request(struct virtqueue *vq) |
| 1400 | { | 1593 | { |
| @@ -1406,47 +1599,64 @@ static void blk_request(struct virtqueue *vq) | |||
| 1406 | struct iovec iov[vq->vring.num]; | 1599 | struct iovec iov[vq->vring.num]; |
| 1407 | off64_t off; | 1600 | off64_t off; |
| 1408 | 1601 | ||
| 1409 | /* Get the next request. */ | 1602 | /* |
| 1603 | * Get the next request, where we normally wait. It triggers the | ||
| 1604 | * interrupt to acknowledge previously serviced requests (if any). | ||
| 1605 | */ | ||
| 1410 | head = wait_for_vq_desc(vq, iov, &out_num, &in_num); | 1606 | head = wait_for_vq_desc(vq, iov, &out_num, &in_num); |
| 1411 | 1607 | ||
| 1412 | /* Every block request should contain at least one output buffer | 1608 | /* |
| 1609 | * Every block request should contain at least one output buffer | ||
| 1413 | * (detailing the location on disk and the type of request) and one | 1610 | * (detailing the location on disk and the type of request) and one |
| 1414 | * input buffer (to hold the result). */ | 1611 | * input buffer (to hold the result). |
| 1612 | */ | ||
| 1415 | if (out_num == 0 || in_num == 0) | 1613 | if (out_num == 0 || in_num == 0) |
| 1416 | errx(1, "Bad virtblk cmd %u out=%u in=%u", | 1614 | errx(1, "Bad virtblk cmd %u out=%u in=%u", |
| 1417 | head, out_num, in_num); | 1615 | head, out_num, in_num); |
| 1418 | 1616 | ||
| 1419 | out = convert(&iov[0], struct virtio_blk_outhdr); | 1617 | out = convert(&iov[0], struct virtio_blk_outhdr); |
| 1420 | in = convert(&iov[out_num+in_num-1], u8); | 1618 | in = convert(&iov[out_num+in_num-1], u8); |
| 1619 | /* | ||
| 1620 | * For historical reasons, block operations are expressed in 512 byte | ||
| 1621 | * "sectors". | ||
| 1622 | */ | ||
| 1421 | off = out->sector * 512; | 1623 | off = out->sector * 512; |
| 1422 | 1624 | ||
| 1423 | /* The block device implements "barriers", where the Guest indicates | 1625 | /* |
| 1626 | * The block device implements "barriers", where the Guest indicates | ||
| 1424 | * that it wants all previous writes to occur before this write. We | 1627 | * that it wants all previous writes to occur before this write. We |
| 1425 | * don't have a way of asking our kernel to do a barrier, so we just | 1628 | * don't have a way of asking our kernel to do a barrier, so we just |
| 1426 | * synchronize all the data in the file. Pretty poor, no? */ | 1629 | * synchronize all the data in the file. Pretty poor, no? |
| 1630 | */ | ||
| 1427 | if (out->type & VIRTIO_BLK_T_BARRIER) | 1631 | if (out->type & VIRTIO_BLK_T_BARRIER) |
| 1428 | fdatasync(vblk->fd); | 1632 | fdatasync(vblk->fd); |
| 1429 | 1633 | ||
| 1430 | /* In general the virtio block driver is allowed to try SCSI commands. | 1634 | /* |
| 1431 | * It'd be nice if we supported eject, for example, but we don't. */ | 1635 | * In general the virtio block driver is allowed to try SCSI commands. |
| 1636 | * It'd be nice if we supported eject, for example, but we don't. | ||
| 1637 | */ | ||
| 1432 | if (out->type & VIRTIO_BLK_T_SCSI_CMD) { | 1638 | if (out->type & VIRTIO_BLK_T_SCSI_CMD) { |
| 1433 | fprintf(stderr, "Scsi commands unsupported\n"); | 1639 | fprintf(stderr, "Scsi commands unsupported\n"); |
| 1434 | *in = VIRTIO_BLK_S_UNSUPP; | 1640 | *in = VIRTIO_BLK_S_UNSUPP; |
| 1435 | wlen = sizeof(*in); | 1641 | wlen = sizeof(*in); |
| 1436 | } else if (out->type & VIRTIO_BLK_T_OUT) { | 1642 | } else if (out->type & VIRTIO_BLK_T_OUT) { |
| 1437 | /* Write */ | 1643 | /* |
| 1438 | 1644 | * Write | |
| 1439 | /* Move to the right location in the block file. This can fail | 1645 | * |
| 1440 | * if they try to write past end. */ | 1646 | * Move to the right location in the block file. This can fail |
| 1647 | * if they try to write past end. | ||
| 1648 | */ | ||
| 1441 | if (lseek64(vblk->fd, off, SEEK_SET) != off) | 1649 | if (lseek64(vblk->fd, off, SEEK_SET) != off) |
| 1442 | err(1, "Bad seek to sector %llu", out->sector); | 1650 | err(1, "Bad seek to sector %llu", out->sector); |
| 1443 | 1651 | ||
| 1444 | ret = writev(vblk->fd, iov+1, out_num-1); | 1652 | ret = writev(vblk->fd, iov+1, out_num-1); |
| 1445 | verbose("WRITE to sector %llu: %i\n", out->sector, ret); | 1653 | verbose("WRITE to sector %llu: %i\n", out->sector, ret); |
| 1446 | 1654 | ||
| 1447 | /* Grr... Now we know how long the descriptor they sent was, we | 1655 | /* |
| 1656 | * Grr... Now we know how long the descriptor they sent was, we | ||
| 1448 | * make sure they didn't try to write over the end of the block | 1657 | * make sure they didn't try to write over the end of the block |
| 1449 | * file (possibly extending it). */ | 1658 | * file (possibly extending it). |
| 1659 | */ | ||
| 1450 | if (ret > 0 && off + ret > vblk->len) { | 1660 | if (ret > 0 && off + ret > vblk->len) { |
| 1451 | /* Trim it back to the correct length */ | 1661 | /* Trim it back to the correct length */ |
| 1452 | ftruncate64(vblk->fd, vblk->len); | 1662 | ftruncate64(vblk->fd, vblk->len); |
| @@ -1456,10 +1666,12 @@ static void blk_request(struct virtqueue *vq) | |||
| 1456 | wlen = sizeof(*in); | 1666 | wlen = sizeof(*in); |
| 1457 | *in = (ret >= 0 ? VIRTIO_BLK_S_OK : VIRTIO_BLK_S_IOERR); | 1667 | *in = (ret >= 0 ? VIRTIO_BLK_S_OK : VIRTIO_BLK_S_IOERR); |
| 1458 | } else { | 1668 | } else { |
| 1459 | /* Read */ | 1669 | /* |
| 1460 | 1670 | * Read | |
| 1461 | /* Move to the right location in the block file. This can fail | 1671 | * |
| 1462 | * if they try to read past end. */ | 1672 | * Move to the right location in the block file. This can fail |
| 1673 | * if they try to read past end. | ||
| 1674 | */ | ||
| 1463 | if (lseek64(vblk->fd, off, SEEK_SET) != off) | 1675 | if (lseek64(vblk->fd, off, SEEK_SET) != off) |
| 1464 | err(1, "Bad seek to sector %llu", out->sector); | 1676 | err(1, "Bad seek to sector %llu", out->sector); |
| 1465 | 1677 | ||
| @@ -1474,13 +1686,16 @@ static void blk_request(struct virtqueue *vq) | |||
| 1474 | } | 1686 | } |
| 1475 | } | 1687 | } |
| 1476 | 1688 | ||
| 1477 | /* OK, so we noted that it was pretty poor to use an fdatasync as a | 1689 | /* |
| 1690 | * OK, so we noted that it was pretty poor to use an fdatasync as a | ||
| 1478 | * barrier. But Christoph Hellwig points out that we need a sync | 1691 | * barrier. But Christoph Hellwig points out that we need a sync |
| 1479 | * *afterwards* as well: "Barriers specify no reordering to the front | 1692 | * *afterwards* as well: "Barriers specify no reordering to the front |
| 1480 | * or the back." And Jens Axboe confirmed it, so here we are: */ | 1693 | * or the back." And Jens Axboe confirmed it, so here we are: |
| 1694 | */ | ||
| 1481 | if (out->type & VIRTIO_BLK_T_BARRIER) | 1695 | if (out->type & VIRTIO_BLK_T_BARRIER) |
| 1482 | fdatasync(vblk->fd); | 1696 | fdatasync(vblk->fd); |
| 1483 | 1697 | ||
| 1698 | /* Finished that request. */ | ||
| 1484 | add_used(vq, head, wlen); | 1699 | add_used(vq, head, wlen); |
| 1485 | } | 1700 | } |
| 1486 | 1701 | ||
| @@ -1491,7 +1706,7 @@ static void setup_block_file(const char *filename) | |||
| 1491 | struct vblk_info *vblk; | 1706 | struct vblk_info *vblk; |
| 1492 | struct virtio_blk_config conf; | 1707 | struct virtio_blk_config conf; |
| 1493 | 1708 | ||
| 1494 | /* The device responds to return from I/O thread. */ | 1709 | /* Creat the device. */ |
| 1495 | dev = new_device("block", VIRTIO_ID_BLOCK); | 1710 | dev = new_device("block", VIRTIO_ID_BLOCK); |
| 1496 | 1711 | ||
| 1497 | /* The device has one virtqueue, where the Guest places requests. */ | 1712 | /* The device has one virtqueue, where the Guest places requests. */ |
| @@ -1510,27 +1725,32 @@ static void setup_block_file(const char *filename) | |||
| 1510 | /* Tell Guest how many sectors this device has. */ | 1725 | /* Tell Guest how many sectors this device has. */ |
| 1511 | conf.capacity = cpu_to_le64(vblk->len / 512); | 1726 | conf.capacity = cpu_to_le64(vblk->len / 512); |
| 1512 | 1727 | ||
| 1513 | /* Tell Guest not to put in too many descriptors at once: two are used | 1728 | /* |
| 1514 | * for the in and out elements. */ | 1729 | * Tell Guest not to put in too many descriptors at once: two are used |
| 1730 | * for the in and out elements. | ||
| 1731 | */ | ||
| 1515 | add_feature(dev, VIRTIO_BLK_F_SEG_MAX); | 1732 | add_feature(dev, VIRTIO_BLK_F_SEG_MAX); |
| 1516 | conf.seg_max = cpu_to_le32(VIRTQUEUE_NUM - 2); | 1733 | conf.seg_max = cpu_to_le32(VIRTQUEUE_NUM - 2); |
| 1517 | 1734 | ||
| 1518 | set_config(dev, sizeof(conf), &conf); | 1735 | /* Don't try to put whole struct: we have 8 bit limit. */ |
| 1736 | set_config(dev, offsetof(struct virtio_blk_config, geometry), &conf); | ||
| 1519 | 1737 | ||
| 1520 | verbose("device %u: virtblock %llu sectors\n", | 1738 | verbose("device %u: virtblock %llu sectors\n", |
| 1521 | ++devices.device_num, le64_to_cpu(conf.capacity)); | 1739 | ++devices.device_num, le64_to_cpu(conf.capacity)); |
| 1522 | } | 1740 | } |
| 1523 | 1741 | ||
| 1524 | struct rng_info { | 1742 | /*L:211 |
| 1525 | int rfd; | 1743 | * Our random number generator device reads from /dev/random into the Guest's |
| 1526 | }; | ||
| 1527 | |||
| 1528 | /* Our random number generator device reads from /dev/random into the Guest's | ||
| 1529 | * input buffers. The usual case is that the Guest doesn't want random numbers | 1744 | * input buffers. The usual case is that the Guest doesn't want random numbers |
| 1530 | * and so has no buffers although /dev/random is still readable, whereas | 1745 | * and so has no buffers although /dev/random is still readable, whereas |
| 1531 | * console is the reverse. | 1746 | * console is the reverse. |
| 1532 | * | 1747 | * |
| 1533 | * The same logic applies, however. */ | 1748 | * The same logic applies, however. |
| 1749 | */ | ||
| 1750 | struct rng_info { | ||
| 1751 | int rfd; | ||
| 1752 | }; | ||
| 1753 | |||
| 1534 | static void rng_input(struct virtqueue *vq) | 1754 | static void rng_input(struct virtqueue *vq) |
| 1535 | { | 1755 | { |
| 1536 | int len; | 1756 | int len; |
| @@ -1543,9 +1763,10 @@ static void rng_input(struct virtqueue *vq) | |||
| 1543 | if (out_num) | 1763 | if (out_num) |
| 1544 | errx(1, "Output buffers in rng?"); | 1764 | errx(1, "Output buffers in rng?"); |
| 1545 | 1765 | ||
| 1546 | /* This is why we convert to iovecs: the readv() call uses them, and so | 1766 | /* |
| 1547 | * it reads straight into the Guest's buffer. We loop to make sure we | 1767 | * Just like the console write, we loop to cover the whole iovec. |
| 1548 | * fill it. */ | 1768 | * In this case, short reads actually happen quite a bit. |
| 1769 | */ | ||
| 1549 | while (!iov_empty(iov, in_num)) { | 1770 | while (!iov_empty(iov, in_num)) { |
| 1550 | len = readv(rng_info->rfd, iov, in_num); | 1771 | len = readv(rng_info->rfd, iov, in_num); |
| 1551 | if (len <= 0) | 1772 | if (len <= 0) |
| @@ -1558,15 +1779,18 @@ static void rng_input(struct virtqueue *vq) | |||
| 1558 | add_used(vq, head, totlen); | 1779 | add_used(vq, head, totlen); |
| 1559 | } | 1780 | } |
| 1560 | 1781 | ||
| 1561 | /* And this creates a "hardware" random number device for the Guest. */ | 1782 | /*L:199 |
| 1783 | * This creates a "hardware" random number device for the Guest. | ||
| 1784 | */ | ||
| 1562 | static void setup_rng(void) | 1785 | static void setup_rng(void) |
| 1563 | { | 1786 | { |
| 1564 | struct device *dev; | 1787 | struct device *dev; |
| 1565 | struct rng_info *rng_info = malloc(sizeof(*rng_info)); | 1788 | struct rng_info *rng_info = malloc(sizeof(*rng_info)); |
| 1566 | 1789 | ||
| 1790 | /* Our device's privat info simply contains the /dev/random fd. */ | ||
| 1567 | rng_info->rfd = open_or_die("/dev/random", O_RDONLY); | 1791 | rng_info->rfd = open_or_die("/dev/random", O_RDONLY); |
| 1568 | 1792 | ||
| 1569 | /* The device responds to return from I/O thread. */ | 1793 | /* Create the new device. */ |
| 1570 | dev = new_device("rng", VIRTIO_ID_RNG); | 1794 | dev = new_device("rng", VIRTIO_ID_RNG); |
| 1571 | dev->priv = rng_info; | 1795 | dev->priv = rng_info; |
| 1572 | 1796 | ||
| @@ -1582,8 +1806,10 @@ static void __attribute__((noreturn)) restart_guest(void) | |||
| 1582 | { | 1806 | { |
| 1583 | unsigned int i; | 1807 | unsigned int i; |
| 1584 | 1808 | ||
| 1585 | /* Since we don't track all open fds, we simply close everything beyond | 1809 | /* |
| 1586 | * stderr. */ | 1810 | * Since we don't track all open fds, we simply close everything beyond |
| 1811 | * stderr. | ||
| 1812 | */ | ||
| 1587 | for (i = 3; i < FD_SETSIZE; i++) | 1813 | for (i = 3; i < FD_SETSIZE; i++) |
| 1588 | close(i); | 1814 | close(i); |
| 1589 | 1815 | ||
| @@ -1594,8 +1820,10 @@ static void __attribute__((noreturn)) restart_guest(void) | |||
| 1594 | err(1, "Could not exec %s", main_args[0]); | 1820 | err(1, "Could not exec %s", main_args[0]); |
| 1595 | } | 1821 | } |
| 1596 | 1822 | ||
| 1597 | /*L:220 Finally we reach the core of the Launcher which runs the Guest, serves | 1823 | /*L:220 |
| 1598 | * its input and output, and finally, lays it to rest. */ | 1824 | * Finally we reach the core of the Launcher which runs the Guest, serves |
| 1825 | * its input and output, and finally, lays it to rest. | ||
| 1826 | */ | ||
| 1599 | static void __attribute__((noreturn)) run_guest(void) | 1827 | static void __attribute__((noreturn)) run_guest(void) |
| 1600 | { | 1828 | { |
| 1601 | for (;;) { | 1829 | for (;;) { |
| @@ -1630,7 +1858,7 @@ static void __attribute__((noreturn)) run_guest(void) | |||
| 1630 | * | 1858 | * |
| 1631 | * Are you ready? Take a deep breath and join me in the core of the Host, in | 1859 | * Are you ready? Take a deep breath and join me in the core of the Host, in |
| 1632 | * "make Host". | 1860 | * "make Host". |
| 1633 | :*/ | 1861 | :*/ |
| 1634 | 1862 | ||
| 1635 | static struct option opts[] = { | 1863 | static struct option opts[] = { |
| 1636 | { "verbose", 0, NULL, 'v' }, | 1864 | { "verbose", 0, NULL, 'v' }, |
| @@ -1651,8 +1879,7 @@ static void usage(void) | |||
| 1651 | /*L:105 The main routine is where the real work begins: */ | 1879 | /*L:105 The main routine is where the real work begins: */ |
| 1652 | int main(int argc, char *argv[]) | 1880 | int main(int argc, char *argv[]) |
| 1653 | { | 1881 | { |
| 1654 | /* Memory, top-level pagetable, code startpoint and size of the | 1882 | /* Memory, code startpoint and size of the (optional) initrd. */ |
| 1655 | * (optional) initrd. */ | ||
| 1656 | unsigned long mem = 0, start, initrd_size = 0; | 1883 | unsigned long mem = 0, start, initrd_size = 0; |
| 1657 | /* Two temporaries. */ | 1884 | /* Two temporaries. */ |
| 1658 | int i, c; | 1885 | int i, c; |
| @@ -1664,24 +1891,32 @@ int main(int argc, char *argv[]) | |||
| 1664 | /* Save the args: we "reboot" by execing ourselves again. */ | 1891 | /* Save the args: we "reboot" by execing ourselves again. */ |
| 1665 | main_args = argv; | 1892 | main_args = argv; |
| 1666 | 1893 | ||
| 1667 | /* First we initialize the device list. We keep a pointer to the last | 1894 | /* |
| 1895 | * First we initialize the device list. We keep a pointer to the last | ||
| 1668 | * device, and the next interrupt number to use for devices (1: | 1896 | * device, and the next interrupt number to use for devices (1: |
| 1669 | * remember that 0 is used by the timer). */ | 1897 | * remember that 0 is used by the timer). |
| 1898 | */ | ||
| 1670 | devices.lastdev = NULL; | 1899 | devices.lastdev = NULL; |
| 1671 | devices.next_irq = 1; | 1900 | devices.next_irq = 1; |
| 1672 | 1901 | ||
| 1902 | /* We're CPU 0. In fact, that's the only CPU possible right now. */ | ||
| 1673 | cpu_id = 0; | 1903 | cpu_id = 0; |
| 1674 | /* We need to know how much memory so we can set up the device | 1904 | |
| 1905 | /* | ||
| 1906 | * We need to know how much memory so we can set up the device | ||
| 1675 | * descriptor and memory pages for the devices as we parse the command | 1907 | * descriptor and memory pages for the devices as we parse the command |
| 1676 | * line. So we quickly look through the arguments to find the amount | 1908 | * line. So we quickly look through the arguments to find the amount |
| 1677 | * of memory now. */ | 1909 | * of memory now. |
| 1910 | */ | ||
| 1678 | for (i = 1; i < argc; i++) { | 1911 | for (i = 1; i < argc; i++) { |
| 1679 | if (argv[i][0] != '-') { | 1912 | if (argv[i][0] != '-') { |
| 1680 | mem = atoi(argv[i]) * 1024 * 1024; | 1913 | mem = atoi(argv[i]) * 1024 * 1024; |
| 1681 | /* We start by mapping anonymous pages over all of | 1914 | /* |
| 1915 | * We start by mapping anonymous pages over all of | ||
| 1682 | * guest-physical memory range. This fills it with 0, | 1916 | * guest-physical memory range. This fills it with 0, |
| 1683 | * and ensures that the Guest won't be killed when it | 1917 | * and ensures that the Guest won't be killed when it |
| 1684 | * tries to access it. */ | 1918 | * tries to access it. |
| 1919 | */ | ||
| 1685 | guest_base = map_zeroed_pages(mem / getpagesize() | 1920 | guest_base = map_zeroed_pages(mem / getpagesize() |
| 1686 | + DEVICE_PAGES); | 1921 | + DEVICE_PAGES); |
| 1687 | guest_limit = mem; | 1922 | guest_limit = mem; |
| @@ -1714,8 +1949,10 @@ int main(int argc, char *argv[]) | |||
| 1714 | usage(); | 1949 | usage(); |
| 1715 | } | 1950 | } |
| 1716 | } | 1951 | } |
| 1717 | /* After the other arguments we expect memory and kernel image name, | 1952 | /* |
| 1718 | * followed by command line arguments for the kernel. */ | 1953 | * After the other arguments we expect memory and kernel image name, |
| 1954 | * followed by command line arguments for the kernel. | ||
| 1955 | */ | ||
| 1719 | if (optind + 2 > argc) | 1956 | if (optind + 2 > argc) |
| 1720 | usage(); | 1957 | usage(); |
| 1721 | 1958 | ||
| @@ -1733,20 +1970,26 @@ int main(int argc, char *argv[]) | |||
| 1733 | /* Map the initrd image if requested (at top of physical memory) */ | 1970 | /* Map the initrd image if requested (at top of physical memory) */ |
| 1734 | if (initrd_name) { | 1971 | if (initrd_name) { |
| 1735 | initrd_size = load_initrd(initrd_name, mem); | 1972 | initrd_size = load_initrd(initrd_name, mem); |
| 1736 | /* These are the location in the Linux boot header where the | 1973 | /* |
| 1737 | * start and size of the initrd are expected to be found. */ | 1974 | * These are the location in the Linux boot header where the |
| 1975 | * start and size of the initrd are expected to be found. | ||
| 1976 | */ | ||
| 1738 | boot->hdr.ramdisk_image = mem - initrd_size; | 1977 | boot->hdr.ramdisk_image = mem - initrd_size; |
| 1739 | boot->hdr.ramdisk_size = initrd_size; | 1978 | boot->hdr.ramdisk_size = initrd_size; |
| 1740 | /* The bootloader type 0xFF means "unknown"; that's OK. */ | 1979 | /* The bootloader type 0xFF means "unknown"; that's OK. */ |
| 1741 | boot->hdr.type_of_loader = 0xFF; | 1980 | boot->hdr.type_of_loader = 0xFF; |
| 1742 | } | 1981 | } |
| 1743 | 1982 | ||
| 1744 | /* The Linux boot header contains an "E820" memory map: ours is a | 1983 | /* |
| 1745 | * simple, single region. */ | 1984 | * The Linux boot header contains an "E820" memory map: ours is a |
| 1985 | * simple, single region. | ||
| 1986 | */ | ||
| 1746 | boot->e820_entries = 1; | 1987 | boot->e820_entries = 1; |
| 1747 | boot->e820_map[0] = ((struct e820entry) { 0, mem, E820_RAM }); | 1988 | boot->e820_map[0] = ((struct e820entry) { 0, mem, E820_RAM }); |
| 1748 | /* The boot header contains a command line pointer: we put the command | 1989 | /* |
| 1749 | * line after the boot header. */ | 1990 | * The boot header contains a command line pointer: we put the command |
| 1991 | * line after the boot header. | ||
| 1992 | */ | ||
| 1750 | boot->hdr.cmd_line_ptr = to_guest_phys(boot + 1); | 1993 | boot->hdr.cmd_line_ptr = to_guest_phys(boot + 1); |
| 1751 | /* We use a simple helper to copy the arguments separated by spaces. */ | 1994 | /* We use a simple helper to copy the arguments separated by spaces. */ |
| 1752 | concat((char *)(boot + 1), argv+optind+2); | 1995 | concat((char *)(boot + 1), argv+optind+2); |
| @@ -1760,11 +2003,13 @@ int main(int argc, char *argv[]) | |||
| 1760 | /* Tell the entry path not to try to reload segment registers. */ | 2003 | /* Tell the entry path not to try to reload segment registers. */ |
| 1761 | boot->hdr.loadflags |= KEEP_SEGMENTS; | 2004 | boot->hdr.loadflags |= KEEP_SEGMENTS; |
| 1762 | 2005 | ||
| 1763 | /* We tell the kernel to initialize the Guest: this returns the open | 2006 | /* |
| 1764 | * /dev/lguest file descriptor. */ | 2007 | * We tell the kernel to initialize the Guest: this returns the open |
| 2008 | * /dev/lguest file descriptor. | ||
| 2009 | */ | ||
| 1765 | tell_kernel(start); | 2010 | tell_kernel(start); |
| 1766 | 2011 | ||
| 1767 | /* Ensure that we terminate if a child dies. */ | 2012 | /* Ensure that we terminate if a device-servicing child dies. */ |
| 1768 | signal(SIGCHLD, kill_launcher); | 2013 | signal(SIGCHLD, kill_launcher); |
| 1769 | 2014 | ||
| 1770 | /* If we exit via err(), this kills all the threads, restores tty. */ | 2015 | /* If we exit via err(), this kills all the threads, restores tty. */ |
diff --git a/Documentation/lockdep-design.txt b/Documentation/lockdep-design.txt index e20d913d5914..abf768c681e2 100644 --- a/Documentation/lockdep-design.txt +++ b/Documentation/lockdep-design.txt | |||
| @@ -30,9 +30,9 @@ State | |||
| 30 | The validator tracks lock-class usage history into 4n + 1 separate state bits: | 30 | The validator tracks lock-class usage history into 4n + 1 separate state bits: |
| 31 | 31 | ||
| 32 | - 'ever held in STATE context' | 32 | - 'ever held in STATE context' |
| 33 | - 'ever head as readlock in STATE context' | 33 | - 'ever held as readlock in STATE context' |
| 34 | - 'ever head with STATE enabled' | 34 | - 'ever held with STATE enabled' |
| 35 | - 'ever head as readlock with STATE enabled' | 35 | - 'ever held as readlock with STATE enabled' |
| 36 | 36 | ||
| 37 | Where STATE can be either one of (kernel/lockdep_states.h) | 37 | Where STATE can be either one of (kernel/lockdep_states.h) |
| 38 | - hardirq | 38 | - hardirq |
diff --git a/Documentation/markers.txt b/Documentation/markers.txt deleted file mode 100644 index d2b3d0e91b26..000000000000 --- a/Documentation/markers.txt +++ /dev/null | |||
| @@ -1,104 +0,0 @@ | |||
| 1 | Using the Linux Kernel Markers | ||
| 2 | |||
| 3 | Mathieu Desnoyers | ||
| 4 | |||
| 5 | |||
| 6 | This document introduces Linux Kernel Markers and their use. It provides | ||
| 7 | examples of how to insert markers in the kernel and connect probe functions to | ||
| 8 | them and provides some examples of probe functions. | ||
| 9 | |||
| 10 | |||
| 11 | * Purpose of markers | ||
| 12 | |||
| 13 | A marker placed in code provides a hook to call a function (probe) that you can | ||
| 14 | provide at runtime. A marker can be "on" (a probe is connected to it) or "off" | ||
| 15 | (no probe is attached). When a marker is "off" it has no effect, except for | ||
| 16 | adding a tiny time penalty (checking a condition for a branch) and space | ||
| 17 | penalty (adding a few bytes for the function call at the end of the | ||
| 18 | instrumented function and adds a data structure in a separate section). When a | ||
| 19 | marker is "on", the function you provide is called each time the marker is | ||
| 20 | executed, in the execution context of the caller. When the function provided | ||
| 21 | ends its execution, it returns to the caller (continuing from the marker site). | ||
| 22 | |||
| 23 | You can put markers at important locations in the code. Markers are | ||
| 24 | lightweight hooks that can pass an arbitrary number of parameters, | ||
| 25 | described in a printk-like format string, to the attached probe function. | ||
| 26 | |||
| 27 | They can be used for tracing and performance accounting. | ||
| 28 | |||
| 29 | |||
| 30 | * Usage | ||
| 31 | |||
| 32 | In order to use the macro trace_mark, you should include linux/marker.h. | ||
| 33 | |||
| 34 | #include <linux/marker.h> | ||
| 35 | |||
| 36 | And, | ||
| 37 | |||
| 38 | trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring); | ||
| 39 | Where : | ||
| 40 | - subsystem_event is an identifier unique to your event | ||
| 41 | - subsystem is the name of your subsystem. | ||
| 42 | - event is the name of the event to mark. | ||
| 43 | - "myint %d mystring %s" is the formatted string for the serializer. "myint" and | ||
| 44 | "mystring" are repectively the field names associated with the first and | ||
| 45 | second parameter. | ||
| 46 | - someint is an integer. | ||
| 47 | - somestring is a char pointer. | ||
| 48 | |||
| 49 | Connecting a function (probe) to a marker is done by providing a probe (function | ||
| 50 | to call) for the specific marker through marker_probe_register() and can be | ||
| 51 | activated by calling marker_arm(). Marker deactivation can be done by calling | ||
| 52 | marker_disarm() as many times as marker_arm() has been called. Removing a probe | ||
| 53 | is done through marker_probe_unregister(); it will disarm the probe. | ||
| 54 | |||
| 55 | marker_synchronize_unregister() must be called between probe unregistration and | ||
| 56 | the first occurrence of | ||
| 57 | - the end of module exit function, | ||
| 58 | to make sure there is no caller left using the probe; | ||
| 59 | - the free of any resource used by the probes, | ||
| 60 | to make sure the probes wont be accessing invalid data. | ||
| 61 | This, and the fact that preemption is disabled around the probe call, make sure | ||
| 62 | that probe removal and module unload are safe. See the "Probe example" section | ||
| 63 | below for a sample probe module. | ||
| 64 | |||
| 65 | The marker mechanism supports inserting multiple instances of the same marker. | ||
| 66 | Markers can be put in inline functions, inlined static functions, and | ||
| 67 | unrolled loops as well as regular functions. | ||
| 68 | |||
| 69 | The naming scheme "subsystem_event" is suggested here as a convention intended | ||
| 70 | to limit collisions. Marker names are global to the kernel: they are considered | ||
| 71 | as being the same whether they are in the core kernel image or in modules. | ||
| 72 | Conflicting format strings for markers with the same name will cause the markers | ||
| 73 | to be detected to have a different format string not to be armed and will output | ||
| 74 | a printk warning which identifies the inconsistency: | ||
| 75 | |||
| 76 | "Format mismatch for probe probe_name (format), marker (format)" | ||
| 77 | |||
| 78 | Another way to use markers is to simply define the marker without generating any | ||
| 79 | function call to actually call into the marker. This is useful in combination | ||
| 80 | with tracepoint probes in a scheme like this : | ||
| 81 | |||
| 82 | void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk); | ||
| 83 | |||
| 84 | DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name, | ||
| 85 | "arg1 %u pid %d"); | ||
| 86 | |||
| 87 | notrace void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk) | ||
| 88 | { | ||
| 89 | struct marker *marker = &GET_MARKER(kernel_irq_entry); | ||
| 90 | /* write data to trace buffers ... */ | ||
| 91 | } | ||
| 92 | |||
| 93 | * Probe / marker example | ||
| 94 | |||
| 95 | See the example provided in samples/markers/src | ||
| 96 | |||
| 97 | Compile them with your kernel. | ||
| 98 | |||
| 99 | Run, as root : | ||
| 100 | modprobe marker-example (insmod order is not important) | ||
| 101 | modprobe probe-example | ||
| 102 | cat /proc/marker-example (returns an expected error) | ||
| 103 | rmmod marker-example probe-example | ||
| 104 | dmesg | ||
diff --git a/Documentation/memory.txt b/Documentation/memory.txt index 2b3dedd39538..802efe58647c 100644 --- a/Documentation/memory.txt +++ b/Documentation/memory.txt | |||
| @@ -1,18 +1,7 @@ | |||
| 1 | There are several classic problems related to memory on Linux | 1 | There are several classic problems related to memory on Linux |
| 2 | systems. | 2 | systems. |
| 3 | 3 | ||
| 4 | 1) There are some buggy motherboards which cannot properly | 4 | 1) There are some motherboards that will not cache above |
| 5 | deal with the memory above 16MB. Consider exchanging | ||
| 6 | your motherboard. | ||
| 7 | |||
| 8 | 2) You cannot do DMA on the ISA bus to addresses above | ||
| 9 | 16M. Most device drivers under Linux allow the use | ||
| 10 | of bounce buffers which work around this problem. Drivers | ||
| 11 | that don't use bounce buffers will be unstable with | ||
| 12 | more than 16M installed. Drivers that use bounce buffers | ||
| 13 | will be OK, but may have slightly higher overhead. | ||
| 14 | |||
| 15 | 3) There are some motherboards that will not cache above | ||
| 16 | a certain quantity of memory. If you have one of these | 5 | a certain quantity of memory. If you have one of these |
| 17 | motherboards, your system will be SLOWER, not faster | 6 | motherboards, your system will be SLOWER, not faster |
| 18 | as you add more memory. Consider exchanging your | 7 | as you add more memory. Consider exchanging your |
| @@ -24,7 +13,7 @@ It can also tell Linux to use less memory than is actually installed. | |||
| 24 | If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid | 13 | If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid |
| 25 | physical address space collisions. | 14 | physical address space collisions. |
| 26 | 15 | ||
| 27 | See the documentation of your boot loader (LILO, loadlin, etc.) about | 16 | See the documentation of your boot loader (LILO, grub, loadlin, etc.) about |
| 28 | how to pass options to the kernel. | 17 | how to pass options to the kernel. |
| 29 | 18 | ||
| 30 | There are other memory problems which Linux cannot deal with. Random | 19 | There are other memory problems which Linux cannot deal with. Random |
| @@ -42,19 +31,3 @@ Try: | |||
| 42 | with the vendor. Consider testing it with memtest86 yourself. | 31 | with the vendor. Consider testing it with memtest86 yourself. |
| 43 | 32 | ||
| 44 | * Exchanging your CPU, cache, or motherboard for one that works. | 33 | * Exchanging your CPU, cache, or motherboard for one that works. |
| 45 | |||
| 46 | * Disabling the cache from the BIOS. | ||
| 47 | |||
| 48 | * Try passing the "mem=4M" option to the kernel to limit | ||
| 49 | Linux to using a very small amount of memory. Use "memmap="-option | ||
| 50 | together with "mem=" on systems with PCI to avoid physical address | ||
| 51 | space collisions. | ||
| 52 | |||
| 53 | |||
| 54 | Other tricks: | ||
| 55 | |||
| 56 | * Try passing the "no-387" option to the kernel to ignore | ||
| 57 | a buggy FPU. | ||
| 58 | |||
| 59 | * Try passing the "no-hlt" option to disable the potentially | ||
| 60 | buggy HLT instruction in your CPU. | ||
diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index 1634c6dcecae..50189bf07d53 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX | |||
| @@ -60,6 +60,8 @@ framerelay.txt | |||
| 60 | - info on using Frame Relay/Data Link Connection Identifier (DLCI). | 60 | - info on using Frame Relay/Data Link Connection Identifier (DLCI). |
| 61 | generic_netlink.txt | 61 | generic_netlink.txt |
| 62 | - info on Generic Netlink | 62 | - info on Generic Netlink |
| 63 | ieee802154.txt | ||
| 64 | - Linux IEEE 802.15.4 implementation, API and drivers | ||
| 63 | ip-sysctl.txt | 65 | ip-sysctl.txt |
| 64 | - /proc/sys/net/ipv4/* variables | 66 | - /proc/sys/net/ipv4/* variables |
| 65 | ip_dynaddr.txt | 67 | ip_dynaddr.txt |
diff --git a/Documentation/networking/6pack.txt b/Documentation/networking/6pack.txt index d0777a1200e1..8f339428fdf4 100644 --- a/Documentation/networking/6pack.txt +++ b/Documentation/networking/6pack.txt | |||
| @@ -1,7 +1,7 @@ | |||
| 1 | This is the 6pack-mini-HOWTO, written by | 1 | This is the 6pack-mini-HOWTO, written by |
| 2 | 2 | ||
| 3 | Andreas Könsgen DG3KQ | 3 | Andreas Könsgen DG3KQ |
| 4 | Internet: ajk@iehk.rwth-aachen.de | 4 | Internet: ajk@comnets.uni-bremen.de |
| 5 | AMPR-net: dg3kq@db0pra.ampr.org | 5 | AMPR-net: dg3kq@db0pra.ampr.org |
| 6 | AX.25: dg3kq@db0ach.#nrw.deu.eu | 6 | AX.25: dg3kq@db0ach.#nrw.deu.eu |
| 7 | 7 | ||
diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt index a0280ad2edc9..23c995e64032 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.txt | |||
| @@ -22,7 +22,7 @@ int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); | |||
| 22 | ..... | 22 | ..... |
| 23 | 23 | ||
| 24 | The address family, socket addresses etc. are defined in the | 24 | The address family, socket addresses etc. are defined in the |
| 25 | include/net/ieee802154/af_ieee802154.h header or in the special header | 25 | include/net/af_ieee802154.h header or in the special header |
| 26 | in our userspace package (see either linux-zigbee sourceforge download page | 26 | in our userspace package (see either linux-zigbee sourceforge download page |
| 27 | or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee). | 27 | or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee). |
| 28 | 28 | ||
| @@ -33,7 +33,7 @@ MLME - MAC Level Management | |||
| 33 | ============================ | 33 | ============================ |
| 34 | 34 | ||
| 35 | Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands. | 35 | Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands. |
| 36 | See the include/net/ieee802154/nl802154.h header. Our userspace tools package | 36 | See the include/net/nl802154.h header. Our userspace tools package |
| 37 | (see above) provides CLI configuration utility for radio interfaces and simple | 37 | (see above) provides CLI configuration utility for radio interfaces and simple |
| 38 | coordinator for IEEE 802.15.4 networks as an example users of MLME protocol. | 38 | coordinator for IEEE 802.15.4 networks as an example users of MLME protocol. |
| 39 | 39 | ||
| @@ -54,10 +54,14 @@ Those types of devices require different approach to be hooked into Linux kernel | |||
| 54 | HardMAC | 54 | HardMAC |
| 55 | ======= | 55 | ======= |
| 56 | 56 | ||
| 57 | See the header include/net/ieee802154/netdevice.h. You have to implement Linux | 57 | See the header include/net/ieee802154_netdev.h. You have to implement Linux |
| 58 | net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family | 58 | net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family |
| 59 | code via plain sk_buffs. The control block of sk_buffs will contain additional | 59 | code via plain sk_buffs. On skb reception skb->cb must contain additional |
| 60 | info as described in the struct ieee802154_mac_cb. | 60 | info as described in the struct ieee802154_mac_cb. During packet transmission |
| 61 | the skb->cb is used to provide additional data to device's header_ops->create | ||
| 62 | function. Be aware, that this data can be overriden later (when socket code | ||
| 63 | submits skb to qdisc), so if you need something from that cb later, you should | ||
| 64 | store info in the skb->data on your own. | ||
| 61 | 65 | ||
| 62 | To hook the MLME interface you have to populate the ml_priv field of your | 66 | To hook the MLME interface you have to populate the ml_priv field of your |
| 63 | net_device with a pointer to struct ieee802154_mlme_ops instance. All fields are | 67 | net_device with a pointer to struct ieee802154_mlme_ops instance. All fields are |
| @@ -69,8 +73,8 @@ We provide an example of simple HardMAC driver at drivers/ieee802154/fakehard.c | |||
| 69 | SoftMAC | 73 | SoftMAC |
| 70 | ======= | 74 | ======= |
| 71 | 75 | ||
| 72 | We are going to provide intermediate layer impelementing IEEE 802.15.4 MAC | 76 | We are going to provide intermediate layer implementing IEEE 802.15.4 MAC |
| 73 | in software. This is currently WIP. | 77 | in software. This is currently WIP. |
| 74 | 78 | ||
| 75 | See header include/net/ieee802154/mac802154.h and several drivers in | 79 | See header include/net/mac802154.h and several drivers in drivers/ieee802154/. |
| 76 | drivers/ieee802154/ | 80 | |
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 8be76235fe67..fbe427a6580c 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt | |||
| @@ -311,9 +311,12 @@ tcp_no_metrics_save - BOOLEAN | |||
| 311 | connections. | 311 | connections. |
| 312 | 312 | ||
| 313 | tcp_orphan_retries - INTEGER | 313 | tcp_orphan_retries - INTEGER |
| 314 | How may times to retry before killing TCP connection, closed | 314 | This value influences the timeout of a locally closed TCP connection, |
| 315 | by our side. Default value 7 corresponds to ~50sec-16min | 315 | when RTO retransmissions remain unacknowledged. |
| 316 | depending on RTO. If you machine is loaded WEB server, | 316 | See tcp_retries2 for more details. |
| 317 | |||
| 318 | The default value is 7. | ||
| 319 | If your machine is a loaded WEB server, | ||
| 317 | you should think about lowering this value, such sockets | 320 | you should think about lowering this value, such sockets |
| 318 | may consume significant resources. Cf. tcp_max_orphans. | 321 | may consume significant resources. Cf. tcp_max_orphans. |
| 319 | 322 | ||
| @@ -327,16 +330,28 @@ tcp_retrans_collapse - BOOLEAN | |||
| 327 | certain TCP stacks. | 330 | certain TCP stacks. |
| 328 | 331 | ||
| 329 | tcp_retries1 - INTEGER | 332 | tcp_retries1 - INTEGER |
| 330 | How many times to retry before deciding that something is wrong | 333 | This value influences the time, after which TCP decides, that |
| 331 | and it is necessary to report this suspicion to network layer. | 334 | something is wrong due to unacknowledged RTO retransmissions, |
| 332 | Minimal RFC value is 3, it is default, which corresponds | 335 | and reports this suspicion to the network layer. |
| 333 | to ~3sec-8min depending on RTO. | 336 | See tcp_retries2 for more details. |
| 337 | |||
| 338 | RFC 1122 recommends at least 3 retransmissions, which is the | ||
| 339 | default. | ||
| 334 | 340 | ||
| 335 | tcp_retries2 - INTEGER | 341 | tcp_retries2 - INTEGER |
| 336 | How may times to retry before killing alive TCP connection. | 342 | This value influences the timeout of an alive TCP connection, |
| 337 | RFC1122 says that the limit should be longer than 100 sec. | 343 | when RTO retransmissions remain unacknowledged. |
| 338 | It is too small number. Default value 15 corresponds to ~13-30min | 344 | Given a value of N, a hypothetical TCP connection following |
| 339 | depending on RTO. | 345 | exponential backoff with an initial RTO of TCP_RTO_MIN would |
| 346 | retransmit N times before killing the connection at the (N+1)th RTO. | ||
| 347 | |||
| 348 | The default value of 15 yields a hypothetical timeout of 924.6 | ||
| 349 | seconds and is a lower bound for the effective timeout. | ||
| 350 | TCP will effectively time out at the first RTO which exceeds the | ||
| 351 | hypothetical timeout. | ||
| 352 | |||
| 353 | RFC 1122 recommends at least 100 seconds for the timeout, | ||
| 354 | which corresponds to a value of at least 8. | ||
| 340 | 355 | ||
| 341 | tcp_rfc1337 - BOOLEAN | 356 | tcp_rfc1337 - BOOLEAN |
| 342 | If set, the TCP stack behaves conforming to RFC1337. If unset, | 357 | If set, the TCP stack behaves conforming to RFC1337. If unset, |
| @@ -1282,6 +1297,16 @@ sctp_rmem - vector of 3 INTEGERs: min, default, max | |||
| 1282 | sctp_wmem - vector of 3 INTEGERs: min, default, max | 1297 | sctp_wmem - vector of 3 INTEGERs: min, default, max |
| 1283 | See tcp_wmem for a description. | 1298 | See tcp_wmem for a description. |
| 1284 | 1299 | ||
| 1300 | addr_scope_policy - INTEGER | ||
| 1301 | Control IPv4 address scoping - draft-stewart-tsvwg-sctp-ipv4-00 | ||
| 1302 | |||
| 1303 | 0 - Disable IPv4 address scoping | ||
| 1304 | 1 - Enable IPv4 address scoping | ||
| 1305 | 2 - Follow draft but allow IPv4 private addresses | ||
| 1306 | 3 - Follow draft but allow IPv4 link local addresses | ||
| 1307 | |||
| 1308 | Default: 1 | ||
| 1309 | |||
| 1285 | 1310 | ||
| 1286 | /proc/sys/net/core/* | 1311 | /proc/sys/net/core/* |
| 1287 | dev_weight - INTEGER | 1312 | dev_weight - INTEGER |
diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt index eaa1a25946c1..ee31369e9e5b 100644 --- a/Documentation/networking/regulatory.txt +++ b/Documentation/networking/regulatory.txt | |||
| @@ -96,7 +96,7 @@ Example code - drivers hinting an alpha2: | |||
| 96 | 96 | ||
| 97 | This example comes from the zd1211rw device driver. You can start | 97 | This example comes from the zd1211rw device driver. You can start |
| 98 | by having a mapping of your device's EEPROM country/regulatory | 98 | by having a mapping of your device's EEPROM country/regulatory |
| 99 | domain value to to a specific alpha2 as follows: | 99 | domain value to a specific alpha2 as follows: |
| 100 | 100 | ||
| 101 | static struct zd_reg_alpha2_map reg_alpha2_map[] = { | 101 | static struct zd_reg_alpha2_map reg_alpha2_map[] = { |
| 102 | { ZD_REGDOMAIN_FCC, "US" }, | 102 | { ZD_REGDOMAIN_FCC, "US" }, |
diff --git a/Documentation/numastat.txt b/Documentation/numastat.txt index 80133ace1eb2..9fcc9a608dc0 100644 --- a/Documentation/numastat.txt +++ b/Documentation/numastat.txt | |||
| @@ -7,10 +7,10 @@ All units are pages. Hugepages have separate counters. | |||
| 7 | 7 | ||
| 8 | numa_hit A process wanted to allocate memory from this node, | 8 | numa_hit A process wanted to allocate memory from this node, |
| 9 | and succeeded. | 9 | and succeeded. |
| 10 | numa_miss A process wanted to allocate memory from this node, | 10 | numa_miss A process wanted to allocate memory from another node, |
| 11 | but ended up with memory from another. | 11 | but ended up with memory from this node. |
| 12 | numa_foreign A process wanted to allocate on another node, | 12 | numa_foreign A process wanted to allocate on this node, |
| 13 | but ended up with memory from this one. | 13 | but ended up with memory from another one. |
| 14 | local_node A process ran on this node and got memory from it. | 14 | local_node A process ran on this node and got memory from it. |
| 15 | other_node A process ran on this node and got memory from another node. | 15 | other_node A process ran on this node and got memory from another node. |
| 16 | interleave_hit Interleaving wanted to allocate from this node | 16 | interleave_hit Interleaving wanted to allocate from this node |
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt new file mode 100644 index 000000000000..f49a33b704d2 --- /dev/null +++ b/Documentation/power/runtime_pm.txt | |||
| @@ -0,0 +1,378 @@ | |||
| 1 | Run-time Power Management Framework for I/O Devices | ||
| 2 | |||
| 3 | (C) 2009 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. | ||
| 4 | |||
| 5 | 1. Introduction | ||
| 6 | |||
| 7 | Support for run-time power management (run-time PM) of I/O devices is provided | ||
| 8 | at the power management core (PM core) level by means of: | ||
| 9 | |||
| 10 | * The power management workqueue pm_wq in which bus types and device drivers can | ||
| 11 | put their PM-related work items. It is strongly recommended that pm_wq be | ||
| 12 | used for queuing all work items related to run-time PM, because this allows | ||
| 13 | them to be synchronized with system-wide power transitions (suspend to RAM, | ||
| 14 | hibernation and resume from system sleep states). pm_wq is declared in | ||
| 15 | include/linux/pm_runtime.h and defined in kernel/power/main.c. | ||
| 16 | |||
| 17 | * A number of run-time PM fields in the 'power' member of 'struct device' (which | ||
| 18 | is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can | ||
| 19 | be used for synchronizing run-time PM operations with one another. | ||
| 20 | |||
| 21 | * Three device run-time PM callbacks in 'struct dev_pm_ops' (defined in | ||
| 22 | include/linux/pm.h). | ||
| 23 | |||
| 24 | * A set of helper functions defined in drivers/base/power/runtime.c that can be | ||
| 25 | used for carrying out run-time PM operations in such a way that the | ||
| 26 | synchronization between them is taken care of by the PM core. Bus types and | ||
| 27 | device drivers are encouraged to use these functions. | ||
| 28 | |||
| 29 | The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM | ||
| 30 | fields of 'struct dev_pm_info' and the core helper functions provided for | ||
| 31 | run-time PM are described below. | ||
| 32 | |||
| 33 | 2. Device Run-time PM Callbacks | ||
| 34 | |||
| 35 | There are three device run-time PM callbacks defined in 'struct dev_pm_ops': | ||
| 36 | |||
| 37 | struct dev_pm_ops { | ||
| 38 | ... | ||
| 39 | int (*runtime_suspend)(struct device *dev); | ||
| 40 | int (*runtime_resume)(struct device *dev); | ||
| 41 | void (*runtime_idle)(struct device *dev); | ||
| 42 | ... | ||
| 43 | }; | ||
| 44 | |||
| 45 | The ->runtime_suspend() callback is executed by the PM core for the bus type of | ||
| 46 | the device being suspended. The bus type's callback is then _entirely_ | ||
| 47 | _responsible_ for handling the device as appropriate, which may, but need not | ||
| 48 | include executing the device driver's own ->runtime_suspend() callback (from the | ||
| 49 | PM core's point of view it is not necessary to implement a ->runtime_suspend() | ||
| 50 | callback in a device driver as long as the bus type's ->runtime_suspend() knows | ||
| 51 | what to do to handle the device). | ||
| 52 | |||
| 53 | * Once the bus type's ->runtime_suspend() callback has completed successfully | ||
| 54 | for given device, the PM core regards the device as suspended, which need | ||
| 55 | not mean that the device has been put into a low power state. It is | ||
| 56 | supposed to mean, however, that the device will not process data and will | ||
| 57 | not communicate with the CPU(s) and RAM until its bus type's | ||
| 58 | ->runtime_resume() callback is executed for it. The run-time PM status of | ||
| 59 | a device after successful execution of its bus type's ->runtime_suspend() | ||
| 60 | callback is 'suspended'. | ||
| 61 | |||
| 62 | * If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN, | ||
| 63 | the device's run-time PM status is supposed to be 'active', which means that | ||
| 64 | the device _must_ be fully operational afterwards. | ||
| 65 | |||
| 66 | * If the bus type's ->runtime_suspend() callback returns an error code | ||
| 67 | different from -EBUSY or -EAGAIN, the PM core regards this as a fatal | ||
| 68 | error and will refuse to run the helper functions described in Section 4 | ||
| 69 | for the device, until the status of it is directly set either to 'active' | ||
| 70 | or to 'suspended' (the PM core provides special helper functions for this | ||
| 71 | purpose). | ||
| 72 | |||
| 73 | In particular, if the driver requires remote wakeup capability for proper | ||
| 74 | functioning and device_may_wakeup() returns 'false' for the device, then | ||
| 75 | ->runtime_suspend() should return -EBUSY. On the other hand, if | ||
| 76 | device_may_wakeup() returns 'true' for the device and the device is put | ||
| 77 | into a low power state during the execution of its bus type's | ||
| 78 | ->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism | ||
| 79 | allowing the device to request a change of its power state, such as PCI PME) | ||
| 80 | will be enabled for the device. Generally, remote wake-up should be enabled | ||
| 81 | for all input devices put into a low power state at run time. | ||
| 82 | |||
| 83 | The ->runtime_resume() callback is executed by the PM core for the bus type of | ||
| 84 | the device being woken up. The bus type's callback is then _entirely_ | ||
| 85 | _responsible_ for handling the device as appropriate, which may, but need not | ||
| 86 | include executing the device driver's own ->runtime_resume() callback (from the | ||
| 87 | PM core's point of view it is not necessary to implement a ->runtime_resume() | ||
| 88 | callback in a device driver as long as the bus type's ->runtime_resume() knows | ||
| 89 | what to do to handle the device). | ||
| 90 | |||
| 91 | * Once the bus type's ->runtime_resume() callback has completed successfully, | ||
| 92 | the PM core regards the device as fully operational, which means that the | ||
| 93 | device _must_ be able to complete I/O operations as needed. The run-time | ||
| 94 | PM status of the device is then 'active'. | ||
| 95 | |||
| 96 | * If the bus type's ->runtime_resume() callback returns an error code, the PM | ||
| 97 | core regards this as a fatal error and will refuse to run the helper | ||
| 98 | functions described in Section 4 for the device, until its status is | ||
| 99 | directly set either to 'active' or to 'suspended' (the PM core provides | ||
| 100 | special helper functions for this purpose). | ||
| 101 | |||
| 102 | The ->runtime_idle() callback is executed by the PM core for the bus type of | ||
| 103 | given device whenever the device appears to be idle, which is indicated to the | ||
| 104 | PM core by two counters, the device's usage counter and the counter of 'active' | ||
| 105 | children of the device. | ||
| 106 | |||
| 107 | * If any of these counters is decreased using a helper function provided by | ||
| 108 | the PM core and it turns out to be equal to zero, the other counter is | ||
| 109 | checked. If that counter also is equal to zero, the PM core executes the | ||
| 110 | device bus type's ->runtime_idle() callback (with the device as an | ||
| 111 | argument). | ||
| 112 | |||
| 113 | The action performed by a bus type's ->runtime_idle() callback is totally | ||
| 114 | dependent on the bus type in question, but the expected and recommended action | ||
| 115 | is to check if the device can be suspended (i.e. if all of the conditions | ||
| 116 | necessary for suspending the device are satisfied) and to queue up a suspend | ||
| 117 | request for the device in that case. | ||
| 118 | |||
| 119 | The helper functions provided by the PM core, described in Section 4, guarantee | ||
| 120 | that the following constraints are met with respect to the bus type's run-time | ||
| 121 | PM callbacks: | ||
| 122 | |||
| 123 | (1) The callbacks are mutually exclusive (e.g. it is forbidden to execute | ||
| 124 | ->runtime_suspend() in parallel with ->runtime_resume() or with another | ||
| 125 | instance of ->runtime_suspend() for the same device) with the exception that | ||
| 126 | ->runtime_suspend() or ->runtime_resume() can be executed in parallel with | ||
| 127 | ->runtime_idle() (although ->runtime_idle() will not be started while any | ||
| 128 | of the other callbacks is being executed for the same device). | ||
| 129 | |||
| 130 | (2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active' | ||
| 131 | devices (i.e. the PM core will only execute ->runtime_idle() or | ||
| 132 | ->runtime_suspend() for the devices the run-time PM status of which is | ||
| 133 | 'active'). | ||
| 134 | |||
| 135 | (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device | ||
| 136 | the usage counter of which is equal to zero _and_ either the counter of | ||
| 137 | 'active' children of which is equal to zero, or the 'power.ignore_children' | ||
| 138 | flag of which is set. | ||
| 139 | |||
| 140 | (4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the | ||
| 141 | PM core will only execute ->runtime_resume() for the devices the run-time | ||
| 142 | PM status of which is 'suspended'). | ||
| 143 | |||
| 144 | Additionally, the helper functions provided by the PM core obey the following | ||
| 145 | rules: | ||
| 146 | |||
| 147 | * If ->runtime_suspend() is about to be executed or there's a pending request | ||
| 148 | to execute it, ->runtime_idle() will not be executed for the same device. | ||
| 149 | |||
| 150 | * A request to execute or to schedule the execution of ->runtime_suspend() | ||
| 151 | will cancel any pending requests to execute ->runtime_idle() for the same | ||
| 152 | device. | ||
| 153 | |||
| 154 | * If ->runtime_resume() is about to be executed or there's a pending request | ||
| 155 | to execute it, the other callbacks will not be executed for the same device. | ||
| 156 | |||
| 157 | * A request to execute ->runtime_resume() will cancel any pending or | ||
| 158 | scheduled requests to execute the other callbacks for the same device. | ||
| 159 | |||
| 160 | 3. Run-time PM Device Fields | ||
| 161 | |||
| 162 | The following device run-time PM fields are present in 'struct dev_pm_info', as | ||
| 163 | defined in include/linux/pm.h: | ||
| 164 | |||
| 165 | struct timer_list suspend_timer; | ||
| 166 | - timer used for scheduling (delayed) suspend request | ||
| 167 | |||
| 168 | unsigned long timer_expires; | ||
| 169 | - timer expiration time, in jiffies (if this is different from zero, the | ||
| 170 | timer is running and will expire at that time, otherwise the timer is not | ||
| 171 | running) | ||
| 172 | |||
| 173 | struct work_struct work; | ||
| 174 | - work structure used for queuing up requests (i.e. work items in pm_wq) | ||
| 175 | |||
| 176 | wait_queue_head_t wait_queue; | ||
| 177 | - wait queue used if any of the helper functions needs to wait for another | ||
| 178 | one to complete | ||
| 179 | |||
| 180 | spinlock_t lock; | ||
| 181 | - lock used for synchronisation | ||
| 182 | |||
| 183 | atomic_t usage_count; | ||
| 184 | - the usage counter of the device | ||
| 185 | |||
| 186 | atomic_t child_count; | ||
| 187 | - the count of 'active' children of the device | ||
| 188 | |||
| 189 | unsigned int ignore_children; | ||
| 190 | - if set, the value of child_count is ignored (but still updated) | ||
| 191 | |||
| 192 | unsigned int disable_depth; | ||
| 193 | - used for disabling the helper funcions (they work normally if this is | ||
| 194 | equal to zero); the initial value of it is 1 (i.e. run-time PM is | ||
| 195 | initially disabled for all devices) | ||
| 196 | |||
| 197 | unsigned int runtime_error; | ||
| 198 | - if set, there was a fatal error (one of the callbacks returned error code | ||
| 199 | as described in Section 2), so the helper funtions will not work until | ||
| 200 | this flag is cleared; this is the error code returned by the failing | ||
| 201 | callback | ||
| 202 | |||
| 203 | unsigned int idle_notification; | ||
| 204 | - if set, ->runtime_idle() is being executed | ||
| 205 | |||
| 206 | unsigned int request_pending; | ||
| 207 | - if set, there's a pending request (i.e. a work item queued up into pm_wq) | ||
| 208 | |||
| 209 | enum rpm_request request; | ||
| 210 | - type of request that's pending (valid if request_pending is set) | ||
| 211 | |||
| 212 | unsigned int deferred_resume; | ||
| 213 | - set if ->runtime_resume() is about to be run while ->runtime_suspend() is | ||
| 214 | being executed for that device and it is not practical to wait for the | ||
| 215 | suspend to complete; means "start a resume as soon as you've suspended" | ||
| 216 | |||
| 217 | enum rpm_status runtime_status; | ||
| 218 | - the run-time PM status of the device; this field's initial value is | ||
| 219 | RPM_SUSPENDED, which means that each device is initially regarded by the | ||
| 220 | PM core as 'suspended', regardless of its real hardware status | ||
| 221 | |||
| 222 | All of the above fields are members of the 'power' member of 'struct device'. | ||
| 223 | |||
| 224 | 4. Run-time PM Device Helper Functions | ||
| 225 | |||
| 226 | The following run-time PM helper functions are defined in | ||
| 227 | drivers/base/power/runtime.c and include/linux/pm_runtime.h: | ||
| 228 | |||
| 229 | void pm_runtime_init(struct device *dev); | ||
| 230 | - initialize the device run-time PM fields in 'struct dev_pm_info' | ||
| 231 | |||
| 232 | void pm_runtime_remove(struct device *dev); | ||
| 233 | - make sure that the run-time PM of the device will be disabled after | ||
| 234 | removing the device from device hierarchy | ||
| 235 | |||
| 236 | int pm_runtime_idle(struct device *dev); | ||
| 237 | - execute ->runtime_idle() for the device's bus type; returns 0 on success | ||
| 238 | or error code on failure, where -EINPROGRESS means that ->runtime_idle() | ||
| 239 | is already being executed | ||
| 240 | |||
| 241 | int pm_runtime_suspend(struct device *dev); | ||
| 242 | - execute ->runtime_suspend() for the device's bus type; returns 0 on | ||
| 243 | success, 1 if the device's run-time PM status was already 'suspended', or | ||
| 244 | error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt | ||
| 245 | to suspend the device again in future | ||
| 246 | |||
| 247 | int pm_runtime_resume(struct device *dev); | ||
| 248 | - execute ->runtime_resume() for the device's bus type; returns 0 on | ||
| 249 | success, 1 if the device's run-time PM status was already 'active' or | ||
| 250 | error code on failure, where -EAGAIN means it may be safe to attempt to | ||
| 251 | resume the device again in future, but 'power.runtime_error' should be | ||
| 252 | checked additionally | ||
| 253 | |||
| 254 | int pm_request_idle(struct device *dev); | ||
| 255 | - submit a request to execute ->runtime_idle() for the device's bus type | ||
| 256 | (the request is represented by a work item in pm_wq); returns 0 on success | ||
| 257 | or error code if the request has not been queued up | ||
| 258 | |||
| 259 | int pm_schedule_suspend(struct device *dev, unsigned int delay); | ||
| 260 | - schedule the execution of ->runtime_suspend() for the device's bus type | ||
| 261 | in future, where 'delay' is the time to wait before queuing up a suspend | ||
| 262 | work item in pm_wq, in milliseconds (if 'delay' is zero, the work item is | ||
| 263 | queued up immediately); returns 0 on success, 1 if the device's PM | ||
| 264 | run-time status was already 'suspended', or error code if the request | ||
| 265 | hasn't been scheduled (or queued up if 'delay' is 0); if the execution of | ||
| 266 | ->runtime_suspend() is already scheduled and not yet expired, the new | ||
| 267 | value of 'delay' will be used as the time to wait | ||
| 268 | |||
| 269 | int pm_request_resume(struct device *dev); | ||
| 270 | - submit a request to execute ->runtime_resume() for the device's bus type | ||
| 271 | (the request is represented by a work item in pm_wq); returns 0 on | ||
| 272 | success, 1 if the device's run-time PM status was already 'active', or | ||
| 273 | error code if the request hasn't been queued up | ||
| 274 | |||
| 275 | void pm_runtime_get_noresume(struct device *dev); | ||
| 276 | - increment the device's usage counter | ||
| 277 | |||
| 278 | int pm_runtime_get(struct device *dev); | ||
| 279 | - increment the device's usage counter, run pm_request_resume(dev) and | ||
| 280 | return its result | ||
| 281 | |||
| 282 | int pm_runtime_get_sync(struct device *dev); | ||
| 283 | - increment the device's usage counter, run pm_runtime_resume(dev) and | ||
| 284 | return its result | ||
| 285 | |||
| 286 | void pm_runtime_put_noidle(struct device *dev); | ||
| 287 | - decrement the device's usage counter | ||
| 288 | |||
| 289 | int pm_runtime_put(struct device *dev); | ||
| 290 | - decrement the device's usage counter, run pm_request_idle(dev) and return | ||
| 291 | its result | ||
| 292 | |||
| 293 | int pm_runtime_put_sync(struct device *dev); | ||
| 294 | - decrement the device's usage counter, run pm_runtime_idle(dev) and return | ||
| 295 | its result | ||
| 296 | |||
| 297 | void pm_runtime_enable(struct device *dev); | ||
| 298 | - enable the run-time PM helper functions to run the device bus type's | ||
| 299 | run-time PM callbacks described in Section 2 | ||
| 300 | |||
| 301 | int pm_runtime_disable(struct device *dev); | ||
| 302 | - prevent the run-time PM helper functions from running the device bus | ||
| 303 | type's run-time PM callbacks, make sure that all of the pending run-time | ||
| 304 | PM operations on the device are either completed or canceled; returns | ||
| 305 | 1 if there was a resume request pending and it was necessary to execute | ||
| 306 | ->runtime_resume() for the device's bus type to satisfy that request, | ||
| 307 | otherwise 0 is returned | ||
| 308 | |||
| 309 | void pm_suspend_ignore_children(struct device *dev, bool enable); | ||
| 310 | - set/unset the power.ignore_children flag of the device | ||
| 311 | |||
| 312 | int pm_runtime_set_active(struct device *dev); | ||
| 313 | - clear the device's 'power.runtime_error' flag, set the device's run-time | ||
| 314 | PM status to 'active' and update its parent's counter of 'active' | ||
| 315 | children as appropriate (it is only valid to use this function if | ||
| 316 | 'power.runtime_error' is set or 'power.disable_depth' is greater than | ||
| 317 | zero); it will fail and return error code if the device has a parent | ||
| 318 | which is not active and the 'power.ignore_children' flag of which is unset | ||
| 319 | |||
| 320 | void pm_runtime_set_suspended(struct device *dev); | ||
| 321 | - clear the device's 'power.runtime_error' flag, set the device's run-time | ||
| 322 | PM status to 'suspended' and update its parent's counter of 'active' | ||
| 323 | children as appropriate (it is only valid to use this function if | ||
| 324 | 'power.runtime_error' is set or 'power.disable_depth' is greater than | ||
| 325 | zero) | ||
| 326 | |||
| 327 | It is safe to execute the following helper functions from interrupt context: | ||
| 328 | |||
| 329 | pm_request_idle() | ||
| 330 | pm_schedule_suspend() | ||
| 331 | pm_request_resume() | ||
| 332 | pm_runtime_get_noresume() | ||
| 333 | pm_runtime_get() | ||
| 334 | pm_runtime_put_noidle() | ||
| 335 | pm_runtime_put() | ||
| 336 | pm_suspend_ignore_children() | ||
| 337 | pm_runtime_set_active() | ||
| 338 | pm_runtime_set_suspended() | ||
| 339 | pm_runtime_enable() | ||
| 340 | |||
| 341 | 5. Run-time PM Initialization, Device Probing and Removal | ||
| 342 | |||
| 343 | Initially, the run-time PM is disabled for all devices, which means that the | ||
| 344 | majority of the run-time PM helper funtions described in Section 4 will return | ||
| 345 | -EAGAIN until pm_runtime_enable() is called for the device. | ||
| 346 | |||
| 347 | In addition to that, the initial run-time PM status of all devices is | ||
| 348 | 'suspended', but it need not reflect the actual physical state of the device. | ||
| 349 | Thus, if the device is initially active (i.e. it is able to process I/O), its | ||
| 350 | run-time PM status must be changed to 'active', with the help of | ||
| 351 | pm_runtime_set_active(), before pm_runtime_enable() is called for the device. | ||
| 352 | |||
| 353 | However, if the device has a parent and the parent's run-time PM is enabled, | ||
| 354 | calling pm_runtime_set_active() for the device will affect the parent, unless | ||
| 355 | the parent's 'power.ignore_children' flag is set. Namely, in that case the | ||
| 356 | parent won't be able to suspend at run time, using the PM core's helper | ||
| 357 | functions, as long as the child's status is 'active', even if the child's | ||
| 358 | run-time PM is still disabled (i.e. pm_runtime_enable() hasn't been called for | ||
| 359 | the child yet or pm_runtime_disable() has been called for it). For this reason, | ||
| 360 | once pm_runtime_set_active() has been called for the device, pm_runtime_enable() | ||
| 361 | should be called for it too as soon as reasonably possible or its run-time PM | ||
| 362 | status should be changed back to 'suspended' with the help of | ||
| 363 | pm_runtime_set_suspended(). | ||
| 364 | |||
| 365 | If the default initial run-time PM status of the device (i.e. 'suspended') | ||
| 366 | reflects the actual state of the device, its bus type's or its driver's | ||
| 367 | ->probe() callback will likely need to wake it up using one of the PM core's | ||
| 368 | helper functions described in Section 4. In that case, pm_runtime_resume() | ||
| 369 | should be used. Of course, for this purpose the device's run-time PM has to be | ||
| 370 | enabled earlier by calling pm_runtime_enable(). | ||
| 371 | |||
| 372 | If the device bus type's or driver's ->probe() or ->remove() callback runs | ||
| 373 | pm_runtime_suspend() or pm_runtime_idle() or their asynchronous counterparts, | ||
| 374 | they will fail returning -EAGAIN, because the device's usage counter is | ||
| 375 | incremented by the core before executing ->probe() and ->remove(). Still, it | ||
| 376 | may be desirable to suspend the device as soon as ->probe() or ->remove() has | ||
| 377 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the device bus | ||
| 378 | type's ->runtime_idle() callback at that time. | ||
diff --git a/Documentation/powerpc/dts-bindings/marvell.txt b/Documentation/powerpc/dts-bindings/marvell.txt index 3708a2fd4747..f1533d91953a 100644 --- a/Documentation/powerpc/dts-bindings/marvell.txt +++ b/Documentation/powerpc/dts-bindings/marvell.txt | |||
| @@ -32,7 +32,7 @@ prefixed with the string "marvell,", for Marvell Technology Group Ltd. | |||
| 32 | devices. This field represents the number of cells needed to | 32 | devices. This field represents the number of cells needed to |
| 33 | represent the address of the memory-mapped registers of devices | 33 | represent the address of the memory-mapped registers of devices |
| 34 | within the system controller chip. | 34 | within the system controller chip. |
| 35 | - #size-cells : Size representation for for the memory-mapped | 35 | - #size-cells : Size representation for the memory-mapped |
| 36 | registers within the system controller chip. | 36 | registers within the system controller chip. |
| 37 | - #interrupt-cells : Defines the width of cells used to represent | 37 | - #interrupt-cells : Defines the width of cells used to represent |
| 38 | interrupts. | 38 | interrupts. |
diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt index 2d10053dd97e..ae66f9b90a25 100644 --- a/Documentation/s390/s390dbf.txt +++ b/Documentation/s390/s390dbf.txt | |||
| @@ -495,6 +495,13 @@ and for each vararg a long value. So e.g. for a debug entry with a format | |||
| 495 | string plus two varargs one would need to allocate a (3 * sizeof(long)) | 495 | string plus two varargs one would need to allocate a (3 * sizeof(long)) |
| 496 | byte data area in the debug_register() function. | 496 | byte data area in the debug_register() function. |
| 497 | 497 | ||
| 498 | IMPORTANT: Using "%s" in sprintf event functions is dangerous. You can only | ||
| 499 | use "%s" in the sprintf event functions, if the memory for the passed string is | ||
| 500 | available as long as the debug feature exists. The reason behind this is that | ||
| 501 | due to performance considerations only a pointer to the string is stored in | ||
| 502 | the debug feature. If you log a string that is freed afterwards, you will get | ||
| 503 | an OOPS when inspecting the debug feature, because then the debug feature will | ||
| 504 | access the already freed memory. | ||
| 498 | 505 | ||
| 499 | NOTE: If using the sprintf view do NOT use other event/exception functions | 506 | NOTE: If using the sprintf view do NOT use other event/exception functions |
| 500 | than the sprintf-event and -exception functions. | 507 | than the sprintf-event and -exception functions. |
diff --git a/Documentation/scheduler/sched-rt-group.txt b/Documentation/scheduler/sched-rt-group.txt index 1df7f9cdab05..86eabe6c3419 100644 --- a/Documentation/scheduler/sched-rt-group.txt +++ b/Documentation/scheduler/sched-rt-group.txt | |||
| @@ -73,7 +73,7 @@ The remaining CPU time will be used for user input and other tasks. Because | |||
| 73 | realtime tasks have explicitly allocated the CPU time they need to perform | 73 | realtime tasks have explicitly allocated the CPU time they need to perform |
| 74 | their tasks, buffer underruns in the graphics or audio can be eliminated. | 74 | their tasks, buffer underruns in the graphics or audio can be eliminated. |
| 75 | 75 | ||
| 76 | NOTE: the above example is not fully implemented as of yet (2.6.25). We still | 76 | NOTE: the above example is not fully implemented yet. We still |
| 77 | lack an EDF scheduler to make non-uniform periods usable. | 77 | lack an EDF scheduler to make non-uniform periods usable. |
| 78 | 78 | ||
| 79 | 79 | ||
| @@ -140,14 +140,15 @@ The other option is: | |||
| 140 | 140 | ||
| 141 | .o CONFIG_CGROUP_SCHED (aka "Basis for grouping tasks" = "Control groups") | 141 | .o CONFIG_CGROUP_SCHED (aka "Basis for grouping tasks" = "Control groups") |
| 142 | 142 | ||
| 143 | This uses the /cgroup virtual file system and "/cgroup/<cgroup>/cpu.rt_runtime_us" | 143 | This uses the /cgroup virtual file system and |
| 144 | to control the CPU time reserved for each control group instead. | 144 | "/cgroup/<cgroup>/cpu.rt_runtime_us" to control the CPU time reserved for each |
| 145 | control group instead. | ||
| 145 | 146 | ||
| 146 | For more information on working with control groups, you should read | 147 | For more information on working with control groups, you should read |
| 147 | Documentation/cgroups/cgroups.txt as well. | 148 | Documentation/cgroups/cgroups.txt as well. |
| 148 | 149 | ||
| 149 | Group settings are checked against the following limits in order to keep the configuration | 150 | Group settings are checked against the following limits in order to keep the |
| 150 | schedulable: | 151 | configuration schedulable: |
| 151 | 152 | ||
| 152 | \Sum_{i} runtime_{i} / global_period <= global_runtime / global_period | 153 | \Sum_{i} runtime_{i} / global_period <= global_runtime / global_period |
| 153 | 154 | ||
| @@ -189,7 +190,7 @@ Implementing SCHED_EDF might take a while to complete. Priority Inheritance is | |||
| 189 | the biggest challenge as the current linux PI infrastructure is geared towards | 190 | the biggest challenge as the current linux PI infrastructure is geared towards |
| 190 | the limited static priority levels 0-99. With deadline scheduling you need to | 191 | the limited static priority levels 0-99. With deadline scheduling you need to |
| 191 | do deadline inheritance (since priority is inversely proportional to the | 192 | do deadline inheritance (since priority is inversely proportional to the |
| 192 | deadline delta (deadline - now). | 193 | deadline delta (deadline - now)). |
| 193 | 194 | ||
| 194 | This means the whole PI machinery will have to be reworked - and that is one of | 195 | This means the whole PI machinery will have to be reworked - and that is one of |
| 195 | the most complex pieces of code we have. | 196 | the most complex pieces of code we have. |
diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index eaa4801f2ce6..38e9e7cadc90 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid | |||
| @@ -514,7 +514,7 @@ iv. Remove yield() while mailbox handshake in synchronous commands | |||
| 514 | 514 | ||
| 515 | v. Remove redundant __megaraid_busywait_mbox routine | 515 | v. Remove redundant __megaraid_busywait_mbox routine |
| 516 | 516 | ||
| 517 | vi. Fix bug in the managment module, which causes a system lockup when the | 517 | vi. Fix bug in the management module, which causes a system lockup when the |
| 518 | IO module is loaded and then unloaded, followed by executing any | 518 | IO module is loaded and then unloaded, followed by executing any |
| 519 | management utility. The current version of management module does not | 519 | management utility. The current version of management module does not |
| 520 | handle the adapter unregister properly. | 520 | handle the adapter unregister properly. |
diff --git a/Documentation/scsi/scsi_fc_transport.txt b/Documentation/scsi/scsi_fc_transport.txt index d7f181701dc2..aec6549ab097 100644 --- a/Documentation/scsi/scsi_fc_transport.txt +++ b/Documentation/scsi/scsi_fc_transport.txt | |||
| @@ -378,7 +378,7 @@ Vport Disable/Enable: | |||
| 378 | int vport_disable(struct fc_vport *vport, bool disable) | 378 | int vport_disable(struct fc_vport *vport, bool disable) |
| 379 | 379 | ||
| 380 | where: | 380 | where: |
| 381 | vport: Is vport to to be enabled or disabled | 381 | vport: Is vport to be enabled or disabled |
| 382 | disable: If "true", the vport is to be disabled. | 382 | disable: If "true", the vport is to be disabled. |
| 383 | If "false", the vport is to be enabled. | 383 | If "false", the vport is to be enabled. |
| 384 | 384 | ||
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 4252697a95d6..1c8eb4518ce0 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt | |||
| @@ -60,6 +60,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
| 60 | slots - Reserve the slot index for the given driver. | 60 | slots - Reserve the slot index for the given driver. |
| 61 | This option takes multiple strings. | 61 | This option takes multiple strings. |
| 62 | See "Module Autoloading Support" section for details. | 62 | See "Module Autoloading Support" section for details. |
| 63 | debug - Specifies the debug message level | ||
| 64 | (0 = disable debug prints, 1 = normal debug messages, | ||
| 65 | 2 = verbose debug messages) | ||
| 66 | This option appears only when CONFIG_SND_DEBUG=y. | ||
| 67 | This option can be dynamically changed via sysfs | ||
| 68 | /sys/modules/snd/parameters/debug file. | ||
| 63 | 69 | ||
| 64 | Module snd-pcm-oss | 70 | Module snd-pcm-oss |
| 65 | ------------------ | 71 | ------------------ |
| @@ -513,6 +519,26 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
| 513 | or input, but you may use this module for any application which | 519 | or input, but you may use this module for any application which |
| 514 | requires a sound card (like RealPlayer). | 520 | requires a sound card (like RealPlayer). |
| 515 | 521 | ||
| 522 | pcm_devs - Number of PCM devices assigned to each card | ||
| 523 | (default = 1, up to 4) | ||
| 524 | pcm_substreams - Number of PCM substreams assigned to each PCM | ||
| 525 | (default = 8, up to 16) | ||
| 526 | hrtimer - Use hrtimer (=1, default) or system timer (=0) | ||
| 527 | fake_buffer - Fake buffer allocations (default = 1) | ||
| 528 | |||
| 529 | When multiple PCM devices are created, snd-dummy gives different | ||
| 530 | behavior to each PCM device: | ||
| 531 | 0 = interleaved with mmap support | ||
| 532 | 1 = non-interleaved with mmap support | ||
| 533 | 2 = interleaved without mmap | ||
| 534 | 3 = non-interleaved without mmap | ||
| 535 | |||
| 536 | As default, snd-dummy drivers doesn't allocate the real buffers | ||
| 537 | but either ignores read/write or mmap a single dummy page to all | ||
| 538 | buffer pages, in order to save the resouces. If your apps need | ||
| 539 | the read/ written buffer data to be consistent, pass fake_buffer=0 | ||
| 540 | option. | ||
| 541 | |||
| 516 | The power-management is supported. | 542 | The power-management is supported. |
| 517 | 543 | ||
| 518 | Module snd-echo3g | 544 | Module snd-echo3g |
| @@ -768,6 +794,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
| 768 | bdl_pos_adj - Specifies the DMA IRQ timing delay in samples. | 794 | bdl_pos_adj - Specifies the DMA IRQ timing delay in samples. |
| 769 | Passing -1 will make the driver to choose the appropriate | 795 | Passing -1 will make the driver to choose the appropriate |
| 770 | value based on the controller chip. | 796 | value based on the controller chip. |
| 797 | patch - Specifies the early "patch" files to modify the HD-audio | ||
| 798 | setup before initializing the codecs. This option is | ||
| 799 | available only when CONFIG_SND_HDA_PATCH_LOADER=y is set. | ||
| 800 | See HD-Audio.txt for details. | ||
| 771 | 801 | ||
| 772 | [Single (global) options] | 802 | [Single (global) options] |
| 773 | single_cmd - Use single immediate commands to communicate with | 803 | single_cmd - Use single immediate commands to communicate with |
diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index 939a3dd58148..f1708b79f963 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt | |||
| @@ -114,8 +114,8 @@ ALC662/663/272 | |||
| 114 | samsung-nc10 Samsung NC10 mini notebook | 114 | samsung-nc10 Samsung NC10 mini notebook |
| 115 | auto auto-config reading BIOS (default) | 115 | auto auto-config reading BIOS (default) |
| 116 | 116 | ||
| 117 | ALC882/885 | 117 | ALC882/883/885/888/889 |
| 118 | ========== | 118 | ====================== |
| 119 | 3stack-dig 3-jack with SPDIF I/O | 119 | 3stack-dig 3-jack with SPDIF I/O |
| 120 | 6stack-dig 6-jack digital with SPDIF I/O | 120 | 6stack-dig 6-jack digital with SPDIF I/O |
| 121 | arima Arima W820Di1 | 121 | arima Arima W820Di1 |
| @@ -127,12 +127,8 @@ ALC882/885 | |||
| 127 | mbp3 Macbook Pro rev3 | 127 | mbp3 Macbook Pro rev3 |
| 128 | imac24 iMac 24'' with jack detection | 128 | imac24 iMac 24'' with jack detection |
| 129 | w2jc ASUS W2JC | 129 | w2jc ASUS W2JC |
| 130 | auto auto-config reading BIOS (default) | 130 | 3stack-2ch-dig 3-jack with SPDIF I/O (ALC883) |
| 131 | 131 | alc883-6stack-dig 6-jack digital with SPDIF I/O (ALC883) | |
| 132 | ALC883/888 | ||
| 133 | ========== | ||
| 134 | 3stack-dig 3-jack with SPDIF I/O | ||
| 135 | 6stack-dig 6-jack digital with SPDIF I/O | ||
| 136 | 3stack-6ch 3-jack 6-channel | 132 | 3stack-6ch 3-jack 6-channel |
| 137 | 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O | 133 | 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O |
| 138 | 6stack-dig-demo 6-jack digital for Intel demo board | 134 | 6stack-dig-demo 6-jack digital for Intel demo board |
| @@ -140,6 +136,7 @@ ALC883/888 | |||
| 140 | acer-aspire Acer Aspire 9810 | 136 | acer-aspire Acer Aspire 9810 |
| 141 | acer-aspire-4930g Acer Aspire 4930G | 137 | acer-aspire-4930g Acer Aspire 4930G |
| 142 | acer-aspire-6530g Acer Aspire 6530G | 138 | acer-aspire-6530g Acer Aspire 6530G |
| 139 | acer-aspire-7730g Acer Aspire 7730G | ||
| 143 | acer-aspire-8930g Acer Aspire 8930G | 140 | acer-aspire-8930g Acer Aspire 8930G |
| 144 | medion Medion Laptops | 141 | medion Medion Laptops |
| 145 | medion-md2 Medion MD2 | 142 | medion-md2 Medion MD2 |
| @@ -155,10 +152,13 @@ ALC883/888 | |||
| 155 | 3stack-hp HP machines with 3stack (Lucknow, Samba boards) | 152 | 3stack-hp HP machines with 3stack (Lucknow, Samba boards) |
| 156 | 6stack-dell Dell machines with 6stack (Inspiron 530) | 153 | 6stack-dell Dell machines with 6stack (Inspiron 530) |
| 157 | mitac Mitac 8252D | 154 | mitac Mitac 8252D |
| 155 | clevo-m540r Clevo M540R (6ch + digital) | ||
| 158 | clevo-m720 Clevo M720 laptop series | 156 | clevo-m720 Clevo M720 laptop series |
| 159 | fujitsu-pi2515 Fujitsu AMILO Pi2515 | 157 | fujitsu-pi2515 Fujitsu AMILO Pi2515 |
| 160 | fujitsu-xa3530 Fujitsu AMILO XA3530 | 158 | fujitsu-xa3530 Fujitsu AMILO XA3530 |
| 161 | 3stack-6ch-intel Intel DG33* boards | 159 | 3stack-6ch-intel Intel DG33* boards |
| 160 | intel-alc889a Intel IbexPeak with ALC889A | ||
| 161 | intel-x58 Intel DX58 with ALC889 | ||
| 162 | asus-p5q ASUS P5Q-EM boards | 162 | asus-p5q ASUS P5Q-EM boards |
| 163 | mb31 MacBook 3,1 | 163 | mb31 MacBook 3,1 |
| 164 | sony-vaio-tt Sony VAIO TT | 164 | sony-vaio-tt Sony VAIO TT |
| @@ -229,7 +229,7 @@ AD1984 | |||
| 229 | ====== | 229 | ====== |
| 230 | basic default configuration | 230 | basic default configuration |
| 231 | thinkpad Lenovo Thinkpad T61/X61 | 231 | thinkpad Lenovo Thinkpad T61/X61 |
| 232 | dell Dell T3400 | 232 | dell_desktop Dell T3400 |
| 233 | 233 | ||
| 234 | AD1986A | 234 | AD1986A |
| 235 | ======= | 235 | ======= |
| @@ -258,6 +258,7 @@ Conexant 5045 | |||
| 258 | laptop-micsense Laptop with Mic sense (old model fujitsu) | 258 | laptop-micsense Laptop with Mic sense (old model fujitsu) |
| 259 | laptop-hpmicsense Laptop with HP and Mic senses | 259 | laptop-hpmicsense Laptop with HP and Mic senses |
| 260 | benq Benq R55E | 260 | benq Benq R55E |
| 261 | laptop-hp530 HP 530 laptop | ||
| 261 | test for testing/debugging purpose, almost all controls | 262 | test for testing/debugging purpose, almost all controls |
| 262 | can be adjusted. Appearing only when compiled with | 263 | can be adjusted. Appearing only when compiled with |
| 263 | $CONFIG_SND_DEBUG=y | 264 | $CONFIG_SND_DEBUG=y |
| @@ -278,9 +279,16 @@ Conexant 5051 | |||
| 278 | hp-dv6736 HP dv6736 | 279 | hp-dv6736 HP dv6736 |
| 279 | lenovo-x200 Lenovo X200 laptop | 280 | lenovo-x200 Lenovo X200 laptop |
| 280 | 281 | ||
| 282 | Conexant 5066 | ||
| 283 | ============= | ||
| 284 | laptop Basic Laptop config (default) | ||
| 285 | dell-laptop Dell laptops | ||
| 286 | olpc-xo-1_5 OLPC XO 1.5 | ||
| 287 | |||
| 281 | STAC9200 | 288 | STAC9200 |
| 282 | ======== | 289 | ======== |
| 283 | ref Reference board | 290 | ref Reference board |
| 291 | oqo OQO Model 2 | ||
| 284 | dell-d21 Dell (unknown) | 292 | dell-d21 Dell (unknown) |
| 285 | dell-d22 Dell (unknown) | 293 | dell-d22 Dell (unknown) |
| 286 | dell-d23 Dell (unknown) | 294 | dell-d23 Dell (unknown) |
| @@ -368,16 +376,18 @@ STAC92HD73* | |||
| 368 | =========== | 376 | =========== |
| 369 | ref Reference board | 377 | ref Reference board |
| 370 | no-jd BIOS setup but without jack-detection | 378 | no-jd BIOS setup but without jack-detection |
| 379 | intel Intel DG45* mobos | ||
| 371 | dell-m6-amic Dell desktops/laptops with analog mics | 380 | dell-m6-amic Dell desktops/laptops with analog mics |
| 372 | dell-m6-dmic Dell desktops/laptops with digital mics | 381 | dell-m6-dmic Dell desktops/laptops with digital mics |
| 373 | dell-m6 Dell desktops/laptops with both type of mics | 382 | dell-m6 Dell desktops/laptops with both type of mics |
| 374 | dell-eq Dell desktops/laptops | 383 | dell-eq Dell desktops/laptops |
| 384 | alienware Alienware M17x | ||
| 375 | auto BIOS setup (default) | 385 | auto BIOS setup (default) |
| 376 | 386 | ||
| 377 | STAC92HD83* | 387 | STAC92HD83* |
| 378 | =========== | 388 | =========== |
| 379 | ref Reference board | 389 | ref Reference board |
| 380 | mic-ref Reference board with power managment for ports | 390 | mic-ref Reference board with power management for ports |
| 381 | dell-s14 Dell laptop | 391 | dell-s14 Dell laptop |
| 382 | auto BIOS setup (default) | 392 | auto BIOS setup (default) |
| 383 | 393 | ||
| @@ -385,3 +395,8 @@ STAC9872 | |||
| 385 | ======== | 395 | ======== |
| 386 | vaio VAIO laptop without SPDIF | 396 | vaio VAIO laptop without SPDIF |
| 387 | auto BIOS setup (default) | 397 | auto BIOS setup (default) |
| 398 | |||
| 399 | Cirrus Logic CS4206/4207 | ||
| 400 | ======================== | ||
| 401 | mbp55 MacBook Pro 5,5 | ||
| 402 | auto BIOS setup (default) | ||
diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt index 71ac995b1915..7b8a5f947d1d 100644 --- a/Documentation/sound/alsa/HD-Audio.txt +++ b/Documentation/sound/alsa/HD-Audio.txt | |||
| @@ -139,6 +139,10 @@ The driver checks PCI SSID and looks through the static configuration | |||
| 139 | table until any matching entry is found. If you have a new machine, | 139 | table until any matching entry is found. If you have a new machine, |
| 140 | you may see a message like below: | 140 | you may see a message like below: |
| 141 | ------------------------------------------------------------------------ | 141 | ------------------------------------------------------------------------ |
| 142 | hda_codec: ALC880: BIOS auto-probing. | ||
| 143 | ------------------------------------------------------------------------ | ||
| 144 | Meanwhile, in the earlier versions, you would see a message like: | ||
| 145 | ------------------------------------------------------------------------ | ||
| 142 | hda_codec: Unknown model for ALC880, trying auto-probe from BIOS... | 146 | hda_codec: Unknown model for ALC880, trying auto-probe from BIOS... |
| 143 | ------------------------------------------------------------------------ | 147 | ------------------------------------------------------------------------ |
| 144 | Even if you see such a message, DON'T PANIC. Take a deep breath and | 148 | Even if you see such a message, DON'T PANIC. Take a deep breath and |
| @@ -403,6 +407,66 @@ re-configure based on that state, run like below: | |||
| 403 | ------------------------------------------------------------------------ | 407 | ------------------------------------------------------------------------ |
| 404 | 408 | ||
| 405 | 409 | ||
| 410 | Early Patching | ||
| 411 | ~~~~~~~~~~~~~~ | ||
| 412 | When CONFIG_SND_HDA_PATCH_LOADER=y is set, you can pass a "patch" as a | ||
| 413 | firmware file for modifying the HD-audio setup before initializing the | ||
| 414 | codec. This can work basically like the reconfiguration via sysfs in | ||
| 415 | the above, but it does it before the first codec configuration. | ||
| 416 | |||
| 417 | A patch file is a plain text file which looks like below: | ||
| 418 | |||
| 419 | ------------------------------------------------------------------------ | ||
| 420 | [codec] | ||
| 421 | 0x12345678 0xabcd1234 2 | ||
| 422 | |||
| 423 | [model] | ||
| 424 | auto | ||
| 425 | |||
| 426 | [pincfg] | ||
| 427 | 0x12 0x411111f0 | ||
| 428 | |||
| 429 | [verb] | ||
| 430 | 0x20 0x500 0x03 | ||
| 431 | 0x20 0x400 0xff | ||
| 432 | |||
| 433 | [hint] | ||
| 434 | hp_detect = yes | ||
| 435 | ------------------------------------------------------------------------ | ||
| 436 | |||
| 437 | The file needs to have a line `[codec]`. The next line should contain | ||
| 438 | three numbers indicating the codec vendor-id (0x12345678 in the | ||
| 439 | example), the codec subsystem-id (0xabcd1234) and the address (2) of | ||
| 440 | the codec. The rest patch entries are applied to this specified codec | ||
| 441 | until another codec entry is given. | ||
| 442 | |||
| 443 | The `[model]` line allows to change the model name of the each codec. | ||
| 444 | In the example above, it will be changed to model=auto. | ||
| 445 | Note that this overrides the module option. | ||
| 446 | |||
| 447 | After the `[pincfg]` line, the contents are parsed as the initial | ||
| 448 | default pin-configurations just like `user_pin_configs` sysfs above. | ||
| 449 | The values can be shown in user_pin_configs sysfs file, too. | ||
| 450 | |||
| 451 | Similarly, the lines after `[verb]` are parsed as `init_verbs` | ||
| 452 | sysfs entries, and the lines after `[hint]` are parsed as `hints` | ||
| 453 | sysfs entries, respectively. | ||
| 454 | |||
| 455 | The hd-audio driver reads the file via request_firmware(). Thus, | ||
| 456 | a patch file has to be located on the appropriate firmware path, | ||
| 457 | typically, /lib/firmware. For example, when you pass the option | ||
| 458 | `patch=hda-init.fw`, the file /lib/firmware/hda-init-fw must be | ||
| 459 | present. | ||
| 460 | |||
| 461 | The patch module option is specific to each card instance, and you | ||
| 462 | need to give one file name for each instance, separated by commas. | ||
| 463 | For example, if you have two cards, one for an on-board analog and one | ||
| 464 | for an HDMI video board, you may pass patch option like below: | ||
| 465 | ------------------------------------------------------------------------ | ||
| 466 | options snd-hda-intel patch=on-board-patch,hdmi-patch | ||
| 467 | ------------------------------------------------------------------------ | ||
| 468 | |||
| 469 | |||
| 406 | Power-Saving | 470 | Power-Saving |
| 407 | ~~~~~~~~~~~~ | 471 | ~~~~~~~~~~~~ |
| 408 | The power-saving is a kind of auto-suspend of the device. When the | 472 | The power-saving is a kind of auto-suspend of the device. When the |
diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 381908d8ca42..719a819f8cc2 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt | |||
| @@ -101,6 +101,8 @@ card*/pcm*/xrun_debug | |||
| 101 | bit 0 = Enable XRUN/jiffies debug messages | 101 | bit 0 = Enable XRUN/jiffies debug messages |
| 102 | bit 1 = Show stack trace at XRUN / jiffies check | 102 | bit 1 = Show stack trace at XRUN / jiffies check |
| 103 | bit 2 = Enable additional jiffies check | 103 | bit 2 = Enable additional jiffies check |
| 104 | bit 3 = Log hwptr update at each period interrupt | ||
| 105 | bit 4 = Log hwptr update at each snd_pcm_update_hw_ptr() | ||
| 104 | 106 | ||
| 105 | When the bit 0 is set, the driver will show the messages to | 107 | When the bit 0 is set, the driver will show the messages to |
| 106 | kernel log when an xrun is detected. The debug message is | 108 | kernel log when an xrun is detected. The debug message is |
| @@ -117,6 +119,9 @@ card*/pcm*/xrun_debug | |||
| 117 | buggy) hardware that doesn't give smooth pointer updates. | 119 | buggy) hardware that doesn't give smooth pointer updates. |
| 118 | This feature is enabled via the bit 2. | 120 | This feature is enabled via the bit 2. |
| 119 | 121 | ||
| 122 | Bits 3 and 4 are for logging the hwptr records. Note that | ||
| 123 | these will give flood of kernel messages. | ||
| 124 | |||
| 120 | card*/pcm*/sub*/info | 125 | card*/pcm*/sub*/info |
| 121 | The general information of this PCM sub-stream. | 126 | The general information of this PCM sub-stream. |
| 122 | 127 | ||
diff --git a/Documentation/spi/spidev_test.c b/Documentation/spi/spidev_test.c index cf0e3ce0d526..c1a5aad3c75a 100644 --- a/Documentation/spi/spidev_test.c +++ b/Documentation/spi/spidev_test.c | |||
| @@ -99,11 +99,13 @@ void parse_opts(int argc, char *argv[]) | |||
| 99 | { "lsb", 0, 0, 'L' }, | 99 | { "lsb", 0, 0, 'L' }, |
| 100 | { "cs-high", 0, 0, 'C' }, | 100 | { "cs-high", 0, 0, 'C' }, |
| 101 | { "3wire", 0, 0, '3' }, | 101 | { "3wire", 0, 0, '3' }, |
| 102 | { "no-cs", 0, 0, 'N' }, | ||
| 103 | { "ready", 0, 0, 'R' }, | ||
| 102 | { NULL, 0, 0, 0 }, | 104 | { NULL, 0, 0, 0 }, |
| 103 | }; | 105 | }; |
| 104 | int c; | 106 | int c; |
| 105 | 107 | ||
| 106 | c = getopt_long(argc, argv, "D:s:d:b:lHOLC3", lopts, NULL); | 108 | c = getopt_long(argc, argv, "D:s:d:b:lHOLC3NR", lopts, NULL); |
| 107 | 109 | ||
| 108 | if (c == -1) | 110 | if (c == -1) |
| 109 | break; | 111 | break; |
| @@ -139,6 +141,12 @@ void parse_opts(int argc, char *argv[]) | |||
| 139 | case '3': | 141 | case '3': |
| 140 | mode |= SPI_3WIRE; | 142 | mode |= SPI_3WIRE; |
| 141 | break; | 143 | break; |
| 144 | case 'N': | ||
| 145 | mode |= SPI_NO_CS; | ||
| 146 | break; | ||
| 147 | case 'R': | ||
| 148 | mode |= SPI_READY; | ||
| 149 | break; | ||
| 142 | default: | 150 | default: |
| 143 | print_usage(argv[0]); | 151 | print_usage(argv[0]); |
| 144 | break; | 152 | break; |
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 322a00bb99d9..3e5b63ebb821 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt | |||
| @@ -19,6 +19,7 @@ Currently, these files might (depending on your configuration) | |||
| 19 | show up in /proc/sys/kernel: | 19 | show up in /proc/sys/kernel: |
| 20 | - acpi_video_flags | 20 | - acpi_video_flags |
| 21 | - acct | 21 | - acct |
| 22 | - callhome [ S390 only ] | ||
| 22 | - auto_msgmni | 23 | - auto_msgmni |
| 23 | - core_pattern | 24 | - core_pattern |
| 24 | - core_uses_pid | 25 | - core_uses_pid |
| @@ -91,6 +92,21 @@ valid for 30 seconds. | |||
| 91 | 92 | ||
| 92 | ============================================================== | 93 | ============================================================== |
| 93 | 94 | ||
| 95 | callhome: | ||
| 96 | |||
| 97 | Controls the kernel's callhome behavior in case of a kernel panic. | ||
| 98 | |||
| 99 | The s390 hardware allows an operating system to send a notification | ||
| 100 | to a service organization (callhome) in case of an operating system panic. | ||
| 101 | |||
| 102 | When the value in this file is 0 (which is the default behavior) | ||
| 103 | nothing happens in case of a kernel panic. If this value is set to "1" | ||
| 104 | the complete kernel oops message is send to the IBM customer service | ||
| 105 | organization in case the mainframe the Linux operating system is running | ||
| 106 | on has a service contract with IBM. | ||
| 107 | |||
| 108 | ============================================================== | ||
| 109 | |||
| 94 | core_pattern: | 110 | core_pattern: |
| 95 | 111 | ||
| 96 | core_pattern is used to specify a core dumpfile pattern name. | 112 | core_pattern is used to specify a core dumpfile pattern name. |
| @@ -303,25 +319,29 @@ This option can be used to select the type of process address | |||
| 303 | space randomization that is used in the system, for architectures | 319 | space randomization that is used in the system, for architectures |
| 304 | that support this feature. | 320 | that support this feature. |
| 305 | 321 | ||
| 306 | 0 - Turn the process address space randomization off by default. | 322 | 0 - Turn the process address space randomization off. This is the |
| 323 | default for architectures that do not support this feature anyways, | ||
| 324 | and kernels that are booted with the "norandmaps" parameter. | ||
| 307 | 325 | ||
| 308 | 1 - Make the addresses of mmap base, stack and VDSO page randomized. | 326 | 1 - Make the addresses of mmap base, stack and VDSO page randomized. |
| 309 | This, among other things, implies that shared libraries will be | 327 | This, among other things, implies that shared libraries will be |
| 310 | loaded to random addresses. Also for PIE-linked binaries, the location | 328 | loaded to random addresses. Also for PIE-linked binaries, the |
| 311 | of code start is randomized. | 329 | location of code start is randomized. This is the default if the |
| 330 | CONFIG_COMPAT_BRK option is enabled. | ||
| 312 | 331 | ||
| 313 | With heap randomization, the situation is a little bit more | 332 | 2 - Additionally enable heap randomization. This is the default if |
| 314 | complicated. | 333 | CONFIG_COMPAT_BRK is disabled. |
| 315 | There a few legacy applications out there (such as some ancient | 334 | |
| 335 | There are a few legacy applications out there (such as some ancient | ||
| 316 | versions of libc.so.5 from 1996) that assume that brk area starts | 336 | versions of libc.so.5 from 1996) that assume that brk area starts |
| 317 | just after the end of the code+bss. These applications break when | 337 | just after the end of the code+bss. These applications break when |
| 318 | start of the brk area is randomized. There are however no known | 338 | start of the brk area is randomized. There are however no known |
| 319 | non-legacy applications that would be broken this way, so for most | 339 | non-legacy applications that would be broken this way, so for most |
| 320 | systems it is safe to choose full randomization. However there is | 340 | systems it is safe to choose full randomization. |
| 321 | a CONFIG_COMPAT_BRK option for systems with ancient and/or broken | 341 | |
| 322 | binaries, that makes heap non-randomized, but keeps all other | 342 | Systems with ancient and/or broken binaries should be configured |
| 323 | parts of process address space randomized if randomize_va_space | 343 | with CONFIG_COMPAT_BRK enabled, which excludes the heap from process |
| 324 | sysctl is turned on. | 344 | address space randomization. |
| 325 | 345 | ||
| 326 | ============================================================== | 346 | ============================================================== |
| 327 | 347 | ||
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index c4de6359d440..e6fb1ec2744b 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt | |||
| @@ -585,7 +585,9 @@ caching of directory and inode objects. | |||
| 585 | At the default value of vfs_cache_pressure=100 the kernel will attempt to | 585 | At the default value of vfs_cache_pressure=100 the kernel will attempt to |
| 586 | reclaim dentries and inodes at a "fair" rate with respect to pagecache and | 586 | reclaim dentries and inodes at a "fair" rate with respect to pagecache and |
| 587 | swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer | 587 | swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer |
| 588 | to retain dentry and inode caches. Increasing vfs_cache_pressure beyond 100 | 588 | to retain dentry and inode caches. When vfs_cache_pressure=0, the kernel will |
| 589 | never reclaim dentries and inodes due to memory pressure and this can easily | ||
| 590 | lead to out-of-memory conditions. Increasing vfs_cache_pressure beyond 100 | ||
| 589 | causes the kernel to prefer to reclaim dentries and inodes. | 591 | causes the kernel to prefer to reclaim dentries and inodes. |
| 590 | 592 | ||
| 591 | ============================================================== | 593 | ============================================================== |
diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index cf42b820ff9d..d56a01775423 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt | |||
| @@ -66,7 +66,8 @@ On all - write a character to /proc/sysrq-trigger. e.g.: | |||
| 66 | 'b' - Will immediately reboot the system without syncing or unmounting | 66 | 'b' - Will immediately reboot the system without syncing or unmounting |
| 67 | your disks. | 67 | your disks. |
| 68 | 68 | ||
| 69 | 'c' - Will perform a kexec reboot in order to take a crashdump. | 69 | 'c' - Will perform a system crash by a NULL pointer dereference. |
| 70 | A crashdump will be taken if configured. | ||
| 70 | 71 | ||
| 71 | 'd' - Shows all locks that are held. | 72 | 'd' - Shows all locks that are held. |
| 72 | 73 | ||
| @@ -141,8 +142,8 @@ useful when you want to exit a program that will not let you switch consoles. | |||
| 141 | re'B'oot is good when you're unable to shut down. But you should also 'S'ync | 142 | re'B'oot is good when you're unable to shut down. But you should also 'S'ync |
| 142 | and 'U'mount first. | 143 | and 'U'mount first. |
| 143 | 144 | ||
| 144 | 'C'rashdump can be used to manually trigger a crashdump when the system is hung. | 145 | 'C'rash can be used to manually trigger a crashdump when the system is hung. |
| 145 | The kernel needs to have been built with CONFIG_KEXEC enabled. | 146 | Note that this just triggers a crash if there is no dump mechanism available. |
| 146 | 147 | ||
| 147 | 'S'ync is great when your system is locked up, it allows you to sync your | 148 | 'S'ync is great when your system is locked up, it allows you to sync your |
| 148 | disks and will certainly lessen the chance of data loss and fscking. Note | 149 | disks and will certainly lessen the chance of data loss and fscking. Note |
diff --git a/Documentation/trace/events-kmem.txt b/Documentation/trace/events-kmem.txt new file mode 100644 index 000000000000..6ef2a8652e17 --- /dev/null +++ b/Documentation/trace/events-kmem.txt | |||
| @@ -0,0 +1,107 @@ | |||
| 1 | Subsystem Trace Points: kmem | ||
| 2 | |||
| 3 | The tracing system kmem captures events related to object and page allocation | ||
| 4 | within the kernel. Broadly speaking there are four major subheadings. | ||
| 5 | |||
| 6 | o Slab allocation of small objects of unknown type (kmalloc) | ||
| 7 | o Slab allocation of small objects of known type | ||
| 8 | o Page allocation | ||
| 9 | o Per-CPU Allocator Activity | ||
| 10 | o External Fragmentation | ||
| 11 | |||
| 12 | This document will describe what each of the tracepoints are and why they | ||
| 13 | might be useful. | ||
| 14 | |||
| 15 | 1. Slab allocation of small objects of unknown type | ||
| 16 | =================================================== | ||
| 17 | kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s | ||
| 18 | kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d | ||
| 19 | kfree call_site=%lx ptr=%p | ||
| 20 | |||
| 21 | Heavy activity for these events may indicate that a specific cache is | ||
| 22 | justified, particularly if kmalloc slab pages are getting significantly | ||
| 23 | internal fragmented as a result of the allocation pattern. By correlating | ||
| 24 | kmalloc with kfree, it may be possible to identify memory leaks and where | ||
| 25 | the allocation sites were. | ||
| 26 | |||
| 27 | |||
| 28 | 2. Slab allocation of small objects of known type | ||
| 29 | ================================================= | ||
| 30 | kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s | ||
| 31 | kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d | ||
| 32 | kmem_cache_free call_site=%lx ptr=%p | ||
| 33 | |||
| 34 | These events are similar in usage to the kmalloc-related events except that | ||
| 35 | it is likely easier to pin the event down to a specific cache. At the time | ||
| 36 | of writing, no information is available on what slab is being allocated from, | ||
| 37 | but the call_site can usually be used to extrapolate that information | ||
| 38 | |||
| 39 | 3. Page allocation | ||
| 40 | ================== | ||
| 41 | mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s | ||
| 42 | mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d | ||
| 43 | mm_page_free_direct page=%p pfn=%lu order=%d | ||
| 44 | mm_pagevec_free page=%p pfn=%lu order=%d cold=%d | ||
| 45 | |||
| 46 | These four events deal with page allocation and freeing. mm_page_alloc is | ||
| 47 | a simple indicator of page allocator activity. Pages may be allocated from | ||
| 48 | the per-CPU allocator (high performance) or the buddy allocator. | ||
| 49 | |||
| 50 | If pages are allocated directly from the buddy allocator, the | ||
| 51 | mm_page_alloc_zone_locked event is triggered. This event is important as high | ||
| 52 | amounts of activity imply high activity on the zone->lock. Taking this lock | ||
| 53 | impairs performance by disabling interrupts, dirtying cache lines between | ||
| 54 | CPUs and serialising many CPUs. | ||
| 55 | |||
| 56 | When a page is freed directly by the caller, the mm_page_free_direct event | ||
| 57 | is triggered. Significant amounts of activity here could indicate that the | ||
| 58 | callers should be batching their activities. | ||
| 59 | |||
| 60 | When pages are freed using a pagevec, the mm_pagevec_free is | ||
| 61 | triggered. Broadly speaking, pages are taken off the LRU lock in bulk and | ||
| 62 | freed in batch with a pagevec. Significant amounts of activity here could | ||
| 63 | indicate that the system is under memory pressure and can also indicate | ||
| 64 | contention on the zone->lru_lock. | ||
| 65 | |||
| 66 | 4. Per-CPU Allocator Activity | ||
| 67 | ============================= | ||
| 68 | mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d | ||
| 69 | mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d | ||
| 70 | |||
| 71 | In front of the page allocator is a per-cpu page allocator. It exists only | ||
| 72 | for order-0 pages, reduces contention on the zone->lock and reduces the | ||
| 73 | amount of writing on struct page. | ||
| 74 | |||
| 75 | When a per-CPU list is empty or pages of the wrong type are allocated, | ||
| 76 | the zone->lock will be taken once and the per-CPU list refilled. The event | ||
| 77 | triggered is mm_page_alloc_zone_locked for each page allocated with the | ||
| 78 | event indicating whether it is for a percpu_refill or not. | ||
| 79 | |||
| 80 | When the per-CPU list is too full, a number of pages are freed, each one | ||
| 81 | which triggers a mm_page_pcpu_drain event. | ||
| 82 | |||
| 83 | The individual nature of the events are so that pages can be tracked | ||
| 84 | between allocation and freeing. A number of drain or refill pages that occur | ||
| 85 | consecutively imply the zone->lock being taken once. Large amounts of PCP | ||
| 86 | refills and drains could imply an imbalance between CPUs where too much work | ||
| 87 | is being concentrated in one place. It could also indicate that the per-CPU | ||
| 88 | lists should be a larger size. Finally, large amounts of refills on one CPU | ||
| 89 | and drains on another could be a factor in causing large amounts of cache | ||
| 90 | line bounces due to writes between CPUs and worth investigating if pages | ||
| 91 | can be allocated and freed on the same CPU through some algorithm change. | ||
| 92 | |||
| 93 | 5. External Fragmentation | ||
| 94 | ========================= | ||
| 95 | mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d | ||
| 96 | |||
| 97 | External fragmentation affects whether a high-order allocation will be | ||
| 98 | successful or not. For some types of hardware, this is important although | ||
| 99 | it is avoided where possible. If the system is using huge pages and needs | ||
| 100 | to be able to resize the pool over the lifetime of the system, this value | ||
| 101 | is important. | ||
| 102 | |||
| 103 | Large numbers of this event implies that memory is fragmenting and | ||
| 104 | high-order allocations will start failing at some time in the future. One | ||
| 105 | means of reducing the occurange of this event is to increase the size of | ||
| 106 | min_free_kbytes in increments of 3*pageblock_size*nr_online_nodes where | ||
| 107 | pageblock_size is usually the size of the default hugepage size. | ||
diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt index f157d7594ea7..02ac6ed38b2d 100644 --- a/Documentation/trace/events.txt +++ b/Documentation/trace/events.txt | |||
| @@ -1,7 +1,7 @@ | |||
| 1 | Event Tracing | 1 | Event Tracing |
| 2 | 2 | ||
| 3 | Documentation written by Theodore Ts'o | 3 | Documentation written by Theodore Ts'o |
| 4 | Updated by Li Zefan | 4 | Updated by Li Zefan and Tom Zanussi |
| 5 | 5 | ||
| 6 | 1. Introduction | 6 | 1. Introduction |
| 7 | =============== | 7 | =============== |
| @@ -22,12 +22,12 @@ tracing information should be printed. | |||
| 22 | --------------------------------- | 22 | --------------------------------- |
| 23 | 23 | ||
| 24 | The events which are available for tracing can be found in the file | 24 | The events which are available for tracing can be found in the file |
| 25 | /debug/tracing/available_events. | 25 | /sys/kernel/debug/tracing/available_events. |
| 26 | 26 | ||
| 27 | To enable a particular event, such as 'sched_wakeup', simply echo it | 27 | To enable a particular event, such as 'sched_wakeup', simply echo it |
| 28 | to /debug/tracing/set_event. For example: | 28 | to /sys/kernel/debug/tracing/set_event. For example: |
| 29 | 29 | ||
| 30 | # echo sched_wakeup >> /debug/tracing/set_event | 30 | # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event |
| 31 | 31 | ||
| 32 | [ Note: '>>' is necessary, otherwise it will firstly disable | 32 | [ Note: '>>' is necessary, otherwise it will firstly disable |
| 33 | all the events. ] | 33 | all the events. ] |
| @@ -35,15 +35,15 @@ to /debug/tracing/set_event. For example: | |||
| 35 | To disable an event, echo the event name to the set_event file prefixed | 35 | To disable an event, echo the event name to the set_event file prefixed |
| 36 | with an exclamation point: | 36 | with an exclamation point: |
| 37 | 37 | ||
| 38 | # echo '!sched_wakeup' >> /debug/tracing/set_event | 38 | # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event |
| 39 | 39 | ||
| 40 | To disable all events, echo an empty line to the set_event file: | 40 | To disable all events, echo an empty line to the set_event file: |
| 41 | 41 | ||
| 42 | # echo > /debug/tracing/set_event | 42 | # echo > /sys/kernel/debug/tracing/set_event |
| 43 | 43 | ||
| 44 | To enable all events, echo '*:*' or '*:' to the set_event file: | 44 | To enable all events, echo '*:*' or '*:' to the set_event file: |
| 45 | 45 | ||
| 46 | # echo *:* > /debug/tracing/set_event | 46 | # echo *:* > /sys/kernel/debug/tracing/set_event |
| 47 | 47 | ||
| 48 | The events are organized into subsystems, such as ext4, irq, sched, | 48 | The events are organized into subsystems, such as ext4, irq, sched, |
| 49 | etc., and a full event name looks like this: <subsystem>:<event>. The | 49 | etc., and a full event name looks like this: <subsystem>:<event>. The |
| @@ -52,29 +52,29 @@ file. All of the events in a subsystem can be specified via the syntax | |||
| 52 | "<subsystem>:*"; for example, to enable all irq events, you can use the | 52 | "<subsystem>:*"; for example, to enable all irq events, you can use the |
| 53 | command: | 53 | command: |
| 54 | 54 | ||
| 55 | # echo 'irq:*' > /debug/tracing/set_event | 55 | # echo 'irq:*' > /sys/kernel/debug/tracing/set_event |
| 56 | 56 | ||
| 57 | 2.2 Via the 'enable' toggle | 57 | 2.2 Via the 'enable' toggle |
| 58 | --------------------------- | 58 | --------------------------- |
| 59 | 59 | ||
| 60 | The events available are also listed in /debug/tracing/events/ hierarchy | 60 | The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy |
| 61 | of directories. | 61 | of directories. |
| 62 | 62 | ||
| 63 | To enable event 'sched_wakeup': | 63 | To enable event 'sched_wakeup': |
| 64 | 64 | ||
| 65 | # echo 1 > /debug/tracing/events/sched/sched_wakeup/enable | 65 | # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable |
| 66 | 66 | ||
| 67 | To disable it: | 67 | To disable it: |
| 68 | 68 | ||
| 69 | # echo 0 > /debug/tracing/events/sched/sched_wakeup/enable | 69 | # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable |
| 70 | 70 | ||
| 71 | To enable all events in sched subsystem: | 71 | To enable all events in sched subsystem: |
| 72 | 72 | ||
| 73 | # echo 1 > /debug/tracing/events/sched/enable | 73 | # echo 1 > /sys/kernel/debug/tracing/events/sched/enable |
| 74 | 74 | ||
| 75 | To eanble all events: | 75 | To enable all events: |
| 76 | 76 | ||
| 77 | # echo 1 > /debug/tracing/events/enable | 77 | # echo 1 > /sys/kernel/debug/tracing/events/enable |
| 78 | 78 | ||
| 79 | When reading one of these enable files, there are four results: | 79 | When reading one of these enable files, there are four results: |
| 80 | 80 | ||
| @@ -83,8 +83,199 @@ When reading one of these enable files, there are four results: | |||
| 83 | X - there is a mixture of events enabled and disabled | 83 | X - there is a mixture of events enabled and disabled |
| 84 | ? - this file does not affect any event | 84 | ? - this file does not affect any event |
| 85 | 85 | ||
| 86 | 2.3 Boot option | ||
| 87 | --------------- | ||
| 88 | |||
| 89 | In order to facilitate early boot debugging, use boot option: | ||
| 90 | |||
| 91 | trace_event=[event-list] | ||
| 92 | |||
| 93 | The format of this boot option is the same as described in section 2.1. | ||
| 94 | |||
| 86 | 3. Defining an event-enabled tracepoint | 95 | 3. Defining an event-enabled tracepoint |
| 87 | ======================================= | 96 | ======================================= |
| 88 | 97 | ||
| 89 | See The example provided in samples/trace_events | 98 | See The example provided in samples/trace_events |
| 90 | 99 | ||
| 100 | 4. Event formats | ||
| 101 | ================ | ||
| 102 | |||
| 103 | Each trace event has a 'format' file associated with it that contains | ||
| 104 | a description of each field in a logged event. This information can | ||
| 105 | be used to parse the binary trace stream, and is also the place to | ||
| 106 | find the field names that can be used in event filters (see section 5). | ||
| 107 | |||
| 108 | It also displays the format string that will be used to print the | ||
| 109 | event in text mode, along with the event name and ID used for | ||
| 110 | profiling. | ||
| 111 | |||
| 112 | Every event has a set of 'common' fields associated with it; these are | ||
| 113 | the fields prefixed with 'common_'. The other fields vary between | ||
| 114 | events and correspond to the fields defined in the TRACE_EVENT | ||
| 115 | definition for that event. | ||
| 116 | |||
| 117 | Each field in the format has the form: | ||
| 118 | |||
| 119 | field:field-type field-name; offset:N; size:N; | ||
| 120 | |||
| 121 | where offset is the offset of the field in the trace record and size | ||
| 122 | is the size of the data item, in bytes. | ||
| 123 | |||
| 124 | For example, here's the information displayed for the 'sched_wakeup' | ||
| 125 | event: | ||
| 126 | |||
| 127 | # cat /debug/tracing/events/sched/sched_wakeup/format | ||
| 128 | |||
| 129 | name: sched_wakeup | ||
| 130 | ID: 60 | ||
| 131 | format: | ||
| 132 | field:unsigned short common_type; offset:0; size:2; | ||
| 133 | field:unsigned char common_flags; offset:2; size:1; | ||
| 134 | field:unsigned char common_preempt_count; offset:3; size:1; | ||
| 135 | field:int common_pid; offset:4; size:4; | ||
| 136 | field:int common_tgid; offset:8; size:4; | ||
| 137 | |||
| 138 | field:char comm[TASK_COMM_LEN]; offset:12; size:16; | ||
| 139 | field:pid_t pid; offset:28; size:4; | ||
| 140 | field:int prio; offset:32; size:4; | ||
| 141 | field:int success; offset:36; size:4; | ||
| 142 | field:int cpu; offset:40; size:4; | ||
| 143 | |||
| 144 | print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid, | ||
| 145 | REC->prio, REC->success, REC->cpu | ||
| 146 | |||
| 147 | This event contains 10 fields, the first 5 common and the remaining 5 | ||
| 148 | event-specific. All the fields for this event are numeric, except for | ||
| 149 | 'comm' which is a string, a distinction important for event filtering. | ||
| 150 | |||
| 151 | 5. Event filtering | ||
| 152 | ================== | ||
| 153 | |||
| 154 | Trace events can be filtered in the kernel by associating boolean | ||
| 155 | 'filter expressions' with them. As soon as an event is logged into | ||
| 156 | the trace buffer, its fields are checked against the filter expression | ||
| 157 | associated with that event type. An event with field values that | ||
| 158 | 'match' the filter will appear in the trace output, and an event whose | ||
| 159 | values don't match will be discarded. An event with no filter | ||
| 160 | associated with it matches everything, and is the default when no | ||
| 161 | filter has been set for an event. | ||
| 162 | |||
| 163 | 5.1 Expression syntax | ||
| 164 | --------------------- | ||
| 165 | |||
| 166 | A filter expression consists of one or more 'predicates' that can be | ||
| 167 | combined using the logical operators '&&' and '||'. A predicate is | ||
| 168 | simply a clause that compares the value of a field contained within a | ||
| 169 | logged event with a constant value and returns either 0 or 1 depending | ||
| 170 | on whether the field value matched (1) or didn't match (0): | ||
| 171 | |||
| 172 | field-name relational-operator value | ||
| 173 | |||
| 174 | Parentheses can be used to provide arbitrary logical groupings and | ||
| 175 | double-quotes can be used to prevent the shell from interpreting | ||
| 176 | operators as shell metacharacters. | ||
| 177 | |||
| 178 | The field-names available for use in filters can be found in the | ||
| 179 | 'format' files for trace events (see section 4). | ||
| 180 | |||
| 181 | The relational-operators depend on the type of the field being tested: | ||
| 182 | |||
| 183 | The operators available for numeric fields are: | ||
| 184 | |||
| 185 | ==, !=, <, <=, >, >= | ||
| 186 | |||
| 187 | And for string fields they are: | ||
| 188 | |||
| 189 | ==, != | ||
| 190 | |||
| 191 | Currently, only exact string matches are supported. | ||
| 192 | |||
| 193 | Currently, the maximum number of predicates in a filter is 16. | ||
| 194 | |||
| 195 | 5.2 Setting filters | ||
| 196 | ------------------- | ||
| 197 | |||
| 198 | A filter for an individual event is set by writing a filter expression | ||
| 199 | to the 'filter' file for the given event. | ||
| 200 | |||
| 201 | For example: | ||
| 202 | |||
| 203 | # cd /debug/tracing/events/sched/sched_wakeup | ||
| 204 | # echo "common_preempt_count > 4" > filter | ||
| 205 | |||
| 206 | A slightly more involved example: | ||
| 207 | |||
| 208 | # cd /debug/tracing/events/sched/sched_signal_send | ||
| 209 | # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter | ||
| 210 | |||
| 211 | If there is an error in the expression, you'll get an 'Invalid | ||
| 212 | argument' error when setting it, and the erroneous string along with | ||
| 213 | an error message can be seen by looking at the filter e.g.: | ||
| 214 | |||
| 215 | # cd /debug/tracing/events/sched/sched_signal_send | ||
| 216 | # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter | ||
| 217 | -bash: echo: write error: Invalid argument | ||
| 218 | # cat filter | ||
| 219 | ((sig >= 10 && sig < 15) || dsig == 17) && comm != bash | ||
| 220 | ^ | ||
| 221 | parse_error: Field not found | ||
| 222 | |||
| 223 | Currently the caret ('^') for an error always appears at the beginning of | ||
| 224 | the filter string; the error message should still be useful though | ||
| 225 | even without more accurate position info. | ||
| 226 | |||
| 227 | 5.3 Clearing filters | ||
| 228 | -------------------- | ||
| 229 | |||
| 230 | To clear the filter for an event, write a '0' to the event's filter | ||
| 231 | file. | ||
| 232 | |||
| 233 | To clear the filters for all events in a subsystem, write a '0' to the | ||
| 234 | subsystem's filter file. | ||
| 235 | |||
| 236 | 5.3 Subsystem filters | ||
| 237 | --------------------- | ||
| 238 | |||
| 239 | For convenience, filters for every event in a subsystem can be set or | ||
| 240 | cleared as a group by writing a filter expression into the filter file | ||
| 241 | at the root of the subsytem. Note however, that if a filter for any | ||
| 242 | event within the subsystem lacks a field specified in the subsystem | ||
| 243 | filter, or if the filter can't be applied for any other reason, the | ||
| 244 | filter for that event will retain its previous setting. This can | ||
| 245 | result in an unintended mixture of filters which could lead to | ||
| 246 | confusing (to the user who might think different filters are in | ||
| 247 | effect) trace output. Only filters that reference just the common | ||
| 248 | fields can be guaranteed to propagate successfully to all events. | ||
| 249 | |||
| 250 | Here are a few subsystem filter examples that also illustrate the | ||
| 251 | above points: | ||
| 252 | |||
| 253 | Clear the filters on all events in the sched subsytem: | ||
| 254 | |||
| 255 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 256 | # echo 0 > filter | ||
| 257 | # cat sched_switch/filter | ||
| 258 | none | ||
| 259 | # cat sched_wakeup/filter | ||
| 260 | none | ||
| 261 | |||
| 262 | Set a filter using only common fields for all events in the sched | ||
| 263 | subsytem (all events end up with the same filter): | ||
| 264 | |||
| 265 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 266 | # echo common_pid == 0 > filter | ||
| 267 | # cat sched_switch/filter | ||
| 268 | common_pid == 0 | ||
| 269 | # cat sched_wakeup/filter | ||
| 270 | common_pid == 0 | ||
| 271 | |||
| 272 | Attempt to set a filter using a non-common field for all events in the | ||
| 273 | sched subsytem (all events but those that have a prev_pid field retain | ||
| 274 | their old filters): | ||
| 275 | |||
| 276 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 277 | # echo prev_pid == 0 > filter | ||
| 278 | # cat sched_switch/filter | ||
| 279 | prev_pid == 0 | ||
| 280 | # cat sched_wakeup/filter | ||
| 281 | common_pid == 0 | ||
diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.txt new file mode 100644 index 000000000000..7003e10f10f5 --- /dev/null +++ b/Documentation/trace/ftrace-design.txt | |||
| @@ -0,0 +1,233 @@ | |||
| 1 | function tracer guts | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Introduction | ||
| 5 | ------------ | ||
| 6 | |||
| 7 | Here we will cover the architecture pieces that the common function tracing | ||
| 8 | code relies on for proper functioning. Things are broken down into increasing | ||
| 9 | complexity so that you can start simple and at least get basic functionality. | ||
| 10 | |||
| 11 | Note that this focuses on architecture implementation details only. If you | ||
| 12 | want more explanation of a feature in terms of common code, review the common | ||
| 13 | ftrace.txt file. | ||
| 14 | |||
| 15 | |||
| 16 | Prerequisites | ||
| 17 | ------------- | ||
| 18 | |||
| 19 | Ftrace relies on these features being implemented: | ||
| 20 | STACKTRACE_SUPPORT - implement save_stack_trace() | ||
| 21 | TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h | ||
| 22 | |||
| 23 | |||
| 24 | HAVE_FUNCTION_TRACER | ||
| 25 | -------------------- | ||
| 26 | |||
| 27 | You will need to implement the mcount and the ftrace_stub functions. | ||
| 28 | |||
| 29 | The exact mcount symbol name will depend on your toolchain. Some call it | ||
| 30 | "mcount", "_mcount", or even "__mcount". You can probably figure it out by | ||
| 31 | running something like: | ||
| 32 | $ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount | ||
| 33 | call mcount | ||
| 34 | We'll make the assumption below that the symbol is "mcount" just to keep things | ||
| 35 | nice and simple in the examples. | ||
| 36 | |||
| 37 | Keep in mind that the ABI that is in effect inside of the mcount function is | ||
| 38 | *highly* architecture/toolchain specific. We cannot help you in this regard, | ||
| 39 | sorry. Dig up some old documentation and/or find someone more familiar than | ||
| 40 | you to bang ideas off of. Typically, register usage (argument/scratch/etc...) | ||
| 41 | is a major issue at this point, especially in relation to the location of the | ||
| 42 | mcount call (before/after function prologue). You might also want to look at | ||
| 43 | how glibc has implemented the mcount function for your architecture. It might | ||
| 44 | be (semi-)relevant. | ||
| 45 | |||
| 46 | The mcount function should check the function pointer ftrace_trace_function | ||
| 47 | to see if it is set to ftrace_stub. If it is, there is nothing for you to do, | ||
| 48 | so return immediately. If it isn't, then call that function in the same way | ||
| 49 | the mcount function normally calls __mcount_internal -- the first argument is | ||
| 50 | the "frompc" while the second argument is the "selfpc" (adjusted to remove the | ||
| 51 | size of the mcount call that is embedded in the function). | ||
| 52 | |||
| 53 | For example, if the function foo() calls bar(), when the bar() function calls | ||
| 54 | mcount(), the arguments mcount() will pass to the tracer are: | ||
| 55 | "frompc" - the address bar() will use to return to foo() | ||
| 56 | "selfpc" - the address bar() (with _mcount() size adjustment) | ||
| 57 | |||
| 58 | Also keep in mind that this mcount function will be called *a lot*, so | ||
| 59 | optimizing for the default case of no tracer will help the smooth running of | ||
| 60 | your system when tracing is disabled. So the start of the mcount function is | ||
| 61 | typically the bare min with checking things before returning. That also means | ||
| 62 | the code flow should usually kept linear (i.e. no branching in the nop case). | ||
| 63 | This is of course an optimization and not a hard requirement. | ||
| 64 | |||
| 65 | Here is some pseudo code that should help (these functions should actually be | ||
| 66 | implemented in assembly): | ||
| 67 | |||
| 68 | void ftrace_stub(void) | ||
| 69 | { | ||
| 70 | return; | ||
| 71 | } | ||
| 72 | |||
| 73 | void mcount(void) | ||
| 74 | { | ||
| 75 | /* save any bare state needed in order to do initial checking */ | ||
| 76 | |||
| 77 | extern void (*ftrace_trace_function)(unsigned long, unsigned long); | ||
| 78 | if (ftrace_trace_function != ftrace_stub) | ||
| 79 | goto do_trace; | ||
| 80 | |||
| 81 | /* restore any bare state */ | ||
| 82 | |||
| 83 | return; | ||
| 84 | |||
| 85 | do_trace: | ||
| 86 | |||
| 87 | /* save all state needed by the ABI (see paragraph above) */ | ||
| 88 | |||
| 89 | unsigned long frompc = ...; | ||
| 90 | unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; | ||
| 91 | ftrace_trace_function(frompc, selfpc); | ||
| 92 | |||
| 93 | /* restore all state needed by the ABI */ | ||
| 94 | } | ||
| 95 | |||
| 96 | Don't forget to export mcount for modules ! | ||
| 97 | extern void mcount(void); | ||
| 98 | EXPORT_SYMBOL(mcount); | ||
| 99 | |||
| 100 | |||
| 101 | HAVE_FUNCTION_TRACE_MCOUNT_TEST | ||
| 102 | ------------------------------- | ||
| 103 | |||
| 104 | This is an optional optimization for the normal case when tracing is turned off | ||
| 105 | in the system. If you do not enable this Kconfig option, the common ftrace | ||
| 106 | code will take care of doing the checking for you. | ||
| 107 | |||
| 108 | To support this feature, you only need to check the function_trace_stop | ||
| 109 | variable in the mcount function. If it is non-zero, there is no tracing to be | ||
| 110 | done at all, so you can return. | ||
| 111 | |||
| 112 | This additional pseudo code would simply be: | ||
| 113 | void mcount(void) | ||
| 114 | { | ||
| 115 | /* save any bare state needed in order to do initial checking */ | ||
| 116 | |||
| 117 | + if (function_trace_stop) | ||
| 118 | + return; | ||
| 119 | |||
| 120 | extern void (*ftrace_trace_function)(unsigned long, unsigned long); | ||
| 121 | if (ftrace_trace_function != ftrace_stub) | ||
| 122 | ... | ||
| 123 | |||
| 124 | |||
| 125 | HAVE_FUNCTION_GRAPH_TRACER | ||
| 126 | -------------------------- | ||
| 127 | |||
| 128 | Deep breath ... time to do some real work. Here you will need to update the | ||
| 129 | mcount function to check ftrace graph function pointers, as well as implement | ||
| 130 | some functions to save (hijack) and restore the return address. | ||
| 131 | |||
| 132 | The mcount function should check the function pointers ftrace_graph_return | ||
| 133 | (compare to ftrace_stub) and ftrace_graph_entry (compare to | ||
| 134 | ftrace_graph_entry_stub). If either of those are not set to the relevant stub | ||
| 135 | function, call the arch-specific function ftrace_graph_caller which in turn | ||
| 136 | calls the arch-specific function prepare_ftrace_return. Neither of these | ||
| 137 | function names are strictly required, but you should use them anyways to stay | ||
| 138 | consistent across the architecture ports -- easier to compare & contrast | ||
| 139 | things. | ||
| 140 | |||
| 141 | The arguments to prepare_ftrace_return are slightly different than what are | ||
| 142 | passed to ftrace_trace_function. The second argument "selfpc" is the same, | ||
| 143 | but the first argument should be a pointer to the "frompc". Typically this is | ||
| 144 | located on the stack. This allows the function to hijack the return address | ||
| 145 | temporarily to have it point to the arch-specific function return_to_handler. | ||
| 146 | That function will simply call the common ftrace_return_to_handler function and | ||
| 147 | that will return the original return address with which, you can return to the | ||
| 148 | original call site. | ||
| 149 | |||
| 150 | Here is the updated mcount pseudo code: | ||
| 151 | void mcount(void) | ||
| 152 | { | ||
| 153 | ... | ||
| 154 | if (ftrace_trace_function != ftrace_stub) | ||
| 155 | goto do_trace; | ||
| 156 | |||
| 157 | +#ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 158 | + extern void (*ftrace_graph_return)(...); | ||
| 159 | + extern void (*ftrace_graph_entry)(...); | ||
| 160 | + if (ftrace_graph_return != ftrace_stub || | ||
| 161 | + ftrace_graph_entry != ftrace_graph_entry_stub) | ||
| 162 | + ftrace_graph_caller(); | ||
| 163 | +#endif | ||
| 164 | |||
| 165 | /* restore any bare state */ | ||
| 166 | ... | ||
| 167 | |||
| 168 | Here is the pseudo code for the new ftrace_graph_caller assembly function: | ||
| 169 | #ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 170 | void ftrace_graph_caller(void) | ||
| 171 | { | ||
| 172 | /* save all state needed by the ABI */ | ||
| 173 | |||
| 174 | unsigned long *frompc = &...; | ||
| 175 | unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; | ||
| 176 | prepare_ftrace_return(frompc, selfpc); | ||
| 177 | |||
| 178 | /* restore all state needed by the ABI */ | ||
| 179 | } | ||
| 180 | #endif | ||
| 181 | |||
| 182 | For information on how to implement prepare_ftrace_return(), simply look at | ||
| 183 | the x86 version. The only architecture-specific piece in it is the setup of | ||
| 184 | the fault recovery table (the asm(...) code). The rest should be the same | ||
| 185 | across architectures. | ||
| 186 | |||
| 187 | Here is the pseudo code for the new return_to_handler assembly function. Note | ||
| 188 | that the ABI that applies here is different from what applies to the mcount | ||
| 189 | code. Since you are returning from a function (after the epilogue), you might | ||
| 190 | be able to skimp on things saved/restored (usually just registers used to pass | ||
| 191 | return values). | ||
| 192 | |||
| 193 | #ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 194 | void return_to_handler(void) | ||
| 195 | { | ||
| 196 | /* save all state needed by the ABI (see paragraph above) */ | ||
| 197 | |||
| 198 | void (*original_return_point)(void) = ftrace_return_to_handler(); | ||
| 199 | |||
| 200 | /* restore all state needed by the ABI */ | ||
| 201 | |||
| 202 | /* this is usually either a return or a jump */ | ||
| 203 | original_return_point(); | ||
| 204 | } | ||
| 205 | #endif | ||
| 206 | |||
| 207 | |||
| 208 | HAVE_FTRACE_NMI_ENTER | ||
| 209 | --------------------- | ||
| 210 | |||
| 211 | If you can't trace NMI functions, then skip this option. | ||
| 212 | |||
| 213 | <details to be filled> | ||
| 214 | |||
| 215 | |||
| 216 | HAVE_FTRACE_SYSCALLS | ||
| 217 | --------------------- | ||
| 218 | |||
| 219 | <details to be filled> | ||
| 220 | |||
| 221 | |||
| 222 | HAVE_FTRACE_MCOUNT_RECORD | ||
| 223 | ------------------------- | ||
| 224 | |||
| 225 | See scripts/recordmcount.pl for more info. | ||
| 226 | |||
| 227 | <details to be filled> | ||
| 228 | |||
| 229 | |||
| 230 | HAVE_DYNAMIC_FTRACE | ||
| 231 | --------------------- | ||
| 232 | |||
| 233 | <details to be filled> | ||
diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index a39b3c749de5..957b22fde2df 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt | |||
| @@ -26,6 +26,12 @@ disabled, and more (ftrace allows for tracer plugins, which | |||
| 26 | means that the list of tracers can always grow). | 26 | means that the list of tracers can always grow). |
| 27 | 27 | ||
| 28 | 28 | ||
| 29 | Implementation Details | ||
| 30 | ---------------------- | ||
| 31 | |||
| 32 | See ftrace-design.txt for details for arch porters and such. | ||
| 33 | |||
| 34 | |||
| 29 | The File System | 35 | The File System |
| 30 | --------------- | 36 | --------------- |
| 31 | 37 | ||
| @@ -85,26 +91,19 @@ of ftrace. Here is a list of some of the key files: | |||
| 85 | This file holds the output of the trace in a human | 91 | This file holds the output of the trace in a human |
| 86 | readable format (described below). | 92 | readable format (described below). |
| 87 | 93 | ||
| 88 | latency_trace: | ||
| 89 | |||
| 90 | This file shows the same trace but the information | ||
| 91 | is organized more to display possible latencies | ||
| 92 | in the system (described below). | ||
| 93 | |||
| 94 | trace_pipe: | 94 | trace_pipe: |
| 95 | 95 | ||
| 96 | The output is the same as the "trace" file but this | 96 | The output is the same as the "trace" file but this |
| 97 | file is meant to be streamed with live tracing. | 97 | file is meant to be streamed with live tracing. |
| 98 | Reads from this file will block until new data | 98 | Reads from this file will block until new data is |
| 99 | is retrieved. Unlike the "trace" and "latency_trace" | 99 | retrieved. Unlike the "trace" file, this file is a |
| 100 | files, this file is a consumer. This means reading | 100 | consumer. This means reading from this file causes |
| 101 | from this file causes sequential reads to display | 101 | sequential reads to display more current data. Once |
| 102 | more current data. Once data is read from this | 102 | data is read from this file, it is consumed, and |
| 103 | file, it is consumed, and will not be read | 103 | will not be read again with a sequential read. The |
| 104 | again with a sequential read. The "trace" and | 104 | "trace" file is static, and if the tracer is not |
| 105 | "latency_trace" files are static, and if the | 105 | adding more data,they will display the same |
| 106 | tracer is not adding more data, they will display | 106 | information every time they are read. |
| 107 | the same information every time they are read. | ||
| 108 | 107 | ||
| 109 | trace_options: | 108 | trace_options: |
| 110 | 109 | ||
| @@ -117,10 +116,10 @@ of ftrace. Here is a list of some of the key files: | |||
| 117 | Some of the tracers record the max latency. | 116 | Some of the tracers record the max latency. |
| 118 | For example, the time interrupts are disabled. | 117 | For example, the time interrupts are disabled. |
| 119 | This time is saved in this file. The max trace | 118 | This time is saved in this file. The max trace |
| 120 | will also be stored, and displayed by either | 119 | will also be stored, and displayed by "trace". |
| 121 | "trace" or "latency_trace". A new max trace will | 120 | A new max trace will only be recorded if the |
| 122 | only be recorded if the latency is greater than | 121 | latency is greater than the value in this |
| 123 | the value in this file. (in microseconds) | 122 | file. (in microseconds) |
| 124 | 123 | ||
| 125 | buffer_size_kb: | 124 | buffer_size_kb: |
| 126 | 125 | ||
| @@ -134,7 +133,7 @@ of ftrace. Here is a list of some of the key files: | |||
| 134 | than requested, the rest of the page will be used, | 133 | than requested, the rest of the page will be used, |
| 135 | making the actual allocation bigger than requested. | 134 | making the actual allocation bigger than requested. |
| 136 | ( Note, the size may not be a multiple of the page size | 135 | ( Note, the size may not be a multiple of the page size |
| 137 | due to buffer managment overhead. ) | 136 | due to buffer management overhead. ) |
| 138 | 137 | ||
| 139 | This can only be updated when the current_tracer | 138 | This can only be updated when the current_tracer |
| 140 | is set to "nop". | 139 | is set to "nop". |
| @@ -210,7 +209,7 @@ Here is the list of current tracers that may be configured. | |||
| 210 | the trace with the longest max latency. | 209 | the trace with the longest max latency. |
| 211 | See tracing_max_latency. When a new max is recorded, | 210 | See tracing_max_latency. When a new max is recorded, |
| 212 | it replaces the old trace. It is best to view this | 211 | it replaces the old trace. It is best to view this |
| 213 | trace via the latency_trace file. | 212 | trace with the latency-format option enabled. |
| 214 | 213 | ||
| 215 | "preemptoff" | 214 | "preemptoff" |
| 216 | 215 | ||
| @@ -307,8 +306,8 @@ the lowest priority thread (pid 0). | |||
| 307 | Latency trace format | 306 | Latency trace format |
| 308 | -------------------- | 307 | -------------------- |
| 309 | 308 | ||
| 310 | For traces that display latency times, the latency_trace file | 309 | When the latency-format option is enabled, the trace file gives |
| 311 | gives somewhat more information to see why a latency happened. | 310 | somewhat more information to see why a latency happened. |
| 312 | Here is a typical trace. | 311 | Here is a typical trace. |
| 313 | 312 | ||
| 314 | # tracer: irqsoff | 313 | # tracer: irqsoff |
| @@ -380,9 +379,10 @@ explains which is which. | |||
| 380 | 379 | ||
| 381 | The above is mostly meaningful for kernel developers. | 380 | The above is mostly meaningful for kernel developers. |
| 382 | 381 | ||
| 383 | time: This differs from the trace file output. The trace file output | 382 | time: When the latency-format option is enabled, the trace file |
| 384 | includes an absolute timestamp. The timestamp used by the | 383 | output includes a timestamp relative to the start of the |
| 385 | latency_trace file is relative to the start of the trace. | 384 | trace. This differs from the output when latency-format |
| 385 | is disabled, which includes an absolute timestamp. | ||
| 386 | 386 | ||
| 387 | delay: This is just to help catch your eye a bit better. And | 387 | delay: This is just to help catch your eye a bit better. And |
| 388 | needs to be fixed to be only relative to the same CPU. | 388 | needs to be fixed to be only relative to the same CPU. |
| @@ -440,7 +440,8 @@ Here are the available options: | |||
| 440 | sym-addr: | 440 | sym-addr: |
| 441 | bash-4000 [01] 1477.606694: simple_strtoul <c0339346> | 441 | bash-4000 [01] 1477.606694: simple_strtoul <c0339346> |
| 442 | 442 | ||
| 443 | verbose - This deals with the latency_trace file. | 443 | verbose - This deals with the trace file when the |
| 444 | latency-format option is enabled. | ||
| 444 | 445 | ||
| 445 | bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \ | 446 | bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \ |
| 446 | (+0.000ms): simple_strtoul (strict_strtoul) | 447 | (+0.000ms): simple_strtoul (strict_strtoul) |
| @@ -472,7 +473,7 @@ Here are the available options: | |||
| 472 | the app is no longer running | 473 | the app is no longer running |
| 473 | 474 | ||
| 474 | The lookup is performed when you read | 475 | The lookup is performed when you read |
| 475 | trace,trace_pipe,latency_trace. Example: | 476 | trace,trace_pipe. Example: |
| 476 | 477 | ||
| 477 | a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 | 478 | a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 |
| 478 | x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] | 479 | x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] |
| @@ -481,6 +482,11 @@ x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] | |||
| 481 | every scheduling event. Will add overhead if | 482 | every scheduling event. Will add overhead if |
| 482 | there's a lot of tasks running at once. | 483 | there's a lot of tasks running at once. |
| 483 | 484 | ||
| 485 | latency-format - This option changes the trace. When | ||
| 486 | it is enabled, the trace displays | ||
| 487 | additional information about the | ||
| 488 | latencies, as described in "Latency | ||
| 489 | trace format". | ||
| 484 | 490 | ||
| 485 | sched_switch | 491 | sched_switch |
| 486 | ------------ | 492 | ------------ |
| @@ -596,12 +602,13 @@ To reset the maximum, echo 0 into tracing_max_latency. Here is | |||
| 596 | an example: | 602 | an example: |
| 597 | 603 | ||
| 598 | # echo irqsoff > current_tracer | 604 | # echo irqsoff > current_tracer |
| 605 | # echo latency-format > trace_options | ||
| 599 | # echo 0 > tracing_max_latency | 606 | # echo 0 > tracing_max_latency |
| 600 | # echo 1 > tracing_enabled | 607 | # echo 1 > tracing_enabled |
| 601 | # ls -ltr | 608 | # ls -ltr |
| 602 | [...] | 609 | [...] |
| 603 | # echo 0 > tracing_enabled | 610 | # echo 0 > tracing_enabled |
| 604 | # cat latency_trace | 611 | # cat trace |
| 605 | # tracer: irqsoff | 612 | # tracer: irqsoff |
| 606 | # | 613 | # |
| 607 | irqsoff latency trace v1.1.5 on 2.6.26 | 614 | irqsoff latency trace v1.1.5 on 2.6.26 |
| @@ -703,12 +710,13 @@ which preemption was disabled. The control of preemptoff tracer | |||
| 703 | is much like the irqsoff tracer. | 710 | is much like the irqsoff tracer. |
| 704 | 711 | ||
| 705 | # echo preemptoff > current_tracer | 712 | # echo preemptoff > current_tracer |
| 713 | # echo latency-format > trace_options | ||
| 706 | # echo 0 > tracing_max_latency | 714 | # echo 0 > tracing_max_latency |
| 707 | # echo 1 > tracing_enabled | 715 | # echo 1 > tracing_enabled |
| 708 | # ls -ltr | 716 | # ls -ltr |
| 709 | [...] | 717 | [...] |
| 710 | # echo 0 > tracing_enabled | 718 | # echo 0 > tracing_enabled |
| 711 | # cat latency_trace | 719 | # cat trace |
| 712 | # tracer: preemptoff | 720 | # tracer: preemptoff |
| 713 | # | 721 | # |
| 714 | preemptoff latency trace v1.1.5 on 2.6.26-rc8 | 722 | preemptoff latency trace v1.1.5 on 2.6.26-rc8 |
| @@ -850,12 +858,13 @@ Again, using this trace is much like the irqsoff and preemptoff | |||
| 850 | tracers. | 858 | tracers. |
| 851 | 859 | ||
| 852 | # echo preemptirqsoff > current_tracer | 860 | # echo preemptirqsoff > current_tracer |
| 861 | # echo latency-format > trace_options | ||
| 853 | # echo 0 > tracing_max_latency | 862 | # echo 0 > tracing_max_latency |
| 854 | # echo 1 > tracing_enabled | 863 | # echo 1 > tracing_enabled |
| 855 | # ls -ltr | 864 | # ls -ltr |
| 856 | [...] | 865 | [...] |
| 857 | # echo 0 > tracing_enabled | 866 | # echo 0 > tracing_enabled |
| 858 | # cat latency_trace | 867 | # cat trace |
| 859 | # tracer: preemptirqsoff | 868 | # tracer: preemptirqsoff |
| 860 | # | 869 | # |
| 861 | preemptirqsoff latency trace v1.1.5 on 2.6.26-rc8 | 870 | preemptirqsoff latency trace v1.1.5 on 2.6.26-rc8 |
| @@ -1012,11 +1021,12 @@ Instead of performing an 'ls', we will run 'sleep 1' under | |||
| 1012 | 'chrt' which changes the priority of the task. | 1021 | 'chrt' which changes the priority of the task. |
| 1013 | 1022 | ||
| 1014 | # echo wakeup > current_tracer | 1023 | # echo wakeup > current_tracer |
| 1024 | # echo latency-format > trace_options | ||
| 1015 | # echo 0 > tracing_max_latency | 1025 | # echo 0 > tracing_max_latency |
| 1016 | # echo 1 > tracing_enabled | 1026 | # echo 1 > tracing_enabled |
| 1017 | # chrt -f 5 sleep 1 | 1027 | # chrt -f 5 sleep 1 |
| 1018 | # echo 0 > tracing_enabled | 1028 | # echo 0 > tracing_enabled |
| 1019 | # cat latency_trace | 1029 | # cat trace |
| 1020 | # tracer: wakeup | 1030 | # tracer: wakeup |
| 1021 | # | 1031 | # |
| 1022 | wakeup latency trace v1.1.5 on 2.6.26-rc8 | 1032 | wakeup latency trace v1.1.5 on 2.6.26-rc8 |
diff --git a/Documentation/trace/function-graph-fold.vim b/Documentation/trace/function-graph-fold.vim new file mode 100644 index 000000000000..0544b504c8b0 --- /dev/null +++ b/Documentation/trace/function-graph-fold.vim | |||
| @@ -0,0 +1,42 @@ | |||
| 1 | " Enable folding for ftrace function_graph traces. | ||
| 2 | " | ||
| 3 | " To use, :source this file while viewing a function_graph trace, or use vim's | ||
| 4 | " -S option to load from the command-line together with a trace. You can then | ||
| 5 | " use the usual vim fold commands, such as "za", to open and close nested | ||
| 6 | " functions. While closed, a fold will show the total time taken for a call, | ||
| 7 | " as would normally appear on the line with the closing brace. Folded | ||
| 8 | " functions will not include finish_task_switch(), so folding should remain | ||
| 9 | " relatively sane even through a context switch. | ||
| 10 | " | ||
| 11 | " Note that this will almost certainly only work well with a | ||
| 12 | " single-CPU trace (e.g. trace-cmd report --cpu 1). | ||
| 13 | |||
| 14 | function! FunctionGraphFoldExpr(lnum) | ||
| 15 | let line = getline(a:lnum) | ||
| 16 | if line[-1:] == '{' | ||
| 17 | if line =~ 'finish_task_switch() {$' | ||
| 18 | return '>1' | ||
| 19 | endif | ||
| 20 | return 'a1' | ||
| 21 | elseif line[-1:] == '}' | ||
| 22 | return 's1' | ||
| 23 | else | ||
| 24 | return '=' | ||
| 25 | endif | ||
| 26 | endfunction | ||
| 27 | |||
| 28 | function! FunctionGraphFoldText() | ||
| 29 | let s = split(getline(v:foldstart), '|', 1) | ||
| 30 | if getline(v:foldend+1) =~ 'finish_task_switch() {$' | ||
| 31 | let s[2] = ' task switch ' | ||
| 32 | else | ||
| 33 | let e = split(getline(v:foldend), '|', 1) | ||
| 34 | let s[2] = e[2] | ||
| 35 | endif | ||
| 36 | return join(s, '|') | ||
| 37 | endfunction | ||
| 38 | |||
| 39 | setlocal foldexpr=FunctionGraphFoldExpr(v:lnum) | ||
| 40 | setlocal foldtext=FunctionGraphFoldText() | ||
| 41 | setlocal foldcolumn=12 | ||
| 42 | setlocal foldmethod=expr | ||
diff --git a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl new file mode 100644 index 000000000000..7df50e8cf4d9 --- /dev/null +++ b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl | |||
| @@ -0,0 +1,418 @@ | |||
| 1 | #!/usr/bin/perl | ||
| 2 | # This is a POC (proof of concept or piece of crap, take your pick) for reading the | ||
| 3 | # text representation of trace output related to page allocation. It makes an attempt | ||
| 4 | # to extract some high-level information on what is going on. The accuracy of the parser | ||
| 5 | # may vary considerably | ||
| 6 | # | ||
| 7 | # Example usage: trace-pagealloc-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe | ||
| 8 | # other options | ||
| 9 | # --prepend-parent Report on the parent proc and PID | ||
| 10 | # --read-procstat If the trace lacks process info, get it from /proc | ||
| 11 | # --ignore-pid Aggregate processes of the same name together | ||
| 12 | # | ||
| 13 | # Copyright (c) IBM Corporation 2009 | ||
| 14 | # Author: Mel Gorman <mel@csn.ul.ie> | ||
| 15 | use strict; | ||
| 16 | use Getopt::Long; | ||
| 17 | |||
| 18 | # Tracepoint events | ||
| 19 | use constant MM_PAGE_ALLOC => 1; | ||
| 20 | use constant MM_PAGE_FREE_DIRECT => 2; | ||
| 21 | use constant MM_PAGEVEC_FREE => 3; | ||
| 22 | use constant MM_PAGE_PCPU_DRAIN => 4; | ||
| 23 | use constant MM_PAGE_ALLOC_ZONE_LOCKED => 5; | ||
| 24 | use constant MM_PAGE_ALLOC_EXTFRAG => 6; | ||
| 25 | use constant EVENT_UNKNOWN => 7; | ||
| 26 | |||
| 27 | # Constants used to track state | ||
| 28 | use constant STATE_PCPU_PAGES_DRAINED => 8; | ||
| 29 | use constant STATE_PCPU_PAGES_REFILLED => 9; | ||
| 30 | |||
| 31 | # High-level events extrapolated from tracepoints | ||
| 32 | use constant HIGH_PCPU_DRAINS => 10; | ||
| 33 | use constant HIGH_PCPU_REFILLS => 11; | ||
| 34 | use constant HIGH_EXT_FRAGMENT => 12; | ||
| 35 | use constant HIGH_EXT_FRAGMENT_SEVERE => 13; | ||
| 36 | use constant HIGH_EXT_FRAGMENT_MODERATE => 14; | ||
| 37 | use constant HIGH_EXT_FRAGMENT_CHANGED => 15; | ||
| 38 | |||
| 39 | my %perprocesspid; | ||
| 40 | my %perprocess; | ||
| 41 | my $opt_ignorepid; | ||
| 42 | my $opt_read_procstat; | ||
| 43 | my $opt_prepend_parent; | ||
| 44 | |||
| 45 | # Catch sigint and exit on request | ||
| 46 | my $sigint_report = 0; | ||
| 47 | my $sigint_exit = 0; | ||
| 48 | my $sigint_pending = 0; | ||
| 49 | my $sigint_received = 0; | ||
| 50 | sub sigint_handler { | ||
| 51 | my $current_time = time; | ||
| 52 | if ($current_time - 2 > $sigint_received) { | ||
| 53 | print "SIGINT received, report pending. Hit ctrl-c again to exit\n"; | ||
| 54 | $sigint_report = 1; | ||
| 55 | } else { | ||
| 56 | if (!$sigint_exit) { | ||
| 57 | print "Second SIGINT received quickly, exiting\n"; | ||
| 58 | } | ||
| 59 | $sigint_exit++; | ||
| 60 | } | ||
| 61 | |||
| 62 | if ($sigint_exit > 3) { | ||
| 63 | print "Many SIGINTs received, exiting now without report\n"; | ||
| 64 | exit; | ||
| 65 | } | ||
| 66 | |||
| 67 | $sigint_received = $current_time; | ||
| 68 | $sigint_pending = 1; | ||
| 69 | } | ||
| 70 | $SIG{INT} = "sigint_handler"; | ||
| 71 | |||
| 72 | # Parse command line options | ||
| 73 | GetOptions( | ||
| 74 | 'ignore-pid' => \$opt_ignorepid, | ||
| 75 | 'read-procstat' => \$opt_read_procstat, | ||
| 76 | 'prepend-parent' => \$opt_prepend_parent, | ||
| 77 | ); | ||
| 78 | |||
| 79 | # Defaults for dynamically discovered regex's | ||
| 80 | my $regex_fragdetails_default = 'page=([0-9a-f]*) pfn=([0-9]*) alloc_order=([-0-9]*) fallback_order=([-0-9]*) pageblock_order=([-0-9]*) alloc_migratetype=([-0-9]*) fallback_migratetype=([-0-9]*) fragmenting=([-0-9]) change_ownership=([-0-9])'; | ||
| 81 | |||
| 82 | # Dyanically discovered regex | ||
| 83 | my $regex_fragdetails; | ||
| 84 | |||
| 85 | # Static regex used. Specified like this for readability and for use with /o | ||
| 86 | # (process_pid) (cpus ) ( time ) (tpoint ) (details) | ||
| 87 | my $regex_traceevent = '\s*([a-zA-Z0-9-]*)\s*(\[[0-9]*\])\s*([0-9.]*):\s*([a-zA-Z_]*):\s*(.*)'; | ||
| 88 | my $regex_statname = '[-0-9]*\s\((.*)\).*'; | ||
| 89 | my $regex_statppid = '[-0-9]*\s\(.*\)\s[A-Za-z]\s([0-9]*).*'; | ||
| 90 | |||
| 91 | sub generate_traceevent_regex { | ||
| 92 | my $event = shift; | ||
| 93 | my $default = shift; | ||
| 94 | my $regex; | ||
| 95 | |||
| 96 | # Read the event format or use the default | ||
| 97 | if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { | ||
| 98 | $regex = $default; | ||
| 99 | } else { | ||
| 100 | my $line; | ||
| 101 | while (!eof(FORMAT)) { | ||
| 102 | $line = <FORMAT>; | ||
| 103 | if ($line =~ /^print fmt:\s"(.*)",.*/) { | ||
| 104 | $regex = $1; | ||
| 105 | $regex =~ s/%p/\([0-9a-f]*\)/g; | ||
| 106 | $regex =~ s/%d/\([-0-9]*\)/g; | ||
| 107 | $regex =~ s/%lu/\([0-9]*\)/g; | ||
| 108 | } | ||
| 109 | } | ||
| 110 | } | ||
| 111 | |||
| 112 | # Verify fields are in the right order | ||
| 113 | my $tuple; | ||
| 114 | foreach $tuple (split /\s/, $regex) { | ||
| 115 | my ($key, $value) = split(/=/, $tuple); | ||
| 116 | my $expected = shift; | ||
| 117 | if ($key ne $expected) { | ||
| 118 | print("WARNING: Format not as expected '$key' != '$expected'"); | ||
| 119 | $regex =~ s/$key=\((.*)\)/$key=$1/; | ||
| 120 | } | ||
| 121 | } | ||
| 122 | |||
| 123 | if (defined shift) { | ||
| 124 | die("Fewer fields than expected in format"); | ||
| 125 | } | ||
| 126 | |||
| 127 | return $regex; | ||
| 128 | } | ||
| 129 | $regex_fragdetails = generate_traceevent_regex("kmem/mm_page_alloc_extfrag", | ||
| 130 | $regex_fragdetails_default, | ||
| 131 | "page", "pfn", | ||
| 132 | "alloc_order", "fallback_order", "pageblock_order", | ||
| 133 | "alloc_migratetype", "fallback_migratetype", | ||
| 134 | "fragmenting", "change_ownership"); | ||
| 135 | |||
| 136 | sub read_statline($) { | ||
| 137 | my $pid = $_[0]; | ||
| 138 | my $statline; | ||
| 139 | |||
| 140 | if (open(STAT, "/proc/$pid/stat")) { | ||
| 141 | $statline = <STAT>; | ||
| 142 | close(STAT); | ||
| 143 | } | ||
| 144 | |||
| 145 | if ($statline eq '') { | ||
| 146 | $statline = "-1 (UNKNOWN_PROCESS_NAME) R 0"; | ||
| 147 | } | ||
| 148 | |||
| 149 | return $statline; | ||
| 150 | } | ||
| 151 | |||
| 152 | sub guess_process_pid($$) { | ||
| 153 | my $pid = $_[0]; | ||
| 154 | my $statline = $_[1]; | ||
| 155 | |||
| 156 | if ($pid == 0) { | ||
| 157 | return "swapper-0"; | ||
| 158 | } | ||
| 159 | |||
| 160 | if ($statline !~ /$regex_statname/o) { | ||
| 161 | die("Failed to math stat line for process name :: $statline"); | ||
| 162 | } | ||
| 163 | return "$1-$pid"; | ||
| 164 | } | ||
| 165 | |||
| 166 | sub parent_info($$) { | ||
| 167 | my $pid = $_[0]; | ||
| 168 | my $statline = $_[1]; | ||
| 169 | my $ppid; | ||
| 170 | |||
| 171 | if ($pid == 0) { | ||
| 172 | return "NOPARENT-0"; | ||
| 173 | } | ||
| 174 | |||
| 175 | if ($statline !~ /$regex_statppid/o) { | ||
| 176 | die("Failed to match stat line process ppid:: $statline"); | ||
| 177 | } | ||
| 178 | |||
| 179 | # Read the ppid stat line | ||
| 180 | $ppid = $1; | ||
| 181 | return guess_process_pid($ppid, read_statline($ppid)); | ||
| 182 | } | ||
| 183 | |||
| 184 | sub process_events { | ||
| 185 | my $traceevent; | ||
| 186 | my $process_pid; | ||
| 187 | my $cpus; | ||
| 188 | my $timestamp; | ||
| 189 | my $tracepoint; | ||
| 190 | my $details; | ||
| 191 | my $statline; | ||
| 192 | |||
| 193 | # Read each line of the event log | ||
| 194 | EVENT_PROCESS: | ||
| 195 | while ($traceevent = <STDIN>) { | ||
| 196 | if ($traceevent =~ /$regex_traceevent/o) { | ||
| 197 | $process_pid = $1; | ||
| 198 | $tracepoint = $4; | ||
| 199 | |||
| 200 | if ($opt_read_procstat || $opt_prepend_parent) { | ||
| 201 | $process_pid =~ /(.*)-([0-9]*)$/; | ||
| 202 | my $process = $1; | ||
| 203 | my $pid = $2; | ||
| 204 | |||
| 205 | $statline = read_statline($pid); | ||
| 206 | |||
| 207 | if ($opt_read_procstat && $process eq '') { | ||
| 208 | $process_pid = guess_process_pid($pid, $statline); | ||
| 209 | } | ||
| 210 | |||
| 211 | if ($opt_prepend_parent) { | ||
| 212 | $process_pid = parent_info($pid, $statline) . " :: $process_pid"; | ||
| 213 | } | ||
| 214 | } | ||
| 215 | |||
| 216 | # Unnecessary in this script. Uncomment if required | ||
| 217 | # $cpus = $2; | ||
| 218 | # $timestamp = $3; | ||
| 219 | } else { | ||
| 220 | next; | ||
| 221 | } | ||
| 222 | |||
| 223 | # Perl Switch() sucks majorly | ||
| 224 | if ($tracepoint eq "mm_page_alloc") { | ||
| 225 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC}++; | ||
| 226 | } elsif ($tracepoint eq "mm_page_free_direct") { | ||
| 227 | $perprocesspid{$process_pid}->{MM_PAGE_FREE_DIRECT}++; | ||
| 228 | } elsif ($tracepoint eq "mm_pagevec_free") { | ||
| 229 | $perprocesspid{$process_pid}->{MM_PAGEVEC_FREE}++; | ||
| 230 | } elsif ($tracepoint eq "mm_page_pcpu_drain") { | ||
| 231 | $perprocesspid{$process_pid}->{MM_PAGE_PCPU_DRAIN}++; | ||
| 232 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED}++; | ||
| 233 | } elsif ($tracepoint eq "mm_page_alloc_zone_locked") { | ||
| 234 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}++; | ||
| 235 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED}++; | ||
| 236 | } elsif ($tracepoint eq "mm_page_alloc_extfrag") { | ||
| 237 | |||
| 238 | # Extract the details of the event now | ||
| 239 | $details = $5; | ||
| 240 | |||
| 241 | my ($page, $pfn); | ||
| 242 | my ($alloc_order, $fallback_order, $pageblock_order); | ||
| 243 | my ($alloc_migratetype, $fallback_migratetype); | ||
| 244 | my ($fragmenting, $change_ownership); | ||
| 245 | |||
| 246 | if ($details !~ /$regex_fragdetails/o) { | ||
| 247 | print "WARNING: Failed to parse mm_page_alloc_extfrag as expected\n"; | ||
| 248 | next; | ||
| 249 | } | ||
| 250 | |||
| 251 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}++; | ||
| 252 | $page = $1; | ||
| 253 | $pfn = $2; | ||
| 254 | $alloc_order = $3; | ||
| 255 | $fallback_order = $4; | ||
| 256 | $pageblock_order = $5; | ||
| 257 | $alloc_migratetype = $6; | ||
| 258 | $fallback_migratetype = $7; | ||
| 259 | $fragmenting = $8; | ||
| 260 | $change_ownership = $9; | ||
| 261 | |||
| 262 | if ($fragmenting) { | ||
| 263 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAG}++; | ||
| 264 | if ($fallback_order <= 3) { | ||
| 265 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}++; | ||
| 266 | } else { | ||
| 267 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}++; | ||
| 268 | } | ||
| 269 | } | ||
| 270 | if ($change_ownership) { | ||
| 271 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}++; | ||
| 272 | } | ||
| 273 | } else { | ||
| 274 | $perprocesspid{$process_pid}->{EVENT_UNKNOWN}++; | ||
| 275 | } | ||
| 276 | |||
| 277 | # Catch a full pcpu drain event | ||
| 278 | if ($perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED} && | ||
| 279 | $tracepoint ne "mm_page_pcpu_drain") { | ||
| 280 | |||
| 281 | $perprocesspid{$process_pid}->{HIGH_PCPU_DRAINS}++; | ||
| 282 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED} = 0; | ||
| 283 | } | ||
| 284 | |||
| 285 | # Catch a full pcpu refill event | ||
| 286 | if ($perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED} && | ||
| 287 | $tracepoint ne "mm_page_alloc_zone_locked") { | ||
| 288 | $perprocesspid{$process_pid}->{HIGH_PCPU_REFILLS}++; | ||
| 289 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED} = 0; | ||
| 290 | } | ||
| 291 | |||
| 292 | if ($sigint_pending) { | ||
| 293 | last EVENT_PROCESS; | ||
| 294 | } | ||
| 295 | } | ||
| 296 | } | ||
| 297 | |||
| 298 | sub dump_stats { | ||
| 299 | my $hashref = shift; | ||
| 300 | my %stats = %$hashref; | ||
| 301 | |||
| 302 | # Dump per-process stats | ||
| 303 | my $process_pid; | ||
| 304 | my $max_strlen = 0; | ||
| 305 | |||
| 306 | # Get the maximum process name | ||
| 307 | foreach $process_pid (keys %perprocesspid) { | ||
| 308 | my $len = length($process_pid); | ||
| 309 | if ($len > $max_strlen) { | ||
| 310 | $max_strlen = $len; | ||
| 311 | } | ||
| 312 | } | ||
| 313 | $max_strlen += 2; | ||
| 314 | |||
| 315 | printf("\n"); | ||
| 316 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 317 | "Process", "Pages", "Pages", "Pages", "Pages", "PCPU", "PCPU", "PCPU", "Fragment", "Fragment", "MigType", "Fragment", "Fragment", "Unknown"); | ||
| 318 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 319 | "details", "allocd", "allocd", "freed", "freed", "pages", "drains", "refills", "Fallback", "Causing", "Changed", "Severe", "Moderate", ""); | ||
| 320 | |||
| 321 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 322 | "", "", "under lock", "direct", "pagevec", "drain", "", "", "", "", "", "", "", ""); | ||
| 323 | |||
| 324 | foreach $process_pid (keys %stats) { | ||
| 325 | # Dump final aggregates | ||
| 326 | if ($stats{$process_pid}->{STATE_PCPU_PAGES_DRAINED}) { | ||
| 327 | $stats{$process_pid}->{HIGH_PCPU_DRAINS}++; | ||
| 328 | $stats{$process_pid}->{STATE_PCPU_PAGES_DRAINED} = 0; | ||
| 329 | } | ||
| 330 | if ($stats{$process_pid}->{STATE_PCPU_PAGES_REFILLED}) { | ||
| 331 | $stats{$process_pid}->{HIGH_PCPU_REFILLS}++; | ||
| 332 | $stats{$process_pid}->{STATE_PCPU_PAGES_REFILLED} = 0; | ||
| 333 | } | ||
| 334 | |||
| 335 | printf("%-" . $max_strlen . "s %8d %10d %8d %8d %8d %8d %8d %8d %8d %8d %8d %8d %8d\n", | ||
| 336 | $process_pid, | ||
| 337 | $stats{$process_pid}->{MM_PAGE_ALLOC}, | ||
| 338 | $stats{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}, | ||
| 339 | $stats{$process_pid}->{MM_PAGE_FREE_DIRECT}, | ||
| 340 | $stats{$process_pid}->{MM_PAGEVEC_FREE}, | ||
| 341 | $stats{$process_pid}->{MM_PAGE_PCPU_DRAIN}, | ||
| 342 | $stats{$process_pid}->{HIGH_PCPU_DRAINS}, | ||
| 343 | $stats{$process_pid}->{HIGH_PCPU_REFILLS}, | ||
| 344 | $stats{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}, | ||
| 345 | $stats{$process_pid}->{HIGH_EXT_FRAG}, | ||
| 346 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}, | ||
| 347 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}, | ||
| 348 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}, | ||
| 349 | $stats{$process_pid}->{EVENT_UNKNOWN}); | ||
| 350 | } | ||
| 351 | } | ||
| 352 | |||
| 353 | sub aggregate_perprocesspid() { | ||
| 354 | my $process_pid; | ||
| 355 | my $process; | ||
| 356 | undef %perprocess; | ||
| 357 | |||
| 358 | foreach $process_pid (keys %perprocesspid) { | ||
| 359 | $process = $process_pid; | ||
| 360 | $process =~ s/-([0-9])*$//; | ||
| 361 | if ($process eq '') { | ||
| 362 | $process = "NO_PROCESS_NAME"; | ||
| 363 | } | ||
| 364 | |||
| 365 | $perprocess{$process}->{MM_PAGE_ALLOC} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC}; | ||
| 366 | $perprocess{$process}->{MM_PAGE_ALLOC_ZONE_LOCKED} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}; | ||
| 367 | $perprocess{$process}->{MM_PAGE_FREE_DIRECT} += $perprocesspid{$process_pid}->{MM_PAGE_FREE_DIRECT}; | ||
| 368 | $perprocess{$process}->{MM_PAGEVEC_FREE} += $perprocesspid{$process_pid}->{MM_PAGEVEC_FREE}; | ||
| 369 | $perprocess{$process}->{MM_PAGE_PCPU_DRAIN} += $perprocesspid{$process_pid}->{MM_PAGE_PCPU_DRAIN}; | ||
| 370 | $perprocess{$process}->{HIGH_PCPU_DRAINS} += $perprocesspid{$process_pid}->{HIGH_PCPU_DRAINS}; | ||
| 371 | $perprocess{$process}->{HIGH_PCPU_REFILLS} += $perprocesspid{$process_pid}->{HIGH_PCPU_REFILLS}; | ||
| 372 | $perprocess{$process}->{MM_PAGE_ALLOC_EXTFRAG} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}; | ||
| 373 | $perprocess{$process}->{HIGH_EXT_FRAG} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAG}; | ||
| 374 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_CHANGED} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}; | ||
| 375 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_SEVERE} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}; | ||
| 376 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_MODERATE} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}; | ||
| 377 | $perprocess{$process}->{EVENT_UNKNOWN} += $perprocesspid{$process_pid}->{EVENT_UNKNOWN}; | ||
| 378 | } | ||
| 379 | } | ||
| 380 | |||
| 381 | sub report() { | ||
| 382 | if (!$opt_ignorepid) { | ||
| 383 | dump_stats(\%perprocesspid); | ||
| 384 | } else { | ||
| 385 | aggregate_perprocesspid(); | ||
| 386 | dump_stats(\%perprocess); | ||
| 387 | } | ||
| 388 | } | ||
| 389 | |||
| 390 | # Process events or signals until neither is available | ||
| 391 | sub signal_loop() { | ||
| 392 | my $sigint_processed; | ||
| 393 | do { | ||
| 394 | $sigint_processed = 0; | ||
| 395 | process_events(); | ||
| 396 | |||
| 397 | # Handle pending signals if any | ||
| 398 | if ($sigint_pending) { | ||
| 399 | my $current_time = time; | ||
| 400 | |||
| 401 | if ($sigint_exit) { | ||
| 402 | print "Received exit signal\n"; | ||
| 403 | $sigint_pending = 0; | ||
| 404 | } | ||
| 405 | if ($sigint_report) { | ||
| 406 | if ($current_time >= $sigint_received + 2) { | ||
| 407 | report(); | ||
| 408 | $sigint_report = 0; | ||
| 409 | $sigint_pending = 0; | ||
| 410 | $sigint_processed = 1; | ||
| 411 | } | ||
| 412 | } | ||
| 413 | } | ||
| 414 | } while ($sigint_pending || $sigint_processed); | ||
| 415 | } | ||
| 416 | |||
| 417 | signal_loop(); | ||
| 418 | report(); | ||
diff --git a/Documentation/trace/power.txt b/Documentation/trace/power.txt deleted file mode 100644 index cd805e16dc27..000000000000 --- a/Documentation/trace/power.txt +++ /dev/null | |||
| @@ -1,17 +0,0 @@ | |||
| 1 | The power tracer collects detailed information about C-state and P-state | ||
| 2 | transitions, instead of just looking at the high-level "average" | ||
| 3 | information. | ||
| 4 | |||
| 5 | There is a helper script found in scrips/tracing/power.pl in the kernel | ||
| 6 | sources which can be used to parse this information and create a | ||
| 7 | Scalable Vector Graphics (SVG) picture from the trace data. | ||
| 8 | |||
| 9 | To use this tracer: | ||
| 10 | |||
| 11 | echo 0 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 12 | echo power > /sys/kernel/debug/tracing/current_tracer | ||
| 13 | echo 1 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 14 | sleep 1 | ||
| 15 | echo 0 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 16 | cat /sys/kernel/debug/tracing/trace | \ | ||
| 17 | perl scripts/tracing/power.pl > out.sv | ||
diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.txt new file mode 100644 index 000000000000..5b1d23d604c5 --- /dev/null +++ b/Documentation/trace/ring-buffer-design.txt | |||
| @@ -0,0 +1,955 @@ | |||
| 1 | Lockless Ring Buffer Design | ||
| 2 | =========================== | ||
| 3 | |||
| 4 | Copyright 2009 Red Hat Inc. | ||
| 5 | Author: Steven Rostedt <srostedt@redhat.com> | ||
| 6 | License: The GNU Free Documentation License, Version 1.2 | ||
| 7 | (dual licensed under the GPL v2) | ||
| 8 | Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto, | ||
| 9 | and Frederic Weisbecker. | ||
| 10 | |||
| 11 | |||
| 12 | Written for: 2.6.31 | ||
| 13 | |||
| 14 | Terminology used in this Document | ||
| 15 | --------------------------------- | ||
| 16 | |||
| 17 | tail - where new writes happen in the ring buffer. | ||
| 18 | |||
| 19 | head - where new reads happen in the ring buffer. | ||
| 20 | |||
| 21 | producer - the task that writes into the ring buffer (same as writer) | ||
| 22 | |||
| 23 | writer - same as producer | ||
| 24 | |||
| 25 | consumer - the task that reads from the buffer (same as reader) | ||
| 26 | |||
| 27 | reader - same as consumer. | ||
| 28 | |||
| 29 | reader_page - A page outside the ring buffer used solely (for the most part) | ||
| 30 | by the reader. | ||
| 31 | |||
| 32 | head_page - a pointer to the page that the reader will use next | ||
| 33 | |||
| 34 | tail_page - a pointer to the page that will be written to next | ||
| 35 | |||
| 36 | commit_page - a pointer to the page with the last finished non nested write. | ||
| 37 | |||
| 38 | cmpxchg - hardware assisted atomic transaction that performs the following: | ||
| 39 | |||
| 40 | A = B iff previous A == C | ||
| 41 | |||
| 42 | R = cmpxchg(A, C, B) is saying that we replace A with B if and only if | ||
| 43 | current A is equal to C, and we put the old (current) A into R | ||
| 44 | |||
| 45 | R gets the previous A regardless if A is updated with B or not. | ||
| 46 | |||
| 47 | To see if the update was successful a compare of R == C may be used. | ||
| 48 | |||
| 49 | The Generic Ring Buffer | ||
| 50 | ----------------------- | ||
| 51 | |||
| 52 | The ring buffer can be used in either an overwrite mode or in | ||
| 53 | producer/consumer mode. | ||
| 54 | |||
| 55 | Producer/consumer mode is where the producer were to fill up the | ||
| 56 | buffer before the consumer could free up anything, the producer | ||
| 57 | will stop writing to the buffer. This will lose most recent events. | ||
| 58 | |||
| 59 | Overwrite mode is where the produce were to fill up the buffer | ||
| 60 | before the consumer could free up anything, the producer will | ||
| 61 | overwrite the older data. This will lose the oldest events. | ||
| 62 | |||
| 63 | No two writers can write at the same time (on the same per cpu buffer), | ||
| 64 | but a writer may interrupt another writer, but it must finish writing | ||
| 65 | before the previous writer may continue. This is very important to the | ||
| 66 | algorithm. The writers act like a "stack". The way interrupts works | ||
| 67 | enforces this behavior. | ||
| 68 | |||
| 69 | |||
| 70 | writer1 start | ||
| 71 | <preempted> writer2 start | ||
| 72 | <preempted> writer3 start | ||
| 73 | writer3 finishes | ||
| 74 | writer2 finishes | ||
| 75 | writer1 finishes | ||
| 76 | |||
| 77 | This is very much like a writer being preempted by an interrupt and | ||
| 78 | the interrupt doing a write as well. | ||
| 79 | |||
| 80 | Readers can happen at any time. But no two readers may run at the | ||
| 81 | same time, nor can a reader preempt/interrupt another reader. A reader | ||
| 82 | can not preempt/interrupt a writer, but it may read/consume from the | ||
| 83 | buffer at the same time as a writer is writing, but the reader must be | ||
| 84 | on another processor to do so. A reader may read on its own processor | ||
| 85 | and can be preempted by a writer. | ||
| 86 | |||
| 87 | A writer can preempt a reader, but a reader can not preempt a writer. | ||
| 88 | But a reader can read the buffer at the same time (on another processor) | ||
| 89 | as a writer. | ||
| 90 | |||
| 91 | The ring buffer is made up of a list of pages held together by a link list. | ||
| 92 | |||
| 93 | At initialization a reader page is allocated for the reader that is not | ||
| 94 | part of the ring buffer. | ||
| 95 | |||
| 96 | The head_page, tail_page and commit_page are all initialized to point | ||
| 97 | to the same page. | ||
| 98 | |||
| 99 | The reader page is initialized to have its next pointer pointing to | ||
| 100 | the head page, and its previous pointer pointing to a page before | ||
| 101 | the head page. | ||
| 102 | |||
| 103 | The reader has its own page to use. At start up time, this page is | ||
| 104 | allocated but is not attached to the list. When the reader wants | ||
| 105 | to read from the buffer, if its page is empty (like it is on start up) | ||
| 106 | it will swap its page with the head_page. The old reader page will | ||
| 107 | become part of the ring buffer and the head_page will be removed. | ||
| 108 | The page after the inserted page (old reader_page) will become the | ||
| 109 | new head page. | ||
| 110 | |||
| 111 | Once the new page is given to the reader, the reader could do what | ||
| 112 | it wants with it, as long as a writer has left that page. | ||
| 113 | |||
| 114 | A sample of how the reader page is swapped: Note this does not | ||
| 115 | show the head page in the buffer, it is for demonstrating a swap | ||
| 116 | only. | ||
| 117 | |||
| 118 | +------+ | ||
| 119 | |reader| RING BUFFER | ||
| 120 | |page | | ||
| 121 | +------+ | ||
| 122 | +---+ +---+ +---+ | ||
| 123 | | |-->| |-->| | | ||
| 124 | | |<--| |<--| | | ||
| 125 | +---+ +---+ +---+ | ||
| 126 | ^ | ^ | | ||
| 127 | | +-------------+ | | ||
| 128 | +-----------------+ | ||
| 129 | |||
| 130 | |||
| 131 | +------+ | ||
| 132 | |reader| RING BUFFER | ||
| 133 | |page |-------------------+ | ||
| 134 | +------+ v | ||
| 135 | | +---+ +---+ +---+ | ||
| 136 | | | |-->| |-->| | | ||
| 137 | | | |<--| |<--| |<-+ | ||
| 138 | | +---+ +---+ +---+ | | ||
| 139 | | ^ | ^ | | | ||
| 140 | | | +-------------+ | | | ||
| 141 | | +-----------------+ | | ||
| 142 | +------------------------------------+ | ||
| 143 | |||
| 144 | +------+ | ||
| 145 | |reader| RING BUFFER | ||
| 146 | |page |-------------------+ | ||
| 147 | +------+ <---------------+ v | ||
| 148 | | ^ +---+ +---+ +---+ | ||
| 149 | | | | |-->| |-->| | | ||
| 150 | | | | | | |<--| |<-+ | ||
| 151 | | | +---+ +---+ +---+ | | ||
| 152 | | | | ^ | | | ||
| 153 | | | +-------------+ | | | ||
| 154 | | +-----------------------------+ | | ||
| 155 | +------------------------------------+ | ||
| 156 | |||
| 157 | +------+ | ||
| 158 | |buffer| RING BUFFER | ||
| 159 | |page |-------------------+ | ||
| 160 | +------+ <---------------+ v | ||
| 161 | | ^ +---+ +---+ +---+ | ||
| 162 | | | | | | |-->| | | ||
| 163 | | | New | | | |<--| |<-+ | ||
| 164 | | | Reader +---+ +---+ +---+ | | ||
| 165 | | | page ----^ | | | ||
| 166 | | | | | | ||
| 167 | | +-----------------------------+ | | ||
| 168 | +------------------------------------+ | ||
| 169 | |||
| 170 | |||
| 171 | |||
| 172 | It is possible that the page swapped is the commit page and the tail page, | ||
| 173 | if what is in the ring buffer is less than what is held in a buffer page. | ||
| 174 | |||
| 175 | |||
| 176 | reader page commit page tail page | ||
| 177 | | | | | ||
| 178 | v | | | ||
| 179 | +---+ | | | ||
| 180 | | |<----------+ | | ||
| 181 | | |<------------------------+ | ||
| 182 | | |------+ | ||
| 183 | +---+ | | ||
| 184 | | | ||
| 185 | v | ||
| 186 | +---+ +---+ +---+ +---+ | ||
| 187 | <---| |--->| |--->| |--->| |---> | ||
| 188 | --->| |<---| |<---| |<---| |<--- | ||
| 189 | +---+ +---+ +---+ +---+ | ||
| 190 | |||
| 191 | This case is still valid for this algorithm. | ||
| 192 | When the writer leaves the page, it simply goes into the ring buffer | ||
| 193 | since the reader page still points to the next location in the ring | ||
| 194 | buffer. | ||
| 195 | |||
| 196 | |||
| 197 | The main pointers: | ||
| 198 | |||
| 199 | reader page - The page used solely by the reader and is not part | ||
| 200 | of the ring buffer (may be swapped in) | ||
| 201 | |||
| 202 | head page - the next page in the ring buffer that will be swapped | ||
| 203 | with the reader page. | ||
| 204 | |||
| 205 | tail page - the page where the next write will take place. | ||
| 206 | |||
| 207 | commit page - the page that last finished a write. | ||
| 208 | |||
| 209 | The commit page only is updated by the outer most writer in the | ||
| 210 | writer stack. A writer that preempts another writer will not move the | ||
| 211 | commit page. | ||
| 212 | |||
| 213 | When data is written into the ring buffer, a position is reserved | ||
| 214 | in the ring buffer and passed back to the writer. When the writer | ||
| 215 | is finished writing data into that position, it commits the write. | ||
| 216 | |||
| 217 | Another write (or a read) may take place at anytime during this | ||
| 218 | transaction. If another write happens it must finish before continuing | ||
| 219 | with the previous write. | ||
| 220 | |||
| 221 | |||
| 222 | Write reserve: | ||
| 223 | |||
| 224 | Buffer page | ||
| 225 | +---------+ | ||
| 226 | |written | | ||
| 227 | +---------+ <--- given back to writer (current commit) | ||
| 228 | |reserved | | ||
| 229 | +---------+ <--- tail pointer | ||
| 230 | | empty | | ||
| 231 | +---------+ | ||
| 232 | |||
| 233 | Write commit: | ||
| 234 | |||
| 235 | Buffer page | ||
| 236 | +---------+ | ||
| 237 | |written | | ||
| 238 | +---------+ | ||
| 239 | |written | | ||
| 240 | +---------+ <--- next positon for write (current commit) | ||
| 241 | | empty | | ||
| 242 | +---------+ | ||
| 243 | |||
| 244 | |||
| 245 | If a write happens after the first reserve: | ||
| 246 | |||
| 247 | Buffer page | ||
| 248 | +---------+ | ||
| 249 | |written | | ||
| 250 | +---------+ <-- current commit | ||
| 251 | |reserved | | ||
| 252 | +---------+ <--- given back to second writer | ||
| 253 | |reserved | | ||
| 254 | +---------+ <--- tail pointer | ||
| 255 | |||
| 256 | After second writer commits: | ||
| 257 | |||
| 258 | |||
| 259 | Buffer page | ||
| 260 | +---------+ | ||
| 261 | |written | | ||
| 262 | +---------+ <--(last full commit) | ||
| 263 | |reserved | | ||
| 264 | +---------+ | ||
| 265 | |pending | | ||
| 266 | |commit | | ||
| 267 | +---------+ <--- tail pointer | ||
| 268 | |||
| 269 | When the first writer commits: | ||
| 270 | |||
| 271 | Buffer page | ||
| 272 | +---------+ | ||
| 273 | |written | | ||
| 274 | +---------+ | ||
| 275 | |written | | ||
| 276 | +---------+ | ||
| 277 | |written | | ||
| 278 | +---------+ <--(last full commit and tail pointer) | ||
| 279 | |||
| 280 | |||
| 281 | The commit pointer points to the last write location that was | ||
| 282 | committed without preempting another write. When a write that | ||
| 283 | preempted another write is committed, it only becomes a pending commit | ||
| 284 | and will not be a full commit till all writes have been committed. | ||
| 285 | |||
| 286 | The commit page points to the page that has the last full commit. | ||
| 287 | The tail page points to the page with the last write (before | ||
| 288 | committing). | ||
| 289 | |||
| 290 | The tail page is always equal to or after the commit page. It may | ||
| 291 | be several pages ahead. If the tail page catches up to the commit | ||
| 292 | page then no more writes may take place (regardless of the mode | ||
| 293 | of the ring buffer: overwrite and produce/consumer). | ||
| 294 | |||
| 295 | The order of pages are: | ||
| 296 | |||
| 297 | head page | ||
| 298 | commit page | ||
| 299 | tail page | ||
| 300 | |||
| 301 | Possible scenario: | ||
| 302 | tail page | ||
| 303 | head page commit page | | ||
| 304 | | | | | ||
| 305 | v v v | ||
| 306 | +---+ +---+ +---+ +---+ | ||
| 307 | <---| |--->| |--->| |--->| |---> | ||
| 308 | --->| |<---| |<---| |<---| |<--- | ||
| 309 | +---+ +---+ +---+ +---+ | ||
| 310 | |||
| 311 | There is a special case that the head page is after either the commit page | ||
| 312 | and possibly the tail page. That is when the commit (and tail) page has been | ||
| 313 | swapped with the reader page. This is because the head page is always | ||
| 314 | part of the ring buffer, but the reader page is not. When ever there | ||
| 315 | has been less than a full page that has been committed inside the ring buffer, | ||
| 316 | and a reader swaps out a page, it will be swapping out the commit page. | ||
| 317 | |||
| 318 | |||
| 319 | reader page commit page tail page | ||
| 320 | | | | | ||
| 321 | v | | | ||
| 322 | +---+ | | | ||
| 323 | | |<----------+ | | ||
| 324 | | |<------------------------+ | ||
| 325 | | |------+ | ||
| 326 | +---+ | | ||
| 327 | | | ||
| 328 | v | ||
| 329 | +---+ +---+ +---+ +---+ | ||
| 330 | <---| |--->| |--->| |--->| |---> | ||
| 331 | --->| |<---| |<---| |<---| |<--- | ||
| 332 | +---+ +---+ +---+ +---+ | ||
| 333 | ^ | ||
| 334 | | | ||
| 335 | head page | ||
| 336 | |||
| 337 | |||
| 338 | In this case, the head page will not move when the tail and commit | ||
| 339 | move back into the ring buffer. | ||
| 340 | |||
| 341 | The reader can not swap a page into the ring buffer if the commit page | ||
| 342 | is still on that page. If the read meets the last commit (real commit | ||
| 343 | not pending or reserved), then there is nothing more to read. | ||
| 344 | The buffer is considered empty until another full commit finishes. | ||
| 345 | |||
| 346 | When the tail meets the head page, if the buffer is in overwrite mode, | ||
| 347 | the head page will be pushed ahead one. If the buffer is in producer/consumer | ||
| 348 | mode, the write will fail. | ||
| 349 | |||
| 350 | Overwrite mode: | ||
| 351 | |||
| 352 | tail page | ||
| 353 | | | ||
| 354 | v | ||
| 355 | +---+ +---+ +---+ +---+ | ||
| 356 | <---| |--->| |--->| |--->| |---> | ||
| 357 | --->| |<---| |<---| |<---| |<--- | ||
| 358 | +---+ +---+ +---+ +---+ | ||
| 359 | ^ | ||
| 360 | | | ||
| 361 | head page | ||
| 362 | |||
| 363 | |||
| 364 | tail page | ||
| 365 | | | ||
| 366 | v | ||
| 367 | +---+ +---+ +---+ +---+ | ||
| 368 | <---| |--->| |--->| |--->| |---> | ||
| 369 | --->| |<---| |<---| |<---| |<--- | ||
| 370 | +---+ +---+ +---+ +---+ | ||
| 371 | ^ | ||
| 372 | | | ||
| 373 | head page | ||
| 374 | |||
| 375 | |||
| 376 | tail page | ||
| 377 | | | ||
| 378 | v | ||
| 379 | +---+ +---+ +---+ +---+ | ||
| 380 | <---| |--->| |--->| |--->| |---> | ||
| 381 | --->| |<---| |<---| |<---| |<--- | ||
| 382 | +---+ +---+ +---+ +---+ | ||
| 383 | ^ | ||
| 384 | | | ||
| 385 | head page | ||
| 386 | |||
| 387 | Note, the reader page will still point to the previous head page. | ||
| 388 | But when a swap takes place, it will use the most recent head page. | ||
| 389 | |||
| 390 | |||
| 391 | Making the Ring Buffer Lockless: | ||
| 392 | -------------------------------- | ||
| 393 | |||
| 394 | The main idea behind the lockless algorithm is to combine the moving | ||
| 395 | of the head_page pointer with the swapping of pages with the reader. | ||
| 396 | State flags are placed inside the pointer to the page. To do this, | ||
| 397 | each page must be aligned in memory by 4 bytes. This will allow the 2 | ||
| 398 | least significant bits of the address to be used as flags. Since | ||
| 399 | they will always be zero for the address. To get the address, | ||
| 400 | simply mask out the flags. | ||
| 401 | |||
| 402 | MASK = ~3 | ||
| 403 | |||
| 404 | address & MASK | ||
| 405 | |||
| 406 | Two flags will be kept by these two bits: | ||
| 407 | |||
| 408 | HEADER - the page being pointed to is a head page | ||
| 409 | |||
| 410 | UPDATE - the page being pointed to is being updated by a writer | ||
| 411 | and was or is about to be a head page. | ||
| 412 | |||
| 413 | |||
| 414 | reader page | ||
| 415 | | | ||
| 416 | v | ||
| 417 | +---+ | ||
| 418 | | |------+ | ||
| 419 | +---+ | | ||
| 420 | | | ||
| 421 | v | ||
| 422 | +---+ +---+ +---+ +---+ | ||
| 423 | <---| |--->| |-H->| |--->| |---> | ||
| 424 | --->| |<---| |<---| |<---| |<--- | ||
| 425 | +---+ +---+ +---+ +---+ | ||
| 426 | |||
| 427 | |||
| 428 | The above pointer "-H->" would have the HEADER flag set. That is | ||
| 429 | the next page is the next page to be swapped out by the reader. | ||
| 430 | This pointer means the next page is the head page. | ||
| 431 | |||
| 432 | When the tail page meets the head pointer, it will use cmpxchg to | ||
| 433 | change the pointer to the UPDATE state: | ||
| 434 | |||
| 435 | |||
| 436 | tail page | ||
| 437 | | | ||
| 438 | v | ||
| 439 | +---+ +---+ +---+ +---+ | ||
| 440 | <---| |--->| |-H->| |--->| |---> | ||
| 441 | --->| |<---| |<---| |<---| |<--- | ||
| 442 | +---+ +---+ +---+ +---+ | ||
| 443 | |||
| 444 | tail page | ||
| 445 | | | ||
| 446 | v | ||
| 447 | +---+ +---+ +---+ +---+ | ||
| 448 | <---| |--->| |-U->| |--->| |---> | ||
| 449 | --->| |<---| |<---| |<---| |<--- | ||
| 450 | +---+ +---+ +---+ +---+ | ||
| 451 | |||
| 452 | "-U->" represents a pointer in the UPDATE state. | ||
| 453 | |||
| 454 | Any access to the reader will need to take some sort of lock to serialize | ||
| 455 | the readers. But the writers will never take a lock to write to the | ||
| 456 | ring buffer. This means we only need to worry about a single reader, | ||
| 457 | and writes only preempt in "stack" formation. | ||
| 458 | |||
| 459 | When the reader tries to swap the page with the ring buffer, it | ||
| 460 | will also use cmpxchg. If the flag bit in the pointer to the | ||
| 461 | head page does not have the HEADER flag set, the compare will fail | ||
| 462 | and the reader will need to look for the new head page and try again. | ||
| 463 | Note, the flag UPDATE and HEADER are never set at the same time. | ||
| 464 | |||
| 465 | The reader swaps the reader page as follows: | ||
| 466 | |||
| 467 | +------+ | ||
| 468 | |reader| RING BUFFER | ||
| 469 | |page | | ||
| 470 | +------+ | ||
| 471 | +---+ +---+ +---+ | ||
| 472 | | |--->| |--->| | | ||
| 473 | | |<---| |<---| | | ||
| 474 | +---+ +---+ +---+ | ||
| 475 | ^ | ^ | | ||
| 476 | | +---------------+ | | ||
| 477 | +-----H-------------+ | ||
| 478 | |||
| 479 | The reader sets the reader page next pointer as HEADER to the page after | ||
| 480 | the head page. | ||
| 481 | |||
| 482 | |||
| 483 | +------+ | ||
| 484 | |reader| RING BUFFER | ||
| 485 | |page |-------H-----------+ | ||
| 486 | +------+ v | ||
| 487 | | +---+ +---+ +---+ | ||
| 488 | | | |--->| |--->| | | ||
| 489 | | | |<---| |<---| |<-+ | ||
| 490 | | +---+ +---+ +---+ | | ||
| 491 | | ^ | ^ | | | ||
| 492 | | | +---------------+ | | | ||
| 493 | | +-----H-------------+ | | ||
| 494 | +--------------------------------------+ | ||
| 495 | |||
| 496 | It does a cmpxchg with the pointer to the previous head page to make it | ||
| 497 | point to the reader page. Note that the new pointer does not have the HEADER | ||
| 498 | flag set. This action atomically moves the head page forward. | ||
| 499 | |||
| 500 | +------+ | ||
| 501 | |reader| RING BUFFER | ||
| 502 | |page |-------H-----------+ | ||
| 503 | +------+ v | ||
| 504 | | ^ +---+ +---+ +---+ | ||
| 505 | | | | |-->| |-->| | | ||
| 506 | | | | |<--| |<--| |<-+ | ||
| 507 | | | +---+ +---+ +---+ | | ||
| 508 | | | | ^ | | | ||
| 509 | | | +-------------+ | | | ||
| 510 | | +-----------------------------+ | | ||
| 511 | +------------------------------------+ | ||
| 512 | |||
| 513 | After the new head page is set, the previous pointer of the head page is | ||
| 514 | updated to the reader page. | ||
| 515 | |||
| 516 | +------+ | ||
| 517 | |reader| RING BUFFER | ||
| 518 | |page |-------H-----------+ | ||
| 519 | +------+ <---------------+ v | ||
| 520 | | ^ +---+ +---+ +---+ | ||
| 521 | | | | |-->| |-->| | | ||
| 522 | | | | | | |<--| |<-+ | ||
| 523 | | | +---+ +---+ +---+ | | ||
| 524 | | | | ^ | | | ||
| 525 | | | +-------------+ | | | ||
| 526 | | +-----------------------------+ | | ||
| 527 | +------------------------------------+ | ||
| 528 | |||
| 529 | +------+ | ||
| 530 | |buffer| RING BUFFER | ||
| 531 | |page |-------H-----------+ <--- New head page | ||
| 532 | +------+ <---------------+ v | ||
| 533 | | ^ +---+ +---+ +---+ | ||
| 534 | | | | | | |-->| | | ||
| 535 | | | New | | | |<--| |<-+ | ||
| 536 | | | Reader +---+ +---+ +---+ | | ||
| 537 | | | page ----^ | | | ||
| 538 | | | | | | ||
| 539 | | +-----------------------------+ | | ||
| 540 | +------------------------------------+ | ||
| 541 | |||
| 542 | Another important point. The page that the reader page points back to | ||
| 543 | by its previous pointer (the one that now points to the new head page) | ||
| 544 | never points back to the reader page. That is because the reader page is | ||
| 545 | not part of the ring buffer. Traversing the ring buffer via the next pointers | ||
| 546 | will always stay in the ring buffer. Traversing the ring buffer via the | ||
| 547 | prev pointers may not. | ||
| 548 | |||
| 549 | Note, the way to determine a reader page is simply by examining the previous | ||
| 550 | pointer of the page. If the next pointer of the previous page does not | ||
| 551 | point back to the original page, then the original page is a reader page: | ||
| 552 | |||
| 553 | |||
| 554 | +--------+ | ||
| 555 | | reader | next +----+ | ||
| 556 | | page |-------->| |<====== (buffer page) | ||
| 557 | +--------+ +----+ | ||
| 558 | | | ^ | ||
| 559 | | v | next | ||
| 560 | prev | +----+ | ||
| 561 | +------------->| | | ||
| 562 | +----+ | ||
| 563 | |||
| 564 | The way the head page moves forward: | ||
| 565 | |||
| 566 | When the tail page meets the head page and the buffer is in overwrite mode | ||
| 567 | and more writes take place, the head page must be moved forward before the | ||
| 568 | writer may move the tail page. The way this is done is that the writer | ||
| 569 | performs a cmpxchg to convert the pointer to the head page from the HEADER | ||
| 570 | flag to have the UPDATE flag set. Once this is done, the reader will | ||
| 571 | not be able to swap the head page from the buffer, nor will it be able to | ||
| 572 | move the head page, until the writer is finished with the move. | ||
| 573 | |||
| 574 | This eliminates any races that the reader can have on the writer. The reader | ||
| 575 | must spin, and this is why the reader can not preempt the writer. | ||
| 576 | |||
| 577 | tail page | ||
| 578 | | | ||
| 579 | v | ||
| 580 | +---+ +---+ +---+ +---+ | ||
| 581 | <---| |--->| |-H->| |--->| |---> | ||
| 582 | --->| |<---| |<---| |<---| |<--- | ||
| 583 | +---+ +---+ +---+ +---+ | ||
| 584 | |||
| 585 | tail page | ||
| 586 | | | ||
| 587 | v | ||
| 588 | +---+ +---+ +---+ +---+ | ||
| 589 | <---| |--->| |-U->| |--->| |---> | ||
| 590 | --->| |<---| |<---| |<---| |<--- | ||
| 591 | +---+ +---+ +---+ +---+ | ||
| 592 | |||
| 593 | The following page will be made into the new head page. | ||
| 594 | |||
| 595 | tail page | ||
| 596 | | | ||
| 597 | v | ||
| 598 | +---+ +---+ +---+ +---+ | ||
| 599 | <---| |--->| |-U->| |-H->| |---> | ||
| 600 | --->| |<---| |<---| |<---| |<--- | ||
| 601 | +---+ +---+ +---+ +---+ | ||
| 602 | |||
| 603 | After the new head page has been set, we can set the old head page | ||
| 604 | pointer back to NORMAL. | ||
| 605 | |||
| 606 | tail page | ||
| 607 | | | ||
| 608 | v | ||
| 609 | +---+ +---+ +---+ +---+ | ||
| 610 | <---| |--->| |--->| |-H->| |---> | ||
| 611 | --->| |<---| |<---| |<---| |<--- | ||
| 612 | +---+ +---+ +---+ +---+ | ||
| 613 | |||
| 614 | After the head page has been moved, the tail page may now move forward. | ||
| 615 | |||
| 616 | tail page | ||
| 617 | | | ||
| 618 | v | ||
| 619 | +---+ +---+ +---+ +---+ | ||
| 620 | <---| |--->| |--->| |-H->| |---> | ||
| 621 | --->| |<---| |<---| |<---| |<--- | ||
| 622 | +---+ +---+ +---+ +---+ | ||
| 623 | |||
| 624 | |||
| 625 | The above are the trivial updates. Now for the more complex scenarios. | ||
| 626 | |||
| 627 | |||
| 628 | As stated before, if enough writes preempt the first write, the | ||
| 629 | tail page may make it all the way around the buffer and meet the commit | ||
| 630 | page. At this time, we must start dropping writes (usually with some kind | ||
| 631 | of warning to the user). But what happens if the commit was still on the | ||
| 632 | reader page? The commit page is not part of the ring buffer. The tail page | ||
| 633 | must account for this. | ||
| 634 | |||
| 635 | |||
| 636 | reader page commit page | ||
| 637 | | | | ||
| 638 | v | | ||
| 639 | +---+ | | ||
| 640 | | |<----------+ | ||
| 641 | | | | ||
| 642 | | |------+ | ||
| 643 | +---+ | | ||
| 644 | | | ||
| 645 | v | ||
| 646 | +---+ +---+ +---+ +---+ | ||
| 647 | <---| |--->| |-H->| |--->| |---> | ||
| 648 | --->| |<---| |<---| |<---| |<--- | ||
| 649 | +---+ +---+ +---+ +---+ | ||
| 650 | ^ | ||
| 651 | | | ||
| 652 | tail page | ||
| 653 | |||
| 654 | If the tail page were to simply push the head page forward, the commit when | ||
| 655 | leaving the reader page would not be pointing to the correct page. | ||
| 656 | |||
| 657 | The solution to this is to test if the commit page is on the reader page | ||
| 658 | before pushing the head page. If it is, then it can be assumed that the | ||
| 659 | tail page wrapped the buffer, and we must drop new writes. | ||
| 660 | |||
| 661 | This is not a race condition, because the commit page can only be moved | ||
| 662 | by the outter most writer (the writer that was preempted). | ||
| 663 | This means that the commit will not move while a writer is moving the | ||
| 664 | tail page. The reader can not swap the reader page if it is also being | ||
| 665 | used as the commit page. The reader can simply check that the commit | ||
| 666 | is off the reader page. Once the commit page leaves the reader page | ||
| 667 | it will never go back on it unless a reader does another swap with the | ||
| 668 | buffer page that is also the commit page. | ||
| 669 | |||
| 670 | |||
| 671 | Nested writes | ||
| 672 | ------------- | ||
| 673 | |||
| 674 | In the pushing forward of the tail page we must first push forward | ||
| 675 | the head page if the head page is the next page. If the head page | ||
| 676 | is not the next page, the tail page is simply updated with a cmpxchg. | ||
| 677 | |||
| 678 | Only writers move the tail page. This must be done atomically to protect | ||
| 679 | against nested writers. | ||
| 680 | |||
| 681 | temp_page = tail_page | ||
| 682 | next_page = temp_page->next | ||
| 683 | cmpxchg(tail_page, temp_page, next_page) | ||
| 684 | |||
| 685 | The above will update the tail page if it is still pointing to the expected | ||
| 686 | page. If this fails, a nested write pushed it forward, the the current write | ||
| 687 | does not need to push it. | ||
| 688 | |||
| 689 | |||
| 690 | temp page | ||
| 691 | | | ||
| 692 | v | ||
| 693 | tail page | ||
| 694 | | | ||
| 695 | v | ||
| 696 | +---+ +---+ +---+ +---+ | ||
| 697 | <---| |--->| |--->| |--->| |---> | ||
| 698 | --->| |<---| |<---| |<---| |<--- | ||
| 699 | +---+ +---+ +---+ +---+ | ||
| 700 | |||
| 701 | Nested write comes in and moves the tail page forward: | ||
| 702 | |||
| 703 | tail page (moved by nested writer) | ||
| 704 | temp page | | ||
| 705 | | | | ||
| 706 | v v | ||
| 707 | +---+ +---+ +---+ +---+ | ||
| 708 | <---| |--->| |--->| |--->| |---> | ||
| 709 | --->| |<---| |<---| |<---| |<--- | ||
| 710 | +---+ +---+ +---+ +---+ | ||
| 711 | |||
| 712 | The above would fail the cmpxchg, but since the tail page has already | ||
| 713 | been moved forward, the writer will just try again to reserve storage | ||
| 714 | on the new tail page. | ||
| 715 | |||
| 716 | But the moving of the head page is a bit more complex. | ||
| 717 | |||
| 718 | tail page | ||
| 719 | | | ||
| 720 | v | ||
| 721 | +---+ +---+ +---+ +---+ | ||
| 722 | <---| |--->| |-H->| |--->| |---> | ||
| 723 | --->| |<---| |<---| |<---| |<--- | ||
| 724 | +---+ +---+ +---+ +---+ | ||
| 725 | |||
| 726 | The write converts the head page pointer to UPDATE. | ||
| 727 | |||
| 728 | tail page | ||
| 729 | | | ||
| 730 | v | ||
| 731 | +---+ +---+ +---+ +---+ | ||
| 732 | <---| |--->| |-U->| |--->| |---> | ||
| 733 | --->| |<---| |<---| |<---| |<--- | ||
| 734 | +---+ +---+ +---+ +---+ | ||
| 735 | |||
| 736 | But if a nested writer preempts here. It will see that the next | ||
| 737 | page is a head page, but it is also nested. It will detect that | ||
| 738 | it is nested and will save that information. The detection is the | ||
| 739 | fact that it sees the UPDATE flag instead of a HEADER or NORMAL | ||
| 740 | pointer. | ||
| 741 | |||
| 742 | The nested writer will set the new head page pointer. | ||
| 743 | |||
| 744 | tail page | ||
| 745 | | | ||
| 746 | v | ||
| 747 | +---+ +---+ +---+ +---+ | ||
| 748 | <---| |--->| |-U->| |-H->| |---> | ||
| 749 | --->| |<---| |<---| |<---| |<--- | ||
| 750 | +---+ +---+ +---+ +---+ | ||
| 751 | |||
| 752 | But it will not reset the update back to normal. Only the writer | ||
| 753 | that converted a pointer from HEAD to UPDATE will convert it back | ||
| 754 | to NORMAL. | ||
| 755 | |||
| 756 | tail page | ||
| 757 | | | ||
| 758 | v | ||
| 759 | +---+ +---+ +---+ +---+ | ||
| 760 | <---| |--->| |-U->| |-H->| |---> | ||
| 761 | --->| |<---| |<---| |<---| |<--- | ||
| 762 | +---+ +---+ +---+ +---+ | ||
| 763 | |||
| 764 | After the nested writer finishes, the outer most writer will convert | ||
| 765 | the UPDATE pointer to NORMAL. | ||
| 766 | |||
| 767 | |||
| 768 | tail page | ||
| 769 | | | ||
| 770 | v | ||
| 771 | +---+ +---+ +---+ +---+ | ||
| 772 | <---| |--->| |--->| |-H->| |---> | ||
| 773 | --->| |<---| |<---| |<---| |<--- | ||
| 774 | +---+ +---+ +---+ +---+ | ||
| 775 | |||
| 776 | |||
| 777 | It can be even more complex if several nested writes came in and moved | ||
| 778 | the tail page ahead several pages: | ||
| 779 | |||
| 780 | |||
| 781 | (first writer) | ||
| 782 | |||
| 783 | tail page | ||
| 784 | | | ||
| 785 | v | ||
| 786 | +---+ +---+ +---+ +---+ | ||
| 787 | <---| |--->| |-H->| |--->| |---> | ||
| 788 | --->| |<---| |<---| |<---| |<--- | ||
| 789 | +---+ +---+ +---+ +---+ | ||
| 790 | |||
| 791 | The write converts the head page pointer to UPDATE. | ||
| 792 | |||
| 793 | tail page | ||
| 794 | | | ||
| 795 | v | ||
| 796 | +---+ +---+ +---+ +---+ | ||
| 797 | <---| |--->| |-U->| |--->| |---> | ||
| 798 | --->| |<---| |<---| |<---| |<--- | ||
| 799 | +---+ +---+ +---+ +---+ | ||
| 800 | |||
| 801 | Next writer comes in, and sees the update and sets up the new | ||
| 802 | head page. | ||
| 803 | |||
| 804 | (second writer) | ||
| 805 | |||
| 806 | tail page | ||
| 807 | | | ||
| 808 | v | ||
| 809 | +---+ +---+ +---+ +---+ | ||
| 810 | <---| |--->| |-U->| |-H->| |---> | ||
| 811 | --->| |<---| |<---| |<---| |<--- | ||
| 812 | +---+ +---+ +---+ +---+ | ||
| 813 | |||
| 814 | The nested writer moves the tail page forward. But does not set the old | ||
| 815 | update page to NORMAL because it is not the outer most writer. | ||
| 816 | |||
| 817 | tail page | ||
| 818 | | | ||
| 819 | v | ||
| 820 | +---+ +---+ +---+ +---+ | ||
| 821 | <---| |--->| |-U->| |-H->| |---> | ||
| 822 | --->| |<---| |<---| |<---| |<--- | ||
| 823 | +---+ +---+ +---+ +---+ | ||
| 824 | |||
| 825 | Another writer preempts and sees the page after the tail page is a head page. | ||
| 826 | It changes it from HEAD to UPDATE. | ||
| 827 | |||
| 828 | (third writer) | ||
| 829 | |||
| 830 | tail page | ||
| 831 | | | ||
| 832 | v | ||
| 833 | +---+ +---+ +---+ +---+ | ||
| 834 | <---| |--->| |-U->| |-U->| |---> | ||
| 835 | --->| |<---| |<---| |<---| |<--- | ||
| 836 | +---+ +---+ +---+ +---+ | ||
| 837 | |||
| 838 | The writer will move the head page forward: | ||
| 839 | |||
| 840 | |||
| 841 | (third writer) | ||
| 842 | |||
| 843 | tail page | ||
| 844 | | | ||
| 845 | v | ||
| 846 | +---+ +---+ +---+ +---+ | ||
| 847 | <---| |--->| |-U->| |-U->| |-H-> | ||
| 848 | --->| |<---| |<---| |<---| |<--- | ||
| 849 | +---+ +---+ +---+ +---+ | ||
| 850 | |||
| 851 | But now that the third writer did change the HEAD flag to UPDATE it | ||
| 852 | will convert it to normal: | ||
| 853 | |||
| 854 | |||
| 855 | (third writer) | ||
| 856 | |||
| 857 | tail page | ||
| 858 | | | ||
| 859 | v | ||
| 860 | +---+ +---+ +---+ +---+ | ||
| 861 | <---| |--->| |-U->| |--->| |-H-> | ||
| 862 | --->| |<---| |<---| |<---| |<--- | ||
| 863 | +---+ +---+ +---+ +---+ | ||
| 864 | |||
| 865 | |||
| 866 | Then it will move the tail page, and return back to the second writer. | ||
| 867 | |||
| 868 | |||
| 869 | (second writer) | ||
| 870 | |||
| 871 | tail page | ||
| 872 | | | ||
| 873 | v | ||
| 874 | +---+ +---+ +---+ +---+ | ||
| 875 | <---| |--->| |-U->| |--->| |-H-> | ||
| 876 | --->| |<---| |<---| |<---| |<--- | ||
| 877 | +---+ +---+ +---+ +---+ | ||
| 878 | |||
| 879 | |||
| 880 | The second writer will fail to move the tail page because it was already | ||
| 881 | moved, so it will try again and add its data to the new tail page. | ||
| 882 | It will return to the first writer. | ||
| 883 | |||
| 884 | |||
| 885 | (first writer) | ||
| 886 | |||
| 887 | tail page | ||
| 888 | | | ||
| 889 | v | ||
| 890 | +---+ +---+ +---+ +---+ | ||
| 891 | <---| |--->| |-U->| |--->| |-H-> | ||
| 892 | --->| |<---| |<---| |<---| |<--- | ||
| 893 | +---+ +---+ +---+ +---+ | ||
| 894 | |||
| 895 | The first writer can not know atomically test if the tail page moved | ||
| 896 | while it updates the HEAD page. It will then update the head page to | ||
| 897 | what it thinks is the new head page. | ||
| 898 | |||
| 899 | |||
| 900 | (first writer) | ||
| 901 | |||
| 902 | tail page | ||
| 903 | | | ||
| 904 | v | ||
| 905 | +---+ +---+ +---+ +---+ | ||
| 906 | <---| |--->| |-U->| |-H->| |-H-> | ||
| 907 | --->| |<---| |<---| |<---| |<--- | ||
| 908 | +---+ +---+ +---+ +---+ | ||
| 909 | |||
| 910 | Since the cmpxchg returns the old value of the pointer the first writer | ||
| 911 | will see it succeeded in updating the pointer from NORMAL to HEAD. | ||
| 912 | But as we can see, this is not good enough. It must also check to see | ||
| 913 | if the tail page is either where it use to be or on the next page: | ||
| 914 | |||
| 915 | |||
| 916 | (first writer) | ||
| 917 | |||
| 918 | A B tail page | ||
| 919 | | | | | ||
| 920 | v v v | ||
| 921 | +---+ +---+ +---+ +---+ | ||
| 922 | <---| |--->| |-U->| |-H->| |-H-> | ||
| 923 | --->| |<---| |<---| |<---| |<--- | ||
| 924 | +---+ +---+ +---+ +---+ | ||
| 925 | |||
| 926 | If tail page != A and tail page does not equal B, then it must reset the | ||
| 927 | pointer back to NORMAL. The fact that it only needs to worry about | ||
| 928 | nested writers, it only needs to check this after setting the HEAD page. | ||
| 929 | |||
| 930 | |||
| 931 | (first writer) | ||
| 932 | |||
| 933 | A B tail page | ||
| 934 | | | | | ||
| 935 | v v v | ||
| 936 | +---+ +---+ +---+ +---+ | ||
| 937 | <---| |--->| |-U->| |--->| |-H-> | ||
| 938 | --->| |<---| |<---| |<---| |<--- | ||
| 939 | +---+ +---+ +---+ +---+ | ||
| 940 | |||
| 941 | Now the writer can update the head page. This is also why the head page must | ||
| 942 | remain in UPDATE and only reset by the outer most writer. This prevents | ||
| 943 | the reader from seeing the incorrect head page. | ||
| 944 | |||
| 945 | |||
| 946 | (first writer) | ||
| 947 | |||
| 948 | A B tail page | ||
| 949 | | | | | ||
| 950 | v v v | ||
| 951 | +---+ +---+ +---+ +---+ | ||
| 952 | <---| |--->| |--->| |--->| |-H-> | ||
| 953 | --->| |<---| |<---| |<---| |<--- | ||
| 954 | +---+ +---+ +---+ +---+ | ||
| 955 | |||
diff --git a/Documentation/trace/tracepoint-analysis.txt b/Documentation/trace/tracepoint-analysis.txt new file mode 100644 index 000000000000..5eb4e487e667 --- /dev/null +++ b/Documentation/trace/tracepoint-analysis.txt | |||
| @@ -0,0 +1,327 @@ | |||
| 1 | Notes on Analysing Behaviour Using Events and Tracepoints | ||
| 2 | |||
| 3 | Documentation written by Mel Gorman | ||
| 4 | PCL information heavily based on email from Ingo Molnar | ||
| 5 | |||
| 6 | 1. Introduction | ||
| 7 | =============== | ||
| 8 | |||
| 9 | Tracepoints (see Documentation/trace/tracepoints.txt) can be used without | ||
| 10 | creating custom kernel modules to register probe functions using the event | ||
| 11 | tracing infrastructure. | ||
| 12 | |||
| 13 | Simplistically, tracepoints will represent an important event that when can | ||
| 14 | be taken in conjunction with other tracepoints to build a "Big Picture" of | ||
| 15 | what is going on within the system. There are a large number of methods for | ||
| 16 | gathering and interpreting these events. Lacking any current Best Practises, | ||
| 17 | this document describes some of the methods that can be used. | ||
| 18 | |||
| 19 | This document assumes that debugfs is mounted on /sys/kernel/debug and that | ||
| 20 | the appropriate tracing options have been configured into the kernel. It is | ||
| 21 | assumed that the PCL tool tools/perf has been installed and is in your path. | ||
| 22 | |||
| 23 | 2. Listing Available Events | ||
| 24 | =========================== | ||
| 25 | |||
| 26 | 2.1 Standard Utilities | ||
| 27 | ---------------------- | ||
| 28 | |||
| 29 | All possible events are visible from /sys/kernel/debug/tracing/events. Simply | ||
| 30 | calling | ||
| 31 | |||
| 32 | $ find /sys/kernel/debug/tracing/events -type d | ||
| 33 | |||
| 34 | will give a fair indication of the number of events available. | ||
| 35 | |||
| 36 | 2.2 PCL | ||
| 37 | ------- | ||
| 38 | |||
| 39 | Discovery and enumeration of all counters and events, including tracepoints | ||
| 40 | are available with the perf tool. Getting a list of available events is a | ||
| 41 | simple case of | ||
| 42 | |||
| 43 | $ perf list 2>&1 | grep Tracepoint | ||
| 44 | ext4:ext4_free_inode [Tracepoint event] | ||
| 45 | ext4:ext4_request_inode [Tracepoint event] | ||
| 46 | ext4:ext4_allocate_inode [Tracepoint event] | ||
| 47 | ext4:ext4_write_begin [Tracepoint event] | ||
| 48 | ext4:ext4_ordered_write_end [Tracepoint event] | ||
| 49 | [ .... remaining output snipped .... ] | ||
| 50 | |||
| 51 | |||
| 52 | 2. Enabling Events | ||
| 53 | ================== | ||
| 54 | |||
| 55 | 2.1 System-Wide Event Enabling | ||
| 56 | ------------------------------ | ||
| 57 | |||
| 58 | See Documentation/trace/events.txt for a proper description on how events | ||
| 59 | can be enabled system-wide. A short example of enabling all events related | ||
| 60 | to page allocation would look something like | ||
| 61 | |||
| 62 | $ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done | ||
| 63 | |||
| 64 | 2.2 System-Wide Event Enabling with SystemTap | ||
| 65 | --------------------------------------------- | ||
| 66 | |||
| 67 | In SystemTap, tracepoints are accessible using the kernel.trace() function | ||
| 68 | call. The following is an example that reports every 5 seconds what processes | ||
| 69 | were allocating the pages. | ||
| 70 | |||
| 71 | global page_allocs | ||
| 72 | |||
| 73 | probe kernel.trace("mm_page_alloc") { | ||
| 74 | page_allocs[execname()]++ | ||
| 75 | } | ||
| 76 | |||
| 77 | function print_count() { | ||
| 78 | printf ("%-25s %-s\n", "#Pages Allocated", "Process Name") | ||
| 79 | foreach (proc in page_allocs-) | ||
| 80 | printf("%-25d %s\n", page_allocs[proc], proc) | ||
| 81 | printf ("\n") | ||
| 82 | delete page_allocs | ||
| 83 | } | ||
| 84 | |||
| 85 | probe timer.s(5) { | ||
| 86 | print_count() | ||
| 87 | } | ||
| 88 | |||
| 89 | 2.3 System-Wide Event Enabling with PCL | ||
| 90 | --------------------------------------- | ||
| 91 | |||
| 92 | By specifying the -a switch and analysing sleep, the system-wide events | ||
| 93 | for a duration of time can be examined. | ||
| 94 | |||
| 95 | $ perf stat -a \ | ||
| 96 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 97 | -e kmem:mm_pagevec_free \ | ||
| 98 | sleep 10 | ||
| 99 | Performance counter stats for 'sleep 10': | ||
| 100 | |||
| 101 | 9630 kmem:mm_page_alloc | ||
| 102 | 2143 kmem:mm_page_free_direct | ||
| 103 | 7424 kmem:mm_pagevec_free | ||
| 104 | |||
| 105 | 10.002577764 seconds time elapsed | ||
| 106 | |||
| 107 | Similarly, one could execute a shell and exit it as desired to get a report | ||
| 108 | at that point. | ||
| 109 | |||
| 110 | 2.4 Local Event Enabling | ||
| 111 | ------------------------ | ||
| 112 | |||
| 113 | Documentation/trace/ftrace.txt describes how to enable events on a per-thread | ||
| 114 | basis using set_ftrace_pid. | ||
| 115 | |||
| 116 | 2.5 Local Event Enablement with PCL | ||
| 117 | ----------------------------------- | ||
| 118 | |||
| 119 | Events can be activate and tracked for the duration of a process on a local | ||
| 120 | basis using PCL such as follows. | ||
| 121 | |||
| 122 | $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 123 | -e kmem:mm_pagevec_free ./hackbench 10 | ||
| 124 | Time: 0.909 | ||
| 125 | |||
| 126 | Performance counter stats for './hackbench 10': | ||
| 127 | |||
| 128 | 17803 kmem:mm_page_alloc | ||
| 129 | 12398 kmem:mm_page_free_direct | ||
| 130 | 4827 kmem:mm_pagevec_free | ||
| 131 | |||
| 132 | 0.973913387 seconds time elapsed | ||
| 133 | |||
| 134 | 3. Event Filtering | ||
| 135 | ================== | ||
| 136 | |||
| 137 | Documentation/trace/ftrace.txt covers in-depth how to filter events in | ||
| 138 | ftrace. Obviously using grep and awk of trace_pipe is an option as well | ||
| 139 | as any script reading trace_pipe. | ||
| 140 | |||
| 141 | 4. Analysing Event Variances with PCL | ||
| 142 | ===================================== | ||
| 143 | |||
| 144 | Any workload can exhibit variances between runs and it can be important | ||
| 145 | to know what the standard deviation in. By and large, this is left to the | ||
| 146 | performance analyst to do it by hand. In the event that the discrete event | ||
| 147 | occurrences are useful to the performance analyst, then perf can be used. | ||
| 148 | |||
| 149 | $ perf stat --repeat 5 -e kmem:mm_page_alloc -e kmem:mm_page_free_direct | ||
| 150 | -e kmem:mm_pagevec_free ./hackbench 10 | ||
| 151 | Time: 0.890 | ||
| 152 | Time: 0.895 | ||
| 153 | Time: 0.915 | ||
| 154 | Time: 1.001 | ||
| 155 | Time: 0.899 | ||
| 156 | |||
| 157 | Performance counter stats for './hackbench 10' (5 runs): | ||
| 158 | |||
| 159 | 16630 kmem:mm_page_alloc ( +- 3.542% ) | ||
| 160 | 11486 kmem:mm_page_free_direct ( +- 4.771% ) | ||
| 161 | 4730 kmem:mm_pagevec_free ( +- 2.325% ) | ||
| 162 | |||
| 163 | 0.982653002 seconds time elapsed ( +- 1.448% ) | ||
| 164 | |||
| 165 | In the event that some higher-level event is required that depends on some | ||
| 166 | aggregation of discrete events, then a script would need to be developed. | ||
| 167 | |||
| 168 | Using --repeat, it is also possible to view how events are fluctuating over | ||
| 169 | time on a system wide basis using -a and sleep. | ||
| 170 | |||
| 171 | $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 172 | -e kmem:mm_pagevec_free \ | ||
| 173 | -a --repeat 10 \ | ||
| 174 | sleep 1 | ||
| 175 | Performance counter stats for 'sleep 1' (10 runs): | ||
| 176 | |||
| 177 | 1066 kmem:mm_page_alloc ( +- 26.148% ) | ||
| 178 | 182 kmem:mm_page_free_direct ( +- 5.464% ) | ||
| 179 | 890 kmem:mm_pagevec_free ( +- 30.079% ) | ||
| 180 | |||
| 181 | 1.002251757 seconds time elapsed ( +- 0.005% ) | ||
| 182 | |||
| 183 | 5. Higher-Level Analysis with Helper Scripts | ||
| 184 | ============================================ | ||
| 185 | |||
| 186 | When events are enabled the events that are triggering can be read from | ||
| 187 | /sys/kernel/debug/tracing/trace_pipe in human-readable format although binary | ||
| 188 | options exist as well. By post-processing the output, further information can | ||
| 189 | be gathered on-line as appropriate. Examples of post-processing might include | ||
| 190 | |||
| 191 | o Reading information from /proc for the PID that triggered the event | ||
| 192 | o Deriving a higher-level event from a series of lower-level events. | ||
| 193 | o Calculate latencies between two events | ||
| 194 | |||
| 195 | Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example | ||
| 196 | script that can read trace_pipe from STDIN or a copy of a trace. When used | ||
| 197 | on-line, it can be interrupted once to generate a report without existing | ||
| 198 | and twice to exit. | ||
| 199 | |||
| 200 | Simplistically, the script just reads STDIN and counts up events but it | ||
| 201 | also can do more such as | ||
| 202 | |||
| 203 | o Derive high-level events from many low-level events. If a number of pages | ||
| 204 | are freed to the main allocator from the per-CPU lists, it recognises | ||
| 205 | that as one per-CPU drain even though there is no specific tracepoint | ||
| 206 | for that event | ||
| 207 | o It can aggregate based on PID or individual process number | ||
| 208 | o In the event memory is getting externally fragmented, it reports | ||
| 209 | on whether the fragmentation event was severe or moderate. | ||
| 210 | o When receiving an event about a PID, it can record who the parent was so | ||
| 211 | that if large numbers of events are coming from very short-lived | ||
| 212 | processes, the parent process responsible for creating all the helpers | ||
| 213 | can be identified | ||
| 214 | |||
| 215 | 6. Lower-Level Analysis with PCL | ||
| 216 | ================================ | ||
| 217 | |||
| 218 | There may also be a requirement to identify what functions with a program | ||
| 219 | were generating events within the kernel. To begin this sort of analysis, the | ||
| 220 | data must be recorded. At the time of writing, this required root | ||
| 221 | |||
| 222 | $ perf record -c 1 \ | ||
| 223 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 224 | -e kmem:mm_pagevec_free \ | ||
| 225 | ./hackbench 10 | ||
| 226 | Time: 0.894 | ||
| 227 | [ perf record: Captured and wrote 0.733 MB perf.data (~32010 samples) ] | ||
| 228 | |||
| 229 | Note the use of '-c 1' to set the event period to sample. The default sample | ||
| 230 | period is quite high to minimise overhead but the information collected can be | ||
| 231 | very coarse as a result. | ||
| 232 | |||
| 233 | This record outputted a file called perf.data which can be analysed using | ||
| 234 | perf report. | ||
| 235 | |||
| 236 | $ perf report | ||
| 237 | # Samples: 30922 | ||
| 238 | # | ||
| 239 | # Overhead Command Shared Object | ||
| 240 | # ........ ......... ................................ | ||
| 241 | # | ||
| 242 | 87.27% hackbench [vdso] | ||
| 243 | 6.85% hackbench /lib/i686/cmov/libc-2.9.so | ||
| 244 | 2.62% hackbench /lib/ld-2.9.so | ||
| 245 | 1.52% perf [vdso] | ||
| 246 | 1.22% hackbench ./hackbench | ||
| 247 | 0.48% hackbench [kernel] | ||
| 248 | 0.02% perf /lib/i686/cmov/libc-2.9.so | ||
| 249 | 0.01% perf /usr/bin/perf | ||
| 250 | 0.01% perf /lib/ld-2.9.so | ||
| 251 | 0.00% hackbench /lib/i686/cmov/libpthread-2.9.so | ||
| 252 | # | ||
| 253 | # (For more details, try: perf report --sort comm,dso,symbol) | ||
| 254 | # | ||
| 255 | |||
| 256 | According to this, the vast majority of events occured triggered on events | ||
| 257 | within the VDSO. With simple binaries, this will often be the case so lets | ||
| 258 | take a slightly different example. In the course of writing this, it was | ||
| 259 | noticed that X was generating an insane amount of page allocations so lets look | ||
| 260 | at it | ||
| 261 | |||
| 262 | $ perf record -c 1 -f \ | ||
| 263 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 264 | -e kmem:mm_pagevec_free \ | ||
| 265 | -p `pidof X` | ||
| 266 | |||
| 267 | This was interrupted after a few seconds and | ||
| 268 | |||
| 269 | $ perf report | ||
| 270 | # Samples: 27666 | ||
| 271 | # | ||
| 272 | # Overhead Command Shared Object | ||
| 273 | # ........ ....... ....................................... | ||
| 274 | # | ||
| 275 | 51.95% Xorg [vdso] | ||
| 276 | 47.95% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 | ||
| 277 | 0.09% Xorg /lib/i686/cmov/libc-2.9.so | ||
| 278 | 0.01% Xorg [kernel] | ||
| 279 | # | ||
| 280 | # (For more details, try: perf report --sort comm,dso,symbol) | ||
| 281 | # | ||
| 282 | |||
| 283 | So, almost half of the events are occuring in a library. To get an idea which | ||
| 284 | symbol. | ||
| 285 | |||
| 286 | $ perf report --sort comm,dso,symbol | ||
| 287 | # Samples: 27666 | ||
| 288 | # | ||
| 289 | # Overhead Command Shared Object Symbol | ||
| 290 | # ........ ....... ....................................... ...... | ||
| 291 | # | ||
| 292 | 51.95% Xorg [vdso] [.] 0x000000ffffe424 | ||
| 293 | 47.93% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] pixmanFillsse2 | ||
| 294 | 0.09% Xorg /lib/i686/cmov/libc-2.9.so [.] _int_malloc | ||
| 295 | 0.01% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] pixman_region32_copy_f | ||
| 296 | 0.01% Xorg [kernel] [k] read_hpet | ||
| 297 | 0.01% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] get_fast_path | ||
| 298 | 0.00% Xorg [kernel] [k] ftrace_trace_userstack | ||
| 299 | |||
| 300 | To see where within the function pixmanFillsse2 things are going wrong | ||
| 301 | |||
| 302 | $ perf annotate pixmanFillsse2 | ||
| 303 | [ ... ] | ||
| 304 | 0.00 : 34eeb: 0f 18 08 prefetcht0 (%eax) | ||
| 305 | : } | ||
| 306 | : | ||
| 307 | : extern __inline void __attribute__((__gnu_inline__, __always_inline__, _ | ||
| 308 | : _mm_store_si128 (__m128i *__P, __m128i __B) : { | ||
| 309 | : *__P = __B; | ||
| 310 | 12.40 : 34eee: 66 0f 7f 80 40 ff ff movdqa %xmm0,-0xc0(%eax) | ||
| 311 | 0.00 : 34ef5: ff | ||
| 312 | 12.40 : 34ef6: 66 0f 7f 80 50 ff ff movdqa %xmm0,-0xb0(%eax) | ||
| 313 | 0.00 : 34efd: ff | ||
| 314 | 12.39 : 34efe: 66 0f 7f 80 60 ff ff movdqa %xmm0,-0xa0(%eax) | ||
| 315 | 0.00 : 34f05: ff | ||
| 316 | 12.67 : 34f06: 66 0f 7f 80 70 ff ff movdqa %xmm0,-0x90(%eax) | ||
| 317 | 0.00 : 34f0d: ff | ||
| 318 | 12.58 : 34f0e: 66 0f 7f 40 80 movdqa %xmm0,-0x80(%eax) | ||
| 319 | 12.31 : 34f13: 66 0f 7f 40 90 movdqa %xmm0,-0x70(%eax) | ||
| 320 | 12.40 : 34f18: 66 0f 7f 40 a0 movdqa %xmm0,-0x60(%eax) | ||
| 321 | 12.31 : 34f1d: 66 0f 7f 40 b0 movdqa %xmm0,-0x50(%eax) | ||
| 322 | |||
| 323 | At a glance, it looks like the time is being spent copying pixmaps to | ||
| 324 | the card. Further investigation would be needed to determine why pixmaps | ||
| 325 | are being copied around so much but a starting point would be to take an | ||
| 326 | ancient build of libpixmap out of the library path where it was totally | ||
| 327 | forgotten about from months ago! | ||
diff --git a/Documentation/vgaarbiter.txt b/Documentation/vgaarbiter.txt new file mode 100644 index 000000000000..987f9b0a5ece --- /dev/null +++ b/Documentation/vgaarbiter.txt | |||
| @@ -0,0 +1,194 @@ | |||
| 1 | |||
| 2 | VGA Arbiter | ||
| 3 | =========== | ||
| 4 | |||
| 5 | Graphic devices are accessed through ranges in I/O or memory space. While most | ||
| 6 | modern devices allow relocation of such ranges, some "Legacy" VGA devices | ||
| 7 | implemented on PCI will typically have the same "hard-decoded" addresses as | ||
| 8 | they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 | ||
| 9 | Standard for Boot (Initialization Configuration) Firmware Revision 2.1" | ||
| 10 | Section 7, Legacy Devices. | ||
| 11 | |||
| 12 | The Resource Access Control (RAC) module inside the X server [0] existed for | ||
| 13 | the legacy VGA arbitration task (besides other bus management tasks) when more | ||
| 14 | than one legacy device co-exists on the same machine. But the problem happens | ||
| 15 | when these devices are trying to be accessed by different userspace clients | ||
| 16 | (e.g. two server in parallel). Their address assignments conflict. Moreover, | ||
| 17 | ideally, being an userspace application, it is not the role of the the X | ||
| 18 | server to control bus resources. Therefore an arbitration scheme outside of | ||
| 19 | the X server is needed to control the sharing of these resources. This | ||
| 20 | document introduces the operation of the VGA arbiter implemented for Linux | ||
| 21 | kernel. | ||
| 22 | |||
| 23 | ---------------------------------------------------------------------------- | ||
| 24 | |||
| 25 | I. Details and Theory of Operation | ||
| 26 | I.1 vgaarb | ||
| 27 | I.2 libpciaccess | ||
| 28 | I.3 xf86VGAArbiter (X server implementation) | ||
| 29 | II. Credits | ||
| 30 | III.References | ||
| 31 | |||
| 32 | |||
| 33 | I. Details and Theory of Operation | ||
| 34 | ================================== | ||
| 35 | |||
| 36 | I.1 vgaarb | ||
| 37 | ---------- | ||
| 38 | |||
| 39 | The vgaarb is a module of the Linux Kernel. When it is initially loaded, it | ||
| 40 | scans all PCI devices and adds the VGA ones inside the arbitration. The | ||
| 41 | arbiter then enables/disables the decoding on different devices of the VGA | ||
| 42 | legacy instructions. Device which do not want/need to use the arbiter may | ||
| 43 | explicitly tell it by calling vga_set_legacy_decoding(). | ||
| 44 | |||
| 45 | The kernel exports a char device interface (/dev/vga_arbiter) to the clients, | ||
| 46 | which has the following semantics: | ||
| 47 | |||
| 48 | open : open user instance of the arbiter. By default, it's attached to | ||
| 49 | the default VGA device of the system. | ||
| 50 | |||
| 51 | close : close user instance. Release locks made by the user | ||
| 52 | |||
| 53 | read : return a string indicating the status of the target like: | ||
| 54 | |||
| 55 | "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (ic,mc)" | ||
| 56 | |||
| 57 | An IO state string is of the form {io,mem,io+mem,none}, mc and | ||
| 58 | ic are respectively mem and io lock counts (for debugging/ | ||
| 59 | diagnostic only). "decodes" indicate what the card currently | ||
| 60 | decodes, "owns" indicates what is currently enabled on it, and | ||
| 61 | "locks" indicates what is locked by this card. If the card is | ||
| 62 | unplugged, we get "invalid" then for card_ID and an -ENODEV | ||
| 63 | error is returned for any command until a new card is targeted. | ||
| 64 | |||
| 65 | |||
| 66 | write : write a command to the arbiter. List of commands: | ||
| 67 | |||
| 68 | target <card_ID> : switch target to card <card_ID> (see below) | ||
| 69 | lock <io_state> : acquires locks on target ("none" is an invalid io_state) | ||
| 70 | trylock <io_state> : non-blocking acquire locks on target (returns EBUSY if | ||
| 71 | unsuccessful) | ||
| 72 | unlock <io_state> : release locks on target | ||
| 73 | unlock all : release all locks on target held by this user (not | ||
| 74 | implemented yet) | ||
| 75 | decodes <io_state> : set the legacy decoding attributes for the card | ||
| 76 | |||
| 77 | poll : event if something changes on any card (not just the | ||
| 78 | target) | ||
| 79 | |||
| 80 | card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" | ||
| 81 | to go back to the system default card (TODO: not implemented yet). Currently, | ||
| 82 | only PCI is supported as a prefix, but the userland API may support other bus | ||
| 83 | types in the future, even if the current kernel implementation doesn't. | ||
| 84 | |||
| 85 | Note about locks: | ||
| 86 | |||
| 87 | The driver keeps track of which user has which locks on which card. It | ||
| 88 | supports stacking, like the kernel one. This complexifies the implementation | ||
| 89 | a bit, but makes the arbiter more tolerant to user space problems and able | ||
| 90 | to properly cleanup in all cases when a process dies. | ||
| 91 | Currently, a max of 16 cards can have locks simultaneously issued from | ||
| 92 | user space for a given user (file descriptor instance) of the arbiter. | ||
| 93 | |||
| 94 | In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to | ||
| 95 | notify them being added/removed in the system and automatically added/removed | ||
| 96 | in the arbiter. | ||
| 97 | |||
| 98 | There's also a in-kernel API of the arbiter in the case of DRM, vgacon and | ||
| 99 | others which may use the arbiter. | ||
| 100 | |||
| 101 | |||
| 102 | I.2 libpciaccess | ||
| 103 | ---------------- | ||
| 104 | |||
| 105 | To use the vga arbiter char device it was implemented an API inside the | ||
| 106 | libpciaccess library. One fieldd was added to struct pci_device (each device | ||
| 107 | on the system): | ||
| 108 | |||
| 109 | /* the type of resource decoded by the device */ | ||
| 110 | int vgaarb_rsrc; | ||
| 111 | |||
| 112 | Besides it, in pci_system were added: | ||
| 113 | |||
| 114 | int vgaarb_fd; | ||
| 115 | int vga_count; | ||
| 116 | struct pci_device *vga_target; | ||
| 117 | struct pci_device *vga_default_dev; | ||
| 118 | |||
| 119 | |||
| 120 | The vga_count is usually need to keep informed how many cards are being | ||
| 121 | arbitrated, so for instance if there's only one then it can totally escape the | ||
| 122 | scheme. | ||
| 123 | |||
| 124 | |||
| 125 | These functions below acquire VGA resources for the given card and mark those | ||
| 126 | resources as locked. If the resources requested are "normal" (and not legacy) | ||
| 127 | resources, the arbiter will first check whether the card is doing legacy | ||
| 128 | decoding for that type of resource. If yes, the lock is "converted" into a | ||
| 129 | legacy resource lock. The arbiter will first look for all VGA cards that | ||
| 130 | might conflict and disable their IOs and/or Memory access, including VGA | ||
| 131 | forwarding on P2P bridges if necessary, so that the requested resources can | ||
| 132 | be used. Then, the card is marked as locking these resources and the IO and/or | ||
| 133 | Memory access is enabled on the card (including VGA forwarding on parent | ||
| 134 | P2P bridges if any). In the case of vga_arb_lock(), the function will block | ||
| 135 | if some conflicting card is already locking one of the required resources (or | ||
| 136 | any resource on a different bus segment, since P2P bridges don't differentiate | ||
| 137 | VGA memory and IO afaik). If the card already owns the resources, the function | ||
| 138 | succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested | ||
| 139 | calls are supported (a per-resource counter is maintained). | ||
| 140 | |||
| 141 | |||
| 142 | Set the target device of this client. | ||
| 143 | int pci_device_vgaarb_set_target (struct pci_device *dev); | ||
| 144 | |||
| 145 | |||
| 146 | For instance, in x86 if two devices on the same bus want to lock different | ||
| 147 | resources, both will succeed (lock). If devices are in different buses and | ||
| 148 | trying to lock different resources, only the first who tried succeeds. | ||
| 149 | int pci_device_vgaarb_lock (void); | ||
| 150 | int pci_device_vgaarb_trylock (void); | ||
| 151 | |||
| 152 | Unlock resources of device. | ||
| 153 | int pci_device_vgaarb_unlock (void); | ||
| 154 | |||
| 155 | Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA | ||
| 156 | Memory, both, or none. All cards default to both, the card driver (fbdev for | ||
| 157 | example) should tell the arbiter if it has disabled legacy decoding, so the | ||
| 158 | card can be left out of the arbitration process (and can be safe to take | ||
| 159 | interrupts at any time. | ||
| 160 | int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); | ||
| 161 | |||
| 162 | Connects to the arbiter device, allocates the struct | ||
| 163 | int pci_device_vgaarb_init (void); | ||
| 164 | |||
| 165 | Close the connection | ||
| 166 | void pci_device_vgaarb_fini (void); | ||
| 167 | |||
| 168 | |||
| 169 | I.3 xf86VGAArbiter (X server implementation) | ||
| 170 | -------------------------------------------- | ||
| 171 | |||
| 172 | (TODO) | ||
| 173 | |||
| 174 | X server basically wraps all the functions that touch VGA registers somehow. | ||
| 175 | |||
| 176 | |||
| 177 | II. Credits | ||
| 178 | =========== | ||
| 179 | |||
| 180 | Benjamin Herrenschmidt (IBM?) started this work when he discussed such design | ||
| 181 | with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and | ||
| 182 | Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work | ||
| 183 | enhancing the kernel code to adapt as a kernel module and also did the | ||
| 184 | implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave | ||
| 185 | Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. | ||
| 186 | |||
| 187 | |||
| 188 | III. References | ||
| 189 | ============== | ||
| 190 | |||
| 191 | [0] http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 | ||
| 192 | [1] http://lists.freedesktop.org/archives/xorg/2005-March/006663.html | ||
| 193 | [2] http://lists.freedesktop.org/archives/xorg/2005-March/006745.html | ||
| 194 | [3] http://lists.freedesktop.org/archives/xorg/2007-October/029507.html | ||
diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 450b8f8c389b..5f33d8486102 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 | |||
| @@ -21,3 +21,6 @@ | |||
| 21 | 20 -> Hauppauge WinTV-HVR1255 [0070:2251] | 21 | 20 -> Hauppauge WinTV-HVR1255 [0070:2251] |
| 22 | 21 -> Hauppauge WinTV-HVR1210 [0070:2291,0070:2295] | 22 | 21 -> Hauppauge WinTV-HVR1210 [0070:2291,0070:2295] |
| 23 | 22 -> Mygica X8506 DMB-TH [14f1:8651] | 23 | 22 -> Mygica X8506 DMB-TH [14f1:8651] |
| 24 | 23 -> Magic-Pro ProHDTV Extreme 2 [14f1:8657] | ||
| 25 | 24 -> Hauppauge WinTV-HVR1850 [0070:8541] | ||
| 26 | 25 -> Compro VideoMate E800 [1858:e800] | ||
diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index 0736518b2f88..3385f8b094a5 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 | |||
| @@ -80,3 +80,4 @@ | |||
| 80 | 79 -> Terratec Cinergy HT PCI MKII [153b:1177] | 80 | 79 -> Terratec Cinergy HT PCI MKII [153b:1177] |
| 81 | 80 -> Hauppauge WinTV-IR Only [0070:9290] | 81 | 80 -> Hauppauge WinTV-IR Only [0070:9290] |
| 82 | 81 -> Leadtek WinFast DTV1800 Hybrid [107d:6654] | 82 | 81 -> Leadtek WinFast DTV1800 Hybrid [107d:6654] |
| 83 | 82 -> WinFast DTV2000 H rev. J [107d:6f2b] | ||
diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index 873630e7e53e..b8afef4c0e01 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx | |||
| @@ -1,5 +1,5 @@ | |||
| 1 | 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] | 1 | 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] |
| 2 | 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883] | 2 | 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2710,eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883,eb1a:2868] |
| 3 | 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] | 3 | 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] |
| 4 | 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] | 4 | 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] |
| 5 | 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] | 5 | 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] |
| @@ -7,7 +7,7 @@ | |||
| 7 | 6 -> Terratec Cinergy 200 USB (em2800) | 7 | 6 -> Terratec Cinergy 200 USB (em2800) |
| 8 | 7 -> Leadtek Winfast USB II (em2800) [0413:6023] | 8 | 7 -> Leadtek Winfast USB II (em2800) [0413:6023] |
| 9 | 8 -> Kworld USB2800 (em2800) | 9 | 8 -> Kworld USB2800 (em2800) |
| 10 | 9 -> Pinnacle Dazzle DVC 90/100/101/107 / Kaiser Baas Video to DVD maker (em2820/em2840) [1b80:e302,2304:0207,2304:021a] | 10 | 9 -> Pinnacle Dazzle DVC 90/100/101/107 / Kaiser Baas Video to DVD maker (em2820/em2840) [1b80:e302,1b80:e304,2304:0207,2304:021a] |
| 11 | 10 -> Hauppauge WinTV HVR 900 (em2880) [2040:6500] | 11 | 10 -> Hauppauge WinTV HVR 900 (em2880) [2040:6500] |
| 12 | 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] | 12 | 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] |
| 13 | 12 -> Kworld PVR TV 2800 RF (em2820/em2840) | 13 | 12 -> Kworld PVR TV 2800 RF (em2820/em2840) |
| @@ -20,7 +20,7 @@ | |||
| 20 | 19 -> EM2860/SAA711X Reference Design (em2860) | 20 | 19 -> EM2860/SAA711X Reference Design (em2860) |
| 21 | 20 -> AMD ATI TV Wonder HD 600 (em2880) [0438:b002] | 21 | 20 -> AMD ATI TV Wonder HD 600 (em2880) [0438:b002] |
| 22 | 21 -> eMPIA Technology, Inc. GrabBeeX+ Video Encoder (em2800) [eb1a:2801] | 22 | 21 -> eMPIA Technology, Inc. GrabBeeX+ Video Encoder (em2800) [eb1a:2801] |
| 23 | 22 -> Unknown EM2750/EM2751 webcam grabber (em2750) [eb1a:2750,eb1a:2751] | 23 | 22 -> EM2710/EM2750/EM2751 webcam grabber (em2750) [eb1a:2750,eb1a:2751] |
| 24 | 23 -> Huaqi DLCW-130 (em2750) | 24 | 23 -> Huaqi DLCW-130 (em2750) |
| 25 | 24 -> D-Link DUB-T210 TV Tuner (em2820/em2840) [2001:f112] | 25 | 24 -> D-Link DUB-T210 TV Tuner (em2820/em2840) [2001:f112] |
| 26 | 25 -> Gadmei UTV310 (em2820/em2840) | 26 | 25 -> Gadmei UTV310 (em2820/em2840) |
| @@ -33,7 +33,7 @@ | |||
| 33 | 34 -> Terratec Cinergy A Hybrid XS (em2860) [0ccd:004f] | 33 | 34 -> Terratec Cinergy A Hybrid XS (em2860) [0ccd:004f] |
| 34 | 35 -> Typhoon DVD Maker (em2860) | 34 | 35 -> Typhoon DVD Maker (em2860) |
| 35 | 36 -> NetGMBH Cam (em2860) | 35 | 36 -> NetGMBH Cam (em2860) |
| 36 | 37 -> Gadmei UTV330 (em2860) | 36 | 37 -> Gadmei UTV330 (em2860) [eb1a:50a6] |
| 37 | 38 -> Yakumo MovieMixer (em2861) | 37 | 38 -> Yakumo MovieMixer (em2861) |
| 38 | 39 -> KWorld PVRTV 300U (em2861) [eb1a:e300] | 38 | 39 -> KWorld PVRTV 300U (em2861) [eb1a:e300] |
| 39 | 40 -> Plextor ConvertX PX-TV100U (em2861) [093b:a005] | 39 | 40 -> Plextor ConvertX PX-TV100U (em2861) [093b:a005] |
| @@ -66,3 +66,6 @@ | |||
| 66 | 68 -> Terratec AV350 (em2860) [0ccd:0084] | 66 | 68 -> Terratec AV350 (em2860) [0ccd:0084] |
| 67 | 69 -> KWorld ATSC 315U HDTV TV Box (em2882) [eb1a:a313] | 67 | 69 -> KWorld ATSC 315U HDTV TV Box (em2882) [eb1a:a313] |
| 68 | 70 -> Evga inDtube (em2882) | 68 | 70 -> Evga inDtube (em2882) |
| 69 | 71 -> Silvercrest Webcam 1.3mpix (em2820/em2840) | ||
| 70 | 72 -> Gadmei UTV330+ (em2861) | ||
| 71 | 73 -> Reddo DVB-C USB TV Box (em2870) | ||
diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 15562427e8a9..2620d60341ee 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 | |||
| @@ -153,8 +153,8 @@ | |||
| 153 | 152 -> Asus Tiger Rev:1.00 [1043:4857] | 153 | 152 -> Asus Tiger Rev:1.00 [1043:4857] |
| 154 | 153 -> Kworld Plus TV Analog Lite PCI [17de:7128] | 154 | 153 -> Kworld Plus TV Analog Lite PCI [17de:7128] |
| 155 | 154 -> Avermedia AVerTV GO 007 FM Plus [1461:f31d] | 155 | 154 -> Avermedia AVerTV GO 007 FM Plus [1461:f31d] |
| 156 | 155 -> Hauppauge WinTV-HVR1120 ATSC/QAM-Hybrid [0070:6706,0070:6708] | 156 | 155 -> Hauppauge WinTV-HVR1150 ATSC/QAM-Hybrid [0070:6706,0070:6708] |
| 157 | 156 -> Hauppauge WinTV-HVR1110r3 DVB-T/Hybrid [0070:6707,0070:6709,0070:670a] | 157 | 156 -> Hauppauge WinTV-HVR1120 DVB-T/Hybrid [0070:6707,0070:6709,0070:670a] |
| 158 | 157 -> Avermedia AVerTV Studio 507UA [1461:a11b] | 158 | 157 -> Avermedia AVerTV Studio 507UA [1461:a11b] |
| 159 | 158 -> AVerMedia Cardbus TV/Radio (E501R) [1461:b7e9] | 159 | 158 -> AVerMedia Cardbus TV/Radio (E501R) [1461:b7e9] |
| 160 | 159 -> Beholder BeholdTV 505 RDS [0000:505B] | 160 | 159 -> Beholder BeholdTV 505 RDS [0000:505B] |
| @@ -167,3 +167,8 @@ | |||
| 167 | 166 -> Beholder BeholdTV 607 RDS [5ace:6073] | 167 | 166 -> Beholder BeholdTV 607 RDS [5ace:6073] |
| 168 | 167 -> Beholder BeholdTV 609 RDS [5ace:6092] | 168 | 167 -> Beholder BeholdTV 609 RDS [5ace:6092] |
| 169 | 168 -> Beholder BeholdTV 609 RDS [5ace:6093] | 169 | 168 -> Beholder BeholdTV 609 RDS [5ace:6093] |
| 170 | 169 -> Compro VideoMate S350/S300 [185b:c900] | ||
| 171 | 170 -> AverMedia AverTV Studio 505 [1461:a115] | ||
| 172 | 171 -> Beholder BeholdTV X7 [5ace:7595] | ||
| 173 | 172 -> RoverMedia TV Link Pro FM [19d1:0138] | ||
| 174 | 173 -> Zolid Hybrid TV Tuner PCI [1131:2004] | ||
diff --git a/Documentation/video4linux/CARDLIST.saa7164 b/Documentation/video4linux/CARDLIST.saa7164 new file mode 100644 index 000000000000..152bd7b781ca --- /dev/null +++ b/Documentation/video4linux/CARDLIST.saa7164 | |||
| @@ -0,0 +1,9 @@ | |||
| 1 | 0 -> Unknown | ||
| 2 | 1 -> Generic Rev2 | ||
| 3 | 2 -> Generic Rev3 | ||
| 4 | 3 -> Hauppauge WinTV-HVR2250 [0070:8880,0070:8810] | ||
| 5 | 4 -> Hauppauge WinTV-HVR2200 [0070:8980] | ||
| 6 | 5 -> Hauppauge WinTV-HVR2200 [0070:8900] | ||
| 7 | 6 -> Hauppauge WinTV-HVR2200 [0070:8901] | ||
| 8 | 7 -> Hauppauge WinTV-HVR2250 [0070:8891,0070:8851] | ||
| 9 | 8 -> Hauppauge WinTV-HVR2250 [0070:88A1] | ||
diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index be67844074dd..e0d298fe8830 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner | |||
| @@ -78,3 +78,6 @@ tuner=77 - TCL tuner MF02GIP-5N-E | |||
| 78 | tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner | 78 | tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner |
| 79 | tuner=79 - Philips PAL/SECAM multi (FM1216 MK5) | 79 | tuner=79 - Philips PAL/SECAM multi (FM1216 MK5) |
| 80 | tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough | 80 | tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough |
| 81 | tuner=81 - Partsnic (Daewoo) PTI-5NF05 | ||
| 82 | tuner=82 - Philips CU1216L | ||
| 83 | tuner=83 - NXP TDA18271 | ||
diff --git a/Documentation/video4linux/CQcam.txt b/Documentation/video4linux/CQcam.txt index 04986efb731c..d230878e473e 100644 --- a/Documentation/video4linux/CQcam.txt +++ b/Documentation/video4linux/CQcam.txt | |||
| @@ -18,8 +18,8 @@ Table of Contents | |||
| 18 | 18 | ||
| 19 | 1.0 Introduction | 19 | 1.0 Introduction |
| 20 | 20 | ||
| 21 | The file ../drivers/char/c-qcam.c is a device driver for the | 21 | The file ../../drivers/media/video/c-qcam.c is a device driver for |
| 22 | Logitech (nee Connectix) parallel port interface color CCD camera. | 22 | the Logitech (nee Connectix) parallel port interface color CCD camera. |
| 23 | This is a fairly inexpensive device for capturing images. Logitech | 23 | This is a fairly inexpensive device for capturing images. Logitech |
| 24 | does not currently provide information for developers, but many people | 24 | does not currently provide information for developers, but many people |
| 25 | have engineered several solutions for non-Microsoft use of the Color | 25 | have engineered several solutions for non-Microsoft use of the Color |
diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt index 2bcf78896e22..3f61825be499 100644 --- a/Documentation/video4linux/gspca.txt +++ b/Documentation/video4linux/gspca.txt | |||
| @@ -44,7 +44,9 @@ zc3xx 0458:7007 Genius VideoCam V2 | |||
| 44 | zc3xx 0458:700c Genius VideoCam V3 | 44 | zc3xx 0458:700c Genius VideoCam V3 |
| 45 | zc3xx 0458:700f Genius VideoCam Web V2 | 45 | zc3xx 0458:700f Genius VideoCam Web V2 |
| 46 | sonixj 0458:7025 Genius Eye 311Q | 46 | sonixj 0458:7025 Genius Eye 311Q |
| 47 | sn9c20x 0458:7029 Genius Look 320s | ||
| 47 | sonixj 0458:702e Genius Slim 310 NB | 48 | sonixj 0458:702e Genius Slim 310 NB |
| 49 | sn9c20x 045e:00f4 LifeCam VX-6000 (SN9C20x + OV9650) | ||
| 48 | sonixj 045e:00f5 MicroSoft VX3000 | 50 | sonixj 045e:00f5 MicroSoft VX3000 |
| 49 | sonixj 045e:00f7 MicroSoft VX1000 | 51 | sonixj 045e:00f7 MicroSoft VX1000 |
| 50 | ov519 045e:028c Micro$oft xbox cam | 52 | ov519 045e:028c Micro$oft xbox cam |
| @@ -138,6 +140,7 @@ spca500 04fc:7333 PalmPixDC85 | |||
| 138 | sunplus 04fc:ffff Pure DigitalDakota | 140 | sunplus 04fc:ffff Pure DigitalDakota |
| 139 | spca501 0506:00df 3Com HomeConnect Lite | 141 | spca501 0506:00df 3Com HomeConnect Lite |
| 140 | sunplus 052b:1513 Megapix V4 | 142 | sunplus 052b:1513 Megapix V4 |
| 143 | sunplus 052b:1803 MegaImage VI | ||
| 141 | tv8532 0545:808b Veo Stingray | 144 | tv8532 0545:808b Veo Stingray |
| 142 | tv8532 0545:8333 Veo Stingray | 145 | tv8532 0545:8333 Veo Stingray |
| 143 | sunplus 0546:3155 Polaroid PDC3070 | 146 | sunplus 0546:3155 Polaroid PDC3070 |
| @@ -170,6 +173,8 @@ ov519 05a9:8519 OmniVision | |||
| 170 | ov519 05a9:a518 D-Link DSB-C310 Webcam | 173 | ov519 05a9:a518 D-Link DSB-C310 Webcam |
| 171 | sunplus 05da:1018 Digital Dream Enigma 1.3 | 174 | sunplus 05da:1018 Digital Dream Enigma 1.3 |
| 172 | stk014 05e1:0893 Syntek DV4000 | 175 | stk014 05e1:0893 Syntek DV4000 |
| 176 | gl860 05e3:0503 Genesys Logic PC Camera | ||
| 177 | gl860 05e3:f191 Genesys Logic PC Camera | ||
| 173 | spca561 060b:a001 Maxell Compact Pc PM3 | 178 | spca561 060b:a001 Maxell Compact Pc PM3 |
| 174 | zc3xx 0698:2003 CTX M730V built in | 179 | zc3xx 0698:2003 CTX M730V built in |
| 175 | spca500 06bd:0404 Agfa CL20 | 180 | spca500 06bd:0404 Agfa CL20 |
| @@ -180,6 +185,7 @@ ov534 06f8:3002 Hercules Blog Webcam | |||
| 180 | ov534 06f8:3003 Hercules Dualpix HD Weblog | 185 | ov534 06f8:3003 Hercules Dualpix HD Weblog |
| 181 | sonixj 06f8:3004 Hercules Classic Silver | 186 | sonixj 06f8:3004 Hercules Classic Silver |
| 182 | sonixj 06f8:3008 Hercules Deluxe Optical Glass | 187 | sonixj 06f8:3008 Hercules Deluxe Optical Glass |
| 188 | pac7311 06f8:3009 Hercules Classic Link | ||
| 183 | spca508 0733:0110 ViewQuest VQ110 | 189 | spca508 0733:0110 ViewQuest VQ110 |
| 184 | spca508 0130:0130 Clone Digital Webcam 11043 | 190 | spca508 0130:0130 Clone Digital Webcam 11043 |
| 185 | spca501 0733:0401 Intel Create and Share | 191 | spca501 0733:0401 Intel Create and Share |
| @@ -233,8 +239,10 @@ pac7311 093a:2621 PAC731x | |||
| 233 | pac7311 093a:2622 Genius Eye 312 | 239 | pac7311 093a:2622 Genius Eye 312 |
| 234 | pac7311 093a:2624 PAC7302 | 240 | pac7311 093a:2624 PAC7302 |
| 235 | pac7311 093a:2626 Labtec 2200 | 241 | pac7311 093a:2626 Labtec 2200 |
| 242 | pac7311 093a:2629 Genious iSlim 300 | ||
| 236 | pac7311 093a:262a Webcam 300k | 243 | pac7311 093a:262a Webcam 300k |
| 237 | pac7311 093a:262c Philips SPC 230 NC | 244 | pac7311 093a:262c Philips SPC 230 NC |
| 245 | jeilinj 0979:0280 Sakar 57379 | ||
| 238 | zc3xx 0ac8:0302 Z-star Vimicro zc0302 | 246 | zc3xx 0ac8:0302 Z-star Vimicro zc0302 |
| 239 | vc032x 0ac8:0321 Vimicro generic vc0321 | 247 | vc032x 0ac8:0321 Vimicro generic vc0321 |
| 240 | vc032x 0ac8:0323 Vimicro Vc0323 | 248 | vc032x 0ac8:0323 Vimicro Vc0323 |
| @@ -245,6 +253,7 @@ zc3xx 0ac8:305b Z-star Vimicro zc0305b | |||
| 245 | zc3xx 0ac8:307b Ldlc VC302+Ov7620 | 253 | zc3xx 0ac8:307b Ldlc VC302+Ov7620 |
| 246 | vc032x 0ac8:c001 Sony embedded vimicro | 254 | vc032x 0ac8:c001 Sony embedded vimicro |
| 247 | vc032x 0ac8:c002 Sony embedded vimicro | 255 | vc032x 0ac8:c002 Sony embedded vimicro |
| 256 | vc032x 0ac8:c301 Samsung Q1 Ultra Premium | ||
| 248 | spca508 0af9:0010 Hama USB Sightcam 100 | 257 | spca508 0af9:0010 Hama USB Sightcam 100 |
| 249 | spca508 0af9:0011 Hama USB Sightcam 100 | 258 | spca508 0af9:0011 Hama USB Sightcam 100 |
| 250 | sonixb 0c45:6001 Genius VideoCAM NB | 259 | sonixb 0c45:6001 Genius VideoCAM NB |
| @@ -282,6 +291,29 @@ sonixj 0c45:613a Microdia Sonix PC Camera | |||
| 282 | sonixj 0c45:613b Surfer SN-206 | 291 | sonixj 0c45:613b Surfer SN-206 |
| 283 | sonixj 0c45:613c Sonix Pccam168 | 292 | sonixj 0c45:613c Sonix Pccam168 |
| 284 | sonixj 0c45:6143 Sonix Pccam168 | 293 | sonixj 0c45:6143 Sonix Pccam168 |
| 294 | sonixj 0c45:6148 Digitus DA-70811/ZSMC USB PC Camera ZS211/Microdia | ||
| 295 | sn9c20x 0c45:6240 PC Camera (SN9C201 + MT9M001) | ||
| 296 | sn9c20x 0c45:6242 PC Camera (SN9C201 + MT9M111) | ||
| 297 | sn9c20x 0c45:6248 PC Camera (SN9C201 + OV9655) | ||
| 298 | sn9c20x 0c45:624e PC Camera (SN9C201 + SOI968) | ||
| 299 | sn9c20x 0c45:624f PC Camera (SN9C201 + OV9650) | ||
| 300 | sn9c20x 0c45:6251 PC Camera (SN9C201 + OV9650) | ||
| 301 | sn9c20x 0c45:6253 PC Camera (SN9C201 + OV9650) | ||
| 302 | sn9c20x 0c45:6260 PC Camera (SN9C201 + OV7670) | ||
| 303 | sn9c20x 0c45:6270 PC Camera (SN9C201 + MT9V011/MT9V111/MT9V112) | ||
| 304 | sn9c20x 0c45:627b PC Camera (SN9C201 + OV7660) | ||
| 305 | sn9c20x 0c45:627c PC Camera (SN9C201 + HV7131R) | ||
| 306 | sn9c20x 0c45:627f PC Camera (SN9C201 + OV9650) | ||
| 307 | sn9c20x 0c45:6280 PC Camera (SN9C202 + MT9M001) | ||
| 308 | sn9c20x 0c45:6282 PC Camera (SN9C202 + MT9M111) | ||
| 309 | sn9c20x 0c45:6288 PC Camera (SN9C202 + OV9655) | ||
| 310 | sn9c20x 0c45:628e PC Camera (SN9C202 + SOI968) | ||
| 311 | sn9c20x 0c45:628f PC Camera (SN9C202 + OV9650) | ||
| 312 | sn9c20x 0c45:62a0 PC Camera (SN9C202 + OV7670) | ||
| 313 | sn9c20x 0c45:62b0 PC Camera (SN9C202 + MT9V011/MT9V111/MT9V112) | ||
| 314 | sn9c20x 0c45:62b3 PC Camera (SN9C202 + OV9655) | ||
| 315 | sn9c20x 0c45:62bb PC Camera (SN9C202 + OV7660) | ||
| 316 | sn9c20x 0c45:62bc PC Camera (SN9C202 + HV7131R) | ||
| 285 | sunplus 0d64:0303 Sunplus FashionCam DXG | 317 | sunplus 0d64:0303 Sunplus FashionCam DXG |
| 286 | etoms 102c:6151 Qcam Sangha CIF | 318 | etoms 102c:6151 Qcam Sangha CIF |
| 287 | etoms 102c:6251 Qcam xxxxxx VGA | 319 | etoms 102c:6251 Qcam xxxxxx VGA |
| @@ -290,6 +322,7 @@ spca561 10fd:7e50 FlyCam Usb 100 | |||
| 290 | zc3xx 10fd:8050 Typhoon Webshot II USB 300k | 322 | zc3xx 10fd:8050 Typhoon Webshot II USB 300k |
| 291 | ov534 1415:2000 Sony HD Eye for PS3 (SLEH 00201) | 323 | ov534 1415:2000 Sony HD Eye for PS3 (SLEH 00201) |
| 292 | pac207 145f:013a Trust WB-1300N | 324 | pac207 145f:013a Trust WB-1300N |
| 325 | sn9c20x 145f:013d Trust WB-3600R | ||
| 293 | vc032x 15b8:6001 HP 2.0 Megapixel | 326 | vc032x 15b8:6001 HP 2.0 Megapixel |
| 294 | vc032x 15b8:6002 HP 2.0 Megapixel rz406aa | 327 | vc032x 15b8:6002 HP 2.0 Megapixel rz406aa |
| 295 | spca501 1776:501c Arowana 300K CMOS Camera | 328 | spca501 1776:501c Arowana 300K CMOS Camera |
| @@ -300,4 +333,11 @@ spca500 2899:012c Toptro Industrial | |||
| 300 | spca508 8086:0110 Intel Easy PC Camera | 333 | spca508 8086:0110 Intel Easy PC Camera |
| 301 | spca500 8086:0630 Intel Pocket PC Camera | 334 | spca500 8086:0630 Intel Pocket PC Camera |
| 302 | spca506 99fa:8988 Grandtec V.cap | 335 | spca506 99fa:8988 Grandtec V.cap |
| 336 | sn9c20x a168:0610 Dino-Lite Digital Microscope (SN9C201 + HV7131R) | ||
| 337 | sn9c20x a168:0611 Dino-Lite Digital Microscope (SN9C201 + HV7131R) | ||
| 338 | sn9c20x a168:0613 Dino-Lite Digital Microscope (SN9C201 + HV7131R) | ||
| 339 | sn9c20x a168:0618 Dino-Lite Digital Microscope (SN9C201 + HV7131R) | ||
| 340 | sn9c20x a168:0614 Dino-Lite Digital Microscope (SN9C201 + MT9M111) | ||
| 341 | sn9c20x a168:0615 Dino-Lite Digital Microscope (SN9C201 + MT9M111) | ||
| 342 | sn9c20x a168:0617 Dino-Lite Digital Microscope (SN9C201 + MT9M111) | ||
| 303 | spca561 abcd:cdee Petcam | 343 | spca561 abcd:cdee Petcam |
diff --git a/Documentation/video4linux/si4713.txt b/Documentation/video4linux/si4713.txt new file mode 100644 index 000000000000..25abdb78209d --- /dev/null +++ b/Documentation/video4linux/si4713.txt | |||
| @@ -0,0 +1,176 @@ | |||
| 1 | Driver for I2C radios for the Silicon Labs Si4713 FM Radio Transmitters | ||
| 2 | |||
| 3 | Copyright (c) 2009 Nokia Corporation | ||
| 4 | Contact: Eduardo Valentin <eduardo.valentin@nokia.com> | ||
| 5 | |||
| 6 | |||
| 7 | Information about the Device | ||
| 8 | ============================ | ||
| 9 | This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address. | ||
| 10 | Basically, it has transmission and signal noise level measurement features. | ||
| 11 | |||
| 12 | The Si4713 integrates transmit functions for FM broadcast stereo transmission. | ||
| 13 | The chip also allows integrated receive power scanning to identify low signal | ||
| 14 | power FM channels. | ||
| 15 | |||
| 16 | The chip is programmed using commands and responses. There are also several | ||
| 17 | properties which can change the behavior of this chip. | ||
| 18 | |||
| 19 | Users must comply with local regulations on radio frequency (RF) transmission. | ||
| 20 | |||
| 21 | Device driver description | ||
| 22 | ========================= | ||
| 23 | There are two modules to handle this device. One is a I2C device driver | ||
| 24 | and the other is a platform driver. | ||
| 25 | |||
| 26 | The I2C device driver exports a v4l2-subdev interface to the kernel. | ||
| 27 | All properties can also be accessed by v4l2 extended controls interface, by | ||
| 28 | using the v4l2-subdev calls (g_ext_ctrls, s_ext_ctrls). | ||
| 29 | |||
| 30 | The platform device driver exports a v4l2 radio device interface to user land. | ||
| 31 | So, it uses the I2C device driver as a sub device in order to send the user | ||
| 32 | commands to the actual device. Basically it is a wrapper to the I2C device driver. | ||
| 33 | |||
| 34 | Applications can use v4l2 radio API to specify frequency of operation, mute state, | ||
| 35 | etc. But mostly of its properties will be present in the extended controls. | ||
| 36 | |||
| 37 | When the v4l2 mute property is set to 1 (true), the driver will turn the chip off. | ||
| 38 | |||
| 39 | Properties description | ||
| 40 | ====================== | ||
| 41 | |||
| 42 | The properties can be accessed using v4l2 extended controls. | ||
| 43 | Here is an output from v4l2-ctl util: | ||
| 44 | / # v4l2-ctl -d /dev/radio0 --all -L | ||
| 45 | Driver Info: | ||
| 46 | Driver name : radio-si4713 | ||
| 47 | Card type : Silicon Labs Si4713 Modulator | ||
| 48 | Bus info : | ||
| 49 | Driver version: 0 | ||
| 50 | Capabilities : 0x00080800 | ||
| 51 | RDS Output | ||
| 52 | Modulator | ||
| 53 | Audio output: 0 (FM Modulator Audio Out) | ||
| 54 | Frequency: 1408000 (88.000000 MHz) | ||
| 55 | Video Standard = 0x00000000 | ||
| 56 | Modulator: | ||
| 57 | Name : FM Modulator | ||
| 58 | Capabilities : 62.5 Hz stereo rds | ||
| 59 | Frequency range : 76.0 MHz - 108.0 MHz | ||
| 60 | Subchannel modulation: stereo+rds | ||
| 61 | |||
| 62 | User Controls | ||
| 63 | |||
| 64 | mute (bool) : default=1 value=0 | ||
| 65 | |||
| 66 | FM Radio Modulator Controls | ||
| 67 | |||
| 68 | rds_signal_deviation (int) : min=0 max=90000 step=10 default=200 value=200 flags=slider | ||
| 69 | rds_program_id (int) : min=0 max=65535 step=1 default=0 value=0 | ||
| 70 | rds_program_type (int) : min=0 max=31 step=1 default=0 value=0 | ||
| 71 | rds_ps_name (str) : min=0 max=96 step=8 value='si4713 ' | ||
| 72 | rds_radio_text (str) : min=0 max=384 step=32 value='' | ||
| 73 | audio_limiter_feature_enabled (bool) : default=1 value=1 | ||
| 74 | audio_limiter_release_time (int) : min=250 max=102390 step=50 default=5010 value=5010 flags=slider | ||
| 75 | audio_limiter_deviation (int) : min=0 max=90000 step=10 default=66250 value=66250 flags=slider | ||
| 76 | audio_compression_feature_enabl (bool) : default=1 value=1 | ||
| 77 | audio_compression_gain (int) : min=0 max=20 step=1 default=15 value=15 flags=slider | ||
| 78 | audio_compression_threshold (int) : min=-40 max=0 step=1 default=-40 value=-40 flags=slider | ||
| 79 | audio_compression_attack_time (int) : min=0 max=5000 step=500 default=0 value=0 flags=slider | ||
| 80 | audio_compression_release_time (int) : min=100000 max=1000000 step=100000 default=1000000 value=1000000 flags=slider | ||
| 81 | pilot_tone_feature_enabled (bool) : default=1 value=1 | ||
| 82 | pilot_tone_deviation (int) : min=0 max=90000 step=10 default=6750 value=6750 flags=slider | ||
| 83 | pilot_tone_frequency (int) : min=0 max=19000 step=1 default=19000 value=19000 flags=slider | ||
| 84 | pre_emphasis_settings (menu) : min=0 max=2 default=1 value=1 | ||
| 85 | tune_power_level (int) : min=0 max=120 step=1 default=88 value=88 flags=slider | ||
| 86 | tune_antenna_capacitor (int) : min=0 max=191 step=1 default=0 value=110 flags=slider | ||
| 87 | / # | ||
| 88 | |||
| 89 | Here is a summary of them: | ||
| 90 | |||
| 91 | * Pilot is an audible tone sent by the device. | ||
| 92 | |||
| 93 | pilot_frequency - Configures the frequency of the stereo pilot tone. | ||
| 94 | pilot_deviation - Configures pilot tone frequency deviation level. | ||
| 95 | pilot_enabled - Enables or disables the pilot tone feature. | ||
| 96 | |||
| 97 | * The si4713 device is capable of applying audio compression to the transmitted signal. | ||
| 98 | |||
| 99 | acomp_enabled - Enables or disables the audio dynamic range control feature. | ||
| 100 | acomp_gain - Sets the gain for audio dynamic range control. | ||
| 101 | acomp_threshold - Sets the threshold level for audio dynamic range control. | ||
| 102 | acomp_attack_time - Sets the attack time for audio dynamic range control. | ||
| 103 | acomp_release_time - Sets the release time for audio dynamic range control. | ||
| 104 | |||
| 105 | * Limiter setups audio deviation limiter feature. Once a over deviation occurs, | ||
| 106 | it is possible to adjust the front-end gain of the audio input and always | ||
| 107 | prevent over deviation. | ||
| 108 | |||
| 109 | limiter_enabled - Enables or disables the limiter feature. | ||
| 110 | limiter_deviation - Configures audio frequency deviation level. | ||
| 111 | limiter_release_time - Sets the limiter release time. | ||
| 112 | |||
| 113 | * Tuning power | ||
| 114 | |||
| 115 | power_level - Sets the output power level for signal transmission. | ||
| 116 | antenna_capacitor - This selects the value of antenna tuning capacitor manually | ||
| 117 | or automatically if set to zero. | ||
| 118 | |||
| 119 | * RDS related | ||
| 120 | |||
| 121 | rds_ps_name - Sets the RDS ps name field for transmission. | ||
| 122 | rds_radio_text - Sets the RDS radio text for transmission. | ||
| 123 | rds_pi - Sets the RDS PI field for transmission. | ||
| 124 | rds_pty - Sets the RDS PTY field for transmission. | ||
| 125 | |||
| 126 | * Region related | ||
| 127 | |||
| 128 | preemphasis - sets the preemphasis to be applied for transmission. | ||
| 129 | |||
| 130 | RNL | ||
| 131 | === | ||
| 132 | |||
| 133 | This device also has an interface to measure received noise level. To do that, you should | ||
| 134 | ioctl the device node. Here is an code of example: | ||
| 135 | |||
| 136 | int main (int argc, char *argv[]) | ||
| 137 | { | ||
| 138 | struct si4713_rnl rnl; | ||
| 139 | int fd = open("/dev/radio0", O_RDWR); | ||
| 140 | int rval; | ||
| 141 | |||
| 142 | if (argc < 2) | ||
| 143 | return -EINVAL; | ||
| 144 | |||
| 145 | if (fd < 0) | ||
| 146 | return fd; | ||
| 147 | |||
| 148 | sscanf(argv[1], "%d", &rnl.frequency); | ||
| 149 | |||
| 150 | rval = ioctl(fd, SI4713_IOC_MEASURE_RNL, &rnl); | ||
| 151 | if (rval < 0) | ||
| 152 | return rval; | ||
| 153 | |||
| 154 | printf("received noise level: %d\n", rnl.rnl); | ||
| 155 | |||
| 156 | close(fd); | ||
| 157 | } | ||
| 158 | |||
| 159 | The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under | ||
| 160 | include/media/si4713.h. | ||
| 161 | |||
| 162 | Stereo/Mono and RDS subchannels | ||
| 163 | =============================== | ||
| 164 | |||
| 165 | The device can also be configured using the available sub channels for | ||
| 166 | transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly. | ||
| 167 | Refer to v4l2-spec for proper use of this ioctl. | ||
| 168 | |||
| 169 | Testing | ||
| 170 | ======= | ||
| 171 | Testing is usually done with v4l2-ctl utility for managing FM tuner cards. | ||
| 172 | The tool can be found in v4l-dvb repository under v4l2-apps/util directory. | ||
| 173 | |||
| 174 | Example for setting rds ps name: | ||
| 175 | # v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy" | ||
| 176 | |||
diff --git a/Documentation/video4linux/soc-camera.txt b/Documentation/video4linux/soc-camera.txt index 178ef3c5e579..3f87c7da4ca2 100644 --- a/Documentation/video4linux/soc-camera.txt +++ b/Documentation/video4linux/soc-camera.txt | |||
| @@ -116,5 +116,45 @@ functionality. | |||
| 116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, | 116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, |
| 117 | listing pixel formats, supported by the camera. | 117 | listing pixel formats, supported by the camera. |
| 118 | 118 | ||
| 119 | VIDIOC_S_CROP and VIDIOC_S_FMT behaviour | ||
| 120 | ---------------------------------------- | ||
| 121 | |||
| 122 | Above user ioctls modify image geometry as follows: | ||
| 123 | |||
| 124 | VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor | ||
| 125 | pixel. Changing sensor window sizes preserves any scaling factors, therefore | ||
| 126 | user window sizes change as well. | ||
| 127 | |||
| 128 | VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as | ||
| 129 | much as possible by modifying scaling factors. If the sensor window cannot be | ||
| 130 | preserved precisely, it may be changed too. | ||
| 131 | |||
| 132 | In soc-camera there are two locations, where scaling and cropping can taks | ||
| 133 | place: in the camera driver and in the host driver. User ioctls are first passed | ||
| 134 | to the host driver, which then generally passes them down to the camera driver. | ||
| 135 | It is more efficient to perform scaling and cropping in the camera driver to | ||
| 136 | save camera bus bandwidth and maximise the framerate. However, if the camera | ||
| 137 | driver failed to set the required parameters with sufficient precision, the host | ||
| 138 | driver may decide to also use its own scaling and cropping to fulfill the user's | ||
| 139 | request. | ||
| 140 | |||
| 141 | Camera drivers are interfaced to the soc-camera core and to host drivers over | ||
| 142 | the v4l2-subdev API, which is completely functional, it doesn't pass any data. | ||
| 143 | Therefore all camera drivers shall reply to .g_fmt() requests with their current | ||
| 144 | output geometry. This is necessary to correctly configure the camera bus. | ||
| 145 | .s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling | ||
| 146 | factors have to be maintained by camera drivers internally. According to the | ||
| 147 | V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we | ||
| 148 | rely on camera drivers implementing .cropcap(). If the camera driver does not | ||
| 149 | support cropping, it may choose to not implement .s_crop(), but to enable | ||
| 150 | cropping support by the camera host driver at least the .g_crop method must be | ||
| 151 | implemented. | ||
| 152 | |||
| 153 | User window geometry is kept in .user_width and .user_height fields in struct | ||
| 154 | soc_camera_device and used by the soc-camera core and host drivers. The core | ||
| 155 | updates these fields upon successful completion of a .s_fmt() call, but if these | ||
| 156 | fields change elsewhere, e.g., during .s_crop() processing, the host driver is | ||
| 157 | responsible for updating them. | ||
| 158 | |||
| 119 | -- | 159 | -- |
| 120 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> | 160 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> |
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index ba4706afc5fb..b806edaf3e75 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt | |||
| @@ -370,19 +370,20 @@ from the remove() callback ensures that this is always done correctly. | |||
| 370 | The bridge driver also has some helper functions it can use: | 370 | The bridge driver also has some helper functions it can use: |
| 371 | 371 | ||
| 372 | struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, | 372 | struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, |
| 373 | "module_foo", "chipid", 0x36); | 373 | "module_foo", "chipid", 0x36, NULL); |
| 374 | 374 | ||
| 375 | This loads the given module (can be NULL if no module needs to be loaded) and | 375 | This loads the given module (can be NULL if no module needs to be loaded) and |
| 376 | calls i2c_new_device() with the given i2c_adapter and chip/address arguments. | 376 | calls i2c_new_device() with the given i2c_adapter and chip/address arguments. |
| 377 | If all goes well, then it registers the subdev with the v4l2_device. | 377 | If all goes well, then it registers the subdev with the v4l2_device. |
| 378 | 378 | ||
| 379 | You can also use v4l2_i2c_new_probed_subdev() which is very similar to | 379 | You can also use the last argument of v4l2_i2c_new_subdev() to pass an array |
| 380 | v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses | 380 | of possible I2C addresses that it should probe. These probe addresses are |
| 381 | that it should probe. Internally it calls i2c_new_probed_device(). | 381 | only used if the previous argument is 0. A non-zero argument means that you |
| 382 | know the exact i2c address so in that case no probing will take place. | ||
| 382 | 383 | ||
| 383 | Both functions return NULL if something went wrong. | 384 | Both functions return NULL if something went wrong. |
| 384 | 385 | ||
| 385 | Note that the chipid you pass to v4l2_i2c_new_(probed_)subdev() is usually | 386 | Note that the chipid you pass to v4l2_i2c_new_subdev() is usually |
| 386 | the same as the module name. It allows you to specify a chip variant, e.g. | 387 | the same as the module name. It allows you to specify a chip variant, e.g. |
| 387 | "saa7114" or "saa7115". In general though the i2c driver autodetects this. | 388 | "saa7114" or "saa7115". In general though the i2c driver autodetects this. |
| 388 | The use of chipid is something that needs to be looked at more closely at a | 389 | The use of chipid is something that needs to be looked at more closely at a |
| @@ -410,11 +411,6 @@ the irq and platform_data arguments after the subdev was setup. The older | |||
| 410 | v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with | 411 | v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with |
| 411 | irq set to 0 and platform_data set to NULL. | 412 | irq set to 0 and platform_data set to NULL. |
| 412 | 413 | ||
| 413 | Note that in the next kernel release the functions v4l2_i2c_new_subdev, | ||
| 414 | v4l2_i2c_new_probed_subdev and v4l2_i2c_new_probed_subdev_addr will all be | ||
| 415 | replaced by a single v4l2_i2c_new_subdev that is identical to | ||
| 416 | v4l2_i2c_new_subdev_cfg but without the irq and platform_data arguments. | ||
| 417 | |||
| 418 | struct video_device | 414 | struct video_device |
| 419 | ------------------- | 415 | ------------------- |
| 420 | 416 | ||
| @@ -490,31 +486,35 @@ VFL_TYPE_RADIO: radioX for radio tuners | |||
| 490 | VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) | 486 | VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) |
| 491 | 487 | ||
| 492 | The last argument gives you a certain amount of control over the device | 488 | The last argument gives you a certain amount of control over the device |
| 493 | kernel number used (i.e. the X in videoX). Normally you will pass -1 to | 489 | device node number used (i.e. the X in videoX). Normally you will pass -1 |
| 494 | let the v4l2 framework pick the first free number. But if a driver creates | 490 | to let the v4l2 framework pick the first free number. But sometimes users |
| 495 | many devices, then it can be useful to have different video devices in | 491 | want to select a specific node number. It is common that drivers allow |
| 496 | separate ranges. For example, video capture devices start at 0, video | 492 | the user to select a specific device node number through a driver module |
| 497 | output devices start at 16. | 493 | option. That number is then passed to this function and video_register_device |
| 498 | 494 | will attempt to select that device node number. If that number was already | |
| 499 | So you can use the last argument to specify a minimum kernel number and | 495 | in use, then the next free device node number will be selected and it |
| 500 | the v4l2 framework will try to pick the first free number that is equal | 496 | will send a warning to the kernel log. |
| 497 | |||
| 498 | Another use-case is if a driver creates many devices. In that case it can | ||
| 499 | be useful to place different video devices in separate ranges. For example, | ||
| 500 | video capture devices start at 0, video output devices start at 16. | ||
| 501 | So you can use the last argument to specify a minimum device node number | ||
| 502 | and the v4l2 framework will try to pick the first free number that is equal | ||
| 501 | or higher to what you passed. If that fails, then it will just pick the | 503 | or higher to what you passed. If that fails, then it will just pick the |
| 502 | first free number. | 504 | first free number. |
| 503 | 505 | ||
| 506 | Since in this case you do not care about a warning about not being able | ||
| 507 | to select the specified device node number, you can call the function | ||
| 508 | video_register_device_no_warn() instead. | ||
| 509 | |||
| 504 | Whenever a device node is created some attributes are also created for you. | 510 | Whenever a device node is created some attributes are also created for you. |
| 505 | If you look in /sys/class/video4linux you see the devices. Go into e.g. | 511 | If you look in /sys/class/video4linux you see the devices. Go into e.g. |
| 506 | video0 and you will see 'name' and 'index' attributes. The 'name' attribute | 512 | video0 and you will see 'name' and 'index' attributes. The 'name' attribute |
| 507 | is the 'name' field of the video_device struct. The 'index' attribute is | 513 | is the 'name' field of the video_device struct. |
| 508 | a device node index that can be assigned by the driver, or that is calculated | ||
| 509 | for you. | ||
| 510 | |||
| 511 | If you call video_register_device(), then the index is just increased by | ||
| 512 | 1 for each device node you register. The first video device node you register | ||
| 513 | always starts off with 0. | ||
| 514 | 514 | ||
| 515 | Alternatively you can call video_register_device_index() which is identical | 515 | The 'index' attribute is the index of the device node: for each call to |
| 516 | to video_register_device(), but with an extra index argument. Here you can | 516 | video_register_device() the index is just increased by 1. The first video |
| 517 | pass a specific index value (between 0 and 31) that should be used. | 517 | device node you register always starts with index 0. |
| 518 | 518 | ||
| 519 | Users can setup udev rules that utilize the index attribute to make fancy | 519 | Users can setup udev rules that utilize the index attribute to make fancy |
| 520 | device names (e.g. 'mpegX' for MPEG video capture device nodes). | 520 | device names (e.g. 'mpegX' for MPEG video capture device nodes). |
| @@ -523,9 +523,8 @@ After the device was successfully registered, then you can use these fields: | |||
| 523 | 523 | ||
| 524 | - vfl_type: the device type passed to video_register_device. | 524 | - vfl_type: the device type passed to video_register_device. |
| 525 | - minor: the assigned device minor number. | 525 | - minor: the assigned device minor number. |
| 526 | - num: the device kernel number (i.e. the X in videoX). | 526 | - num: the device node number (i.e. the X in videoX). |
| 527 | - index: the device index number (calculated or set explicitly using | 527 | - index: the device index number. |
| 528 | video_register_device_index). | ||
| 529 | 528 | ||
| 530 | If the registration failed, then you need to call video_device_release() | 529 | If the registration failed, then you need to call video_device_release() |
| 531 | to free the allocated video_device struct, or free your own struct if the | 530 | to free the allocated video_device struct, or free your own struct if the |
diff --git a/Documentation/vm/00-INDEX b/Documentation/vm/00-INDEX index 2f77ced35df7..e57d6a9dd32b 100644 --- a/Documentation/vm/00-INDEX +++ b/Documentation/vm/00-INDEX | |||
| @@ -6,6 +6,8 @@ balance | |||
| 6 | - various information on memory balancing. | 6 | - various information on memory balancing. |
| 7 | hugetlbpage.txt | 7 | hugetlbpage.txt |
| 8 | - a brief summary of hugetlbpage support in the Linux kernel. | 8 | - a brief summary of hugetlbpage support in the Linux kernel. |
| 9 | ksm.txt | ||
| 10 | - how to use the Kernel Samepage Merging feature. | ||
| 9 | locking | 11 | locking |
| 10 | - info on how locking and synchronization is done in the Linux vm code. | 12 | - info on how locking and synchronization is done in the Linux vm code. |
| 11 | numa | 13 | numa |
| @@ -20,3 +22,5 @@ slabinfo.c | |||
| 20 | - source code for a tool to get reports about slabs. | 22 | - source code for a tool to get reports about slabs. |
| 21 | slub.txt | 23 | slub.txt |
| 22 | - a short users guide for SLUB. | 24 | - a short users guide for SLUB. |
| 25 | map_hugetlb.c | ||
| 26 | - an example program that uses the MAP_HUGETLB mmap flag. | ||
diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index ea8714fcc3ad..82a7bd1800b2 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt | |||
| @@ -18,13 +18,13 @@ First the Linux kernel needs to be built with the CONFIG_HUGETLBFS | |||
| 18 | automatically when CONFIG_HUGETLBFS is selected) configuration | 18 | automatically when CONFIG_HUGETLBFS is selected) configuration |
| 19 | options. | 19 | options. |
| 20 | 20 | ||
| 21 | The kernel built with hugepage support should show the number of configured | 21 | The kernel built with huge page support should show the number of configured |
| 22 | hugepages in the system by running the "cat /proc/meminfo" command. | 22 | huge pages in the system by running the "cat /proc/meminfo" command. |
| 23 | 23 | ||
| 24 | /proc/meminfo also provides information about the total number of hugetlb | 24 | /proc/meminfo also provides information about the total number of hugetlb |
| 25 | pages configured in the kernel. It also displays information about the | 25 | pages configured in the kernel. It also displays information about the |
| 26 | number of free hugetlb pages at any time. It also displays information about | 26 | number of free hugetlb pages at any time. It also displays information about |
| 27 | the configured hugepage size - this is needed for generating the proper | 27 | the configured huge page size - this is needed for generating the proper |
| 28 | alignment and size of the arguments to the above system calls. | 28 | alignment and size of the arguments to the above system calls. |
| 29 | 29 | ||
| 30 | The output of "cat /proc/meminfo" will have lines like: | 30 | The output of "cat /proc/meminfo" will have lines like: |
| @@ -37,25 +37,27 @@ HugePages_Surp: yyy | |||
| 37 | Hugepagesize: zzz kB | 37 | Hugepagesize: zzz kB |
| 38 | 38 | ||
| 39 | where: | 39 | where: |
| 40 | HugePages_Total is the size of the pool of hugepages. | 40 | HugePages_Total is the size of the pool of huge pages. |
| 41 | HugePages_Free is the number of hugepages in the pool that are not yet | 41 | HugePages_Free is the number of huge pages in the pool that are not yet |
| 42 | allocated. | 42 | allocated. |
| 43 | HugePages_Rsvd is short for "reserved," and is the number of hugepages | 43 | HugePages_Rsvd is short for "reserved," and is the number of huge pages for |
| 44 | for which a commitment to allocate from the pool has been made, but no | 44 | which a commitment to allocate from the pool has been made, |
| 45 | allocation has yet been made. It's vaguely analogous to overcommit. | 45 | but no allocation has yet been made. Reserved huge pages |
| 46 | HugePages_Surp is short for "surplus," and is the number of hugepages in | 46 | guarantee that an application will be able to allocate a |
| 47 | the pool above the value in /proc/sys/vm/nr_hugepages. The maximum | 47 | huge page from the pool of huge pages at fault time. |
| 48 | number of surplus hugepages is controlled by | 48 | HugePages_Surp is short for "surplus," and is the number of huge pages in |
| 49 | /proc/sys/vm/nr_overcommit_hugepages. | 49 | the pool above the value in /proc/sys/vm/nr_hugepages. The |
| 50 | maximum number of surplus huge pages is controlled by | ||
| 51 | /proc/sys/vm/nr_overcommit_hugepages. | ||
| 50 | 52 | ||
| 51 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured | 53 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured |
| 52 | in the kernel. | 54 | in the kernel. |
| 53 | 55 | ||
| 54 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb | 56 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb |
| 55 | pages in the kernel. Super user can dynamically request more (or free some | 57 | pages in the kernel. Super user can dynamically request more (or free some |
| 56 | pre-configured) hugepages. | 58 | pre-configured) huge pages. |
| 57 | The allocation (or deallocation) of hugetlb pages is possible only if there are | 59 | The allocation (or deallocation) of hugetlb pages is possible only if there are |
| 58 | enough physically contiguous free pages in system (freeing of hugepages is | 60 | enough physically contiguous free pages in system (freeing of huge pages is |
| 59 | possible only if there are enough hugetlb pages free that can be transferred | 61 | possible only if there are enough hugetlb pages free that can be transferred |
| 60 | back to regular memory pool). | 62 | back to regular memory pool). |
| 61 | 63 | ||
| @@ -67,43 +69,82 @@ use either the mmap system call or shared memory system calls to start using | |||
| 67 | the huge pages. It is required that the system administrator preallocate | 69 | the huge pages. It is required that the system administrator preallocate |
| 68 | enough memory for huge page purposes. | 70 | enough memory for huge page purposes. |
| 69 | 71 | ||
| 70 | Use the following command to dynamically allocate/deallocate hugepages: | 72 | The administrator can preallocate huge pages on the kernel boot command line by |
| 73 | specifying the "hugepages=N" parameter, where 'N' = the number of huge pages | ||
| 74 | requested. This is the most reliable method for preallocating huge pages as | ||
| 75 | memory has not yet become fragmented. | ||
| 76 | |||
| 77 | Some platforms support multiple huge page sizes. To preallocate huge pages | ||
| 78 | of a specific size, one must preceed the huge pages boot command parameters | ||
| 79 | with a huge page size selection parameter "hugepagesz=<size>". <size> must | ||
| 80 | be specified in bytes with optional scale suffix [kKmMgG]. The default huge | ||
| 81 | page size may be selected with the "default_hugepagesz=<size>" boot parameter. | ||
| 82 | |||
| 83 | /proc/sys/vm/nr_hugepages indicates the current number of configured [default | ||
| 84 | size] hugetlb pages in the kernel. Super user can dynamically request more | ||
| 85 | (or free some pre-configured) huge pages. | ||
| 86 | |||
| 87 | Use the following command to dynamically allocate/deallocate default sized | ||
| 88 | huge pages: | ||
| 71 | 89 | ||
| 72 | echo 20 > /proc/sys/vm/nr_hugepages | 90 | echo 20 > /proc/sys/vm/nr_hugepages |
| 73 | 91 | ||
| 74 | This command will try to configure 20 hugepages in the system. The success | 92 | This command will try to configure 20 default sized huge pages in the system. |
| 75 | or failure of allocation depends on the amount of physically contiguous | 93 | On a NUMA platform, the kernel will attempt to distribute the huge page pool |
| 76 | memory that is preset in system at this time. System administrators may want | 94 | over the all on-line nodes. These huge pages, allocated when nr_hugepages |
| 77 | to put this command in one of the local rc init files. This will enable the | 95 | is increased, are called "persistent huge pages". |
| 78 | kernel to request huge pages early in the boot process (when the possibility | 96 | |
| 79 | of getting physical contiguous pages is still very high). In either | 97 | The success or failure of huge page allocation depends on the amount of |
| 80 | case, administrators will want to verify the number of hugepages actually | 98 | physically contiguous memory that is preset in system at the time of the |
| 81 | allocated by checking the sysctl or meminfo. | 99 | allocation attempt. If the kernel is unable to allocate huge pages from |
| 82 | 100 | some nodes in a NUMA system, it will attempt to make up the difference by | |
| 83 | /proc/sys/vm/nr_overcommit_hugepages indicates how large the pool of | 101 | allocating extra pages on other nodes with sufficient available contiguous |
| 84 | hugepages can grow, if more hugepages than /proc/sys/vm/nr_hugepages are | 102 | memory, if any. |
| 85 | requested by applications. echo'ing any non-zero value into this file | 103 | |
| 86 | indicates that the hugetlb subsystem is allowed to try to obtain | 104 | System administrators may want to put this command in one of the local rc init |
| 87 | hugepages from the buddy allocator, if the normal pool is exhausted. As | 105 | files. This will enable the kernel to request huge pages early in the boot |
| 88 | these surplus hugepages go out of use, they are freed back to the buddy | 106 | process when the possibility of getting physical contiguous pages is still |
| 107 | very high. Administrators can verify the number of huge pages actually | ||
| 108 | allocated by checking the sysctl or meminfo. To check the per node | ||
| 109 | distribution of huge pages in a NUMA system, use: | ||
| 110 | |||
| 111 | cat /sys/devices/system/node/node*/meminfo | fgrep Huge | ||
| 112 | |||
| 113 | /proc/sys/vm/nr_overcommit_hugepages specifies how large the pool of | ||
| 114 | huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are | ||
| 115 | requested by applications. Writing any non-zero value into this file | ||
| 116 | indicates that the hugetlb subsystem is allowed to try to obtain "surplus" | ||
| 117 | huge pages from the buddy allocator, when the normal pool is exhausted. As | ||
| 118 | these surplus huge pages go out of use, they are freed back to the buddy | ||
| 89 | allocator. | 119 | allocator. |
| 90 | 120 | ||
| 121 | When increasing the huge page pool size via nr_hugepages, any surplus | ||
| 122 | pages will first be promoted to persistent huge pages. Then, additional | ||
| 123 | huge pages will be allocated, if necessary and if possible, to fulfill | ||
| 124 | the new huge page pool size. | ||
| 125 | |||
| 126 | The administrator may shrink the pool of preallocated huge pages for | ||
| 127 | the default huge page size by setting the nr_hugepages sysctl to a | ||
| 128 | smaller value. The kernel will attempt to balance the freeing of huge pages | ||
| 129 | across all on-line nodes. Any free huge pages on the selected nodes will | ||
| 130 | be freed back to the buddy allocator. | ||
| 131 | |||
| 91 | Caveat: Shrinking the pool via nr_hugepages such that it becomes less | 132 | Caveat: Shrinking the pool via nr_hugepages such that it becomes less |
| 92 | than the number of hugepages in use will convert the balance to surplus | 133 | than the number of huge pages in use will convert the balance to surplus |
| 93 | huge pages even if it would exceed the overcommit value. As long as | 134 | huge pages even if it would exceed the overcommit value. As long as |
| 94 | this condition holds, however, no more surplus huge pages will be | 135 | this condition holds, however, no more surplus huge pages will be |
| 95 | allowed on the system until one of the two sysctls are increased | 136 | allowed on the system until one of the two sysctls are increased |
| 96 | sufficiently, or the surplus huge pages go out of use and are freed. | 137 | sufficiently, or the surplus huge pages go out of use and are freed. |
| 97 | 138 | ||
| 98 | With support for multiple hugepage pools at run-time available, much of | 139 | With support for multiple huge page pools at run-time available, much of |
| 99 | the hugepage userspace interface has been duplicated in sysfs. The above | 140 | the huge page userspace interface has been duplicated in sysfs. The above |
| 100 | information applies to the default hugepage size (which will be | 141 | information applies to the default huge page size which will be |
| 101 | controlled by the proc interfaces for backwards compatibility). The root | 142 | controlled by the /proc interfaces for backwards compatibility. The root |
| 102 | hugepage control directory is | 143 | huge page control directory in sysfs is: |
| 103 | 144 | ||
| 104 | /sys/kernel/mm/hugepages | 145 | /sys/kernel/mm/hugepages |
| 105 | 146 | ||
| 106 | For each hugepage size supported by the running kernel, a subdirectory | 147 | For each huge page size supported by the running kernel, a subdirectory |
| 107 | will exist, of the form | 148 | will exist, of the form |
| 108 | 149 | ||
| 109 | hugepages-${size}kB | 150 | hugepages-${size}kB |
| @@ -116,9 +157,9 @@ Inside each of these directories, the same set of files will exist: | |||
| 116 | resv_hugepages | 157 | resv_hugepages |
| 117 | surplus_hugepages | 158 | surplus_hugepages |
| 118 | 159 | ||
| 119 | which function as described above for the default hugepage-sized case. | 160 | which function as described above for the default huge page-sized case. |
| 120 | 161 | ||
| 121 | If the user applications are going to request hugepages using mmap system | 162 | If the user applications are going to request huge pages using mmap system |
| 122 | call, then it is required that system administrator mount a file system of | 163 | call, then it is required that system administrator mount a file system of |
| 123 | type hugetlbfs: | 164 | type hugetlbfs: |
| 124 | 165 | ||
| @@ -127,7 +168,7 @@ type hugetlbfs: | |||
| 127 | none /mnt/huge | 168 | none /mnt/huge |
| 128 | 169 | ||
| 129 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory | 170 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory |
| 130 | /mnt/huge. Any files created on /mnt/huge uses hugepages. The uid and gid | 171 | /mnt/huge. Any files created on /mnt/huge uses huge pages. The uid and gid |
| 131 | options sets the owner and group of the root of the file system. By default | 172 | options sets the owner and group of the root of the file system. By default |
| 132 | the uid and gid of the current process are taken. The mode option sets the | 173 | the uid and gid of the current process are taken. The mode option sets the |
| 133 | mode of root of file system to value & 0777. This value is given in octal. | 174 | mode of root of file system to value & 0777. This value is given in octal. |
| @@ -146,24 +187,26 @@ Regular chown, chgrp, and chmod commands (with right permissions) could be | |||
| 146 | used to change the file attributes on hugetlbfs. | 187 | used to change the file attributes on hugetlbfs. |
| 147 | 188 | ||
| 148 | Also, it is important to note that no such mount command is required if the | 189 | Also, it is important to note that no such mount command is required if the |
| 149 | applications are going to use only shmat/shmget system calls. Users who | 190 | applications are going to use only shmat/shmget system calls or mmap with |
| 150 | wish to use hugetlb page via shared memory segment should be a member of | 191 | MAP_HUGETLB. Users who wish to use hugetlb page via shared memory segment |
| 151 | a supplementary group and system admin needs to configure that gid into | 192 | should be a member of a supplementary group and system admin needs to |
| 152 | /proc/sys/vm/hugetlb_shm_group. It is possible for same or different | 193 | configure that gid into /proc/sys/vm/hugetlb_shm_group. It is possible for |
| 153 | applications to use any combination of mmaps and shm* calls, though the | 194 | same or different applications to use any combination of mmaps and shm* |
| 154 | mount of filesystem will be required for using mmap calls. | 195 | calls, though the mount of filesystem will be required for using mmap calls |
| 196 | without MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see | ||
| 197 | map_hugetlb.c. | ||
| 155 | 198 | ||
| 156 | ******************************************************************* | 199 | ******************************************************************* |
| 157 | 200 | ||
| 158 | /* | 201 | /* |
| 159 | * Example of using hugepage memory in a user application using Sys V shared | 202 | * Example of using huge page memory in a user application using Sys V shared |
| 160 | * memory system calls. In this example the app is requesting 256MB of | 203 | * memory system calls. In this example the app is requesting 256MB of |
| 161 | * memory that is backed by huge pages. The application uses the flag | 204 | * memory that is backed by huge pages. The application uses the flag |
| 162 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is | 205 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is |
| 163 | * requesting hugepages. | 206 | * requesting huge pages. |
| 164 | * | 207 | * |
| 165 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for | 208 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for |
| 166 | * hugepages. That means the addresses starting with 0x800000... will need | 209 | * huge pages. That means the addresses starting with 0x800000... will need |
| 167 | * to be specified. Specifying a fixed address is not required on ppc64, | 210 | * to be specified. Specifying a fixed address is not required on ppc64, |
| 168 | * i386 or x86_64. | 211 | * i386 or x86_64. |
| 169 | * | 212 | * |
| @@ -252,14 +295,14 @@ int main(void) | |||
| 252 | ******************************************************************* | 295 | ******************************************************************* |
| 253 | 296 | ||
| 254 | /* | 297 | /* |
| 255 | * Example of using hugepage memory in a user application using the mmap | 298 | * Example of using huge page memory in a user application using the mmap |
| 256 | * system call. Before running this application, make sure that the | 299 | * system call. Before running this application, make sure that the |
| 257 | * administrator has mounted the hugetlbfs filesystem (on some directory | 300 | * administrator has mounted the hugetlbfs filesystem (on some directory |
| 258 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this | 301 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this |
| 259 | * example, the app is requesting memory of size 256MB that is backed by | 302 | * example, the app is requesting memory of size 256MB that is backed by |
| 260 | * huge pages. | 303 | * huge pages. |
| 261 | * | 304 | * |
| 262 | * For ia64 architecture, Linux kernel reserves Region number 4 for hugepages. | 305 | * For ia64 architecture, Linux kernel reserves Region number 4 for huge pages. |
| 263 | * That means the addresses starting with 0x800000... will need to be | 306 | * That means the addresses starting with 0x800000... will need to be |
| 264 | * specified. Specifying a fixed address is not required on ppc64, i386 | 307 | * specified. Specifying a fixed address is not required on ppc64, i386 |
| 265 | * or x86_64. | 308 | * or x86_64. |
diff --git a/Documentation/vm/ksm.txt b/Documentation/vm/ksm.txt new file mode 100644 index 000000000000..72a22f65960e --- /dev/null +++ b/Documentation/vm/ksm.txt | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | How to use the Kernel Samepage Merging feature | ||
| 2 | ---------------------------------------------- | ||
| 3 | |||
| 4 | KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, | ||
| 5 | added to the Linux kernel in 2.6.32. See mm/ksm.c for its implementation, | ||
| 6 | and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ | ||
| 7 | |||
| 8 | The KSM daemon ksmd periodically scans those areas of user memory which | ||
| 9 | have been registered with it, looking for pages of identical content which | ||
| 10 | can be replaced by a single write-protected page (which is automatically | ||
| 11 | copied if a process later wants to update its content). | ||
| 12 | |||
| 13 | KSM was originally developed for use with KVM (where it was known as | ||
| 14 | Kernel Shared Memory), to fit more virtual machines into physical memory, | ||
| 15 | by sharing the data common between them. But it can be useful to any | ||
| 16 | application which generates many instances of the same data. | ||
| 17 | |||
| 18 | KSM only merges anonymous (private) pages, never pagecache (file) pages. | ||
| 19 | KSM's merged pages are at present locked into kernel memory for as long | ||
| 20 | as they are shared: so cannot be swapped out like the user pages they | ||
| 21 | replace (but swapping KSM pages should follow soon in a later release). | ||
| 22 | |||
| 23 | KSM only operates on those areas of address space which an application | ||
| 24 | has advised to be likely candidates for merging, by using the madvise(2) | ||
| 25 | system call: int madvise(addr, length, MADV_MERGEABLE). | ||
| 26 | |||
| 27 | The app may call int madvise(addr, length, MADV_UNMERGEABLE) to cancel | ||
| 28 | that advice and restore unshared pages: whereupon KSM unmerges whatever | ||
| 29 | it merged in that range. Note: this unmerging call may suddenly require | ||
| 30 | more memory than is available - possibly failing with EAGAIN, but more | ||
| 31 | probably arousing the Out-Of-Memory killer. | ||
| 32 | |||
| 33 | If KSM is not configured into the running kernel, madvise MADV_MERGEABLE | ||
| 34 | and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was | ||
| 35 | built with CONFIG_KSM=y, those calls will normally succeed: even if the | ||
| 36 | the KSM daemon is not currently running, MADV_MERGEABLE still registers | ||
| 37 | the range for whenever the KSM daemon is started; even if the range | ||
| 38 | cannot contain any pages which KSM could actually merge; even if | ||
| 39 | MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. | ||
| 40 | |||
| 41 | Like other madvise calls, they are intended for use on mapped areas of | ||
| 42 | the user address space: they will report ENOMEM if the specified range | ||
| 43 | includes unmapped gaps (though working on the intervening mapped areas), | ||
| 44 | and might fail with EAGAIN if not enough memory for internal structures. | ||
| 45 | |||
| 46 | Applications should be considerate in their use of MADV_MERGEABLE, | ||
| 47 | restricting its use to areas likely to benefit. KSM's scans may use | ||
| 48 | a lot of processing power, and its kernel-resident pages are a limited | ||
| 49 | resource. Some installations will disable KSM for these reasons. | ||
| 50 | |||
| 51 | The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/, | ||
| 52 | readable by all but writable only by root: | ||
| 53 | |||
| 54 | max_kernel_pages - set to maximum number of kernel pages that KSM may use | ||
| 55 | e.g. "echo 2000 > /sys/kernel/mm/ksm/max_kernel_pages" | ||
| 56 | Value 0 imposes no limit on the kernel pages KSM may use; | ||
| 57 | but note that any process using MADV_MERGEABLE can cause | ||
| 58 | KSM to allocate these pages, unswappable until it exits. | ||
| 59 | Default: 2000 (chosen for demonstration purposes) | ||
| 60 | |||
| 61 | pages_to_scan - how many present pages to scan before ksmd goes to sleep | ||
| 62 | e.g. "echo 200 > /sys/kernel/mm/ksm/pages_to_scan" | ||
| 63 | Default: 200 (chosen for demonstration purposes) | ||
| 64 | |||
| 65 | sleep_millisecs - how many milliseconds ksmd should sleep before next scan | ||
| 66 | e.g. "echo 20 > /sys/kernel/mm/ksm/sleep_millisecs" | ||
| 67 | Default: 20 (chosen for demonstration purposes) | ||
| 68 | |||
| 69 | run - set 0 to stop ksmd from running but keep merged pages, | ||
| 70 | set 1 to run ksmd e.g. "echo 1 > /sys/kernel/mm/ksm/run", | ||
| 71 | set 2 to stop ksmd and unmerge all pages currently merged, | ||
| 72 | but leave mergeable areas registered for next run | ||
| 73 | Default: 1 (for immediate use by apps which register) | ||
| 74 | |||
| 75 | The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: | ||
| 76 | |||
| 77 | pages_shared - how many shared unswappable kernel pages KSM is using | ||
| 78 | pages_sharing - how many more sites are sharing them i.e. how much saved | ||
| 79 | pages_unshared - how many pages unique but repeatedly checked for merging | ||
| 80 | pages_volatile - how many pages changing too fast to be placed in a tree | ||
| 81 | full_scans - how many times all mergeable areas have been scanned | ||
| 82 | |||
| 83 | A high ratio of pages_sharing to pages_shared indicates good sharing, but | ||
| 84 | a high ratio of pages_unshared to pages_sharing indicates wasted effort. | ||
| 85 | pages_volatile embraces several different kinds of activity, but a high | ||
| 86 | proportion there would also indicate poor use of madvise MADV_MERGEABLE. | ||
| 87 | |||
| 88 | Izik Eidus, | ||
| 89 | Hugh Dickins, 30 July 2009 | ||
diff --git a/Documentation/vm/map_hugetlb.c b/Documentation/vm/map_hugetlb.c new file mode 100644 index 000000000000..e2bdae37f499 --- /dev/null +++ b/Documentation/vm/map_hugetlb.c | |||
| @@ -0,0 +1,77 @@ | |||
| 1 | /* | ||
| 2 | * Example of using hugepage memory in a user application using the mmap | ||
| 3 | * system call with MAP_HUGETLB flag. Before running this program make | ||
| 4 | * sure the administrator has allocated enough default sized huge pages | ||
| 5 | * to cover the 256 MB allocation. | ||
| 6 | * | ||
| 7 | * For ia64 architecture, Linux kernel reserves Region number 4 for hugepages. | ||
| 8 | * That means the addresses starting with 0x800000... will need to be | ||
| 9 | * specified. Specifying a fixed address is not required on ppc64, i386 | ||
| 10 | * or x86_64. | ||
| 11 | */ | ||
| 12 | #include <stdlib.h> | ||
| 13 | #include <stdio.h> | ||
| 14 | #include <unistd.h> | ||
| 15 | #include <sys/mman.h> | ||
| 16 | #include <fcntl.h> | ||
| 17 | |||
| 18 | #define LENGTH (256UL*1024*1024) | ||
| 19 | #define PROTECTION (PROT_READ | PROT_WRITE) | ||
| 20 | |||
| 21 | #ifndef MAP_HUGETLB | ||
| 22 | #define MAP_HUGETLB 0x40 | ||
| 23 | #endif | ||
| 24 | |||
| 25 | /* Only ia64 requires this */ | ||
| 26 | #ifdef __ia64__ | ||
| 27 | #define ADDR (void *)(0x8000000000000000UL) | ||
| 28 | #define FLAGS (MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB | MAP_FIXED) | ||
| 29 | #else | ||
| 30 | #define ADDR (void *)(0x0UL) | ||
| 31 | #define FLAGS (MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB) | ||
| 32 | #endif | ||
| 33 | |||
| 34 | void check_bytes(char *addr) | ||
| 35 | { | ||
| 36 | printf("First hex is %x\n", *((unsigned int *)addr)); | ||
| 37 | } | ||
| 38 | |||
| 39 | void write_bytes(char *addr) | ||
| 40 | { | ||
| 41 | unsigned long i; | ||
| 42 | |||
| 43 | for (i = 0; i < LENGTH; i++) | ||
| 44 | *(addr + i) = (char)i; | ||
| 45 | } | ||
| 46 | |||
| 47 | void read_bytes(char *addr) | ||
| 48 | { | ||
| 49 | unsigned long i; | ||
| 50 | |||
| 51 | check_bytes(addr); | ||
| 52 | for (i = 0; i < LENGTH; i++) | ||
| 53 | if (*(addr + i) != (char)i) { | ||
| 54 | printf("Mismatch at %lu\n", i); | ||
| 55 | break; | ||
| 56 | } | ||
| 57 | } | ||
| 58 | |||
| 59 | int main(void) | ||
| 60 | { | ||
| 61 | void *addr; | ||
| 62 | |||
| 63 | addr = mmap(ADDR, LENGTH, PROTECTION, FLAGS, 0, 0); | ||
| 64 | if (addr == MAP_FAILED) { | ||
| 65 | perror("mmap"); | ||
| 66 | exit(1); | ||
| 67 | } | ||
| 68 | |||
| 69 | printf("Returned address is %p\n", addr); | ||
| 70 | check_bytes(addr); | ||
| 71 | write_bytes(addr); | ||
| 72 | read_bytes(addr); | ||
| 73 | |||
| 74 | munmap(addr, LENGTH); | ||
| 75 | |||
| 76 | return 0; | ||
| 77 | } | ||
diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt index bb1f5c6e28b3..510917ff59ed 100644 --- a/Documentation/vm/slub.txt +++ b/Documentation/vm/slub.txt | |||
| @@ -41,6 +41,8 @@ Possible debug options are | |||
| 41 | P Poisoning (object and padding) | 41 | P Poisoning (object and padding) |
| 42 | U User tracking (free and alloc) | 42 | U User tracking (free and alloc) |
| 43 | T Trace (please only use on single slabs) | 43 | T Trace (please only use on single slabs) |
| 44 | O Switch debugging off for caches that would have | ||
| 45 | caused higher minimum slab orders | ||
| 44 | - Switch all debugging off (useful if the kernel is | 46 | - Switch all debugging off (useful if the kernel is |
| 45 | configured with CONFIG_SLUB_DEBUG_ON) | 47 | configured with CONFIG_SLUB_DEBUG_ON) |
| 46 | 48 | ||
| @@ -59,6 +61,14 @@ to the dentry cache with | |||
| 59 | 61 | ||
| 60 | slub_debug=F,dentry | 62 | slub_debug=F,dentry |
| 61 | 63 | ||
| 64 | Debugging options may require the minimum possible slab order to increase as | ||
| 65 | a result of storing the metadata (for example, caches with PAGE_SIZE object | ||
| 66 | sizes). This has a higher liklihood of resulting in slab allocation errors | ||
| 67 | in low memory situations or if there's high fragmentation of memory. To | ||
| 68 | switch off debugging for such caches by default, use | ||
| 69 | |||
| 70 | slub_debug=O | ||
| 71 | |||
| 62 | In case you forgot to enable debugging on the kernel command line: It is | 72 | In case you forgot to enable debugging on the kernel command line: It is |
| 63 | possible to enable debugging manually when the kernel is up. Look at the | 73 | possible to enable debugging manually when the kernel is up. Look at the |
| 64 | contents of: | 74 | contents of: |
diff --git a/Documentation/x86/00-INDEX b/Documentation/x86/00-INDEX index dbe3377754af..f37b46d34861 100644 --- a/Documentation/x86/00-INDEX +++ b/Documentation/x86/00-INDEX | |||
| @@ -2,3 +2,5 @@ | |||
| 2 | - this file | 2 | - this file |
| 3 | mtrr.txt | 3 | mtrr.txt |
| 4 | - how to use x86 Memory Type Range Registers to increase performance | 4 | - how to use x86 Memory Type Range Registers to increase performance |
| 5 | exception-tables.txt | ||
| 6 | - why and how Linux kernel uses exception tables on x86 | ||
diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 8da3a795083f..30b43e1b2697 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt | |||
| @@ -599,6 +599,7 @@ Protocol: 2.07+ | |||
| 599 | 0x00000000 The default x86/PC environment | 599 | 0x00000000 The default x86/PC environment |
| 600 | 0x00000001 lguest | 600 | 0x00000001 lguest |
| 601 | 0x00000002 Xen | 601 | 0x00000002 Xen |
| 602 | 0x00000003 Moorestown MID | ||
| 602 | 603 | ||
| 603 | Field name: hardware_subarch_data | 604 | Field name: hardware_subarch_data |
| 604 | Type: write (subarch-dependent) | 605 | Type: write (subarch-dependent) |
diff --git a/Documentation/exception.txt b/Documentation/x86/exception-tables.txt index 2d5aded64247..32901aa36f0a 100644 --- a/Documentation/exception.txt +++ b/Documentation/x86/exception-tables.txt | |||
| @@ -1,123 +1,123 @@ | |||
| 1 | Kernel level exception handling in Linux 2.1.8 | 1 | Kernel level exception handling in Linux |
| 2 | Commentary by Joerg Pommnitz <joerg@raleigh.ibm.com> | 2 | Commentary by Joerg Pommnitz <joerg@raleigh.ibm.com> |
| 3 | 3 | ||
| 4 | When a process runs in kernel mode, it often has to access user | 4 | When a process runs in kernel mode, it often has to access user |
| 5 | mode memory whose address has been passed by an untrusted program. | 5 | mode memory whose address has been passed by an untrusted program. |
| 6 | To protect itself the kernel has to verify this address. | 6 | To protect itself the kernel has to verify this address. |
| 7 | 7 | ||
| 8 | In older versions of Linux this was done with the | 8 | In older versions of Linux this was done with the |
| 9 | int verify_area(int type, const void * addr, unsigned long size) | 9 | int verify_area(int type, const void * addr, unsigned long size) |
| 10 | function (which has since been replaced by access_ok()). | 10 | function (which has since been replaced by access_ok()). |
| 11 | 11 | ||
| 12 | This function verified that the memory area starting at address | 12 | This function verified that the memory area starting at address |
| 13 | 'addr' and of size 'size' was accessible for the operation specified | 13 | 'addr' and of size 'size' was accessible for the operation specified |
| 14 | in type (read or write). To do this, verify_read had to look up the | 14 | in type (read or write). To do this, verify_read had to look up the |
| 15 | virtual memory area (vma) that contained the address addr. In the | 15 | virtual memory area (vma) that contained the address addr. In the |
| 16 | normal case (correctly working program), this test was successful. | 16 | normal case (correctly working program), this test was successful. |
| 17 | It only failed for a few buggy programs. In some kernel profiling | 17 | It only failed for a few buggy programs. In some kernel profiling |
| 18 | tests, this normally unneeded verification used up a considerable | 18 | tests, this normally unneeded verification used up a considerable |
| 19 | amount of time. | 19 | amount of time. |
| 20 | 20 | ||
| 21 | To overcome this situation, Linus decided to let the virtual memory | 21 | To overcome this situation, Linus decided to let the virtual memory |
| 22 | hardware present in every Linux-capable CPU handle this test. | 22 | hardware present in every Linux-capable CPU handle this test. |
| 23 | 23 | ||
| 24 | How does this work? | 24 | How does this work? |
| 25 | 25 | ||
| 26 | Whenever the kernel tries to access an address that is currently not | 26 | Whenever the kernel tries to access an address that is currently not |
| 27 | accessible, the CPU generates a page fault exception and calls the | 27 | accessible, the CPU generates a page fault exception and calls the |
| 28 | page fault handler | 28 | page fault handler |
| 29 | 29 | ||
| 30 | void do_page_fault(struct pt_regs *regs, unsigned long error_code) | 30 | void do_page_fault(struct pt_regs *regs, unsigned long error_code) |
| 31 | 31 | ||
| 32 | in arch/i386/mm/fault.c. The parameters on the stack are set up by | 32 | in arch/x86/mm/fault.c. The parameters on the stack are set up by |
| 33 | the low level assembly glue in arch/i386/kernel/entry.S. The parameter | 33 | the low level assembly glue in arch/x86/kernel/entry_32.S. The parameter |
| 34 | regs is a pointer to the saved registers on the stack, error_code | 34 | regs is a pointer to the saved registers on the stack, error_code |
| 35 | contains a reason code for the exception. | 35 | contains a reason code for the exception. |
| 36 | 36 | ||
| 37 | do_page_fault first obtains the unaccessible address from the CPU | 37 | do_page_fault first obtains the unaccessible address from the CPU |
| 38 | control register CR2. If the address is within the virtual address | 38 | control register CR2. If the address is within the virtual address |
| 39 | space of the process, the fault probably occurred, because the page | 39 | space of the process, the fault probably occurred, because the page |
| 40 | was not swapped in, write protected or something similar. However, | 40 | was not swapped in, write protected or something similar. However, |
| 41 | we are interested in the other case: the address is not valid, there | 41 | we are interested in the other case: the address is not valid, there |
| 42 | is no vma that contains this address. In this case, the kernel jumps | 42 | is no vma that contains this address. In this case, the kernel jumps |
| 43 | to the bad_area label. | 43 | to the bad_area label. |
| 44 | 44 | ||
| 45 | There it uses the address of the instruction that caused the exception | 45 | There it uses the address of the instruction that caused the exception |
| 46 | (i.e. regs->eip) to find an address where the execution can continue | 46 | (i.e. regs->eip) to find an address where the execution can continue |
| 47 | (fixup). If this search is successful, the fault handler modifies the | 47 | (fixup). If this search is successful, the fault handler modifies the |
| 48 | return address (again regs->eip) and returns. The execution will | 48 | return address (again regs->eip) and returns. The execution will |
| 49 | continue at the address in fixup. | 49 | continue at the address in fixup. |
| 50 | 50 | ||
| 51 | Where does fixup point to? | 51 | Where does fixup point to? |
| 52 | 52 | ||
| 53 | Since we jump to the contents of fixup, fixup obviously points | 53 | Since we jump to the contents of fixup, fixup obviously points |
| 54 | to executable code. This code is hidden inside the user access macros. | 54 | to executable code. This code is hidden inside the user access macros. |
| 55 | I have picked the get_user macro defined in include/asm/uaccess.h as an | 55 | I have picked the get_user macro defined in arch/x86/include/asm/uaccess.h |
| 56 | example. The definition is somewhat hard to follow, so let's peek at | 56 | as an example. The definition is somewhat hard to follow, so let's peek at |
| 57 | the code generated by the preprocessor and the compiler. I selected | 57 | the code generated by the preprocessor and the compiler. I selected |
| 58 | the get_user call in drivers/char/console.c for a detailed examination. | 58 | the get_user call in drivers/char/sysrq.c for a detailed examination. |
| 59 | 59 | ||
| 60 | The original code in console.c line 1405: | 60 | The original code in sysrq.c line 587: |
| 61 | get_user(c, buf); | 61 | get_user(c, buf); |
| 62 | 62 | ||
| 63 | The preprocessor output (edited to become somewhat readable): | 63 | The preprocessor output (edited to become somewhat readable): |
| 64 | 64 | ||
| 65 | ( | 65 | ( |
| 66 | { | 66 | { |
| 67 | long __gu_err = - 14 , __gu_val = 0; | 67 | long __gu_err = - 14 , __gu_val = 0; |
| 68 | const __typeof__(*( ( buf ) )) *__gu_addr = ((buf)); | 68 | const __typeof__(*( ( buf ) )) *__gu_addr = ((buf)); |
| 69 | if (((((0 + current_set[0])->tss.segment) == 0x18 ) || | 69 | if (((((0 + current_set[0])->tss.segment) == 0x18 ) || |
| 70 | (((sizeof(*(buf))) <= 0xC0000000UL) && | 70 | (((sizeof(*(buf))) <= 0xC0000000UL) && |
| 71 | ((unsigned long)(__gu_addr ) <= 0xC0000000UL - (sizeof(*(buf))))))) | 71 | ((unsigned long)(__gu_addr ) <= 0xC0000000UL - (sizeof(*(buf))))))) |
| 72 | do { | 72 | do { |
| 73 | __gu_err = 0; | 73 | __gu_err = 0; |
| 74 | switch ((sizeof(*(buf)))) { | 74 | switch ((sizeof(*(buf)))) { |
| 75 | case 1: | 75 | case 1: |
| 76 | __asm__ __volatile__( | 76 | __asm__ __volatile__( |
| 77 | "1: mov" "b" " %2,%" "b" "1\n" | 77 | "1: mov" "b" " %2,%" "b" "1\n" |
| 78 | "2:\n" | 78 | "2:\n" |
| 79 | ".section .fixup,\"ax\"\n" | 79 | ".section .fixup,\"ax\"\n" |
| 80 | "3: movl %3,%0\n" | 80 | "3: movl %3,%0\n" |
| 81 | " xor" "b" " %" "b" "1,%" "b" "1\n" | 81 | " xor" "b" " %" "b" "1,%" "b" "1\n" |
| 82 | " jmp 2b\n" | 82 | " jmp 2b\n" |
| 83 | ".section __ex_table,\"a\"\n" | 83 | ".section __ex_table,\"a\"\n" |
| 84 | " .align 4\n" | 84 | " .align 4\n" |
| 85 | " .long 1b,3b\n" | 85 | " .long 1b,3b\n" |
| 86 | ".text" : "=r"(__gu_err), "=q" (__gu_val): "m"((*(struct __large_struct *) | 86 | ".text" : "=r"(__gu_err), "=q" (__gu_val): "m"((*(struct __large_struct *) |
| 87 | ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )) ; | 87 | ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )) ; |
| 88 | break; | 88 | break; |
| 89 | case 2: | 89 | case 2: |
| 90 | __asm__ __volatile__( | 90 | __asm__ __volatile__( |
| 91 | "1: mov" "w" " %2,%" "w" "1\n" | 91 | "1: mov" "w" " %2,%" "w" "1\n" |
| 92 | "2:\n" | 92 | "2:\n" |
| 93 | ".section .fixup,\"ax\"\n" | 93 | ".section .fixup,\"ax\"\n" |
| 94 | "3: movl %3,%0\n" | 94 | "3: movl %3,%0\n" |
| 95 | " xor" "w" " %" "w" "1,%" "w" "1\n" | 95 | " xor" "w" " %" "w" "1,%" "w" "1\n" |
| 96 | " jmp 2b\n" | 96 | " jmp 2b\n" |
| 97 | ".section __ex_table,\"a\"\n" | 97 | ".section __ex_table,\"a\"\n" |
| 98 | " .align 4\n" | 98 | " .align 4\n" |
| 99 | " .long 1b,3b\n" | 99 | " .long 1b,3b\n" |
| 100 | ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) | 100 | ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) |
| 101 | ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )); | 101 | ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )); |
| 102 | break; | 102 | break; |
| 103 | case 4: | 103 | case 4: |
| 104 | __asm__ __volatile__( | 104 | __asm__ __volatile__( |
| 105 | "1: mov" "l" " %2,%" "" "1\n" | 105 | "1: mov" "l" " %2,%" "" "1\n" |
| 106 | "2:\n" | 106 | "2:\n" |
| 107 | ".section .fixup,\"ax\"\n" | 107 | ".section .fixup,\"ax\"\n" |
| 108 | "3: movl %3,%0\n" | 108 | "3: movl %3,%0\n" |
| 109 | " xor" "l" " %" "" "1,%" "" "1\n" | 109 | " xor" "l" " %" "" "1,%" "" "1\n" |
| 110 | " jmp 2b\n" | 110 | " jmp 2b\n" |
| 111 | ".section __ex_table,\"a\"\n" | 111 | ".section __ex_table,\"a\"\n" |
| 112 | " .align 4\n" " .long 1b,3b\n" | 112 | " .align 4\n" " .long 1b,3b\n" |
| 113 | ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) | 113 | ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) |
| 114 | ( __gu_addr )) ), "i"(- 14 ), "0"(__gu_err)); | 114 | ( __gu_addr )) ), "i"(- 14 ), "0"(__gu_err)); |
| 115 | break; | 115 | break; |
| 116 | default: | 116 | default: |
| 117 | (__gu_val) = __get_user_bad(); | 117 | (__gu_val) = __get_user_bad(); |
| 118 | } | 118 | } |
| 119 | } while (0) ; | 119 | } while (0) ; |
| 120 | ((c)) = (__typeof__(*((buf))))__gu_val; | 120 | ((c)) = (__typeof__(*((buf))))__gu_val; |
| 121 | __gu_err; | 121 | __gu_err; |
| 122 | } | 122 | } |
| 123 | ); | 123 | ); |
| @@ -127,12 +127,12 @@ see what code gcc generates: | |||
| 127 | 127 | ||
| 128 | > xorl %edx,%edx | 128 | > xorl %edx,%edx |
| 129 | > movl current_set,%eax | 129 | > movl current_set,%eax |
| 130 | > cmpl $24,788(%eax) | 130 | > cmpl $24,788(%eax) |
| 131 | > je .L1424 | 131 | > je .L1424 |
| 132 | > cmpl $-1073741825,64(%esp) | 132 | > cmpl $-1073741825,64(%esp) |
| 133 | > ja .L1423 | 133 | > ja .L1423 |
| 134 | > .L1424: | 134 | > .L1424: |
| 135 | > movl %edx,%eax | 135 | > movl %edx,%eax |
| 136 | > movl 64(%esp),%ebx | 136 | > movl 64(%esp),%ebx |
| 137 | > #APP | 137 | > #APP |
| 138 | > 1: movb (%ebx),%dl /* this is the actual user access */ | 138 | > 1: movb (%ebx),%dl /* this is the actual user access */ |
| @@ -149,17 +149,17 @@ see what code gcc generates: | |||
| 149 | > .L1423: | 149 | > .L1423: |
| 150 | > movzbl %dl,%esi | 150 | > movzbl %dl,%esi |
| 151 | 151 | ||
| 152 | The optimizer does a good job and gives us something we can actually | 152 | The optimizer does a good job and gives us something we can actually |
| 153 | understand. Can we? The actual user access is quite obvious. Thanks | 153 | understand. Can we? The actual user access is quite obvious. Thanks |
| 154 | to the unified address space we can just access the address in user | 154 | to the unified address space we can just access the address in user |
| 155 | memory. But what does the .section stuff do????? | 155 | memory. But what does the .section stuff do????? |
| 156 | 156 | ||
| 157 | To understand this we have to look at the final kernel: | 157 | To understand this we have to look at the final kernel: |
| 158 | 158 | ||
| 159 | > objdump --section-headers vmlinux | 159 | > objdump --section-headers vmlinux |
| 160 | > | 160 | > |
| 161 | > vmlinux: file format elf32-i386 | 161 | > vmlinux: file format elf32-i386 |
| 162 | > | 162 | > |
| 163 | > Sections: | 163 | > Sections: |
| 164 | > Idx Name Size VMA LMA File off Algn | 164 | > Idx Name Size VMA LMA File off Algn |
| 165 | > 0 .text 00098f40 c0100000 c0100000 00001000 2**4 | 165 | > 0 .text 00098f40 c0100000 c0100000 00001000 2**4 |
| @@ -198,18 +198,18 @@ final kernel executable: | |||
| 198 | 198 | ||
| 199 | The whole user memory access is reduced to 10 x86 machine instructions. | 199 | The whole user memory access is reduced to 10 x86 machine instructions. |
| 200 | The instructions bracketed in the .section directives are no longer | 200 | The instructions bracketed in the .section directives are no longer |
| 201 | in the normal execution path. They are located in a different section | 201 | in the normal execution path. They are located in a different section |
| 202 | of the executable file: | 202 | of the executable file: |
| 203 | 203 | ||
| 204 | > objdump --disassemble --section=.fixup vmlinux | 204 | > objdump --disassemble --section=.fixup vmlinux |
| 205 | > | 205 | > |
| 206 | > c0199ff5 <.fixup+10b5> movl $0xfffffff2,%eax | 206 | > c0199ff5 <.fixup+10b5> movl $0xfffffff2,%eax |
| 207 | > c0199ffa <.fixup+10ba> xorb %dl,%dl | 207 | > c0199ffa <.fixup+10ba> xorb %dl,%dl |
| 208 | > c0199ffc <.fixup+10bc> jmp c017e7a7 <do_con_write+e3> | 208 | > c0199ffc <.fixup+10bc> jmp c017e7a7 <do_con_write+e3> |
| 209 | 209 | ||
| 210 | And finally: | 210 | And finally: |
| 211 | > objdump --full-contents --section=__ex_table vmlinux | 211 | > objdump --full-contents --section=__ex_table vmlinux |
| 212 | > | 212 | > |
| 213 | > c01aa7c4 93c017c0 e09f19c0 97c017c0 99c017c0 ................ | 213 | > c01aa7c4 93c017c0 e09f19c0 97c017c0 99c017c0 ................ |
| 214 | > c01aa7d4 f6c217c0 e99f19c0 a5e717c0 f59f19c0 ................ | 214 | > c01aa7d4 f6c217c0 e99f19c0 a5e717c0 f59f19c0 ................ |
| 215 | > c01aa7e4 080a18c0 01a019c0 0a0a18c0 04a019c0 ................ | 215 | > c01aa7e4 080a18c0 01a019c0 0a0a18c0 04a019c0 ................ |
| @@ -235,8 +235,8 @@ sections in the ELF object file. So the instructions | |||
| 235 | ended up in the .fixup section of the object file and the addresses | 235 | ended up in the .fixup section of the object file and the addresses |
| 236 | .long 1b,3b | 236 | .long 1b,3b |
| 237 | ended up in the __ex_table section of the object file. 1b and 3b | 237 | ended up in the __ex_table section of the object file. 1b and 3b |
| 238 | are local labels. The local label 1b (1b stands for next label 1 | 238 | are local labels. The local label 1b (1b stands for next label 1 |
| 239 | backward) is the address of the instruction that might fault, i.e. | 239 | backward) is the address of the instruction that might fault, i.e. |
| 240 | in our case the address of the label 1 is c017e7a5: | 240 | in our case the address of the label 1 is c017e7a5: |
| 241 | the original assembly code: > 1: movb (%ebx),%dl | 241 | the original assembly code: > 1: movb (%ebx),%dl |
| 242 | and linked in vmlinux : > c017e7a5 <do_con_write+e1> movb (%ebx),%dl | 242 | and linked in vmlinux : > c017e7a5 <do_con_write+e1> movb (%ebx),%dl |
| @@ -254,7 +254,7 @@ The assembly code | |||
| 254 | becomes the value pair | 254 | becomes the value pair |
| 255 | > c01aa7d4 c017c2f6 c0199fe9 c017e7a5 c0199ff5 ................ | 255 | > c01aa7d4 c017c2f6 c0199fe9 c017e7a5 c0199ff5 ................ |
| 256 | ^this is ^this is | 256 | ^this is ^this is |
| 257 | 1b 3b | 257 | 1b 3b |
| 258 | c017e7a5,c0199ff5 in the exception table of the kernel. | 258 | c017e7a5,c0199ff5 in the exception table of the kernel. |
| 259 | 259 | ||
| 260 | So, what actually happens if a fault from kernel mode with no suitable | 260 | So, what actually happens if a fault from kernel mode with no suitable |
| @@ -266,9 +266,9 @@ vma occurs? | |||
| 266 | 3.) CPU calls do_page_fault | 266 | 3.) CPU calls do_page_fault |
| 267 | 4.) do page fault calls search_exception_table (regs->eip == c017e7a5); | 267 | 4.) do page fault calls search_exception_table (regs->eip == c017e7a5); |
| 268 | 5.) search_exception_table looks up the address c017e7a5 in the | 268 | 5.) search_exception_table looks up the address c017e7a5 in the |
| 269 | exception table (i.e. the contents of the ELF section __ex_table) | 269 | exception table (i.e. the contents of the ELF section __ex_table) |
| 270 | and returns the address of the associated fault handle code c0199ff5. | 270 | and returns the address of the associated fault handle code c0199ff5. |
| 271 | 6.) do_page_fault modifies its own return address to point to the fault | 271 | 6.) do_page_fault modifies its own return address to point to the fault |
| 272 | handle code and returns. | 272 | handle code and returns. |
| 273 | 7.) execution continues in the fault handling code. | 273 | 7.) execution continues in the fault handling code. |
| 274 | 8.) 8a) EAX becomes -EFAULT (== -14) | 274 | 8.) 8a) EAX becomes -EFAULT (== -14) |
diff --git a/Documentation/x86/zero-page.txt b/Documentation/x86/zero-page.txt index 4f913857b8a2..feb37e177010 100644 --- a/Documentation/x86/zero-page.txt +++ b/Documentation/x86/zero-page.txt | |||
| @@ -12,6 +12,7 @@ Offset Proto Name Meaning | |||
| 12 | 000/040 ALL screen_info Text mode or frame buffer information | 12 | 000/040 ALL screen_info Text mode or frame buffer information |
| 13 | (struct screen_info) | 13 | (struct screen_info) |
| 14 | 040/014 ALL apm_bios_info APM BIOS information (struct apm_bios_info) | 14 | 040/014 ALL apm_bios_info APM BIOS information (struct apm_bios_info) |
| 15 | 058/008 ALL tboot_addr Physical address of tboot shared page | ||
| 15 | 060/010 ALL ist_info Intel SpeedStep (IST) BIOS support information | 16 | 060/010 ALL ist_info Intel SpeedStep (IST) BIOS support information |
| 16 | (struct ist_info) | 17 | (struct ist_info) |
| 17 | 080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!! | 18 | 080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!! |
